Stairs/API.md

# API

- [GET /api/version](#get-version)
- [GET /api/connection/status](#get-connection-status)
- [GET /api/connection](#get-connection)
- [POST /api/connection](#post-connection)
- [GET /api/steps](#get-steps)
- [POST /api/steps](#post-steps)
- [POST /api/firmware](#post-firmware)

<a name="get-version"></a>
## GET /api/version

Returns the unique identifier of the chip and the version of the firmware.

*Example response:*
```json
{
    "systemID": "st41r",
    "version": "2.0.0-beta.1+6"
}
```

<a name="get-connection-status"></a>
## GET /api/connection/status

Returns the status of the WiFi connections.

The value of the 'status' element corresponds to the ```wl_status_t``` enum as defined in [wl_definitions.h](https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/src/include/wl_definitions.h).

*Example response:*
```json
{
    "ap": {
        "enabled": true,
        "ip": "192.168.4.1"
    },
    "station": {
        "enabled": true,
        "status": 3,
        "ip": "10.138.1.10"
    }
}
```

<a name="get-connection"></a>
## GET /api/connection

Returns the settings of the WiFi connections.

*Example response:*
```json
{
    "hostname": "stairs",
    "accesspoint": true,
    "station": true,
    "ssid": "MyWiFi",
    "password": "12345678",
    "dhcp": true,
    "ip": "",
    "subnetmask": "",
    "gateway": ""
}
```


<a name="post-connection"></a>
## POST /api/connection

Updates the settings of the WiFi connections. The module will apply the new settings immediately and will break existing connections.

*Example request:*
```json
{
    "hostname": "LivingRoomStairs",
    "accesspoint": false,
    "station": true,
    "ssid": "MyWiFi",
    "password": "12345678",
    "dhcp": false,
    "ip": "10.138.1.100",
    "subnetmask": "255.255.255.0",
    "gateway": "10.138.1.1"
}
```


<a name="get-steps"></a>
## GET /api/steps

Returns the current brightness value for each step. The number of items in the array is equal to the number of configured steps. Each value has a range of 0 to 255.

*Example response:*
```json
[
    0, 10, 30, 50, 80, 110, 130, 150,
    160, 170, 180, 190, 200, 230, 255
]
```

<a name="post-steps"></a>
## POST /api/steps

Changes the brightness value for each step. If the number of values in the array is less than the number of configured steps, each subsequent step is considered to be off.

An optional element 'transitionTime' can be included which specifies how long the transition from the current value of each step to it's new value should take, the module will then smoothly fade between the values. The transition time must be specified in milliseconds. Assume a maximum of 30 seconds, because I did not test with higher values. Ain't nobody got time for that! If no transition time or 0 is specified, the new values will be applied immediately.

An optional array 'startTime' can be included which specifies the delay, for each step individually, before the transition will start. The example request uses this to create a sweeping effect. If no or not enough values are provided, they are assumed to be 0.

*Example request:*
```json
{
  "transitionTime": 500,
  "values": [
    128, 128, 128, 128, 128, 128, 128, 128,
    128, 128, 128, 128, 128, 128, 128
  ],
  "startTime": [
    0, 50, 100, 150, 200, 250, 300, 350,
    400, 450, 500, 550, 600, 650, 700
  ]
}
```

<a name="post-firmware"></a>
## POST /api/firmware

Uploads new firmware. The bin file should be posted as a multipart/form-data file attachment. Name is not relevant.