hyperion.ng/doc/datasheets/fadecandy_opc_protocol.md
redpanther e8a441ca98 add fadecandy/opc specs
Former-commit-id: 287fa1501e569df439eed8aac6dd44077ecb0994
2016-02-04 13:17:40 +01:00

3.2 KiB

Fadecandy: Open Pixel Control Protocol

The Fadecandy Server (fcserver) operates as a bridge between LED controllers attached over USB, and visual effects that communicate via a TCP socket.

The primary protocol supported by fcserver is Open Pixel Control, a super simple way to send RGB values over a socket. We support the standard Open Pixel Control commands, as well as some Fadecandy extensions.

Socket

Open Pixel Control uses a TCP socket, by default on port 7890. For the best performance, remember to set TCP_NODELAY socket option.

Command Format

All OPC commands follow the same general format. All multi-byte values in Open Pixel Control are in network byte order, high byte followed by low byte.

Channel Command Length (N) Data
1 byte 1 byte 2 bytes N bytes of message data

Set Pixel Colors

Video data arrives in a Set Pixel Colors command:

Byte Set Pixel Colors command
0 Channel Number
1 Command (0x00)
2 - 3 Data length
4 Pixel #0, Red
5 Pixel #0, Green
6 Pixel #0, Blue
7 Pixel #1, Red
8 Pixel #1, Green
9 Pixel #1, Blue

As soon as a complete Set Pixel Colors command is received, a new frame of video will be broadcast simultaneously to all attached Fadecandy devices.

Set Global Color Correction

The color correction data (from the 'color' configuration key) can also be changed at runtime, by sending a new blob of JSON text in a Fadecandy-specific command. Fadecandy's 16-bit System ID for Open Pixel Control's System Exclusive (0xFF) command is 0x0001.

Byte Set Global Color Correction command
0 Channel Number (0x00, reserved)
1 Command (0xFF, System Exclusive)
2 - 3 Data length (JSON Length + 4)
4 - 5 System ID (0x0001, Fadecandy)
6 - 7 SysEx ID (0x0001, Set Global Color Correction)
8 - … JSON Text

Set Firmware Configuration

The firmware supports some runtime configuration options. Any OPC client can send a new firmware configuration packet using this command. If the supplied data is shorter than the firmware's configuration buffer, only the provided bytes will be changed.

Byte Set Firmware Configuration command
0 Channel Number (0x00, reserved)
1 Command (0xFF, System Exclusive)
2 - 3 Data length (Configuration Length + 4)
4 - 5 System ID (0x0001, Fadecandy)
6 - 7 SysEx ID (0x0002, Set Firmware Configuration)
8 - … Configuration Data

Current firmwares support the following configuration options:

Byte Offset Bits Description
0 7 … 4 (reserved)
0 3 Manual LED control bit
0 2 0 = LED shows USB activity, 1 = LED under manual control
0 1 Disable keyframe interpolation
0 0 Disable dithering
1 … 62 7 … 0 (reserved)