OpenRGB SDK Documentation
August 29, 2026 ยท View on GitHub
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 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.0rc1 | Add zone flags, controller flags, effects-only zones, alternative LED names, add ClearSegments and AddSegments |
| 6* | 1.0 | Add matrix map segments, per-zone modes, remote SettingsManager and ProfileManager, update callbacks |
* 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_id | Device ID |
| 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_id: 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.
* 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.
Device IDs
The OpenRGB SDK is used to allow a client to access one or more RGBControllers on the server. As there are usually more than one controllers on the server, an identifier is needed to specify which controller the client wants to access. The pkt_dev_id field in the header is used for this purpose. Originally, OpenRGB used a simple indexing scheme, where the value of pkt_dev_id is the index in the server's controllers list. Starting with protocol version 6, however, OpenRGB switched to using a unique ID scheme, where each controller detected on the server is assigned a unique ID and then the server sends a list of these unique IDs to the client. If the list changes, the IDs of any existing controllers stay the same but new controllers have new unique IDs, allowing the client to keep track of which controllers stayed the same and which have changed. The control flow for both schemes is described below.
Protocol versions 0-5 (indexed IDs)
In this scheme, the client starts by sending NET_PACKET_ID_REQUEST_CONTROLLER_COUNT to the server, which returns the count of controllers in the list. The client then sends NET_PACKET_ID_REQUEST_CONTROLLER_DATA with pkt_dev_id for each controller index 0 to [count - 1], waiting for each controller data response before moving on to the next controller. Following this, any accesses to the controllers use the index for the pkt_dev_id field of any NET_PACKET_ID_RGBCONTROLLER packet. If the device list changes (indicated by the server sending NET_PACKET_ID_DEVICE_LIST_UPDATED), the indexes on the client side may no longer match those on the server side. The client must immediately stop using the existing indexes, clear its list of controllers, and obtain the new list by performing this sequence again.
Protocol versions 6 and above (unique IDs)
In this scheme, the client starts by sending NET_PACKET_ID_REQUEST_CONTROLLER_COUNT to the server, which returns both the count of controllers in the list as well as a list of unique 32-bit IDs. Each unique ID represents one controller in the server's list. The order of these unique IDs also matches the order of controllers in the server's list. The client then sends NET_PACKET_ID_REQUEST_CONTROLLER_DATA with pkt_dev_id for each unique ID in the list, waiting for each controller data response before moving on to the next controller. Following this, any accesses to the controllers use the unique ID for the pkt_dev_id field of any NET_PACKET_ID_RGBCONTROLLER packet. If the device list changes (indicated by the server sending NET_PACKET_ID_DEVICE_LIST_UPDATED), the client must request a new list of unique IDs by sending NET_PACKET_ID_REQUEST_CONTROLLER_COUNT again. Once the response is received, the client should compare the new list of unique IDs against its existing list. Unique IDs that were in its existing list that no longer exist in the new list should be deleted on the client as these controllers are no longer present. Unique IDs that exist in the new list but did not exist in the existing list are newly added controllers and the client should request these by sending NET_PACKET_ID_REQUEST_CONTROLLER_DATA with pkt_dev_id for each newly added unique ID, waiting for each controller data response before moving on to the next controller. Unique IDs that are present in the existing list as well as the new list are controllers that have not changed on the server side, so the client does not need to re-request these controllers and can continue using them as is.
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 [Protocol 0-5 Size: 4] [Protocol 6+ Size: 4 + (4 * number of controllers)]
The server responds to this request with the number of controllers in the device list. For protocol versions below 6, the response contains a single unsigned int, size 4, holding this value.
For protocol versions 6 and above, the response contains a single unsigned int, size 4, holding this value followed by a list of unsigned ints, each size 4, representing the unique IDs of each controller in the device list. See the Device IDs section for more information.
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_id of this request's header indicates which controller you are requesting data for. See the Device IDs section for more information.
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 |
| Variable | Device Data | device_data | 0 | See Device Data block format table |
Device Data
The Device Data block represents an entire RGBController. This data block is provided by RGBController::GetDeviceDescriptionData(). Portions of this block are omitted if the requested protocol level is below the listed value.
| Size | Format | Name | Protocol Version | Description |
|---|---|---|---|---|
| 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 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 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 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_display_names | 5 | Number of LED alternate name strings |
| Variable | LED Display Name[num_led_display_names] | led_display_names | 5 | See LED Display Name Data block format table. Repeat num_led_display_names times |
| 4 | unsigned int | flags | 5 | RGBController flags field value |
| 2 | unsigned short | display_name_len | 6 | Length of RGBController display name field string, including null termination |
| display_name_len | char[display_name_len] | display_name | 6 | RGBController display name field string value, including null termination |
| 4 | unsigned int | configuration_len | 6 | Length of RGBController configuration field string, including null termination |
| configuration_len | char[configuration_len] | configuration | 6 | RGBController configuration field string value, including null termination |
Mode Data
The Mode Data block represents one entry in the RGBController::modes vector. This data block is provided by RGBController::GetModeDescriptionData(). 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 | <6* | 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 |
* The mode_value field was removed starting with protocol version 6. This is an internal-use-only field that does not need to be exposed to clients. For protocol versions 5 and below, the client must track the mode_value received from the server and send it back as part of the UpdateMode/SaveMode packets.
Zone Data
The Zone Data block represents one entry in the RGBController::zones vector. This data block is provided by RGBController::GetZoneDescriptionData(). 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 | 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 map length if matrix_map exists, otherwise 0 if matrix_map NULL |
| zone_matrix_len | Matrix Map Data | zone_matrix_map | 0 | See Matrix Map Data block format table, 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 block format table. Repeat num_segments times |
| 4 | unsigned int | zone_flags | 5 | Zone flags value |
| 4 | int | zone_active_mode | 6 | Zone active_mode field value |
| 2 | unsigned short | zone_num_modes | 6 | Number of modes in zone |
| Variable | Mode Data[zone_num_modes] | zone_modes | 6 | See Mode Data block format table. Repeat zone_num_modes times |
| 2 | unsigned short | zone_display_name_len | 6 | Length of zone display name string, including null termination |
| zone_display_name_len | char[zone_display_name_len] | zone_display_name | 6 | Zone display name string value, including null termination |
Segment Data
The Segment Data block represents one entry in the RGBController::zones::segments vector. This data block is provided by RGBController::GetSegmentDescriptionData(). 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 | 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 |
| 2 | unsigned short | segment_matrix_len | 6 | Segment matrix map length if matrix_map exists, otherwise 0 if matrix_map NULL |
| segment_matrix_len | Matrix Map Data | segment_matrix_map | 6 | See Matrix Map Data block format table, only if matrix_map exists. |
| 4 | unsigned int | segment_flags | 6 | Segment flags value |
Matrix Map Data
The Matrix Map Data block represents the matrix_map_type type. This data block is provided by RGBController::GetMatrixMapDescriptionData(). Portions of this block are omitted if the requested protocol level is below the listed value.
| Size | Format | Name | Protocol Version | Description |
|---|---|---|---|---|
| 4 | unsigned int | matrix_map_height | 0 | Matrix_map height |
| 4 | unsigned int | matrix_map_width | 0 | Matrix_map width |
| (zone_matrix_len - 8)* | unsigned int[matrix_map_height * matrix_map_width] | matrix_map_data | 0 | Matrix_map data |
LED Data
The LED Data block represents one entry in the RGBController::leds vector. This data block is provided by RGBController::GetLEDDescriptionData(). 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 | 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 | <6* | LED value field value |
* The led_value field was removed starting with protocol version 6. This is an internal-use-only field that does not need to be exposed to clients.
LED Display Name Data
The LED Display Name Data block represents one entry in the RGBController::led_display_names vector. This data block was introduced in protocol version 5.
| Size | Format | Name | Protocol Version | Description |
|---|---|---|---|---|
| 2 | unsigned short | led_display_name_len | 5 | Length of LED display name string, including null termination |
| led_display_name_len | char[led_display_name_len] | led_display_name | 5 | LED display 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_ACK
Acknowledgement [Size: 8]
This packet is sent by the server to acknowledge any packet sent by the client. The ACK contains two unsigned 32-bit integer values, the first being the packet ID of the packet being acknowledged and the second being a status code. The pkt_dev_id field of the header is also set to the pkt_dev_id of the packet being acknowledged.
The status codes are shown below.
| Status Code | Name | Description |
|---|---|---|
| 0 | NET_PACKET_STATUS_OK | OK/Success |
| 1 | NET_PACKET_STATUS_ERROR_GENERIC | Generic error |
| 2 | NET_PACKET_STATUS_ERROR_UNSUPPORTED | Unsupported error |
| 3 | NET_PACKET_STATUS_ERROR_NOT_ALLOWED | Not allowed error |
| 4 | NET_PACKET_STATUS_ERROR_INVALID_ID | Invalid device ID or index error |
| 5 | NET_PACKET_STATUS_ERROR_INVALID_DATA | Invalid data error |
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_SET_SERVER_NAME
Server Only [Size: Variable]
The server uses this ID to send the server's null-terminated name string to the client. 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_SET_CLIENT_FLAGS
Client Only [Size: 4]
The client uses this ID to send the client's flags value to the server. The client sets the NET_CLIENT_FLAG_REQUEST_LOCAL_CLIENT flag if it wants to request local client status. The server responds in NET_PACKET_ID_SET_SERVER_FLAGS whether it was granted or not.
| Bit | Flag Name | Flag Description |
|---|---|---|
| 0 | NET_CLIENT_FLAG_SUPPORTS_RGBCONTROLLER | Client supports RGBController API |
| 1 | NET_CLIENT_FLAG_SUPPORTS_LOGMANAGER | Client supports LogManager API |
| 2 | NET_CLIENT_FLAG_SUPPORTS_PROFILEMANAGER | Client supports ProfileManager API |
| 3 | NET_CLIENT_FLAG_SUPPORTS_PLUGINMANAGER | Client supports PluginManager API |
| 4 | NET_CLIENT_FLAG_SUPPORTS_SETTINGSMANAGER | Client supports SettingsManager API |
| 16 | NET_CLIENT_FLAG_REQUEST_LOCAL_CLIENT | Request local client |
NET_PACKET_ID_SET_SERVER_FLAGS
Server Only [Size: 4]
The server uses this ID to send the server's flags value to the client. The server sets the NET_SERVER_FLAG_LOCAL_CLIENT flag to grant the connected client local client status. The server will only set NET_SERVER_FLAG_LOCAL_CLIENT if the client requested local client status with NET_CLIENT_FLAG_REQUEST_LOCAL_CLIENT and the client is connected from the localhost address.
| Bit | Flag Name | Flag Description |
|---|---|---|
| 0 | NET_SERVER_FLAG_SUPPORTS_RGBCONTROLLER | Server supports RGBController API |
| 1 | NET_SERVER_FLAG_SUPPORTS_LOGMANAGER | Server supports LogManager API |
| 2 | NET_SERVER_FLAG_SUPPORTS_PROFILEMANAGER | Server supports ProfileManager API |
| 3 | NET_SERVER_FLAG_SUPPORTS_PLUGINMANAGER | Server supports PluginManager API |
| 4 | NET_SERVER_FLAG_SUPPORTS_SETTINGSMANAGER | Server supports SettingsManager API |
| 5 | NET_SERVER_FLAG_SUPPORTS_DETECTION | Server supports detection functions |
| 6 | NET_SERVER_FLAG_SUPPORTS_DEVICE_INFO | Server supports device info functions |
| 16 | NET_SERVER_FLAG_LOCAL_CLIENT | Confirm that client is local client |
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_DETECTION_STARTED
Server Only [Size: 0]
The server uses this ID to notifiy a client that the server's detection process has started.
NET_PACKET_ID_DETECTION_PROGRESS_CHANGED
Server Only [Size: Variable]
The server uses this ID to notify a client that the server's detection progress has changed. The format of the block is shown below.
| Size | Format | Name | Protocol Version | Description |
|---|---|---|---|---|
| 4 | unsigned int | data_size | 6 | Size of all data in packet |
| 4 | unsigned int | detection_percent | 6 | Detection percent |
| 2 | unsigned short | string_length | 6 | Length of detection string, including null termination |
| Variable | char[string_length] | detection_string | 6 | Detection string value, including null termination |
NET_PACKET_ID_DETECTION_COMPLETE
Server Only [Size: 0]
The server uses this ID to notify a client that the server's detection process has completed.
NET_PACKET_ID_GET_I2C_BUS_INFO
Request [Size: 0]
The client uses this ID to request a list of I2C bus info from the server. The request contains no data. This request should only be used if the server sets the NET_SERVER_FLAG_SUPPORTS_DEVICE_INFO flag.
Response [Size: Variable]
The server responds with a data block containing I2C bus information.
| Size | Format | Name | Protocol Version | Description |
|---|---|---|---|---|
| 4 | unsigned int | data_size | 6 | Size of all data in packet |
| 2 | unsigned short | bus_count | 6 | Number of I2C bus entries |
| Variable | i2c_smbus_info[bus_count] | bus_info | 6 | I2C bus info data, each entry is the fixed-size i2c_smbus_info struct |
NET_PACKET_ID_GET_HID_DEVICE_INFO
Request [Size: 0]
The client uses this ID to request a list of HID device info from the server. The request contains no data. This request should only be used if the server sets the NET_SERVER_FLAG_SUPPORTS_DEVICE_INFO flag.
Response [Size: Variable]
The server responds with a data block containing HID device information.
| Size | Format | Name | Protocol Version | Description |
|---|---|---|---|---|
| 4 | unsigned int | data_size | 6 | Size of all data in packet |
| 2 | unsigned short | device_count | 6 | Number of HID device entries |
| Variable | HID Device Data[device_count] | device_data | 6 | See HID Device Data block format table. Repeat device_count times |
HID Device Data
| Size | Format | Name | Protocol Version | Description |
|---|---|---|---|---|
| 2 | unsigned short | vendor_id | 6 | HID vendor ID |
| 2 | unsigned short | product_id | 6 | HID product ID |
| 2 | unsigned short | release_number | 6 | HID release number |
| 2 | unsigned short | usage_page | 6 | HID usage page |
| 2 | unsigned short | usage | 6 | HID usage |
| 4 | int | interface_number | 6 | HID interface number |
| 2 | unsigned short | serial_number_size | 6 | Length of serial number string, including null termination |
| serial_number_size | char[serial_number_size] | serial_number | 6 | Serial number string value, including null termination |
| 2 | unsigned short | manufacturer_size | 6 | Length of manufacturer string, including null termination |
| manufacturer_size | char[manufacturer_size] | manufacturer_string | 6 | Manufacturer string value, including null termination |
| 2 | unsigned short | product_string_size | 6 | Length of product string, including null termination |
| product_string_size | char[product_string_size] | product_string | 6 | Product string value, including null termination |
| 2 | unsigned short | path_size | 6 | Length of path string, including null termination |
| path_size | char[path_size] | path | 6 | Path string value, including null termination |
NET_PACKET_ID_GET_USB_DEVICE_INFO
Request [Size: 0]
The client uses this ID to request a list of USB device info from the server. The request contains no data. This request should only be used if the server sets the NET_SERVER_FLAG_SUPPORTS_DEVICE_INFO flag.
Response [Size: Variable]
The server responds with a data block containing USB device information.
| Size | Format | Name | Protocol Version | Description |
|---|---|---|---|---|
| 4 | unsigned int | data_size | 6 | Size of all data in packet |
| 2 | unsigned short | device_count | 6 | Number of USB device entries |
| Variable | USB Device Data[device_count] | device_data | 6 | See USB Device Data block format table. Repeat device_count times |
USB Device Data
| Size | Format | Name | Protocol Version | Description |
|---|---|---|---|---|
| 2 | unsigned short | vendor_id | 6 | USB vendor ID |
| 2 | unsigned short | product_id | 6 | USB product ID |
| 2 | unsigned short | serial_number_size | 6 | Length of serial number string, including null termination |
| serial_number_size | char[serial_number_size] | serial_number | 6 | Serial number string value, including null termination |
| 2 | unsigned short | manufacturer_size | 6 | Length of manufacturer string, including null termination |
| manufacturer_size | char[manufacturer_size] | manufacturer_string | 6 | Manufacturer string value, including null termination |
| 2 | unsigned short | product_string_size | 6 | Length of product string, including null termination |
| product_string_size | char[product_string_size] | product_string | 6 | Product string value, including null termination |
NET_PACKET_ID_GET_SERIAL_PORTS
Request [Size: 0]
The client uses this ID to request a list of serial ports from the server. The request contains no data. This request should only be used if the server sets the NET_SERVER_FLAG_SUPPORTS_DEVICE_INFO flag.
Response [Size: Variable]
The server responds with a data block containing serial port information.
| Size | Format | Name | Protocol Version | Description |
|---|---|---|---|---|
| 4 | unsigned int | data_size | 6 | Size of all data in packet |
| 2 | unsigned short | port_count | 6 | Number of serial port entries |
| Variable | Serial Port Data[port_count] | port_data | 6 | See Serial Port Data block format table. Repeat port_count times |
Serial Port Data
| Size | Format | Name | Protocol Version | Description |
|---|---|---|---|---|
| 2 | unsigned short | port_string_size | 6 | Length of port string, including null termination |
| port_string_size | char[port_string_size] | port_string | 6 | Port string value, including null termination |
NET_PACKET_ID_GET_USB_SERIAL_PORTS
Request [Size: 0]
The client uses this ID to request a list of USB serial port device info from the server. The request contains no data. This request should only be used if the server sets the NET_SERVER_FLAG_SUPPORTS_DEVICE_INFO flag.
Response [Size: Variable]
The server responds with a data block containing USB serial port information.
| Size | Format | Name | Protocol Version | Description |
|---|---|---|---|---|
| 4 | unsigned int | data_size | 6 | Size of all data in packet |
| 2 | unsigned short | port_count | 6 | Number of USB serial port entries |
| Variable | Serial Port Data[port_count] | port_data | 6 | See Serial Port Data block format table. Repeat port_count times |
USB Serial Port Data
| Size | Format | Name | Protocol Version | Description |
|---|---|---|---|---|
| 2 | unsigned short | vendor_id | 6 | USB vendor ID |
| 2 | unsigned short | product_id | 6 | USB product ID |
| 2 | unsigned short | port_path_size | 6 | Length of port path string, including null termination |
| port_path_size | char[port_path_size] | port_path | 6 | Port path string value, including null termination |
| 2 | unsigned short | usb_path_size | 6 | Length of port path string, including null termination |
| usb_path_size | char[usb_path_size] | usb_path | 6 | USB path string value, including null termination |
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_PROFILEMANAGER_GET_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 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_PROFILEMANAGER_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.
This packet requires local client status.
There is no response from the server for this packet.
NET_PACKET_ID_PROFILEMANAGER_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.
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_PROFILEMANAGER_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.
This packet requires local client status.
There is no response from the server for this packet.
NET_PACKET_ID_PROFILEMANAGER_UPLOAD_PROFILE
Client Only [Size: Variable]
The client uses this ID to upload a JSON-formatted profile to the server. The JSON data is sent 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.
This packet requires local client status.
NET_PACKET_ID_PROFILEMANAGER_DOWNLOAD_PROFILE
Request [Size: Variable]
The client uses this ID to download a JSON-formatted profile from the server. The name of the profile to download is sent 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.
Response [Size: Variable]
The server responds to this request with the JSON-formatted profile. The JSON data is sent 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.
NET_PACKET_ID_PROFILEMANAGER_GET_ACTIVE_PROFILE
Request [Size: 0]
The client uses this ID to request the name of the active profile from the server. The request contains no data.
Response [Size: Variable]
The server responds to this request with the name of the active profile or an empty string if no profile is active. This string is sent null-terminated. The size of the packet is the size of the string including the null terminator. In C, this is strlen() + 1.
NET_PACKET_ID_PROFILEMANAGER_ACTIVE_PROFILE_CHANGED
Server Only [Size: Variable]
The server uses this ID to notify the client that the active profile has changed. The data contains the name of the active profile 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.
This packet is sent only to clients that have the NET_CLIENT_FLAG_SUPPORTS_PROFILEMANAGER flag set.
NET_PACKET_ID_PROFILEMANAGER_PROFILE_LOADED
Server Only [Size: Variable]
The server uses this ID to notify the active (local) client that a profile has been loaded. The data contains the full profile data as a JSON-formatted null-terminated string. The size of the packet is the size of the string including the null terminator. In C, this is strlen() + 1.
This packet is sent only to clients that have the NET_CLIENT_FLAG_SUPPORTS_PROFILEMANAGER flag set and have local client status.
NET_PACKET_ID_PROFILEMANAGER_PROFILE_ABOUT_TO_LOAD
Server Only [Size: 0]
The server uses this ID to notify all clients that a profile is about to be loaded. This packet contains no data. Clients should acknowledge this packet with an ACK before the profile load continues. The server waits for all ProfileManager-capable clients to acknowledge before proceeding.
NET_PACKET_ID_PROFILEMANAGER_PROFILE_LIST_UPDATED
Server Only [Size: Variable]
The server uses this ID to notify a client that the profile list has been updated. The data block format is the same as the response for NET_PACKET_ID_PROFILEMANAGER_GET_PROFILE_LIST.
NET_PACKET_ID_PROFILEMANAGER_CLEAR_ACTIVE_PROFILE
Client Only [Size: 0]
The client uses this ID to command the server to clear the active profile. The packet contains no data.
NET_PACKET_ID_PLUGINMANAGER_GET_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 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_PLUGINMANAGER_PLUGIN_SPECIFIC
Request [Size: Variable]
This packet is used to send data to a plugin. The pkt_dev_id 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:
Response [Size: Variable]
The response is optionally generated by the plugin. The data in the packet is plugin-specific.
NET_PACKET_ID_SETTINGSMANAGER_GET_SETTINGS
Request [Size: Variable]
The client uses this ID to request a settings value for a given key in JSON format from the server. The key is sent 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.
Response [Size: Variable]
The server responds to this request with the settings value for the given key in JSON format, 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.
NET_PACKET_ID_SETTINGSMANAGER_GET_SETTINGS_SCHEMA
Request [Size: Variable]
The client uses this ID to request a settings schema for a given key in JSON format from the server. The key is sent 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.
Response [Size: Variable]
The server responds to this request with the settings schema for the given key in JSON format, 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.
NET_PACKET_ID_SETTINGSMANAGER_MODIFY_SETTINGS
Client Only [Size: Variable]
The client uses this ID to modify the settings for a given key in JSON format. The JSON data is sent 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.
This packet requires local client status.
There is no response from the server for this packet.
NET_PACKET_ID_SETTINGSMANAGER_SET_SETTINGS
Client Only [Size: Variable]
The client uses this ID to set the settings for a given key in JSON format. The JSON data is sent 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.
This packet requires local client status.
There is no response from the server for this packet.
NET_PACKET_ID_SETTINGSMANAGER_SAVE_SETTINGS
Client Only [Size: 0]
The client uses this ID to command the server to save settings. The packet contains no data.
This packet requires local client status.
There is no response from the server for this packet.
NET_PACKET_ID_LOGMANAGER_CLEAR_LOG_BUFFER
Client Only [Size: 0]
The client uses this ID to command the server to clear the log buffer. The packet contains no data.
NET_PACKET_ID_LOGMANAGER_GET_LOG_BUFFER
Client Only [Size: 0]
The client uses this ID to request the server to send the log buffer. The packet contains no data.
NET_PACKET_ID_LOGMANAGER_GET_LOG_LEVEL
Request [Size: 0]
The client uses this ID to request the current log level from the server. The request contains no data.
Response [Size: 4]
The server responds to this request with a single unsigned int, size 4, containing the current log level value.
NET_PACKET_ID_LOGMANAGER_SET_LOG_LEVEL
Client Only [Size: 4]
The client uses this ID to set the log level on the server. The packet contains a single unsigned int, size 4, containing the log level value to set.
NET_PACKET_ID_LOGMANAGER_LOGGED_ENTRY
Server Only [Size: Variable]
The server uses this ID to forward a LogManager log entry to the client. The format of the block is shown below.
| Size | Format | Name | Protocol Version | Description |
|---|---|---|---|---|
| 4 | unsigned int | data_size | 6 | Size of all data in packet |
| 4 | unsigned int | log_level | 6 | Log level value |
| 4 | unsigned int | line | 6 | Line number of log entry |
| 4 | unsigned int | timestamp | 6 | Timestamp of log entry |
| 2 | unsigned short | filename_size | 6 | Length of filename string, including null termination |
| filename_size | char[filename_size] | filename | 6 | Filename string value, including null termination |
| 2 | unsigned short | text_size | 6 | Length of text string, including null termination |
| text_size | char[text_size] | text | 6 | Log text string value, including null termination |
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_id of this request's header indicates which controller you are calling ResizeZone() on. See the Device IDs section for more information.
| 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_id of this request's header indicates which controller you are calling ClearSegments() on. See the Device IDs section for more information.
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_id of this request's header indicates which controller you are calling AddSegment() on. See the Device IDs section for more information.
| 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 block format table. |
NET_PACKET_ID_RGBCONTROLLER_CONFIGUREZONE
Client Only [Size: Variable]
The client uses this ID to call the ConfigureZone() function of an RGBController device. The packet contains a data block. The format of the block is shown below. The pkt_dev_id of this request's header indicates which controller you are calling ConfigureZone() on. See the Device IDs section for more information.
| Size | Format | Name | Description |
|---|---|---|---|
| 4 | unsigned int | data_size | Size of all data in packet |
| 4 | unsigned int | zone_idx | Zone index to configure |
| Variable | Zone Data | zone | See Zone Data block format table. |
NET_PACKET_ID_RGBCONTROLLER_CONFIGUREDEVICE
Client Only [Size: Variable]
The client uses this ID to call the ConfigureDevice() function of an RGBController device. The packet contains a data block. The format of the block is shown below. The pkt_dev_id of this request's header indicates which controller you are calling ConfigureDevice() on. See the Device IDs section for more information.
| Size | Format | Name | Description |
|---|---|---|---|
| 4 | unsigned int | data_size | Size of all data in packet |
| 4 | unsigned int | flags | New controller flags value |
| 2 | unsigned short | name_len | Length of controller name string, including null termination |
| name_len | char[name_len] | name | New controller name string value, including null termination |
NET_PACKET_ID_RGBCONTROLLER_SETHIDDEN
Client Only [Size: 1]
The client uses this ID to call the SetHidden() function of an RGBController device. The packet contains a single bool value (size 1). The pkt_dev_id of this request's header indicates which controller you are calling SetHidden() on. See the Device IDs section for more information.
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_id of this request's header indicates which controller you are calling UpdateLEDs() on. See the Device IDs section for more information.
| 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_id of this request's header indicates which controller you are calling UpdateZoneLEDs() on. See the Device IDs section for more information.
| 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_id of this request's header indicates which controller you are calling UpdateSingleLED() on. See the Device IDs section for more information.
| 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_id of this request's header indicates which controller you are calling SetCustomMode() on. See the Device IDs section for more information.
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_id of this request's header indicates which controller you are calling UpdateMode() on. See the Device IDs section for more information.
| 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 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. The pkt_dev_id of this request's header indicates which controller you are calling SaveMode() on.
NET_PACKET_ID_RGBCONTROLLER_UPDATEZONEMODE
Client Only [Size: Variable]
The client uses this ID to call the UpdateZoneMode() function of an RGBController device. The packet contains a data block. The format of the data block is shown below. The pkt_dev_id of this request's header indicates which controller you are calling UpdateZoneMode() on. See the Device IDs section for more information.
| Size | Format | Name | Protocol Version | Description |
|---|---|---|---|---|
| 4 | unsigned int | data_size | 0 | Size of all data in packet |
| 4 | int | zone_idx | 6 | Zone index to update mode on |
| 4 | int | mode_idx | 6 | Mode index to update |
| Variable | Mode Data | mode | 6 | See Mode Data block format table. |
NET_PACKET_ID_RGBCONTROLLER_SETDEVICESPECIFICCONFIGURATION
Client Only [Size: Variable]
The client uses this ID to call the SetDeviceSpecificConfiguration function of an RGBController device. The pkt_dev_id of this request's header indicates which controller you are calling SetDeviceSpecificConfiguration on. See the Device IDs section for more information.
| Size | Format | Name | Description |
|---|---|---|---|
| Variable | char[data_size] | configuration | Configuration JSON string, including null termination (size = data_size) |
NET_PACKET_ID_RGBCONTROLLER_SETDEVICESPECIFICZONECONFIGURATION
Client Only [Size: Variable]
The client uses this ID to call the SetDeviceSpecificZoneConfiguration function of an RGBController device. The pkt_dev_id of this request's header indicates which controller you are calling SetDeviceSpecificZoneConfiguration on. See the Device IDs section for more information.
| Size | Format | Name | Description |
|---|---|---|---|
| 4 | int | zone_idx | Zone index to configure |
| 4 | unsigned int | configuration_string_size | Size of configuration string, including null termination |
| Variable | char[configuration_string_size] | configuration | Configuration JSON string, including null termination |
NET_PACKET_ID_RGBCONTROLLER_SIGNALUPDATE
Server Only [Size: Variable]
The server uses this ID to signal the client that SignalUpdate() was called on an RGBController device. The packet contains a data block. The format of the data block is shown below. The pkt_dev_id of this request's header indicates which controller signalled SignalUpdate(). See the Device IDs section for more information.
| Size | Format | Name | Description |
|---|---|---|---|
| 4 | unsigned int | data_size | Size of all data in packet |
| 4 | unsigned int | update_reason | Update reason code. See table below |
| Variable | Description Data | description | Controller description data or color description data |
The update reason code determines the format of the description data:
| Reason Code | Value | Description Data Format |
|---|---|---|
| RGBCONTROLLER_UPDATE_REASON_UPDATELEDS | Color Description format | |
| All other reasons | Device Data format |
Color Description Data
| Size | Format | Name | Description |
|---|---|---|---|
| 2 | unsigned short | num_colors | Number of color values |
| 4 * num_colors | RGBColor[num_colors] | colors | Color values for each LED |