Jens/LumaOps-Public
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Publish LumaOps source

Browse Source
This commit is contained in:
LumaOps release export
2026-09-03 01:18:36 +02:00
commit 7f1c0e5f71
2363 changed files with 501543 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Documentation/Common-Modes.md
+19
View File
@@ -0,0 +1,19 @@
# Common Modes in OpenRGB
OpenRGB uses "modes" to describe RGB effects built into a device’s firmware. These effects can be changed by selecting a mode in the OpenRGB interface. The patterns are generated by the device’s RGB controller, not by OpenRGB, and run independently of the PC. In the interest of being able to better describe these modes, we are trying to standardize the mode names across all supported devices.
There are several effects that are pretty common across many brands and vendors of RGB hardware. Manufacturers often use different names for the same mode. For example, a fade-in/fade-out effect might be called "Fading", "Breathing", or "Breath". A color-cycling effect might appear as "Cycle", "Spectrum Cycle", "Spectrum", or "Rainbow". A lot of OpenRGB's existing code simply copies the same names the official software gave to the modes, but these differences in name prevent us from being able to apply what is essentially the same effect across multiple devices when the names don't match. It also limits our ability to provide clear descriptions of modes through tooltips. To remedy this, we have compiled a list of common modes and providing names that we can use across all devices for any mode that implements a certain style of effect. If all devices have their fade on/fade off mode called "Breathing", we can just set "Breathing" across all devices and end up with something that looks at least sort of uniform, if not synchronized in time.
# Common OpenRGB Modes
| Standardized Name | Description | Example GIF |
| ----------------- | ----------- | ----------- |
| Direct | Direct mode is a mode that allows setting individual LEDs to static colors that does not fade or flicker upon color changes and does not save the updated colors to device memory. Used for effect engine software to rapidly update the LEDs for PC software driven effects. Some devices require a continuous packet stream to remain in direct mode, otherwise they revert to built-in effects. | |
| Custom | Custom mode is a mode that allows setting individual LEDs to static colors, but does not meet the criteria for being a Direct mode. This means it either flickers, fades, or saves to device memory. Generally unsuitable for effect engine software. | |
| Static | Static mode is a mode that sets the entire device or device zones, but not individual LEDs, to a static color. This mode may fade or flicker and may save to device memory. | |
| Breathing | Light gradually fades from fully off to fully on over some period of time and then gradually fades back to fully off. | |
| Flashing | Light abruptly changes from fully off to fully on instantly, then instantly turns back off after a period of time. | |
| Spectrum Cycle | Light gradually cycles through the entire color spectrum. All lights on the device are the same color. | |
| Rainbow Wave | Light gradually cycles through the entire color spectrum. Lights are staggered as to produce a rainbow pattern that moves. | |
| Reactive | Generally only available on input devices, this is a mode that lights one or more LEDs when an input (key, mouse button, etc) is pressed. | |
| Off | All lights are disabled. | |
Documentation/Compiling.md
+71
View File
@@ -0,0 +1,71 @@
# Compiling
This document details the process to compile OpenRGB from source on supported operating systems.
## Windows
* You will need the **Microsoft Visual 2019 C++ runtime** installed. You can get it [here](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist)
* To build the application yourself on Windows:
1. [Install Git](https://git-scm.com/download)
2. Clone the [OpenRGB-Qt-Packages](https://gitlab.com/OpenRGBDevelopers/OpenRGB-Qt-Packages) git repo and run `install.bat` (or optionally `install-chocolatey.bat` if you use the Chocolatey package manager).
3. In the OpenRGB source directory, run the `scripts\build-windows.bat` file with arguments `<Qt Version> <MSVC Version> <Bits>`.
* Qt versions provided by `OpenRGB-Qt-Packages` include `5.15.0` (using MSVC `2019`) and `6.8.3` (using MSVC `2022`).
* For example, for a Qt5 64-bit build, `.\scripts\build-windows.bat 5.15.0 2019 64`
4. You can also use Qt Creator to build and debug the project, you will need to install it from the Qt Online Installer or by downloading and extracting a binary release and manually configuring it.
## Linux
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 qttools5-dev-tools`
- Fedora: `sudo dnf install automake gcc-c++ git hidapi-devel libusbx-devel mbedtls-devel pkgconf qt5-qtbase-devel qt5-linguist`
2. `git clone https://gitlab.com/CalcProgrammer1/OpenRGB`
3. `cd OpenRGB`
4. `mkdir build`
5. `cd build`
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](UdevRules.md).
#### Packaging
You can also build OpenRGB generic AppImage packages and distribution-specific packages for Debian-based and Fedora-based distros. Install the build dependencies from the section above for your distribution before proceeding.
* AppImage:
* Debian/Ubuntu:
* Make sure OpenRGB is cloned in ~/OpenRGB before proceeding. Output .deb is in ~/.
1. `sudo apt install debhelper`
2. `cd ~/OpenRGB`
3. `scripts/build-package-files.sh debian/changelog`
4. `dpkg-buildpackage -us -B`
* Fedora:
* Make sure OpenRGB is cloned in ~/OpenRGB before proceeding. Output .rpm is in ~/rpmbuild/RPMS/.
1. `sudo dnf install rpmdevtools dnf-plugins-core`
2. `cd ~/`
3. `rpmdev-setuptree`
4. `tar -cf rpmbuild/SOURCES/OpenRGB.tar.gz OpenRGB/`
4. `cd OpenRGB`
5. `./scripts/build-package-files.sh fedora/OpenRGB.spec`
6. `cd ~/`
7. `cp OpenRGB/fedora/OpenRGB.spec rpmbuild/SPECS/`
8. `sudo dnf builddep rpmbuild/SPECS/OpenRGB.spec -y`
9. `cd rpmbuild/SOURCES`
10. `tar -xf OpenRGB.tar.gz`
11. `cd ~/`
12. `rpmbuild -ba rpmbuild/SPECS/OpenRGB.spec`
## MacOS
1. Install build dependencies with Homebrew
- Install Homebrew by following the instructions at https://brew.sh/
- `brew install git qt5 hidapi libusb mbedtls@2`
- `brew link qt5`
2. [Create a local certificate](https://support.apple.com/guide/keychain-access/create-self-signed-certificates-kyca8916/mac) called OpenRGB with code signing capability
3. git clone https://gitlab.com/CalcProgrammer1/OpenRGB
4. cd OpenRGB
5. qmake OpenRGB.pro
6. make -j8
7. macdeployqt OpenRGB.app -codesign=OpenRGB
8. Copy the OpenRGB.app application package to Applications
Documentation/Images/OpenRGB.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 23 KiB

Documentation/Images/OpenRGB_Screenshot.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 151 KiB

Documentation/KernelParameters.md
+17
View File
@@ -0,0 +1,17 @@
# 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`.
### Arch Linux
* Please see [the Arch wiki](https://wiki.archlinux.org/title/kernel_parameters) for details on how to update your bootloader.
### Debian/Ubuntu
* Please see [the Ubuntu Documentation](https://wiki.ubuntu.com/Kernel/KernelBootParameters) for Kernel Parameters for more information on updating your boot parameters.
### Fedora
* 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).
Documentation/OpenRGBSDK.md
+405
View File
@@ -0,0 +1,405 @@
# OpenRGB SDK Documentation
OpenRGB provides a network-based Software Development Kit (SDK) interface for third-party software applications to integrate with OpenRGB to control lighting on OpenRGB-supported devices. This protocol is a binary, packet-based protocol designed for efficient, lightweight transfer of lighting data over a TCP/IP connection. It may be used locally or over a physical network between computers. The protocol is versioned. Client and server must negotiate a minimum supported protocol version upon connection. The selected protocol version determines what capabilities are available and can change packet format for certain packets as new information is added to the protocol.
The protocol mimics the [RGBController API](The-RGBController-API) closely. It can be thought of as "RGBController over IP" in that the protocol is designed so that a network RGBController object can be created on the client that is a direct copy of the real RGBController object on the server. Calls to the network client RGBController object send packets to the server which trigger calls to the real object, updating the necessary object data before the call.
# Protocol Versions
| Protocol Version | OpenRGB Release | Description |
| ---------------- | --------------- | -------------------------------------------------------------------------------------------------------------- |
| 0 | 0.3 | Initial (unversioned) protocol |
| 1 | 0.5 | Add versioning, add vendor string |
| 2 | 0.6 | Add profile controls |
| 3 | 0.7 | Add brightness field to modes, add SaveMode() |
| 4 | 0.9 | Add segments field to zones, plugin interface |
| 5 | 1.0 | Add zone flags, controller flags, effects-only zones, alternative LED names, add ClearSegments and AddSegments |
\* Denotes unreleased version, reflects status of current pipeline
# Protocol Basics
The default port for the OpenRGB SDK server is 6742. This is "ORGB" on a telephone keypad.
Each packet starts with a header that indicates the packet is an OpenRGB SDK packet and provides the device and packet IDs. The header format is described in the following table.
### NetPacketHeader structure
| Size | Format | Name | Description |
| ---- | ------------ | ----------- | ------------------- |
| 4 | char[4] | pkt_magic | Magic value, "ORGB" |
| 4 | unsigned int | pkt_dev_idx | Device Index |
| 4 | unsigned int | pkt_id | Packet ID |
| 4 | unsigned int | pkt_size | Packet Size |
`pkt_magic`: Always set this to the literal value "ORGB".
`pkt_dev_idx`: The device index that the command is targeting.
`pkt_id`: The command ID, see IDs table below
`pkt_size`: The size, in bytes, of the packet data
### Packet IDs
The following IDs represent different SDK commands. Each ID packet has a certain format of data associated with it, which will be explained under each ID's section of this document. Gaps have been left in the ID values to allow for future expansion. The same ID values are often used for both request and response packets.
| Value | Name | Description | Protocol Version |
| ----- | ------------------------------------------------------------------------------------------- | ------------------------------------------------ | ---------------- |
| 0 | [NET_PACKET_ID_REQUEST_CONTROLLER_COUNT](#net_packet_id_request_controller_count) | Request RGBController device count from server | 0 |
| 1 | [NET_PACKET_ID_REQUEST_CONTROLLER_DATA](#net_packet_id_request_controller_data) | Request RGBController data block | 0 |
| 40 | [NET_PACKET_ID_REQUEST_PROTOCOL_VERSION](#net_packet_id_request_protocol_version) | Request OpenRGB SDK protocol version from server | 1* |
| 50 | [NET_PACKET_ID_SET_CLIENT_NAME](#net_packet_id_set_client_name) | Send client name string to server | 0 |
| 100 | [NET_PACKET_ID_DEVICE_LIST_UPDATED](#net_packet_id_device_list_updated) | Indicate to clients that device list has updated | 1 |
| 140 | [NET_PACKET_ID_REQUEST_RESCAN_DEVICES](#net_packet_id_request_rescan_devices) | Request server to rescan devices | 5 |
| 150 | [NET_PACKET_ID_REQUEST_PROFILE_LIST](#net_packet_id_request_profile_list) | Request profile list | 2 |
| 151 | [NET_PACKET_ID_REQUEST_SAVE_PROFILE](#net_packet_id_request_save_profile) | Save current configuration in a new profile | 2 |
| 152 | [NET_PACKET_ID_REQUEST_LOAD_PROFILE](#net_packet_id_request_load_profile) | Load a given profile | 2 |
| 153 | [NET_PACKET_ID_REQUEST_DELETE_PROFILE](#net_packet_id_request_delete_profile) | Delete a given profile | 2 |
| 200 | [NET_PACKET_ID_REQUEST_PLUGIN_LIST](#net_packet_id_request_plugin_list) | Request plugin list | 4 |
| 201 | [NET_PACKET_ID_PLUGIN_SPECIFIC](#net_packet_id_plugin_specific) | Plugin specific | 4 |
| 1000 | [NET_PACKET_ID_RGBCONTROLLER_RESIZEZONE](#net_packet_id_rgbcontroller_resizezone) | RGBController::ResizeZone() | 0 |
| 1001 | [NET_PACKET_ID_RGBCONTROLLER_CLEARSEGMENTS](#net_packet_id_rgbcontroller_clearsegments) | RGBController::ClearSegments() | 5 |
| 1002 | [NET_PACKET_ID_RGBCONTROLLER_ADDSEGMENT](#net_packet_id_rgbcontroller_addsegment) | RGBController::AddSegment() | 5 |
| 1050 | [NET_PACKET_ID_RGBCONTROLLER_UPDATELEDS](#net_packet_id_rgbcontroller_updateleds) | RGBController::UpdateLEDs() | 0 |
| 1051 | [NET_PACKET_ID_RGBCONTROLLER_UPDATEZONELEDS](#net_packet_id_rgbcontroller_updatezoneleds) | RGBController::UpdateZoneLEDs() | 0 |
| 1052 | [NET_PACKET_ID_RGBCONTROLLER_UPDATESINGLELED](#net_packet_id_rgbcontroller_updatesingleled) | RGBController::UpdateSingleLED() | 0 |
| 1100 | [NET_PACKET_ID_RGBCONTROLLER_SETCUSTOMMODE](#net_packet_id_rgbcontroller_setcustommode) | RGBController::SetCustomMode() | 0 |
| 1101 | [NET_PACKET_ID_RGBCONTROLLER_UPDATEMODE](#net_packet_id_rgbcontroller_updatemode) | RGBController::UpdateMode() | 0 |
| 1102 | [NET_PACKET_ID_RGBCONTROLLER_SAVEMODE](#net_packet_id_rgbcontroller_savemode) | RGBController::SaveMode() | 3 |
\* The NET_PACKET_ID_REQUEST_PROTOCOL_VERSION packet was not present in protocol version 0, but clients supporting protocol versions 1+ should always send this packet. If no response is received, it should be assumed that the server is using protocol 0.
# Packet-Specific Documentation
## NET_PACKET_ID_REQUEST_CONTROLLER_COUNT
### Request [Size: 0]
The client uses this ID to request the number of controllers on the server. The request contains no data.
### Response [Size: 4]
The server responds to this request with the number of controllers in the device list. The response contains a single `unsigned int`, size 4, holding this value.
## NET_PACKET_ID_REQUEST_CONTROLLER_DATA
### Request [Protocol 0 Size: 0] [Protocol 1+ Size: 4]
The client uses this ID to request the controller data for a given controller. For protocol 0, this request contains no data. For protocol 1 or higher, this request contains a single `unsigned int`, size 4, holding the highest protocol version supported by both the client and the server. The `pkt_dev_idx` of this request's header indicates which controller you are requesting data for. Upon connecting, the client should request controller data from 0 to [controller count], where [controller count] is the value from NET_PACKET_ID_REQUEST_CONTROLLER_COUNT.
NOTE: Before sending this request, the client should request the protocol version from the server and determine the value to send, if any. If the server is using protocol version 0, even if the SDK implementation supports higher, send this packet with no data.
### Response [Size: Variable]
The server responds to this request with a large data block. The format of the block is shown below. Portions of this block are omitted if the requested protocol level is below the listed value. The receiver is expected to parse this data block using the same protocol version sent in the request (or protocol 0 if the request is sent with no data).
| Size | Format | Name | Protocol Version | Description |
| ------------------- | ------------------------------------- | ------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------ |
| 4 | unsigned int | data_size | 0 | Size of all data in packet |
| 4 | int | type | 0 | RGBController type field value |
| 2 | unsigned short | name_len | 0 | Length of RGBController name field string, including null termination |
| name_len | char[name_len] | name | 0 | RGBController name field string value, including null termination |
| 2 | unsigned short | vendor_len | 1 | Length of RGBController vendor field string, including null termination |
| vendor_len | char[vendor_len] | vendor | 1 | RGBController vendor field string value, including null termination |
| 2 | unsigned short | description_len | 0 | Length of RGBController description field string, including null termination |
| description_len | char[description_len] | description | 0 | RGBController description field string value, including null termination |
| 2 | unsigned short | version_len | 0 | Length of RGBController version field string, including null termination |
| version_len | char[version_len] | version | 0 | RGBController version field string value, including null termination |
| 2 | unsigned short | serial_len | 0 | Length of RGBController serial field string, including null termination |
| serial_len | char[serial_len] | serial | 0 | RGBController serial field string value, including null termination |
| 2 | unsigned short | location_len | 0 | Length of RGBController location field string, including null termination |
| location_len | char[location_len] | location | 0 | RGBController location field string value, including null termination |
| 2 | unsigned short | num_modes | 0 | Number of modes in RGBController |
| 4 | int | active_mode | 0 | RGBController active_mode field value |
| Variable | Mode Data[num_modes] | modes | 0 | See [Mode Data](#mode-data) block format table. Repeat num_modes times |
| 2 | unsigned short | num_zones | 0 | Number of zones in RGBController |
| Variable | Zone Data[num_zones] | zones | 0 | See [Zone Data](#zone-data) block format table. Repeat num_zones times |
| 2 | unsigned short | num_leds | 0 | Number of LEDs in RGBController |
| Variable | LED Data[num_leds] | leds | 0 | See [LED Data](#led-data) block format table. Repeat num_leds times |
| 2 | unsigned short | num_colors | 0 | Number of colors in RGBController |
| 4 * num_colors | RGBColor[num_colors] | colors | 0 | RGBController colors field values |
| 2 | unsigned short | num_led_alt_names | 5 | Number of LED alternate name strings |
| Variable | LED Alternate Name[num_led_alt_names] | led_alt_names | 5 | See [LED Alternate Name Data](#led-alternate-names-data) block format table. Repeat num_led_alt_names times |
| 4 | unsigned int | flags | 5 | RGBController flags field value |
## Mode Data
The Mode Data block represents one entry in the `RGBController::modes` vector. Portions of this block are omitted if the requested protocol level is below the listed value.
| Size | Format | Name | Protocol Version | Description |
| ------------------- | ------------------------- | ------------------- | ---------------- | ------------------------------------------------------ |
| 2 | unsigned short | mode_name_len | 0 | Length of mode name string, including null termination |
| mode_name_len | char[mode_name_len] | mode_name | 0 | Mode name string value, including null termination |
| 4 | int | mode_value | 0 | Mode value field value |
| 4 | unsigned int | mode_flags | 0 | Mode flags field value |
| 4 | unsigned int | mode_speed_min | 0 | Mode speed_min field value |
| 4 | unsigned int | mode_speed_max | 0 | Mode speed_max field value |
| 4 | unsigned int | mode_brightness_min | 3 | Mode brightness_min field value |
| 4 | unsigned int | mode_brightness_max | 3 | Mode brightness_max field value |
| 4 | unsigned int | mode_colors_min | 0 | Mode colors_min field value |
| 4 | unsigned int | mode_colors_max | 0 | Mode colors_max field value |
| 4 | unsigned int | mode_speed | 0 | Mode speed value |
| 4 | unsigned int | mode_brightness | 3 | Mode brightness value |
| 4 | unsigned int | mode_direction | 0 | Mode direction value |
| 4 | unsigned int | mode_color_mode | 0 | Mode color_mode value |
| 2 | unsigned short | mode_num_colors | 0 | Mode number of colors |
| 4 * mode_num_colors | RGBColor[mode_num_colors] | mode_colors | 0 | Mode color values |
## Zone Data
The Zone Data block represents one entry in the `RGBController::zones` vector.
| Size | Format | Name | Protocol Version | Description |
| ---------------------- | --------------------------------- | ------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------ |
| 2 | unsigned short | zone_name_len | 0 | Length of zone name string, including null termination |
| zone_name_len | char[zone_name_len] | zone_name | 0 | Zone name string value, including null termination |
| 4 | int | zone_type | 0 | Zone type value |
| 4 | unsigned int | zone_leds_min | 0 | Zone leds_min value |
| 4 | unsigned int | zone_leds_max | 0 | Zone leds_max value |
| 4 | unsigned int | zone_leds_count | 0 | Zone leds_count value |
| 2 | unsigned short | zone_matrix_len | 0 | Zone matrix length if matrix_map exists: (matrix_map width * height * 4) + 8 OTHERWISE 0 if matrix_map NULL |
| 4* | unsigned int | zone_matrix_height | 0 | Zone matrix_map height (*only if matrix_map exists) |
| 4* | unsigned int | zone_matrix_width | 0 | Zone matrix_map width (*only if matrix_map exists) |
| (zone_matrix_len - 8)* | unsigned int[zone_matrix_len - 8] | zone_matrix_data | 0 | Zone matrix_map data (*only if matrix_map exists) |
| 2 | unsigned short | num_segments | 4 | Number of segments in zone |
| Variable | Segment Data[num_segments] | segments | 4 | See [Segment Data](#segment-data) block format table. Repeat num_segments times |
| 4 | unsigned int | zone_flags | 5 | Zone flags value |
## Segment Data
The Segment Data block represents one entry in the `RGBController::zones::segments` vector. This data block was introduced in protocol version 4.
| Size | Format | Name | Protocol Version | Description |
| ---------------- | ---------------------- | ------------------ | ---------------- | --------------------------------------------------------- |
| 2 | unsigned short | segment_name_len | 4 | Length of segment name string, including null termination |
| segment_name_len | char[segment_name_len] | segment_name | 4 | Segment name string value, including null termination |
| 4 | int | segment_type | 4 | Segment type value |
| 4 | unsigned int | segment_start_idx | 4 | Segment start_idx value |
| 4 | unsigned int | segment_leds_count | 4 | Segment leds_count value |
## LED Data
The LED Data block represents one entry in the `RGBController::leds` vector.
| Size | Format | Name | Protocol Version | Description |
| ------------------- | ------------------------- | ------------------- | ---------------- | ------------------------------------------------------ |
| 2 | unsigned short | led_name_len | 0 | Length of LED name string, including null termination |
| led_name_len | char[led_name_len] | led_name | 0 | LED name string value, including null termination |
| 4 | unsigned int | led_value | 0 | LED value field value |
## LED Alternate Name Data
The LED Alternate Name Data block represents one entry in the `RGBController::led_alt_names` vector. This data block was introduced in protocol version 5.
| Size | Format | Name | Protocol Version | Description |
| ---------------- | ---------------------- | ---------------- | ---------------- | --------------------------------------------------------------- |
| 2 | unsigned short | led_alt_name_len | 5 | Length of LED alternate name string, including null termination |
| led_alt_name_len | char[led_alt_name_len] | led_alt_name | 5 | LED alternate name string value, including null termination |
## NET_PACKET_ID_REQUEST_PROTOCOL_VERSION
### Request [Size: 4]
The client uses this ID to request the server's highest supported protocol version as well as to indicate to the server the client's highest supported protocol version. The request contains a single `unsigned int`, size 4, containing the client's highest supported protocol version.
### Response [Size: 4]
The server responds to this request with a single `unsigned int`, size 4, containing the server's highest supported protocol version. If the server is using protocol version 0, it will not send a response. If no response is received, assume the server's highest supported protocol version is version 0.
## NET_PACKET_ID_SET_CLIENT_NAME
### Client Only [Size: Variable]
The client uses this ID to send the client's null-terminated name string to the server. The size of the packet is the size of the string including the null terminator. In C, this is strlen() + 1. There is no response from the server for this packet.
## NET_PACKET_ID_DEVICE_LIST_UPDATED
### Server Only [Size: 0]
The server uses this ID to notify a client that the server's device list has been updated. Upon receiving this packet, clients should synchronize their local device lists with the server by requesting size and controller data again. This packet contains no data.
## NET_PACKET_ID_REQUEST_RESCAN_DEVICES
### Client Only [Size: 0]
The client uses this ID to request the server rescan its devices.
## NET_PACKET_ID_REQUEST_PROFILE_LIST
### Request [Size: 0]
The client uses this ID to request the server's profile list. The request contains no data.
### Response [Size: Variable]
The server responds to this request with a data block. The format of the block is shown below.
| Size | Format | Name | Protocol Version | Description |
| -------- | -------------------------- | ------------ | ---------------- | -------------------------------------------------------------------------------- |
| 4 | unsigned int | data_size | 2 | Size of all data in packet |
| 2 | unsigned short | num_profiles | 2 | Number of profiles on server |
| Variable | Profile Data[num_profiles] | profiles | 2 | See [Profile Data](#profile-data) block format table. Repeat num_profiles times |
## Profile Data
The profile data block represents the information of one profile. This data block was introduced in protocol version 2.
| Size | Format | Name | Protocol Version | Description |
| ---------------- | ---------------------- | ---------------- | ---------------- | --------------------------------------------------------- |
| 2 | unsigned short | profile_name_len | 2 | Length of profile name string, including null termination |
| profile_name_len | char[profile_name_len] | profile_name | 2 | Profile name string value, including null termination |
## NET_PACKET_ID_REQUEST_SAVE_PROFILE
### Client Only [Size: Variable]
The client uses this ID to command the server to save the current configuration to a profile. It passes the name of the profile to save as a null-terminated string. The size of the packet is the size of the string including the null terminator. In C, this is strlen() + 1. There is no response from the server for this packet.
## NET_PACKET_ID_REQUEST_LOAD_PROFILE
### Client Only [Size: Variable]
The client uses this ID to command the server to load the given profile. It passes the name of the profile to load as a null-terminated string. The size of the packet is the size of the string including the null terminator. In C, this is strlen() + 1. There is no response from the server for this packet.
Calling this function will not actually update the controllers. Instead, the controller states will be updated from the profile on the server side. After sending this request, the client should re-request all controller states from the server so that the client controller states match the server states loaded from the profile. After requesting all of the controller data, the client shall call UpdateMode() on all controllers to apply the updated state.
## NET_PACKET_ID_REQUEST_DELETE_PROFILE
### Client Only [Size: Variable]
The client uses this ID to command the server to delete the given profile. It passes the name of the profile to delete as a null-terminated string. The size of the packet is the size of the string including the null terminator. In C, this is strlen() + 1. There is no response from the server for this packet.
## NET_PACKET_ID_REQUEST_PLUGIN_LIST
### Request [Size: 0]
The client uses this ID to request the server's plugin list. The request contains no data.
### Response [Size: Variable]
The server responds to this request with a data block. The format of the block is shown below.
| Size | Format | Name | Protocol Version | Description |
| -------- | ------------------------ | ----------- | ---------------- | ----------------------------------------------------------------------------- |
| 4 | unsigned int | data_size | 4 | Size of all data in packet |
| 2 | unsigned short | num_plugins | 4 | Number of plugins on server |
| Variable | Plugin Data[num_plugins] | plugins | 4 | See [Plugin Data](#plugin-data) block format table. Repeat num_plugins times |
## Plugin Data
The plugin data block represents the information of one plugin. This data block was introduced in protocol version 4.
| Size | Format | Name | Protocol Version | Description |
| ---------------------- | ---------------------------- | ----------------------- | ---------------- | --------------------------------------------------------------- |
| 2 | unsigned short | plugin_name_len | 4 | Length of plugin name string, including null termination |
| plugin_name_len | char[plugin_name_len] | plugin_name | 4 | Plugin name string value, including null termination |
| 2 | unsigned short | plugin_description_len | 4 | Length of plugin description string, including null termination |
| plugin_description_len | char[plugin_description_len] | plugin_description | 4 | Plugin description string value, including null termination |
| 2 | unsigned short | plugin_version_len | 4 | Length of plugin version string, including null termination |
| plugin_version_len | char[plugin_version_len] | plugin_version | 4 | Plugin version string value, including null termination |
| 4 | unsigned int | plugin_index | 4 | Plugin index value |
| 4 | unsigned int | plugin_protocol_version | 4 | Plugin protocol version value |
## NET_PACKET_ID_PLUGIN_SPECIFIC
### Request [Size: Variable]
This packet is used to send data to a plugin. The `pkt_dev_idx` field in the header specifies which plugin to send to and corresponds to the `plugin_index` field in the plugin list. The first 4 bytes of the data is the plugin packet type, the rest of the packet is plugin-specific.
List of plugins that currently support this:
- [Effects plugin](https://gitlab.com/OpenRGBDevelopers/OpenRGBEffectsPlugin/-/blob/master/SDK.md)
### Response [Size: Variable]
The response is optionally generated by the plugin. The data in the packet is plugin-specific.
## NET_PACKET_ID_RGBCONTROLLER_RESIZEZONE
### Client Only [Size: 8]
The client uses this ID to call the ResizeZone() function of an RGBController device. The packet data contains a data block. The format of the block is shown below. The `pkt_dev_idx` of this request's header indicates which controller you are calling ResizeZone() on.
| Size | Format | Name | Description |
| ---- | ------ | -------- | -------------------- |
| 4 | int | zone_idx | Zone index to resize |
| 4 | int | new_size | New size of the zone |
## NET_PACKET_ID_RGBCONTROLLER_CLEARSEGMENTS
### Client Only [Size: 4]
The client uses this ID to call the ClearSegments() function of an RGBController device. The packet contains the index of the zone to clear segments on, type int (size 4). The `pkt_dev_idx` of this request's header indicates which controller you are calling ClearSegments() on.
## NET_PACKET_ID_RGBCONTROLLER_ADDSEGMENT
### Client Only [Size: Variable]
The client uses this ID to call the AddSegment() function of an RGBController device. The packet contains a data block. The format of the block is shown below. The `pkt_dev_idx` of this request's header indicates which controller you are calling AddSegment() on.
| Size | Format | Name | Description |
| ---------------- | ---------------------- | ---------------- | --------------------------------------------------------- |
| 4 | unsigned int | data_size | Size of all data in packet |
| 4 | unsigned int | zone_idx | Zone index to add segment to |
| Variable | Segment Data | segment | See [Segment Data](#segment-data) block format table. |
## NET_PACKET_ID_RGBCONTROLLER_UPDATELEDS
### Client Only [Size: Variable]
The client uses this ID to call the UpdateLEDs() function of an RGBController device. The packet data contains a data block. The format of the block is shown below. The `pkt_dev_idx` of this request's header indicates which controller you are calling UpdateLEDs() on.
| Size | Format | Name | Description |
| -------------- | -------------------- | ---------- | ----------------------------------- |
| 4 | unsigned int | data_size | Size of all data in packet |
| 2 | unsigned short | num_colors | Number of color values in packet |
| 4 * num_colors | RGBColor[num_colors] | led_color | Color values for each LED in device |
## NET_PACKET_ID_RGBCONTROLLER_UPDATEZONELEDS
### Client Only [Size: Variable]
The client uses this ID to call the UpdateZoneLEDs() function of an RGBController device. The packet data contains a data block. The format of the data block is shown below. The `pkt_dev_idx` of this request's header indicates which controller you are calling UpdateZoneLEDs() on.
| Size | Format | Name | Description |
| -------------- | -------------------- | ---------- | --------------------------------- |
| 4 | unsigned int | data_size | Size of all data in packet |
| 4 | unsigned int | zone_idx | Zone index to update |
| 2 | unsigned short | num_colors | Number of color values in packet |
| 4 * num_colors | RGBColor[num_colors] | led_color | Color values for each LED in zone |
## NET_PACKET_ID_RGBCONTROLLER_UPDATESINGLELED
### Client Only [Size: 8]
The client uses this ID to call the UpdateSingleLED() function of an RGBController device. The packet data contains a data block. The format of the data block is shown below. The `pkt_dev_idx` of this request's header indicates which controller you are calling UpdateSingleLED() on.
| Size | Format | Name | Description |
| ---- | -------- | --------- | ----------- |
| 4 | int | led_idx | LED index |
| 4 | RGBColor | led_color | LED color |
## NET_PACKET_ID_RGBCONTROLLER_SETCUSTOMMODE
### Client Only [Size: 0]
The client uses this ID to call the SetCustomMode() function of an RGBController device. The packet contains no data. The `pkt_dev_idx` of this request's header indicates which controller you are calling SetCustomMode() on.
## NET_PACKET_ID_RGBCONTROLLER_UPDATEMODE
### Client Only [Size: Variable]
The client uses this ID to call the UpdateMode() function of an RGBController device. The packet contains a data block. The format of the data block is shown below. The `pkt_dev_idx` of this request's header indicates which controller you are calling UpdateMode() on.
| Size | Format | Name | Protocol Version | Description |
| ------------------- | ------------------------- | ------------------- | ---------------- | ------------------------------------------------------ |
| 4 | unsigned int | data_size | 0 | Size of all data in packet |
| 4 | int | mode_idx | 0 | Mode index to update |
| Variable | Mode Data | mode | 0 | See [Mode Data](#mode-data) block format table. |
## NET_PACKET_ID_RGBCONTROLLER_SAVEMODE
### Client Only [Size: Variable]
The client uses this ID to call the SaveMode() function of an RGBController device. The packet contains a data block. The format of the data block is the same as for [NET_PACKET_ID_RGBCONTROLLER_UPDATEMODE](#net_packet_id_rgbcontroller_updatemode). The `pkt_dev_idx` of this request's header indicates which controller you are calling SaveMode() on.
Documentation/RGBControllerAPI.md
+325
View File
@@ -0,0 +1,325 @@
# RGBController API
Device support in OpenRGB can be broken down into three major components.
* Controller
* Detector
* RGBController
## **Controller**
A device's Controller class is a free-form class that provides whatever functionality is necessary to communicate with a device. This class should implement functions to send control packets to a device and receive information packets from a device. It should provide the capability to set device colors and modes. The Controller header file should provide defined constants for mode, speed, and other control values specific to the device's protocol. If possible, this class should provide the capability to retrieve firmware version and serial number information from the device. This class can also provide additional device protocol functionality even if it goes unused in OpenRGB currently. For instance, you may provide functions for controlling mouse DPI, polling rate, fan speed, or any other device-specific capability you want. If OpenRGB ever implements these extra functions in the future, having them implemented already in the Controller will make that easier.
The Controller class files are kept in the Controllers/ folder.
## **Detector**
A device's Detector function scans the system's interfaces to see if a particular device (Controller/RGBController) exists. Several types of detectors exist and are listed below. Each detector type is passed different arguments based on the interface it is detecting. The REGISTER_DETECTOR macros are used to register a detector function with the ResourceManager which is responsible for calling detector functions at detection time. Detector functions are then responsible for creating instances of Controllers and RGBControllers and registering them with the ResourceManager by calling the `ResourceManager::RegisterRGBController` interface.
HID Detectors
HID (Human Interface Device) is the most common interface for USB devices with RGB capabilities, especially for peripherals such as keyboards and mice. While it is usually used over USB, HID can also be used over Bluetooth. The `hidapi` library is used for interfacing with HID devices. The following detector formats can be registered:
```C++
REGISTER_HID_DETECTOR("HID Detector Name", DetectHIDDevicesFunction, HID_VID, HID_PID);
REGISTER_HID_DETECTOR_I("HID Detector Name", DetectHIDDevicesFunction, HID_VID, HID_PID, HID_INTERFACE);
REGISTER_HID_DETECTOR_IP("HID Detector Name", DetectHIDDevicesFunction, HID_VID, HID_PID, HID_INTERFACE, HID_PAGE);
REGISTER_HID_DETECTOR_IPU("HID Detector Name", DetectHIDDevicesFunction, HID_VID, HID_PID, HID_INTERFACE, HID_PAGE, HID_USAGE);
REGISTER_HID_DETECTOR_P("HID Detector Name", DetectHIDDevicesFunction, HID_VID, HID_PID, HID_PAGE);
REGISTER_HID_DETECTOR_PU("HID Detector Name", DetectHIDDevicesFunction, HID_VID, HID_PID, HID_PAGE, HID_USAGE);
```
The I/IP/IPU/P/PU variants add filtering for specific HID interfaces, pages, and usages as many HID devices expose multiple interfaces and not all are used for RGB control.
I2C/SMBus Detectors
I2C (Inter-Integrated Circuit), or SMBus (System Management Bus, a compatible subset of I2C), is the second most common interface used by RGB devices and is used for on-board RGB on certrain motherboards, most graphics cards, and all RAM modules. Each I2C device has a 7-bit address. As I2C does not offer a standardized means of identifying a device on the bus, we have several different options for detecting I2C devices that can narrow down the search to a specific I2C bus.
```C++
REGISTER_I2C_DETECTOR("I2C Detector Name", DetectI2CDevicesFunction);
REGISTER_I2C_DIMM_DETECTOR("I2C Detector Name", DetectI2CDevicesFunction, JEDEC_ID, DIMM_TYPE);
REGISTER_I2C_PCI_DETECTOR("I2C Detector Name", DetectI2CDevicesFunction, PCI_VEN, PCI_DEV, PCI_SUBVEN, PCI_SUBDEV, I2C_ADDR);
```
The standard version of the I2C detector calls the detector function with a vector of all available I2C buses. The detector can then perform any chip specific detection necessary to determine if the device exists on any of the given buses. Only use this version of the detector if the DIMM or PCI variants are not suitable for your device. There are additional macros that can be used to narrow down I2C bus detection such as `IF_MOBO_SMBUS` for motherboard buses and `IF_DRAM_SMBUS` for DRAM buses.
The DIMM version of the detector can be used to filter for specific DRAM modules using SPD information. Only the I2C bus for the DRAM will be provided and the detector will only be called if the JEDEC ID and DIMM type match.
The PCI version of the detector can be used to filter for I2C devices on specific PCI cards, usually graphics cards. The detector will only be called for I2C buses with matching PCI IDs. The detector can also provide a specific address, though it is possible for the detector function to ignore this address if more complex address determination is needed.
Generic Detectors
The generic detector type is used for any device that doesn't fit into one of the previous detection types. This detector is frequently used for manually configured devices such as network and serial port devices. It is also used for USB devices that cannot be accessed via `hidapi` or serial and instead requiring direct USB access via `libusb`.
```C++
REGISTER_DETECTOR("Generic Detector Name", DetectDevicesFunction);
```
The Detector files are kept in the Controllers/ folder.
## **RGBController**
OpenRGB uses an internal API called RGBController to standardize the interface to RGB devices from multiple vendors and categories. This API uses vectors to describe each device. This API is implemented as an RGBController class that is inherited by each implementation, for example the RGBController_CorsairPeripheral is defined like so:
```C++
#include "RGBController.h"
class RGBController_CorsairPeripheral : public RGBController
{
```
The RGBController files for a controller implementation are kept in the Controllers/ folder alongside the Controller and Detector files.
The RGBController class specification contains the following:
* Device Name
* Device Vendor
* Device Description
* Device Version
* Device Serial
* Device Location
* Vector of LEDs
* Vector of Zones
* Vector of Modes
* Vector of Colors (32-bit 0x00BBGGRR format)
* Device Type (enum)
* Active mode index
* Vector of LED Alternate Names
* Controller Flags
### Device Types
| Value | Description |
| ----- | ------------- |
| 0 | Motherboard |
| 1 | DRAM |
| 2 | GPU |
| 3 | Cooler |
| 4 | LED Strip |
| 5 | Keyboard |
| 6 | Mouse |
| 7 | Mousemat |
| 8 | Headset |
| 9 | Headset Stand |
| 10 | Gamepad |
| 11 | Light |
| 12 | Speaker |
| 13 | Virtual |
| 14 | Storage |
| 15 | Case |
| 16 | Microphone |
| 17 | Accessory |
| 18 | Keypad |
| 19 | Laptop |
| 20 | Monitor |
| 21 | Unknown |
Additional device types may be added in the future. They are added after the last known device type. Anything out of range should be considered Unknown.
### Controller Flags
| Controller Flags Bit | Name | Description |
| -------------------- | ------- | --------------------------------------------------- |
| 0 | Local | Controller is provided by this OpenRGB instance |
| 1 | Remote | Controller is provided by a remote OpenRGB instance |
| 2 | Virtual | Controller is virtual (not a physical device) |
### LED Alternate Names
The LED Altrernate Names vector can override the base name of an LED. The intended use case for this field is providing regional key names for non-English keyboard layouts. The base key names should always be provided in English QWERYY layout for positional mapping to work on certain SDK applications, so the alternate names field can override the base name to provide the correct key name for the localized layout without disrupting SDK application mapping. If not overriding any LED names, this vector can be left empty. If only overriding certain LED names, those not being overridden can be empty strings. If used, the length of this vector must equal the length of the LEDs vector.
## LEDs
The LED structure contains information about an LED.
* LED Name
* LED Value
The Value has no defined functionality in the RGBController API and is provided for implementation-specific use. You can use this field to associate implementation-specific data with an LED.
## Zones
The Zone structure contains information about a zone. A zone is a logical grouping of LEDs defined by the RGBController implementation. LEDs in a zone must be contiguous in the RGBController's LEDs/Colors vectors.
* Zone Name
* Zone Type
* LED pointer
* Color pointer
* Start Index
* LED Count
* Minimum number of LEDs
* Maximum number of LEDs
* Matrix map pointer
* Vector of segments
* Zone Flags
The LED pointer and Color pointer point to the first LED/Color in the RGBController's LEDs/Colors vector associated with this zone. The Start Index is the index to the same LED/Color in the vectors.
The LED count is the number of LEDs in the zone. For zones with a fixed number of LEDs, the count, min, and max values should all be equal. For zones with a user-adjustable number of LEDs, the count should be between the min and max values, inclusively. User-adjustable zones are most commonly used to represent addressable RGB (ARGB) controllers as the number of LEDs depends on what strips/devices are attached to the ARGB headers. The ResizeZone function in the RGBController API is used to resize the number of LEDs in the zone. The initial value should be zero for ARGB zones if the device does not provide a means to automatically determint the number of connected LEDs.
### Zone Types
The zone type enum defines the zone type. This describes the physical layout of the zone and can be used by software to generate appropriate effects for the zone.
| Zone Type Value | Description |
| --------------- | ----------- |
| 0 | Single |
| 1 | Linear (1D) |
| 2 | Matrix (2D) |
### Matrix Map
Each zone has a matrix map pointer which allows an optional matrix map to be associated with the zone. The matrix map is used to provide positioning information about LEDs in a 2D grid. If a matrix map is not provided for a zone, the zone's matrix map pointer must be set to NULL.
A matrix map has the following:
* Height
* Width
* Map data pointer
The height and width determine the size of the map data. The map data pointer should point to a data block of (Height * Width) unsigned 32-bit integers. This data can be accessed as if it were a Map[Y][X] 2D array. The values of the map are LED index values in the zone (so offset by Start Index from the RGBController's LEDs vector). If a spot in the matrix is unused and does not map to an LED, it should be set to 0xFFFFFFFF.
### Segments
Each Zone contains a vector of Segments. Segments can be used to divide a physical zone (such as an ARGB header) into multiple logical sub-zones, or segments. This is mainly used for ARGB zones with multiple components daisy-chained together. For example, segments can be used to group multiple rings on an ARGB fan or multiple daisy-chained fans connected to one header. If the device is capable of automatically detecting multiple components connected to a single output, the RGBController may create segments automatically during zone creation. Otherwise, leaving this vector empty will indicate that the zone contains no segments, though resizable zones allow the user to define their own segments.
A segment contains the following:
* Segment Name
* Segment Type (See Zone Type values)
* Start Index
* LED Count
The Start Index is the index within the Zone where the Segment starts. The LED Count is the number of LEDs in the Segment. Care should be taken to ensure that the total number of LEDs across all segments equals the number of LEDs in the Zone and the start indices do not overlap.
### Zone Flags
The Zone Flags field is a bitfield with informational flags related to the Zone.
| Zone Flags Bit | Name | Description |
| -------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| 0 | Resize Effects Only | This zone is resizable, but the size is only used for effects modes. The zone is treated as a single LED in the Colors vector for per-LED modes |
## Modes
Modes represent internal effects and have a name field that describes the effect. The mode's index in the vector is its ID. The Active Mode variable in the RGBController class specifies which mode is currently selected. A mode contains the following:
* Mode Name
* Mode Value
* Mode Flags
* Minimum Speed
* Maximum Speed
* Minimum number of colors
* Maximum number of colors
* Speed Value
* Direction
* Color Mode
* Colors Vector
The mode value is field is provided to hold an implementation-defined mode value. This is usually the mode's value in the hardware protocol.
The mode flags field is a bitfield that contains information about what features a mode has.
| Mode Flags Bit | Description |
| -------------- | ------------------------------------------------ |
| 0 | Mode has speed parameter |
| 1 | Mode has left/right direction parameter |
| 2 | Mode has up/down direction parameter |
| 3 | Mode has horizontal/vertical direction parameter |
| 4 | Mode has brightness parameter |
| 5 | Mode has per-LED color settings |
| 6 | Mode has mode specific color settings |
| 7 | Mode has random color option |
The mode minimum and maximum speed fields should be set to the implementation-specific minimum and maximum speed values for the given mode if the mode supports speed control. The mode speed value field will be set between the minimum and maximum value, inclusively. The minimum speed may be a greater numerical value than the maximum speed if your device's speed adjustment is inverted (usually because the device takes a delay period rather than a speed value).
The mode minimum and maximum number of colors fields should be used if the mode supports mode-specific color settings. These determine the size range of the mode's Colors vector. If the mode has a fixed number of colors, the minimum and maximum should be equal. Mode-specific colors are used when a mode has one or more configurable colors but these colors do not apply directly to individual LEDs. Example would be a breathing mode that cycles between one or more colors each breath pulse. A mode may have multiple color options available, for instance a breathing mode that can either use one or more defined colors or just cycle through random colors. The available color modes for a given mode are set with the flags. The selected color mode is set using the color mode field, which can be one of the following values.
| Color Mode Value | Description |
| ---------------- | ------------------------------------------------------------------------------------------------- |
| 0 | None - this mode does not have configurable colors |
| 1 | Per-LED - this mode uses the RGBController's colors vector to set each LED to its specified color |
| 2 | Mode Specific - this mode has one or more configurable colors, but not individual LED control |
| 3 | Random - this mode can be switched to a random or cycling color palette |
## Functions
### `std::string GetName()`
Returns the `name` string of the device.
### `std::string GetVendor()`
Returns the `vendor` string of the device.
### `std::string GetDescription()`
Returns the `description` string of the device.
### `std::string GetVersion()`
Returns the `version` string of the device.
### `std::string GetSerial()`
Returns the `serial` string of the device.
### `std::string GetLocation()`
Returns the `location` string of the device.
### `std::string GetModeName(int mode)`
Returns the `name` string of the given mode in the `modes` vector.
### `std::string GetZoneName(int zone)`
Returns the `name` string of the given zone in the `zones` vector.
### `std::string GetLEDName(int led)`
Returns the `name` string of the given LED in the `leds` vector.
### `RGBColor GetLED(unsigned int led)`
Returns the color value of the given LED in the `colors` vector.
### `void SetLED(unsigned int led, RGBColor color)`
Sets the color value of the given LED in the `colors` vector.
### `void SetAllLEDs(RGBColor color)`
Sets the color value of all LEDs in the `colors` vector.
### `void SetAllZoneLEDs(int zone, RGBColor color)`
Sets the color value of all LEDs in the given zone in the `colors` vector.
### `int GetMode()`
Returns the active mode index of the device. The returned int should line up with the `modes` vector.
### `void SetMode(int mode)`
Sets the active mode index of the device. The mode should be the index in the `modes` vector of the mode you wish to set.
### `void SetCustomMode()`
When called, the device should be put into its software-controlled mode. This differs between devices, but generally devices have a direct control or static effect mode. Ideally, this mode should not save to the device's internal Flash. This function sets up a device for software effect control.
### `void UpdateLEDs()`
Update all LEDs based on the `colors` vector.
### `void UpdateZoneLEDs(int zone)`
Update all LEDs in the given zone based on the `colors` vector.
### `void UpdateSingleLED(int led)`
Update a single LED based on the `colors` vector.
### `void UpdateMode()`
Update the mode based on the active mode index and the `modes` vector.
Documentation/SMBusAccess.md
+49
View File
@@ -0,0 +1,49 @@
# SMBus Access
This document details the process to set up SMBus/I2C access on supported operating systems.
SMBus, or [System Management Bus](https://en.wikipedia.org/wiki/System_Management_Bus), is a low-level interface present on most PC motherboards. Some RGB control devices are attached via SMBus. These include all DDR4 and DDR5 RAM modules with integrated RGB lighting as well as the onboard lighting on several motherboards, mostly from the X370/Z270 and X470/Z370 generations.
If you are not using RGB RAM and you are not using a motherboard from the X370/Z270 or X470/Z370 generation you can skip these steps and ignore the SMBus warning if it appears.
SMBus is generally not meant to be accessed by user applications, but RGB software creates an exception to this rule. This means that some steps may be necessary to allow OpenRGB permission to access the SMBus interface. These steps are listed below.
## Windows
* On Windows, OpenRGB uses the [PawnIO](https://pawnio.eu/) driver to access the SMBus interface. You must install PawnIO by downloading and running its installer prior to using OpenRGB.
* **You must run the application as Administrator in order for PawnIO to be able to access SMBus. OpenRGB may be installed as a background service that runs with Administrator permissions.**
* Early versions of OpenRGB used [WinRing0](https://github.com/GermanAizek/WinRing0) and even earlier versions used [InpOut32](https://www.highrez.co.uk/downloads/inpout32/). These drivers are no longer used and should be removed to avoid warnings by anti-cheat and anti-virus software. You can uninstall Inpout32 by following the instructions [here](https://gitlab.com/CalcProgrammer1/OpenRGB/-/issues/669#note_461054255).
## Linux
1. Install the `i2c-tools` package.
2. Load the i2c-dev module: `sudo modprobe i2c-dev`
3. Load the i2c driver for your chipset:
* Intel
* `sudo modprobe i2c-i801`
* AMD
* `sudo modprobe i2c-piix4`
* Nuvoton
* This interface is used alongside `i2c-i801` on some older ASUS Intel motherboards for the on-board lighting.
* `sudo modprobe i2c-nct6793`
* Note: The i2c-nct6793 driver must be installed separately, see [i2c-nct6793-dkms](https://gitlab.com/CalcProgrammer1/i2c-nct6793-dkms)
* If you want the i2c modules to load automatically at boot, run the following:
1. `sudo touch /etc/modules-load.d/i2c.conf`
2. `sudo sh -c 'echo "i2c-dev" >> /etc/modules-load.d/i2c.conf'`
3. Run the following based on which i2c drivers you loaded in the previous section:
* `sudo sh -c 'echo "i2c-i801" >> /etc/modules-load.d/i2c.conf'`
* `sudo sh -c 'echo "i2c-piix4" >> /etc/modules-load.d/i2c.conf'`
* You will have to enable user access to the i2c devices if you don't run OpenRGB as root.
1. List all SMBus controllers: `sudo i2cdetect -l`
2. Note the number(s) for piix4 or i801 controllers.
3. Give user access to those controllers. If you have not installed OpenRGB from a distribution package then most likely you need to install the udev rules manually.
* Some Gigabyte/Aorus motherboards have an ACPI conflict with the SMBus controller. You can bypass this conflict by adding the `acpi_enforce_resources=lax` kernel parameter to your kernel command line. See the [Kernel Parameters](Documentation/KernelParameters.md) page for more information.
* The [spd5118 kernel driver](https://docs.kernel.org/hwmon/spd5118.html) can claim certain I2C addresses for Kingston Fury DDR5 memory and thus prevent other kernel modules from accessing them. This is the case if the `i2cdetect` command prints the character string `UU` on the I2C bus responsible for the DRAM. A solution to this problem is to unload the `spd5118` kernel driver using `rmmod spd5118`.
## MacOS
* For Intel devices using a controller in the i801 family you have to download and install the [macUSPCIO driver](https://github.com/ShadyNawara/macUSPCIO/releases)
Documentation/USBAccess.md
+23
View File
@@ -0,0 +1,23 @@
# USB Access
This document details the process to set up USB access on supported operating systems.
USB, or [Universal Serial Bus](https://en.wikipedia.org/wiki/USB) is the most common interface used to connect RGB devices to a PC. It can be used both externally, where a device has a cable which plugs into a USB port or motherboard header, or internally, where a device such as an RGB controller chip built into a motherboard is wired directly to the processor or chipset's USB interface.
USB access permissions vary based on the type of device and the operating system. Some steps may be necessary to allow OpenRGB permission to access these devices.
## Windows
* Windows should not need any special setup to access USB devices.
* If a device does not get detected, try running OpenRGB as Administrator.
* Early versions of OpenRGB used the WinUSB driver, installed using Zadig. This is no longer required, and you need to uninstall the WinUSB driver if you previously installed it. You can uninstall the WinUSB driver by following [this guide](https://gitlab.com/CalcProgrammer1/OpenRGB/-/wikis/Frequently-Asked-Questions#i-installed-the-winusb-driver-for-a-device-and-i-wish-to-uninstall-it).
## Linux
* USB devices require [udev rules](/Documentation/UdevRules.md) 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.
## MacOS
* USB devices may require the Input Monitoring permission. You can add OpenRGB in System Preferences > Security & Privacy > Privacy.
Documentation/UdevRules.md
+16
View File
@@ -0,0 +1,16 @@
# Udev Rules
On Linux, OpenRGB provides a udev rules file to configure access permissions to supported devices.
If you install OpenRGB through a distribution-specific package, whether provided by your distribution's official repositories, from packages downloaded from OpenRGB's website or GitLab CI, or from building packages yourself, the udev rules should be installed as part of that package. You should not need to manually install them.
If you are using OpenRGB compiled from source (not as part of a package), using OpenRGB as an AppImage, or using OpenRGB from Flatpak, you will need to install the udev rules manually.
## Installation
* If you have installed OpenRGB from a package then latest udev rules are installed locally at `/usr/lib/udev/rules.d/60-openrgb.rules`
* 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+amd64+AppImage&inline=false) from Gitlab.
- Copy this 60-openrgb.rules file to `/usr/lib/udev/rules.d/` or to `/etc/udev/rules.d/` if you're on an immutable system.
- Then reload rules with `sudo udevadm control --reload-rules && sudo udevadm trigger`
* There is also a [udev rules installation script available at openrgb.org](https://openrgb.org/udev.html).