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

Update SDK Documentation, fix plugin protocol version type in NetworkServer

Browse source
This commit is contained in:
Adam Honse 2025-01-10 11:25:05 -06:00
parent 1c42cdc928
commit ff2188ba45
2 changed files with 83 additions and 29 deletions
Download patch file Download diff file Expand all files Collapse all files

108
Documentation/OpenRGBSDK.md
View file

@ -6,12 +6,13 @@ The protocol mimics the [RGBController API](The-RGBController-API) closely. It
# Protocol Versions
| 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() |
| 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 |
\* Denotes unreleased version, reflects status of current pipeline
@ -42,24 +43,28 @@ Each packet starts with a header that indicates the packet is an OpenRGB SDK pac
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](#net_packet_id_request_controller_count) | Request RGBController device count from server |
| 1 | [NET_PACKET_ID_REQUEST_CONTROLLER_DATA](#net_packet_id_request_controller_data) | Request RGBController data block |
| 40 | [NET_PACKET_ID_REQUEST_PROTOCOL_VERSION](#net_packet_id_request_protocol_version) | Request OpenRGB SDK protocol version from server |
| 50 | [NET_PACKET_ID_SET_CLIENT_NAME](#net_packet_id_set_client_name) | Send client name string to server |
| 100 | [NET_PACKET_ID_DEVICE_LIST_UPDATED](#net_packet_id_device_list_updated) | Indicate to clients that device list has updated |
| 150 | [NET_PACKET_ID_REQUEST_PROFILE_LIST](#net_packet_id_request_profile_list) | Request profile list |
| 151 | [NET_PACKET_ID_REQUEST_SAVE_PROFILE](#net_packet_id_request_save_profile) | Save current configuration in a new profile |
| 152 | [NET_PACKET_ID_REQUEST_LOAD_PROFILE](#net_packet_id_request_load_profile) | Load a given profile |
| 153 | [NET_PACKET_ID_REQUEST_DELETE_PROFILE](#net_packet_id_request_delete_profile) | Delete a given profile |
| 1000 | [NET_PACKET_ID_RGBCONTROLLER_RESIZEZONE](#net_packet_id_rgbcontroller_resizezone) | RGBController::ResizeZone() |
| 1050 | [NET_PACKET_ID_RGBCONTROLLER_UPDATELEDS](#net_packet_id_rgbcontroller_updateleds) | RGBController::UpdateLEDs() |
| 1051 | [NET_PACKET_ID_RGBCONTROLLER_UPDATEZONELEDS](#net_packet_id_rgbcontroller_updatezoneleds) | RGBController::UpdateZoneLEDs() |
| 1052 | [NET_PACKET_ID_RGBCONTROLLER_UPDATESINGLELED](#net_packet_id_rgbcontroller_updatesingleled) | RGBController::UpdateSingleLED() |
| 1100 | [NET_PACKET_ID_RGBCONTROLLER_SETCUSTOMMODE](#net_packet_id_rgbcontroller_setcustommode) | RGBController::SetCustomMode() |
| 1101 | [NET_PACKET_ID_RGBCONTROLLER_UPDATEMODE](#net_packet_id_rgbcontroller_updatemode) | RGBController::UpdateMode() |
| 1102 | [NET_PACKET_ID_RGBCONTROLLER_SAVEMODE](#net_packet_id_rgbcontroller_savemode) | RGBController::SaveMode() |
| 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 | 0 |
| 150 | [NET_PACKET_ID_REQUEST_PROFILE_LIST](#net_packet_id_request_profile_list) | Request profile list | 0 |
| 151 | [NET_PACKET_ID_REQUEST_SAVE_PROFILE](#net_packet_id_request_save_profile) | Save current configuration in a new profile | 0 |
| 152 | [NET_PACKET_ID_REQUEST_LOAD_PROFILE](#net_packet_id_request_load_profile) | Load a given profile | 0 |
| 153 | [NET_PACKET_ID_REQUEST_DELETE_PROFILE](#net_packet_id_request_delete_profile) | Delete a given profile | 0 |
| 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 |
| 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() | 0 |
\* 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
@ -150,8 +155,22 @@ The Zone Data block represents one entry in the `RGBController::zones` vector.
| 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 |
## LED data
## 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.
@ -160,7 +179,7 @@ The LED Data block represents one entry in the `RGBController::leds` vector.
| ------------------- | ------------------------- | ------------------- | ---------------- | ------------------------------------------------------ |
| 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 |
| 4 | unsigned int | led_value | 0 | LED value field value |
## NET_PACKET_ID_REQUEST_PROTOCOL_VERSION
@ -170,7 +189,7 @@ The client uses this ID to request the server's highest supported protocol versi
### Response [Size: 4]
The server responds to this request with a single `unsigned int`, size 4, containing the server'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. 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
@ -214,6 +233,41 @@ Calling this function will not actually update the controllers. Instead, the co
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 | Description |
| -------- | ------------------------ | ----------- | ----------------------------------------------------------------------------- |
| 4 | unsigned int | data_size | Size of all data in packet |
| 2 | unsigned short | num_plugins | Number of plugins on server |
| Variable | Plugin Data[num_plugins] | plugins | 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 | Description |
| ---------------------- | ---------------------------- | ----------------------- | --------------------------------------------------------------- |
| 2 | unsigned short | plugin_name_len | Length of plugin name string, including null termination |
| plugin_name_len | char[plugin_name_len] | plugin_name | Plugin name string value, including null termination |
| 2 | unsigned short | plugin_description_len | Length of plugin description string, including null termination |
| plugin_description_len | char[plugin_description_len] | plugin_description | Plugin description string value, including null termination |
| 2 | unsigned short | plugin_version_len | Length of plugin version string, including null termination |
| plugin_version_len | char[plugin_version_len] | plugin_version | Plugin version string value, including null termination |
| 4 | unsigned int | plugin_index | Plugin index value |
| 4 | unsigned int | plugin_protocol_version | Plugin protocol version value |
## NET_PACKET_ID_PLUGIN_SPECIFIC
This packet is used to send data to a plugin.
## NET_PACKET_ID_RGBCONTROLLER_RESIZEZONE
### Client Only [Size: 8]

4
NetworkServer.cpp
View file

@ -1167,8 +1167,8 @@ void NetworkServer::SendReply_PluginList(SOCKET client_sock)
/*---------------------------------------------------------*\
| Copy in plugin sdk version (data) |
\*---------------------------------------------------------*/
memcpy(&data_buf[data_ptr], &plugins[i].protocol_version, sizeof(int));
data_ptr += sizeof(int);
memcpy(&data_buf[data_ptr], &plugins[i].protocol_version, sizeof(unsigned int));
data_ptr += sizeof(unsigned int);
}
NetPacketHeader reply_hdr;