Skip to content

Commit ff2188b

Browse files
CalcProgrammer1CalcProgrammer1
committed
Update SDK Documentation, fix plugin protocol version type in NetworkServer
1 parent 1c42cdc commit ff2188b

File tree

2 files changed

+83
-29
lines changed

2 files changed

+83
-29
lines changed

‎Documentation/OpenRGBSDK.md

Lines changed: 81 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,13 @@ The protocol mimics the [RGBController API](The-RGBController-API) closely. It
66

77
# Protocol Versions
88

9-
| Version | Release | Description |
10-
| ------- | ------- | --------------------------------------------- |
11-
| 0 | 0.3 | Initial (unversioned) protocol |
12-
| 1 | 0.5 | Add versioning, add vendor string |
13-
| 2 | 0.6 | Add profile controls |
14-
| 3 | 0.7* | Add brightness field to modes, add SaveMode() |
9+
| Protocol Version | OpenRGB Release | Description |
10+
| ---------------- | --------------- | --------------------------------------------- |
11+
| 0 | 0.3 | Initial (unversioned) protocol |
12+
| 1 | 0.5 | Add versioning, add vendor string |
13+
| 2 | 0.6 | Add profile controls |
14+
| 3 | 0.7 | Add brightness field to modes, add SaveMode() |
15+
| 4 | 0.9 | Add segments field to zones |
1516

1617
\* Denotes unreleased version, reflects status of current pipeline
1718

@@ -42,24 +43,28 @@ Each packet starts with a header that indicates the packet is an OpenRGB SDK pac
4243

4344
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.
4445

