Open Pixel Control

ping@zesty.ca

Open Pixel Control (OPC) is a simple protocol for controlling arrays of RGB lights, such as Total Control Lighting LEDs.

Get the code at github.com. Show off your creations! Tag your photos with openpixelcontrol on flickr, and see everyone else's photos.

Overview

OPC describes the format of a stream of bytes, typically sent over a TCP connection, to control an array of RGB lights (pixels). The pixels are assumed to be arranged in strands, where each pixel has a fixed index in its strand.

The purpose of OPC is to separate the generation of light patterns from the control of hardware lights. If you write a program that emits OPC messages, it will be independent of the lighting hardware. You can write your animation or interactive display program once, and then use the same program with many kinds of lighting hardware, as well as a simulator that lets you test and visualize your program before wiring it to real lights.

Specification

An OPC stream consists of a sequence of messages. Each message has a 4-byte header followed by a variable-length data block:

channel command length (n) data
0 to 255 0 to 255 high byte low byte n bytes of message data

Channel: Up to 255 separate strands of pixels can be controlled. Each strand is given a channel number from 1 to 255 and listens for messages with that channel number. Messages with channel 0 are considered broadcast messages; all strands should treat a message with channel 0 as if it were sent on all channels.

Command: The command code determines the format of the data and the expected behaviour in response to the message. Individual commands are defined below.

Length: The message data block can have any length from 0 to 65535, transmitted as an unsigned two-byte number with the high byte first.

Data: The data block must contain exactly the number of bytes indicated by the length field, from 0 to 65535.

Commands

Set 8-bit pixel colours (command 0): The data block contains 8-bit RGB values: three bytes in red, green, blue order for each pixel to set. If the data block has length 3*n, then the first n pixels of the specified channel are set. All other pixels are unaffected and retain their current colour values. If the data length is not a multiple of 3, or there is data for more pixels than are present, the extra data is ignored. (Because the maximum data length is 65535, this command can control a maximum of 21845 pixels per channel, or a maximum of 5570475 pixels on all 255 channels.)

Set 16-bit pixel colours (command 2): The data block contains 16-bit RGB values: six bytes for each pixel to set, consisting of three 16-bit words in red, green, blue order with each two-byte word in big-endian order. If the data block has length 6*n, then the first n pixels of the specified channel are set. All other pixels are unaffected and retain their current colour values. If the data length is not a multiple of 6, or there is data for more pixels than are present, the extra data is ignored. (Because the maximum data length is 65535, this command can control a maximum of 10922 pixels per channel, or a maximum of 2785110 pixels on all 255 channels.)

System exclusive (command 255): Command 0xff is used to send a message that is specific to a particular device or software system. The data block should begin with a two-byte system ID; designers of that system are then free to define any message format for the rest of the data block.

System IDs

Currently assigned system IDs are as follows: