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.
| Version | 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() |
* Denotes unreleased version, reflects status of current pipeline
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.
| 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
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 |
|---|---|---|
| 0 | NET_PACKET_ID_REQUEST_CONTROLLER_COUNT | Request RGBController device count from server |
| 1 | NET_PACKET_ID_REQUEST_CONTROLLER_DATA | Request RGBController data block |
| 40 | NET_PACKET_ID_REQUEST_PROTOCOL_VERSION | Request OpenRGB SDK protocol version from server |
| 50 | NET_PACKET_ID_SET_CLIENT_NAME | Send client name string to server |
| 100 | NET_PACKET_ID_DEVICE_LIST_UPDATED | Indicate to clients that device list has updated |
| 150 | NET_PACKET_ID_REQUEST_PROFILE_LIST | Request profile list |
| 151 | NET_PACKET_ID_REQUEST_SAVE_PROFILE | Save current configuration in a new profile |
| 152 | NET_PACKET_ID_REQUEST_LOAD_PROFILE | Load a given profile |
| 153 | NET_PACKET_ID_REQUEST_DELETE_PROFILE | Delete a given profile |
| 1000 | NET_PACKET_ID_RGBCONTROLLER_RESIZEZONE | RGBController::ResizeZone() |
| 1050 | NET_PACKET_ID_RGBCONTROLLER_UPDATELEDS | RGBController::UpdateLEDs() |
| 1051 | NET_PACKET_ID_RGBCONTROLLER_UPDATEZONELEDS | RGBController::UpdateZoneLEDs() |
| 1052 | NET_PACKET_ID_RGBCONTROLLER_UPDATESINGLELED | RGBController::UpdateSingleLED() |
| 1100 | NET_PACKET_ID_RGBCONTROLLER_SETCUSTOMMODE | RGBController::SetCustomMode() |
| 1101 | NET_PACKET_ID_RGBCONTROLLER_UPDATEMODE | RGBController::UpdateMode() |
| 1102 | NET_PACKET_ID_RGBCONTROLLER_SAVEMODE | RGBController::SaveMode() |
The client uses this ID to request the number of controllers on the server. The request contains no data.
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.
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.
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 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 |
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 |
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) |
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 | unsignd int | led_value | 0 | LED value field value |
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.
The server responds to this request with a single unsigned int, size 4, containing the server's highest supported protocol version.
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.
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.
The client uses this ID to request the server's profile list. The request contains no data.
The server responds to this request with a data block. The format of the block is shown below.
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.
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.
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.
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 |
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 |
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 |
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 |
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.
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 block format table. |
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_idx of this request's header indicates which controller you are calling SaveMode() on.