31 |
32 |
Open Pixel Control (OPC) is a simple protocol
33 | for controlling arrays of RGB lights,
34 | such as Total Control Lighting LEDs.
35 |
36 |
37 | Get the code at github.com.
38 |
39 | Show off your creations!
40 | Tag your photos with openpixelcontrol
41 | on flickr,
42 | and see everyone else's photos.
43 |
44 |
71 |
72 |
75 |
Overview
76 |
77 |
OPC describes the format of a stream of bytes,
78 | typically sent over a TCP connection,
79 | to control an array of RGB lights (pixels).
80 | The pixels are assumed to be arranged in strands,
81 | where each pixel has a fixed index in its strand.
82 |
83 |
84 | The purpose of OPC is to separate the generation of light patterns
85 | from the control of hardware lights.
86 | If you write a program that emits OPC messages,
87 | it will be independent of the lighting hardware.
88 | You can write your animation or interactive display program once,
89 | and then use the same program with many kinds of lighting hardware,
90 | as well as a simulator that lets you test and visualize your program
91 | before wiring it to real lights.
92 |
93 |
Specification
94 |
95 |
96 | An OPC stream consists of a sequence of messages.
97 | Each message has a 4-byte header followed by a variable-length data block:
98 |
99 |
100 |
101 |
102 |
103 |
104 |
105 | | data |
106 |
107 |
108 |
109 |
110 |
111 |
112 | | n bytes of message data |
113 |
114 |
115 |
116 |
117 | Channel:
118 | Up to 255 separate strands of pixels can be controlled.
119 | Each strand is given a channel number from 1 to 255
120 | and listens for messages with that channel number.
121 | Messages with channel 0 are considered broadcast messages;
122 | all strands should treat a message with channel 0
123 | as if it were sent on all channels.
124 |
125 |
126 | Command:
127 | The command code determines the format of the data
128 | and the expected behaviour in response to the message.
129 | Individual commands are defined below.
130 |
131 |
132 | Length:
133 | The message data block can have any length from 0 to 65535,
134 | transmitted as an unsigned two-byte number with the high byte first.
135 |
136 |
137 | Data:
138 | The data block must contain
139 | exactly the number of bytes indicated by the length field,
140 | from 0 to 65535.
141 |
142 |
Commands
143 |
144 |
145 | Set 8-bit pixel colours (command 0):
146 | The data block contains 8-bit RGB values:
147 | three bytes in red, green, blue order for each pixel to set.
148 | If the data block has length 3*n,
149 | then the first n pixels of the specified channel are set.
150 | All other pixels are unaffected and retain their current colour values.
151 | If the data length is not a multiple of 3,
152 | or there is data for more pixels than are present, the extra data is ignored.
153 | (Because the maximum data length is 65535,
154 | this command can control a maximum of 21845 pixels per channel,
155 | or a maximum of 5570475 pixels on all 255 channels.)
156 |
157 |
158 | Set 16-bit pixel colours (command 2):
159 | The data block contains 16-bit RGB values:
160 | six bytes for each pixel to set,
161 | consisting of three 16-bit words in red, green, blue order
162 | with each two-byte word in big-endian order.
163 | If the data block has length 6*n,
164 | then the first n pixels of the specified channel are set.
165 | All other pixels are unaffected and retain their current colour values.
166 | If the data length is not a multiple of 6,
167 | or there is data for more pixels than are present, the extra data is ignored.
168 | (Because the maximum data length is 65535,
169 | this command can control a maximum of 10922 pixels per channel,
170 | or a maximum of 2785110 pixels on all 255 channels.)
171 |
172 |
173 | System exclusive (command 255):
174 | Command 0xff is used to send a message that is specific
175 | to a particular device or software system.
176 | The data block should begin with a two-byte system ID;
177 | designers of that system are then free to define any message format
178 | for the rest of the data block.
179 |
180 |
System IDs
181 |
182 |
183 | Currently assigned system IDs are as follows:
184 |
188 |
zesty
ca