HACKING

Protocols
=========


Router Web API
--------------

If enabled in the router config, the router can be
controlled using an HTTP-based API. The default port
is 7535.

Use the dimmer to regulate the global brightness::

  POST /api/dimmer       <= on
  POST /api/dimmer       <= off
  POST /api/dimmer       <= A0A0
  GET  /api/dimmer       => A0A0

The backlight is a special layer that is below all other
layers. It always sets all LEDs to the same color::

  POST /api/backlight    <= FF00FF
  GET  /api/backlight    => FF00FF

You can also get a list of connected clients, and close
their connections::

  GET  /api/clients
  POST /api/clients/1234 <= kill

The dimmer and backlight support jsonp. Just add `?jsonp=func` as
a GET parameter and the response will be javascript calling the
function named `func` with the results.


Router Webhooks
---------------

In the router configuration, you can specify URLs that the router
will call when the backlight color or dimmer setting changes:

    GET /foo?dimmer=12826
    GET /bar?color=ffff0000ffff


Network protocol
----------------

This section is probably only useful if you want
to implement the actual low-level network protocol.
Check `vaporware/language_bindings/` - there may
already be a library for your language!

Open a TCP connection to the router
(default port: 7534) and send commands::

  <command> ::= <auth>
              | <set-led-8>
              | <set-led-16>
              | <strobe>

All commands consist of a 1-byte opcode and a payload.

First, you have to authenticate yourself using
the auth command and a 16-byte access token.
Shorter tokens are to be padded with 0x00 bytes.
Tokens have a priority defined in the server
config which determines rendering order::

  <auth> ::= 0x02 <token>
  <token> ::= <byte>{16}

Now, you can set LEDs to colors.

Currently, you can only set desired raw PWM values. Values range
from 0x0000 (lowest or, for the alpha channel, transparent)
to 0xFFFF (highest or opaque)::

  <set-led-16> ::= 0x03 <led-id:int16> <rgba-16>
  <rgba-16> ::= <r:int16> <g:int16> <b:int16> <a:int16>
  <int16> ::= <high:byte> <low:byte>

For historicaly reasons, there is also a legacy
low-precision version of the set-led command::

  <set-led-8> ::= 0x01 <led-id:int16> <rgba-8>
  <rgba-8> ::= <r:byte> <g:byte> <b:byte> <a:byte>

Changes don't take effect until you issue
a strobe command, at which point they take
effect all at once::

  <strobe> ::= 0xFF


Bus protocol
------------

The following describes the protocol the router
uses to communicate with the LED modules.

The router acts as the bus master. It is the only device
that can send data on the bus. The LED modules may only receive.
The bus speed is 500000 baud (slower bus speeds may be used;
however that requires a special firmware for the LED modules).

The router sends whole frames.
The byte 0x54 is called the escape mark and 0x55 the stark mark.
To escape a payload, substitute 0x54 by 0x54 0x00 and 0x55 by 0x54 0x01.
Each frame consists of the start mark and an escaped payload.

  <frame> ::= 0x55 escape(<frame-payload>)
  <frame-payload> ::= <address> <command>
  <command> ::= <set-raw> | <set-xyY> | <set-conf> | <set-addr> | <strobe>

The set-raw command can be used to set the values for the PWM output
channels directly. Currently, all LED modules have 16 channels.

  <set-raw> ::= 0x00 ( <int16> ){16}

Alternatively, the desired colors can be expressed using the xyY color
space. Note that this requires properly calibrated LED modules.

  <set-xyy> ::= 0x01 ( <xyY> ){5}
  <xyY> ::= <x: int16> <y: int16> <Y: int16>

Updates only take effect when a strobe command is sent:

  <strobe> ::= 0xff

Again, all 16-bit numbers are big endian::

  <int16> ::= <high byte> <low byte>

The set-conf and set-addr commands are currently
unsupported and unspecified.