Skip to content
This repository was archived by the owner on Oct 6, 2020. It is now read-only.

2.1 JSON API reference

Jump to bottom
Patrick Jahns edited this page Apr 24, 2016 · 11 revisions

JSON Web API

All API endpoints will either return data/success on a successful request. If a request failed - an error msg will be provided. The API can be secured via HTTP Basic Auth - please send the Credentials via a HTTP Authorization header. If the Authorization fails, API Endpoints will return 401

GET /info

Get information about the controller

Response

200 OK (application/json)

{
 "deviceid": "14081297",
 "firmware": "0.2.3",
 "git_version":"0.2.3-3-ge0db-dirty",
 "git_date":"2016-04-18",
 "config_version": 1,
 "sming": 2.1,
 "rgbww":{
    "version":"0.8.0",
    "queuesize":50
   }
 "connection": {
    "connected": true,
    "ssid": "network1",
    "dhcp": true,
    "ip": "192.168.1.100",
    "netmask": "255.255.255.0",
    "gateway": "192.168.1.1",
    "mac": "fe:as:01:be:a2"
  }
}



GET /ping

Useful for checking if we can still reach the device

Response

200 OK (application/json)

{ "ping": "pong" }



GET /networks

List available networks

Response

200 OK (application/json)

{
  "scanning": false,
  "available" [
    { "id": "1", "ssid": "Network_2", "signal": -53, "encryption": "WEP" },
    { "id": "2", "ssid": "Network_1", "signal": -65, "encryption": "WPA" },
    { "id": "3", "ssid": "Network_3", "signal": -71, "encryption": "WPA2" },
    { "id": "4", "ssid": "Network_5", "signal": -94, "encryption": "OPEN" }
    ]
}

Scanning indicates if a network scan is currently active The list of availables networks is sorted by best to worst signal strength

POST /scan_networks

Initiate a network scan

Request body

the body can be empty

Response

200 OK (application/json)

{ "success" : true }



POST /connect

Connect to specified network

Request body

(application/json)

{ 
    "ssid": "ssid of new network",
    "password":"password"
}

Password can be omitted for open networks

Response

200 OK (application/json)

{ 'success' : true }

### __GET /connect__ Return information about connection attempt
Response

The response will contain status which reflects the current status of the connection attempt. Possible values:

  • 0 - idle (not connecting)
  • 1 - connecting
  • 2 - successfully connected
  • 3 - failed to connect / error

200 OK (application/json)

  • during connection attempt
{ "status": "1" }
  • successful connection
{
  "status": "2",
  "ip": "192.168.1.100",
  "dhcp": true,
  "ssid": "network ssid"
}
  • failed connection attempt
{
  "status": "3",
  "error": "error msg"
}



GET /config

Receive the current configuration values

Response

200 OK (application/json)

{
"network":{
  "connection":{
    "dhcp":true,
    "ip":"0.0.0.0",
    "netmask":"0.0.0.0",
    "gateway":"0.0.0.0"
   },
  "ap":{
    "secured":false,
    "ssid":"RGBWW14081297"
   },
  "mqtt":{
    "enabled":false,
    "server":"",
    "port":0,
    "username":"",
   }
  },
  "color":{
    "outputmode":0,
    "hsv":{
      "model":0,
      "red":0.00,
      "yellow":0.00,
      "green":0.00,
      "cyan":0.00,
      "blue":0.00,
      "magenta":0.00
    },
    "brightness":{
      "red":100,
      "green":100,
      "blue":100,
      "ww":100,
      "cw":100
    },
    "colortemp":{
      "ww":2700,
      "cw":6000
    }
  },
  "security":{
    "api_secured":false
  }
}

For security purposes all passwords (mqtt, api, accesspoint) will be omitted

POST /config

Change configuration values

Request body

(application/json)
See GET for full json structure

For changing the passwords, please add the respective fields

  • mqtt
[...]
"mqtt":{
  "username":"new_username",
  "password":"new_password"
  }
[...]
  • to secure the controller accesspoint
[...]
"ap":{
  "secured":true,
  "password":"password
}
[...]
  • to secure api access
[...]
"security":{
  "api_secured":true,
  "api_password": "password"
}
[...]

##### Response
  • In case of success 200 OK (application/json)
{ "success" : true }
  • In case of error