45-
| Value | Name | Description |
46-
| ----- | ------------------------------------------------------------------------------------------- | ------------------------------------------------ |
47-
| 0 | [NET_PACKET_ID_REQUEST_CONTROLLER_COUNT](#net_packet_id_request_controller_count) | Request RGBController device count from server |
48-
| 1 | [NET_PACKET_ID_REQUEST_CONTROLLER_DATA](#net_packet_id_request_controller_data) | Request RGBController data block |
49-
| 40 | [NET_PACKET_ID_REQUEST_PROTOCOL_VERSION](#net_packet_id_request_protocol_version) | Request OpenRGB SDK protocol version from server |
50-
| 50 | [NET_PACKET_ID_SET_CLIENT_NAME](#net_packet_id_set_client_name) | Send client name string to server |
51-
| 100 | [NET_PACKET_ID_DEVICE_LIST_UPDATED](#net_packet_id_device_list_updated) | Indicate to clients that device list has updated |
52-
| 150 | [NET_PACKET_ID_REQUEST_PROFILE_LIST](#net_packet_id_request_profile_list) | Request profile list |
53-
| 151 | [NET_PACKET_ID_REQUEST_SAVE_PROFILE](#net_packet_id_request_save_profile) | Save current configuration in a new profile |
54-
| 152 | [NET_PACKET_ID_REQUEST_LOAD_PROFILE](#net_packet_id_request_load_profile) | Load a given profile |
55-
| 153 | [NET_PACKET_ID_REQUEST_DELETE_PROFILE](#net_packet_id_request_delete_profile) | Delete a given profile |
56-
| 1000 | [NET_PACKET_ID_RGBCONTROLLER_RESIZEZONE](#net_packet_id_rgbcontroller_resizezone) | RGBController::ResizeZone() |
57-
| 1050 | [NET_PACKET_ID_RGBCONTROLLER_UPDATELEDS](#net_packet_id_rgbcontroller_updateleds) | RGBController::UpdateLEDs() |
58-
| 1051 | [NET_PACKET_ID_RGBCONTROLLER_UPDATEZONELEDS](#net_packet_id_rgbcontroller_updatezoneleds) | RGBController::UpdateZoneLEDs() |
59-
| 1052 | [NET_PACKET_ID_RGBCONTROLLER_UPDATESINGLELED](#net_packet_id_rgbcontroller_updatesingleled) | RGBController::UpdateSingleLED() |
60-
| 1100 | [NET_PACKET_ID_RGBCONTROLLER_SETCUSTOMMODE](#net_packet_id_rgbcontroller_setcustommode) | RGBController::SetCustomMode() |
61-
| 1101 | [NET_PACKET_ID_RGBCONTROLLER_UPDATEMODE](#net_packet_id_rgbcontroller_updatemode) | RGBController::UpdateMode() |
62-
| 1102 | [NET_PACKET_ID_RGBCONTROLLER_SAVEMODE](#net_packet_id_rgbcontroller_savemode) | RGBController::SaveMode() |
46+
| Value | Name | Description | Protocol Version |
47+
| ----- | ------------------------------------------------------------------------------------------- | ------------------------------------------------ | ---------------- |
48+
| 0 | [NET_PACKET_ID_REQUEST_CONTROLLER_COUNT](#net_packet_id_request_controller_count) | Request RGBController device count from server | 0 |
49+
| 1 | [NET_PACKET_ID_REQUEST_CONTROLLER_DATA](#net_packet_id_request_controller_data) | Request RGBController data block | 0 |
50+
| 40 | [NET_PACKET_ID_REQUEST_PROTOCOL_VERSION](#net_packet_id_request_protocol_version) | Request OpenRGB SDK protocol version from server | 1* |
51+
| 50 | [NET_PACKET_ID_SET_CLIENT_NAME](#net_packet_id_set_client_name) | Send client name string to server | 0 |
52+
| 100 | [NET_PACKET_ID_DEVICE_LIST_UPDATED](#net_packet_id_device_list_updated) | Indicate to clients that device list has updated | 0 |
53+
| 150 | [NET_PACKET_ID_REQUEST_PROFILE_LIST](#net_packet_id_request_profile_list) | Request profile list | 0 |
54+
| 151 | [NET_PACKET_ID_REQUEST_SAVE_PROFILE](#net_packet_id_request_save_profile) | Save current configuration in a new profile | 0 |
55+
| 152 | [NET_PACKET_ID_REQUEST_LOAD_PROFILE](#net_packet_id_request_load_profile) | Load a given profile | 0 |
56+
| 153 | [NET_PACKET_ID_REQUEST_DELETE_PROFILE](#net_packet_id_request_delete_profile) | Delete a given profile | 0 |
57+
| 200 | [NET_PACKET_ID_REQUEST_PLUGIN_LIST](#net_packet_id_request_plugin_list) | Request plugin list | 4 |
58+
| 201 | [NET_PACKET_ID_PLUGIN_SPECIFIC](#net_packet_id_plugin_specific) | Plugin specific | 4 |
59+
| 1000 | [NET_PACKET_ID_RGBCONTROLLER_RESIZEZONE](#net_packet_id_rgbcontroller_resizezone) | RGBController::ResizeZone() | 0 |
60+
| 1050 | [NET_PACKET_ID_RGBCONTROLLER_UPDATELEDS](#net_packet_id_rgbcontroller_updateleds) | RGBController::UpdateLEDs() | 0 |
61+
| 1051 | [NET_PACKET_ID_RGBCONTROLLER_UPDATEZONELEDS](#net_packet_id_rgbcontroller_updatezoneleds) | RGBController::UpdateZoneLEDs() | 0 |
62+
| 1052 | [NET_PACKET_ID_RGBCONTROLLER_UPDATESINGLELED](#net_packet_id_rgbcontroller_updatesingleled) | RGBController::UpdateSingleLED() | 0 |
63+
| 1100 | [NET_PACKET_ID_RGBCONTROLLER_SETCUSTOMMODE](#net_packet_id_rgbcontroller_setcustommode) | RGBController::SetCustomMode() | 0 |
64+
| 1101 | [NET_PACKET_ID_RGBCONTROLLER_UPDATEMODE](#net_packet_id_rgbcontroller_updatemode) | RGBController::UpdateMode() | 0 |
65+
| 1102 | [NET_PACKET_ID_RGBCONTROLLER_SAVEMODE](#net_packet_id_rgbcontroller_savemode) | RGBController::SaveMode() | 0 |
66+
67+
\* 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.
6368

6469
# Packet-Specific Documentation
6570

@@ -150,8 +155,22 @@ The Zone Data block represents one entry in the `RGBController::zones` vector.
150155
| 4* | unsigned int | zone_matrix_height | 0 | Zone matrix_map height (*only if matrix_map exists) |
151156
| 4* | unsigned int | zone_matrix_width | 0 | Zone matrix_map width (*only if matrix_map exists) |
152157
| (zone_matrix_len - 8)* | unsigned int[zone_matrix_len - 8] | zone_matrix_data | 0 | Zone matrix_map data (*only if matrix_map exists) |
158+
| 2 | unsigned short | num_segments | 4 | Number of segments in zone |
159+
| Variable | Segment Data[num_segments] | segments | 4 | See [Segment Data](#segment-data) block format table. Repeat num_segments times |
153160

154-
## LED data
161+
## Segment Data
162+
163+
The Segment Data block represents one entry in the `RGBController::zones::segments` vector. This data block was introduced in protocol version 4.
164+
165+
| Size | Format | Name | Protocol Version | Description |
166+
| ---------------- | ---------------------- | ------------------ | ---------------- | --------------------------------------------------------- |
167+
| 2 | unsigned short | segment_name_len | 4 | Length of segment name string, including null termination |
168+
| segment_name_len | char[segment_name_len] | segment_name | 4 | Segment name string value, including null termination |
169+
| 4 | int | segment_type | 4 | Segment type value |
170+
| 4 | unsigned int | segment_start_idx | 4 | Segment start_idx value |
171+
| 4 | unsigned int | segment_leds_count | 4 | Segment leds_count value |
172+
173+
## LED Data
155174

156175
The LED Data block represents one entry in the `RGBController::leds` vector.
157176

@@ -160,7 +179,7 @@ The LED Data block represents one entry in the `RGBController::leds` vector.
160179
| ------------------- | ------------------------- | ------------------- | ---------------- | ------------------------------------------------------ |
161180
| 2 | unsigned short | led_name_len | 0 | Length of LED name string, including null termination |
162181
| led_name_len | char[led_name_len] | led_name | 0 | LED name string value, including null termination |
163-
| 4 | unsignd int | led_value | 0 | LED value field value |
182+
| 4 | unsigned int | led_value | 0 | LED value field value |
164183

165184
## NET_PACKET_ID_REQUEST_PROTOCOL_VERSION
166185

@@ -170,7 +189,7 @@ The client uses this ID to request the server's highest supported protocol versi
170189

171190
### Response [Size: 4]
172191

173-
The server responds to this request with a single `unsigned int`, size 4, containing the server's highest supported protocol version.
192+
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.
174193

175194
## NET_PACKET_ID_SET_CLIENT_NAME
176195

@@ -214,6 +233,41 @@ Calling this function will not actually update the controllers. Instead, the co
214233

215234
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.
216235

236+
## NET_PACKET_ID_REQUEST_PLUGIN_LIST
237+
238+
### Request [Size: 0]
239+
240+
The client uses this ID to request the server's plugin list. The request contains no data.
241+
242+
### Response [Size: Variable]
243+
244+
The server responds to this request with a data block. The format of the block is shown below.
245+
246+
| Size | Format | Name | Description |
247+
| -------- | ------------------------ | ----------- | ----------------------------------------------------------------------------- |
248+
| 4 | unsigned int | data_size | Size of all data in packet |
249+
| 2 | unsigned short | num_plugins | Number of plugins on server |
250+
| Variable | Plugin Data[num_plugins] | plugins | See [Plugin Data](#plugin-data) block format table. Repeat num_plugins times |
251+
252+
## Plugin Data
253+
254+
The plugin data block represents the information of one plugin. This data block was introduced in protocol version 4.
255+
256+
| Size | Format | Name | Description |
257+
| ---------------------- | ---------------------------- | ----------------------- | --------------------------------------------------------------- |
258+
| 2 | unsigned short | plugin_name_len | Length of plugin name string, including null termination |
259+
| plugin_name_len | char[plugin_name_len] | plugin_name | Plugin name string value, including null termination |
260+
| 2 | unsigned short | plugin_description_len | Length of plugin description string, including null termination |
261+
| plugin_description_len | char[plugin_description_len] | plugin_description | Plugin description string value, including null termination |
262+
| 2 | unsigned short | plugin_version_len | Length of plugin version string, including null termination |
263+
| plugin_version_len | char[plugin_version_len] | plugin_version | Plugin version string value, including null termination |
264+
| 4 | unsigned int | plugin_index | Plugin index value |
265+
| 4 | unsigned int | plugin_protocol_version | Plugin protocol version value |
266+
267+
## NET_PACKET_ID_PLUGIN_SPECIFIC
268+
269+
This packet is used to send data to a plugin.
270+
217271
## NET_PACKET_ID_RGBCONTROLLER_RESIZEZONE
218272

219273
### Client Only [Size: 8]

‎NetworkServer.cpp

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1167,8 +1167,8 @@ void NetworkServer::SendReply_PluginList(SOCKET client_sock)
11671167
/*---------------------------------------------------------*\
11681168
| Copy in plugin sdk version (data) |
11691169
\*---------------------------------------------------------*/
1170-
memcpy(&data_buf[data_ptr], &plugins[i].protocol_version, sizeof(int));
1171-
data_ptr += sizeof(int);
1170+
memcpy(&data_buf[data_ptr], &plugins[i].protocol_version, sizeof(unsigned int));
1171+
data_ptr += sizeof(unsigned int);
11721172
}
11731173

11741174
NetPacketHeader reply_hdr;

0 commit comments

Comments
 (0)