Stairs/docs/protocol.md

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
0x05	GetRange
0x06	SetRange
0xFF	UpdateFirmware

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:
none

Output parameters:
steps (byte): The number of steps.

GetMode

Returns the current mode.

Input parameters:
none

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

SetMode

Changed the current mode.

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

Output parameters:
Same as input parameters

GetRange

Gets the current range configuration. Each step has it's own parameters which adjust the PWM curve, which can be used to compensate for the differences in LED strips or signal strength.

The ranges are stored on the ESP8266's filesystem and will be restored after a power loss.

Input parameters:
none

Output parameters:
useScaling (byte): 0 (off) or 1 (on), default 1. If enabled, the brightness value will be converted to a PWM value using an exponential function. If disabled, the brightness is used as is (but still accounting for rangeStart/rangeEnd). repeated for each step:
rangeStart (word): value in range 0 (off) to 4095 (fully on), default 0. Determines the minimum PWM on value for a brightness of 1. rangeEnd (word): value in range 0 (off) to 4095 (fully on), default 4094. Determines the maximum PWM on value for a brightness of 4094.

SetRange

Sets the current range configuration.

Input parameters:
See GetRange

Output parameters:
Same as input parameters

UpdateFirmware

Updates the firmware over WiFi. This functionality may be limited in the configuration which is hardcoded into the firmware. There are three modes of operation:

1. Disabled, firmware can not be updated over WiFi
2. Enabled with a hardcoded URL. You may request an update check but any source provided will be ignored.
3. Enabled with the URL as input parameters.

You can only request an update once every 5 seconds (by default), otherwise an error will be returned.

Please note that the entire packet must not exceed 254 bytes or the remainder will be discarded.

For further information on implementing an update server, see Arduino ESP8266's HTTPUpdate reference.

Input parameters:
If enabled port (word): the port on which the HTTP update server runs host (null-terminated string): the host name or IP address on which the HTTP update server runs path (null-terminated string): the path to

Output parameters:
1 if succesful, 0 if no updates are available.

Modes

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

Static

Sets all steps to the same brightness.

Parameters:
brightness (word): value in range 0 (off) to 4095 (fully on). easeTime (word): the time in milliseconds to ease into the new brightness value (only applies if the mode was already set to static before).

Custom

Sets the brightness for each of the steps individually.

Parameters:
brightness (word[stepCount]): array of brightness values in range 0 - 4095. 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:
interval (word): The time each set of steps is lit in milliseconds.
brightness (word): value in range 0 (off) to 4095 (fully on).

Slide

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

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