400 BAD REQUEST (application/json)

{ "error": "error msg" }



POST /system

Issue system commands

Request body

(application/json)

{ "cmd": "cmd_to_execute" }

Valid commands are:

  • restart
  • reset
  • forget_wifi
  • stop_ap
  • start_ap
  • stopapandrestart

To enable system debugging it is also possible to send

{ "cmd": "debug", "enable": "true/false" }
Response
  • In case of success: 200 OK (application/json)
{ "success" : true }
  • In case of error 400 BAD REQUEST (application/json)
{ "error" : "error msg" }



POST /update

Initialize OTA update

Request body

(application/json)

{
"rom": {
    "version": "0.1.2",
    "url": "http://patrickjahns.github.io/esp_rgbww_firmware/release/rom0.bin"
  },
"webapp": {
    "version":"0.1.3",
    "url":[
      "http://patrickjahns.github.io/esp_rgbww_firmware/release/init.html.gz",
      "http://patrickjahns.github.io/esp_rgbww_firmware/release/index.html.gz",
      "http://patrickjahns.github.io/esp_rgbww_firmware/release/app.min.css.gz",
      "http://patrickjahns.github.io/esp_rgbww_firmware/release/app.min.js.gz"
    ]
  }
}

It is possible to only update the rom/firmware or the webapplication by omitting the other one.

The latest json for the OTA is hosted at github at: http://patrickjahns.github.io/esp_rgbww_firmware/release/version.json

Response
  • In case of success 200 OK (application/json)
{ "success" : true }
  • In case of error

400 BAD REQUEST (application/json)

{ "error": "error msg" }

### __GET `/update`__ Receive information on the current update process ##### Response 200 OK (application/json) ``` { "rom_status": 0, "webapp_status: 0 } ``` The status of each OTA is represented by an int. Values are: * 0 - not update * 1 - update in progress * 2 - ota success * 3 - ota failed

For more verbose information on the OTA progress a serial connection to the controller is required

GET /color?mode=

Return the current color values

Query paramater
  • mode - [hsv/raw] change the mode for the colorinformation to be returned
Response

200 OK (application/json)

mode=hsv
{
  "hsv": {
    "h": 200.1,
    "s": 100.0,
    "v": 50.0,
    "ct": 480
  }
}
  • h - hue (float) [0.0 - 360.0]
  • s - saturation (float) [0.0 - 100.0]
  • v - value (float) [0.0 - 100.0]
  • ct - color temperature mirek (int) [100 - 500]


##### mode=raw ``` { "raw":{ "r":378, "g":294, "b":0, "ww":0, "cw":0 } } ``` * r - value of red channel [0 - 1023] * g - value of green channel [0 - 1023] * b - value of blue channel [0 - 1023] * ww - value of warm white channel [0 - 1023] * cw - value of cold white channel [0 - 1023]

POST /color

Change the color

Request body

(application/json)

HSV
{ 
  "hsv": {
   "h": 200.0,
   "s": 100.0,
   "v": 100.0,
   "ct": 2700,
  },
  cmd: "fade",
  "t": 600,
  "q": false,
  "d": 1
  
}

Values for h,s,v see GET /color

  • ct - color temperatur in mirek [100 - 500] or kelvin [2000 - 10000]
  • cmd - [fade/solid] fade to the new color in time t or show color for period t (cmd=solid)
  • t - time (ms), the amount of time in which a transition takes place to the new color
  • q - queue(true/false), if the transition should be queued or executed directly
  • d - direction(1/0), if the transition should be via the shortest (1) or longest(0) distance between two colors


RAW
{ 
  "raw": {
   "r": 600,
   "g": 600,
   "b": 0,
   "ww": 0,
   "cw": 1023
  },
  cmd: "fade",
  "t": 600,
  "q": false
  
}
  • cmd - [fade/solid] fade to the new color in time t or show color for period t (cmd=solid)
  • t - time (ms), the amount of time in which a transition takes place to the new color
  • q - queue(true/false), if the transition should be queued or executed directly
Response
  • In case of success 200 OK (application/json)
{ "success" : true }
  • In case of error

400 BAD REQUEST (application/json)

{ "error": "error msg" }
Clone this wiki locally