The Stairs firmware on the ESP8266 can be accessed using a custom light-weight UDP protocol. It is not intended to be accessed directly from the internet, and thus there is no security on the device itself. This is by design. Authentication should in my opinion be handled by a device with more processing power, such as a Raspberry Pi.

A Node.js application is included which provides a ReST interface. It is also not intended to be accessible from the internet, and does not provide any authentication either!


Protocol
========

The default port for UDP communication is 3126. Every request message will result in a response message which is either an error, the requested information or a confirmation of the newly stored data. Each message should be a separate packet.

16-bit (word) values are expected in little endian order (least significant byte first).


Request
-------

The first byte of a request is the command. Further data depends on the command.

| Command | Name |
| ------- | ---- |
| 0x01 | Ping |
| 0x03 | GetMode |
| 0x04 | SetMode |


Response
--------

A response is sent to the source address and port and starts with the Reply command.

| Command | Name |
| ------- | ---- |
| 0x02 | Reply |


The second byte is the request command for which this reply is intended, or Error if the request command was not recognized or contained invalid parameters.

| Command | Name |
| ------- | ---- |
| 0x00 | Error |

In the case of an Error, the third byte will be the actual request command (or unrecognized value).


### Ping
A no-op command which can be used to tell if the device is responding. Returns the number of steps.

Input parameters:<br>
_none_

Output parameters:<br>
**steps** (byte): The number of steps.


### GetMode
Returns the current mode.

Input parameters:<br>
_none_

Output parameters:<br>
**mode** (byte): The identifier of the current mode. See Modes below.<br>
**data** (0..n bytes): The parameters specific to the current mode. See Modes below.


### SetMode
Changed the current mode.

Input parameters:<br>
**mode** (byte): The identifier of the current mode.<br>
**data** (0..n bytes): The parameters specific to the current mode.

Output parameters:<br>
_Same as input parameters_

Modes
=====

| Mode | Name |
| ---- | ---- |
| 0x01 | Static |
| 0x02 | Custom |
| 0x03 | Alternate |
| 0x04 | Slide |

### Static
Sets all steps to the same brightness.

Parameters:<br>
**brightness** (word): value in range 0 (off) to 4096 (fully on).


### Custom
Sets the brightness for each of the steps individually.

Parameters:<br>
**brightness** (word[stepCount]): array of brightness values in range 0 - 4096. The number of values must be equal to the number of steps are reported in the Ping response. Bottom step first.


### Alternate
Alternates between even and odd steps being lit. Bring out our next contestant!

Parameters:<br>
**interval** (word): The time each set of steps is lit in milliseconds.<br>
**brightness** (word): value in range 0 (off) to 4096 (fully on).


### Slide
Lights one step at a time, moving up or down.

Parameters:<br>
**interval** (word): How long each step is lit before moving to the next.<br>
**direction** (byte): Determines the starting step / direction. Either Bottom/Up (0) or Top/Down (1).<br>
**fadeOutTime** (word): If greater than 0 each step will fade out instead of turning off instantly after moving to the next. Specified in milliseconds.