Stairs/API.md

# API

- [GET /api/set](#get-apiset)
- [GET /api/status](#get-apistatus)
- [GET /api/connection/status](#get-apiconnectionstatus)
- [GET /api/connection](#get-apiconnection)
- [POST /api/connection](#post-apiconnection)
- [GET /api/system](#get-apisystem)
- [POST /api/system](#post-apisystem)
- [GET /api/steps/values](#get-apistepsvalues)
- [POST /api/steps/values](#post-apistepsvalues)
- [GET /api/triggers/time](#get-apitriggerstime)
- [POST /api/triggers/time](#post-apitriggerstime)
- [GET /api/triggers/motion](#get-apitriggersmotion)
- [POST /api/triggers/motion](#post-apitriggersmotion)
- [POST /api/firmware](#post-apifirmware)
- [GET /api/stacktrace/get](#get-apistacktraceget)
- [GET /api/stacktrace/delete](#get-apistacktracedelete)

#### Debug API
- [GET /api/crash/exception](#get-apicrashexception)
- [GET /api/crash/softwdt](#get-apicrashsoftwdt)
- [GET /api/crash/wdt](#get-apicrashwdt)


## GET /api/set

Intended for integration into scripts or home automation systems, like Domoticz, where it's often easier to perform GET calls than it is to post JSON data.

The following query parameters are supported:

| Parameter name | Description |
| -------------- | - |
| value | Brightness value from 0 to 255. Applied to all steps. |
| percent | Percentage value from 0 to 100. Same behaviour as value. |
| time | Optional. Transition time in milliseconds. |
| from | Optional. Where to start the fade. Can be either 'top' or 'bottom'. If omitted or any other value, all steps change brightness at the same time. |

Either value or percent is required.

*Example request*

```http://192.168.4.1/api/set?percent=50&time=1000&from=top```



## GET /api/status

Returns the unique identifier of the chip, the version of the firmware and various other bits of status information.

*Example response:*
```json
{
    "systemID": "st41r",
    "version": "2.0.0-beta.1+6",
    time: 1518467160,
    timeOffset: 3600,
    resetReason: 2,
    stackTrace: true
}
```

## 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"
    }
}
```

## 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": ""
}
```


## 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"
}
```


## GET /api/system

*Example response:*
```json
{
  "ntpServer": "eu.pool.ntp.org",
  "ntpInterval": 5,
  "lat": 52.370216,
  "lng": 4.895168,
  "pins": {
    "ledAP": 4,
    "ledSTA": 5,
    "apButton": 2,
    "pwmSDA": 13,
    "pwmSCL": 12
  },
  "pwmAddress": 64,
  "pwmFrequency": 1600,
  "mapsAPIKey": ""
}
```

## POST /api/system

## GET /api/steps/values

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
]
```

## POST /api/steps/values

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
  ]
}
```

## GET /api/triggers/time

Returns the current settings for the time triggers.

time:
Meaning depends on the triggerType

| triggerType | description |
| ----------- | - |
| 0 | fixed time, set time to the number of minutes since midnight |
| 1 | relative to sunrise, set time to the number of minutes before or after sunrise to trigger (negative numbers mean before sunrise) |
| 2 | relative to sunset, set time to the number of minutes before or after sunset to trigger (negative numbers mean before sunset) |

daysOfWeek:
Flags determining which days of the week the trigger is active.

| value | day |
| ----- | --- |
| 1 | Monday |
| 2 | Tuesday |
| 4 | Wednesday |
| 8 | Thursday |
| 16 | Friday |
| 32 | Saturday |
| 64 | Sunday |

Therefore 127 means every day of the week.


brightness: value from 0 to 255

enabled: whether or not this trigger is enabled

*Example response:*
```json
{
  "enabled": true,
  "transitionTime": 1000,
  "triggers": [
    {
       "time": 480,
       "daysOfWeek": 127,
       "brightness": 0,
       "triggerType": 0,
       "enabled": true
    },
    {
       "time": 1200,
       "daysOfWeek": 127,
       "brightness": 255,
       "triggerType": 0,
       "enabled": true
    }
  ]
}
```

## POST /api/triggers/time

Changes the time trigger settings. Request body format is the same as is returned in the GET request.

If the "triggers" array is omitted entirely, the items will not be cleared or overwritten.


## GET /api/triggers/motion

Returns the current settings for the motion triggers.

delay: How long to keep the lights on after the last sensor stops detecting motion.

pin: GPIO pin to which the motion sensor is connected. High is assumed to be active.

direction:
Enumeration determining from which side the sweep animation starts if transitionTime is set.

| value | description |
| ----- | --- |
| 1 | Non-directional. All steps change brightness at the same time. |
| 2 | Top-down. Starts a sweeping fade from the top step. |
| 3 | Bottom-up. Starts a sweeping fade from the bottom step. |

brightness: value from 0 to 255

enabled: whether or not this trigger is enabled

*Example response:*
```json
{
  "enabled": true,
  "enabledDuringTimeTrigger": 0,
  "enabledDuringDay": false,
  "transitionTime": 1000,
  "delay": 30000,
  "triggers": [
    {
       "pin": 14,
       "brightness": 64,
       "direction": 2,
       "enabled": true
    },
    {
       "pin": 15,
       "brightness": 64,
       "direction": 3,
       "enabled": true
    }
  ]
}
```

## POST /api/triggers/motion

Changes the motion trigger settings. Request body format is the same as is returned in the GET request.

If the "triggers" array is omitted entirely, the items will not be cleared or overwritten.

## POST /api/firmware

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

## GET /api/stacktrace/get

If an exception occurs and the stack trace was recorded before the device reset, this will return the stack trace as a file named "stacktrace.txt".

## GET /api/stacktrace/delete

Removes any recorded stack trace.

# Debug API

These APIs are hopefully never enabled unless you've changed the config.h for the purpose of testing the exception handler. Don't forget to turn it back off afterwards.

## GET /api/crash/exception

Causes a crash due to an unhandled exception. Should provide a stack trace afterwards.

## GET /api/crash/softwdt

Causes the software watchdog to reset.

## GET /api/crash/wdt

Disables the software watchdog and causes the hardware watchdog.