Skip to content

Commit 85625a3

Browse files
CalcProgrammer1CalcProgrammer1
committed
SDK cleanup, update SDK documentation
1 parent e88f9a1 commit 85625a3

2 files changed

Lines changed: 69 additions & 36 deletions

File tree

‎Documentation/OpenRGBSDK.md‎

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

77
# Protocol Versions
88

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, plugin interface |
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, plugin interface |
16+
| 5 | 1.0 | Add zone flags, controller flags, effects-only zones, alternative LED names, add ClearSegments and AddSegments |
1617

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

@@ -57,6 +58,8 @@ The following IDs represent different SDK commands. Each ID packet has a certai
5758
| 200 | [NET_PACKET_ID_REQUEST_PLUGIN_LIST](#net_packet_id_request_plugin_list) | Request plugin list | 4 |
5859
| 201 | [NET_PACKET_ID_PLUGIN_SPECIFIC](#net_packet_id_plugin_specific) | Plugin specific | 4 |
5960
| 1000 | [NET_PACKET_ID_RGBCONTROLLER_RESIZEZONE](#net_packet_id_rgbcontroller_resizezone) | RGBController::ResizeZone() | 0 |
61+
| 1001 | [NET_PACKET_ID_RGBCONTROLLER_CLEARSEGMENTS](#net_packet_id_rgbcontroller_clearsegments) | RGBController::ClearSegments() | 5 |
62+
| 1002 | [NET_PACKET_ID_RGBCONTROLLER_ADDSEGMENT](#net_packet_id_rgbcontroller_addsegment) | RGBController::AddSegment() | 5 |
6063
| 1050 | [NET_PACKET_ID_RGBCONTROLLER_UPDATELEDS](#net_packet_id_rgbcontroller_updateleds) | RGBController::UpdateLEDs() | 0 |
6164
| 1051 | [NET_PACKET_ID_RGBCONTROLLER_UPDATEZONELEDS](#net_packet_id_rgbcontroller_updatezoneleds) | RGBController::UpdateZoneLEDs() | 0 |
6265
| 1052 | [NET_PACKET_ID_RGBCONTROLLER_UPDATESINGLELED](#net_packet_id_rgbcontroller_updatesingleled) | RGBController::UpdateSingleLED() | 0 |
@@ -90,31 +93,34 @@ NOTE: Before sending this request, the client should request the protocol versio
9093

9194
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).
9295

93-
| Size | Format | Name | Protocol Version | Description |
94-
| ------------------- | ------------------------- | ------------------- | ---------------- | ---------------------------------------------------------------------------- |
95-
| 4 | unsigned int | data_size | 0 | Size of all data in packet |
96-
| 4 | int | type | 0 | RGBController type field value |
97-
| 2 | unsigned short | name_len | 0 | Length of RGBController name field string, including null termination |
98-
| name_len | char[name_len] | name | 0 | RGBController name field string value, including null termination |
99-
| 2 | unsigned short | vendor_len | 1 | Length of RGBController vendor field string, including null termination |
100-
| vendor_len | char[vendor_len] | vendor | 1 | RGBController vendor field string value, including null termination |
101-
| 2 | unsigned short | description_len | 0 | Length of RGBController description field string, including null termination |
102-
| description_len | char[description_len] | description | 0 | RGBController description field string value, including null termination |
103-
| 2 | unsigned short | version_len | 0 | Length of RGBController version field string, including null termination |
104-
| version_len | char[version_len] | version | 0 | RGBController version field string value, including null termination |
105-
| 2 | unsigned short | serial_len | 0 | Length of RGBController serial field string, including null termination |
106-
| serial_len | char[serial_len] | serial | 0 | RGBController serial field string value, including null termination |
107-
| 2 | unsigned short | location_len | 0 | Length of RGBController location field string, including null termination |
108-
| location_len | char[location_len] | location | 0 | RGBController location field string value, including null termination |
109-
| 2 | unsigned short | num_modes | 0 | Number of modes in RGBController |
110-
| 4 | int | active_mode | 0 | RGBController active_mode field value |
111-
| Variable | Mode Data[num_modes] | modes | 0 | See [Mode Data](#mode-data) block format table. Repeat num_modes times |
112-
| 2 | unsigned short | num_zones | 0 | Number of zones in RGBController |
113-
| Variable | Zone Data[num_zones] | zones | 0 | See [Zone Data](#zone-data) block format table. Repeat num_zones times |
114-
| 2 | unsigned short | num_leds | 0 | Number of LEDs in RGBController |
115-
| Variable | LED Data[num_leds] | leds | 0 | See [LED Data](#led-data) block format table. Repeat num_leds times |
116-
| 2 | unsigned short | num_colors | 0 | Number of colors in RGBController |
117-
| 4 * num_colors | RGBColor[num_colors] | colors | 0 | RGBController colors field values |
96+
| Size | Format | Name | Protocol Version | Description |
97+
| ------------------- | ------------------------------------- | ------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------ |
98+
| 4 | unsigned int | data_size | 0 | Size of all data in packet |
99+
| 4 | int | type | 0 | RGBController type field value |
100+
| 2 | unsigned short | name_len | 0 | Length of RGBController name field string, including null termination |
101+
| name_len | char[name_len] | name | 0 | RGBController name field string value, including null termination |
102+
| 2 | unsigned short | vendor_len | 1 | Length of RGBController vendor field string, including null termination |
103+
| vendor_len | char[vendor_len] | vendor | 1 | RGBController vendor field string value, including null termination |
104+
| 2 | unsigned short | description_len | 0 | Length of RGBController description field string, including null termination |
105+
| description_len | char[description_len] | description | 0 | RGBController description field string value, including null termination |
106+
| 2 | unsigned short | version_len | 0 | Length of RGBController version field string, including null termination |
107+
| version_len | char[version_len] | version | 0 | RGBController version field string value, including null termination |
108+
| 2 | unsigned short | serial_len | 0 | Length of RGBController serial field string, including null termination |
109+
| serial_len | char[serial_len] | serial | 0 | RGBController serial field string value, including null termination |
110+
| 2 | unsigned short | location_len | 0 | Length of RGBController location field string, including null termination |
111+
| location_len | char[location_len] | location | 0 | RGBController location field string value, including null termination |
112+
| 2 | unsigned short | num_modes | 0 | Number of modes in RGBController |
113+
| 4 | int | active_mode | 0 | RGBController active_mode field value |
114+
| Variable | Mode Data[num_modes] | modes | 0 | See [Mode Data](#mode-data) block format table. Repeat num_modes times |
115+
| 2 | unsigned short | num_zones | 0 | Number of zones in RGBController |
116+
| Variable | Zone Data[num_zones] | zones | 0 | See [Zone Data](#zone-data) block format table. Repeat num_zones times |
117+
| 2 | unsigned short | num_leds | 0 | Number of LEDs in RGBController |
118+
| Variable | LED Data[num_leds] | leds | 0 | See [LED Data](#led-data) block format table. Repeat num_leds times |
119+
| 2 | unsigned short | num_colors | 0 | Number of colors in RGBController |
120+
| 4 * num_colors | RGBColor[num_colors] | colors | 0 | RGBController colors field values |
121+
| 2 | unsigned short | num_led_alt_names | 5 | Number of LED alternate name strings |
122+
| Variable | LED Alternate Name[num_led_alt_names] | led_alt_names | 5 | See [LED Alternate Name Data](#led-alternate-names-data) block format table. Repeat num_led_alt_names times |
123+
| 4 | unsigned int | flags | 5 | RGBController flags field value |
118124

119125
## Mode Data
120126

@@ -157,6 +163,7 @@ The Zone Data block represents one entry in the `RGBController::zones` vector.
157163
| (zone_matrix_len - 8)* | unsigned int[zone_matrix_len - 8] | zone_matrix_data | 0 | Zone matrix_map data (*only if matrix_map exists) |
158164
| 2 | unsigned short | num_segments | 4 | Number of segments in zone |
159165
| Variable | Segment Data[num_segments] | segments | 4 | See [Segment Data](#segment-data) block format table. Repeat num_segments times |
166+
| 4 | unsigned int | zone_flags | 5 | Zone flags value |
160167

161168
## Segment Data
162169

@@ -174,13 +181,21 @@ The Segment Data block represents one entry in the `RGBController::zones::segmen
174181

175182
The LED Data block represents one entry in the `RGBController::leds` vector.
176183

177-
178184
| Size | Format | Name | Protocol Version | Description |
179185
| ------------------- | ------------------------- | ------------------- | ---------------- | ------------------------------------------------------ |
180186
| 2 | unsigned short | led_name_len | 0 | Length of LED name string, including null termination |
181187
| led_name_len | char[led_name_len] | led_name | 0 | LED name string value, including null termination |
182188
| 4 | unsigned int | led_value | 0 | LED value field value |
183189

190+
## LED Alternate Name Data
191+
192+
The LED Alternate Name Data block represents one entry in the `RGBController::led_alt_names` vector. This data block was introduced in protocol version 5.
193+
194+
| Size | Format | Name | Protocol Version | Description |
195+
| ---------------- | ---------------------- | ---------------- | ---------------- | --------------------------------------------------------------- |
196+
| 2 | unsigned short | led_alt_name_len | 5 | Length of LED alternate name string, including null termination |
197+
| led_alt_name_len | char[led_alt_name_len] | led_alt_name | 5 | LED alternate name string value, including null termination |
198+
184199
## NET_PACKET_ID_REQUEST_PROTOCOL_VERSION
185200

186201
### Request [Size: 4]
@@ -300,6 +315,24 @@ The client uses this ID to call the ResizeZone() function of an RGBController de
300315
| 4 | int | zone_idx | Zone index to resize |
301316
| 4 | int | new_size | New size of the zone |
302317

318+
## NET_PACKET_ID_RGBCONTROLLER_CLEARSEGMENTS
319+
320+
### Client Only [Size: 4]
321+
322+
The client uses this ID to call the ClearSegments() function of an RGBController device. The packet contains the index of the zone to clear segments on, type int (size 4). The `pkt_dev_idx` of this request's header indicates which controller you are calling ClearSegments() on.
323+
324+
## NET_PACKET_ID_RGBCONTROLLER_ADDSEGMENT
325+
326+
### Client Only [Size: Variable]
327+
328+
The client uses this ID to call the AddSegment() function of an RGBController device. The packet contains a data block. The format of the block is shown below. The `pkt_dev_idx` of this request's header indicates which controller you are calling AddSegment() on.
329+
330+
| Size | Format | Name | Description |
331+
| ---------------- | ---------------------- | ---------------- | --------------------------------------------------------- |
332+
| 4 | unsigned int | data_size | Size of all data in packet |
333+
| 4 | unsigned int | zone_idx | Zone index to add segment to |
334+
| Variable | Segment Data | segment | See [Segment Data](#segment-data) block format table. |
335+
303336
## NET_PACKET_ID_RGBCONTROLLER_UPDATELEDS
304337

305338
### Client Only [Size: Variable]

‎NetworkServer.cpp‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -946,16 +946,16 @@ void NetworkServer::ListenThreadFunction(NetworkClientInfo * client_info)
946946

947947
memcpy(&zone, data, sizeof(int));
948948

949-
controllers[header.pkt_dev_idx]->zones[zone].segments.clear();
949+
controllers[header.pkt_dev_idx]->ClearSegments(zone);
950950
profile_manager->SaveProfile("sizes", true);
951951
}
952952
break;
953953

954954
case NET_PACKET_ID_RGBCONTROLLER_ADDSEGMENT:
955955
{
956956
/*---------------------------------------------------------*\
957-
| Verify the mode description size (first 4 bytes of data) |
958-
| matches the packet size in the header |
957+
| Verify the segment description size (first 4 bytes of |
958+
| data) matches the packet size in the header |
959959
\*---------------------------------------------------------*/
960960
if(header.pkt_size == *((unsigned int*)data))
961961
{

0 commit comments

Comments
 (0)