jalr/OpenRGB
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Some edits to the Readme.md for version 0.8

Browse source 
+ Refomatted and expanded the "Installing OpenRGB" on Linux section
+ Added link to new automated UDEV rules file `60-openrgb.rules`
+ Removed reference to `chmod` for SMBus access to resolve #2343
This commit is contained in:
Chris 2022-04-17 14:38:59 +10:00 • committed by Adam Honse
parent eca8ee3a31
commit 0b515ba901
1 changed files with 139 additions and 49 deletions
Download patch file Download diff file Expand all files Collapse all files

188
README.md
View file

@ -1,4 +1,4 @@
## ![OpenRGB](https://gitlab.com/CalcProgrammer1/OpenRGB/-/wikis/uploads/5b7e633ac9f63b00c8a4c72686206c3f/OpenRGB.png)
## ![OpenRGB](https://gitlab.com/CalcProgrammer1/OpenRGB/-/wikis/uploads/5b7e633ac9f63b00c8a4c72686206c3f/OpenRGB.png "OpenRGB Logo")
![Visitors](https://visitor-badge.glitch.me/badge?page_id=org.openrgb.readme) ![Pipeline Status](https://gitlab.com/CalcProgrammer1/OpenRGB/badges/master/pipeline.svg)
@ -35,17 +35,27 @@ There have been two instances of hardware damage in OpenRGB's development and we
* The Mystic Light motherboard code bricked the RGB controller of some MSI motherboards. The code was disabled and reworked. We have been re-adding these motherboards to the support list as we verify that the new code works with them. Affected boards can be unbricked with a Nuvoton Nu-Link adapter.
* There were reports of bricked Gigabyte Aorus Z390 motherboards caused by dumping SMBus address 0x68 in an attempt to reverse engineer the RGB. Due to this, the SMBus Tools page on OpenRGB is hidden by default now as it has no real use to non-developers.
![OpenRGB_Device_View](https://gitlab.com/CalcProgrammer1/OpenRGB/-/wikis/uploads/e1d8d4603ecdd04f1acbcf6b2314fc66/OpenRGB_0.31_Device_View.PNG)
![OpenRGB_Device_View](https://gitlab.com/CalcProgrammer1/OpenRGB/-/wikis/uploads/e1d8d4603ecdd04f1acbcf6b2314fc66/OpenRGB_0.31_Device_View.PNG "OpenRGB Device View Screenshot")
## Windows
* Pre-built binaries are available under the Releases section on GitLab.
- You will need the **Microsoft Visual 2019 C++ runtime** installed. You can get it [here](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads)
* If you wish to build the application yourself:
* You will need the **Microsoft Visual 2019 C++ runtime** installed. You can get it [here](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads)
* Pre-built Release binaries are available for Windows 10 / 11 64bit under the [Releases section](https://gitlab.com/CalcProgrammer1/OpenRGB/-/releases/permalink/latest#Windows-64-bit) on GitLab.
* If you want to test the latest (potentially unstable) code you can also get the Windows package from [the pipeline builds](https://gitlab.com/CalcProgrammer1/OpenRGB/-/jobs/artifacts/master/download?job=Windows+64).
<details>
<summary><h5>Compiling</h5></summary>
* To build the application yourself on Windows:
1. Download the latest Visual Studio Community Edition and Qt Creator.
2. Open the OpenRGB.pro project in Qt Creator.
3. Use the MSVC compiler kit, either 32- or 64-bit, to build the application.
4. Run the project from Qt Creator. If you want to use your custom build standalone, download the latest matching Release package and replace the OpenRGB.exe in it with your new build.
</details>
----
### SMBus Access
* **You must run the application as Administrator the first time to allow WinRing0 to set up. It can be run as a normal user afterwards**
* Early versions of OpenRGB used InpOut32. This is no longer needed and should be removed to avoid warnings by some anti-cheat software. You can uninstall Inpout32 by following the instructions [here](https://gitlab.com/CalcProgrammer1/OpenRGB/-/issues/669#note_461054255).
@ -56,59 +66,139 @@ There have been two instances of hardware damage in OpenRGB's development and we
## Linux
* Pre-built binaries in AppImage format are available under the Releases section on GitLab.
* You can build the project using Qt Creator or on the command line.
1. Install build dependencies
- Debian/Ubuntu: `sudo apt install git build-essential qtcreator qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools libusb-1.0-0-dev libhidapi-dev pkgconf libmbedtls-dev`
- Debian (before `bullseye`) or Ubuntu (before 21.04): `sudo apt install git build-essential qtcreator qt5-default libusb-1.0-0-dev libhidapi-dev pkgconf libmbedtls-dev`
- Fedora: `sudo dnf install automake gcc-c++ qt5-qtbase-devel hidapi-devel libusbx-devel mbedtls-devel`
2. git clone https://gitlab.com/CalcProgrammer1/OpenRGB
3. cd OpenRGB
4. qmake OpenRGB.pro
- On Fedora, replace qmake with qmake-qt5
5. make -j$(nproc)
* Run the application with ./openrgb
* You can also build a Debian package (.deb) from this source code with dpkg-buildpackage -us -B
- Building a Debian package requires `debhelper` to be installed: `sudo apt install debhelper`
* Pre-built binaries in AppImage format are available under the [Releases](https://gitlab.com/CalcProgrammer1/OpenRGB/-/releases/permalink/latest#Linux-64-bit) section on GitLab.
* There is also a unofficial universal Flatpak build [available on Flathub](https://flathub.org/apps/details/org.openrgb.OpenRGB). Note: To ensure you have device permissions please [install the latest UDEV rules](#installing-udev-rules-manually).
<details>
<summary><h5>Arch</h5></summary>
##### Binaries
* OpenRGB is available in the AUR for both the [release](https://aur.archlinux.org/packages/openrgb/) and [pipeline](https://aur.archlinux.org/packages/openrgb-git/) builds
</details>
<details>
<summary><h5>Debian / Ubuntu</h5></summary>
##### Binaries
* OpenRGB builds an official Debian package for Bullseye and Ubuntu 21.04 onwards for both the 64bit [release](https://gitlab.com/CalcProgrammer1/OpenRGB/-/releases/permalink/latest#Debian-Bullseye-amd64) and [pipeline](https://gitlab.com/CalcProgrammer1/OpenRGB/-/jobs/artifacts/master/download?job=Linux+64+.deb+%28Debian+Bullseye%29) builds
* There is also a legacy package for Debian 64bit Buster and it's derivatives (Ubuntu prior to 21.04) with [release](https://gitlab.com/CalcProgrammer1/OpenRGB/-/releases/permalink/latest#Debian-Buster-amd64) and [pipeline](https://gitlab.com/CalcProgrammer1/OpenRGB/-/jobs/artifacts/master/download?job=Linux+64+.deb+%28Debian+Buster%29) builds
##### Compiling
1. Install build dependencies
- `sudo apt install git build-essential qtcreator qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools libusb-1.0-0-dev libhidapi-dev pkgconf libmbedtls-dev`
2. git clone https://gitlab.com/CalcProgrammer1/OpenRGB
3. cd OpenRGB
4. qmake OpenRGB.pro
5. make -j$(nproc)
6. You can then run the application from the compile directory with `./openrgb` or install with `make install`
7. You will also need to [install the latest UDEV rules](#installing-udev-rules-manually).
##### Packaging
* You can also build a Debian package (.deb) from this source code with `dpkg-buildpackage -us -B`
- Building a Debian package requires `debhelper` to be installed: `sudo apt install debhelper`
</details>
<details>
<summary><h5>Fedora</h5></summary>
##### Binaries
* OpenRGB builds an official Fedora 35 and 36 package for both the [release](https://gitlab.com/CalcProgrammer1/OpenRGB/-/releases/permalink/latest#Linux-64-bit) and [pipeline](https://gitlab.com/CalcProgrammer1/OpenRGB/-/jobs/artifacts/master/download?job=Linux+64+rpm) builds
##### Compiling
1. Install build dependencies
- `sudo dnf install automake gcc-c++ qt5-qtbase-devel hidapi-devel libusbx-devel mbedtls-devel`
2. git clone https://gitlab.com/CalcProgrammer1/OpenRGB
3. cd OpenRGB
4. qmake-qt5 OpenRGB.pro
5. make -j$(nproc)
6. You can then run the application from the compile directory with `./openrgb` or install with `make install`
7. You will also need to [install the latest UDEV rules](#installing-udev-rules-manually).
</details>
----
### SMBus Access
* SMBus access is necessary for controlling RGB RAM and certain motherboard on-board LEDs.
* If you are not trying to use OpenRGB to control RGB RAM or motherboard LEDs, you may skip this section.
* ASUS and ASRock motherboards have their RGB controller on an SMBus interface that is not accessible by an unmodified Linux kernel (for now). I am working on getting patches submitted upstream, but for now you must patch your kernel with the provided OpenRGB.patch file.
* Allowing access to SMBus:
1. Load the i2c-dev module: `sudo modprobe i2c-dev`
2. Load the i2c driver for your chipset:
- Intel:
- `sudo modprobe i2c-i801`
- `sudo modprobe i2c-nct6775` - Secondary controller for motherboard LEDs (requires patch)
- AMD:
- `modprobe i2c-piix4`
- Unmodified kernel will have one interface, patched kernel will have two. The first at 0x0B00 and the second at 0x0B20. The 0x0B20 interface is for motherboard LEDs.
* Instructions on patching the kernel:
- https://gitlab.com/CalcProgrammer1/OpenRGB/-/wikis/OpenRGB-Kernel-Patch
* Some Gigabyte/Aorus motherboards have an ACPI conflict with the SMBus controller.
- Add `acpi_enforce_resources=lax` to your kernel command line and reboot. The controller should now show up.
- On Fedora, install `grubby` and then execute this.
```
grubby --update-kernel=ALL --args="acpi_enforce_resources=lax"
```
- If you want to check if the kernel was loaded with this option you can execute this command from the terminal once you've rebooted.
```
cat /proc/cmdline
```
* SMBus access is necessary for controlling RGB RAM and certain motherboard on-board LEDs.
* If you are not trying to use OpenRGB to control RGB RAM or motherboard LEDs, you may skip this section.
* ASUS and ASRock motherboards have their RGB controller on a secondary SMBus interface and requires a Linux kernel > 5.7 <sup>[commit](https://github.com/torvalds/linux/commit/f27237c174fd9653033330e4e532cd9d153ce824)</sup>
* Allowing access to SMBus:
1. Load the i2c-dev module: `sudo modprobe i2c-dev`
2. Load the i2c driver for your chipset:
<details>
<summary><h6>Intel</h6></summary>
* `sudo modprobe i2c-i801`
* `sudo modprobe i2c-nct6775` - Secondary controller for motherboard LEDs (requires [kernel patch](https://gitlab.com/CalcProgrammer1/OpenRGB/-/wikis/OpenRGB-Kernel-Patch))
</details>
<details>
<summary><h6>AMD</h6></summary>
* `sudo modprobe i2c-piix4`
* Unmodified kernel will have one interface, patched kernel will have two. The first at 0x0B00 and the second at 0x0B20. The 0x0B20 interface is for motherboard LEDs.
</details>
----
* You'll have to enable user access to your SMBus if you don't run as root.
- List all SMBus controllers: `sudo i2cdetect -l`
- Note the number for PIIX4, I801, and NCT6775 controllers.
- Give user access to those controllers, for instance: `sudo chmod 777 /dev/i2c-0`
- Give user access to those controllers. If you have not installed OpenRGB from a package (e.g. deb, RPM or from the AUR) then most likely you need to [install the UDEV rules](#installing-udev-rules-manually).
* The i2c-nct6775 kernel module requires patching, please refer to [instructions here](https://gitlab.com/CalcProgrammer1/OpenRGB/-/wikis/OpenRGB-Kernel-Patch)
* Some Gigabyte/Aorus motherboards have an ACPI conflict with the SMBus controller. Please [add a kernel parameter](#kernel-parameters) to resolve this conflict.
### USB Access
* USB devices require udev rules to access as a normal user.
* You can run OpenRGB as root to detect all USB devices.
* Udev rules are included in this repo:
- Copy the 60-openrgb.rules file to /etc/udev/rules.d/
- Reload rules with `sudo udevadm control --reload-rules && sudo udevadm trigger`
* USB devices require [udev rules](#installing-udev-rules-manually) to access as a normal user.
* Alternatively you can run OpenRGB as root to detect all USB devices. (Not recommended)
* USB based Gigabyte AORUS motherboards may also have an ACPI conflict. Please [add a kernel parameter](#kernel-parameters) to resolve this conflict.
### Installing UDEV rules manually
* If you have installed OpenRGB from a package then latest UDEV rules are installed locally at `/usr/lib/udev/rules.d/60-openrgb.rules`
* Flatpak and Appimage "packages" will need to install this file manually.
* Udev rules are built from the source at compile time. When building locally they are installed with the `make install` step to `/usr/lib/udev/rules.d/60-openrgb.rules`
* If you need to install the UDEV rules file manually you can also download the [latest compiled udev rules](https://gitlab.com/CalcProgrammer1/OpenRGB/-/jobs/artifacts/master/raw/60-openrgb.rules?job=Linux+64+AppImage&inline=false) from Gitlab.
- Copy this 60-openrgb.rules file to `/usr/lib/udev/rules.d/`
- Then reload rules with `sudo udevadm control --reload-rules && sudo udevadm trigger`
### Kernel Parameters
* To resolve an ACPI conflict add the `acpi_enforce_resources=lax` kernel parameter.
* If you want to check if the kernel was loaded with this option you can execute this command from the terminal once you've rebooted.
* `cat /proc/cmdline`
<details>
<summary><h5>Arch</h5></summary>
* Please see [the Arch wiki](https://wiki.archlinux.org/title/kernel_parameters) for details on how to update your bootloader.
</details>
<details>
<summary><h5>Debian / Ubuntu</h5></summary>
* Please see [the Ubuntu Documentation](https://wiki.ubuntu.com/Kernel/KernelBootParameters) for Kernel Parameters for more information on updating your boot parameters.
</details>
<details>
<summary><h5>Fedora</h5></summary>
* On Fedora, install `grubby` and then following command:
`grubby --update-kernel=ALL --args="acpi_enforce_resources=lax"`
* For more information please refer to the Fedora docs for [grubby](https://docs.fedoraproject.org/en-US/fedora/latest/system-administrators-guide/kernel-module-driver-configuration/Working_with_the_GRUB_2_Boot_Loader/#sec-Making_Persistent_Changes_to_a_GRUB_2_Menu_Using_the_grubby_Tool).
</details>
----
## MacOS