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.

Coming here from Freespace? Welcome!

If you'd like to write your own patterns for the Freespace pixel grid, have a look at an example, raver_plaid.py. You can run a simulator on your Mac or Linux laptop to see how the program will look:

git clone git://github.com/zestyping/openpixelcontrol.git
cd openpixelcontrol
make
bin/gl_server layouts/freespace.json
Then, in another terminal window:
python_clients/raver_plaid.py

Or you can run the program directly on the real lights. Just plug the USB cable into your laptop and run this command:

python_clients/raver_plaid.py 192.168.7.2:7890

Now make your own copy of raver_plaid.py and edit it to make your own beautiful effects!

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

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: