Skip to content

HTTP Interface

Jump to bottom
verybadsoldier edited this page Jul 17, 2019 · 10 revisions

The firmware features a HTTP interface which allows full configuration and also the retrieval of the current state. All endpoints accept either the HTTP methods GET or POST or both. Details are giving in the documentation below.

Reasonable HTTP error codes will be returned. Successful requests will be answered with code 200. If an error occured additionally an error message will be returned in the HTTP body.

The interface uses JSON messages for responses and also for the content of the POSTrequests. Examples are provided along with the endpoint documentation.

The API can be secured via HTTP Basic Authentication. For details see here: For details see here

GET /info

Get information about the controller

Response

200 OK (application/json)

{  
   "deviceid":"538282",
   "current_rom":"0",
   "git_version":"4.2.0-rc1",
   "git_date":"2019-06-26",
   "webapp_version":"0.3.3-shojo7",
   "sming":"3.8.0",
   "event_num_clients":1,
   "uptime":321540,
   "heap_free":22536,
   "rgbww":{  
      "version":"0.9.0",
      "queuesize":100
   },
   "connection":{  
      "connected":true,
      "ssid":"hsync",
      "dhcp":true,
      "ip":"192.168.2.53",
      "netmask":"255.255.255.0",
      "gateway":"192.168.2.1",
      "mac":"a020a60836aa"
   }
}



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,
         "password":"rgbwwctrl",
         "ssid":""
      },
      "mqtt":{  
         "enabled":true,
         "server":"mqtt_host",
         "port":1883,
         "username":"",
         "password":"",
         "topic_base":"home/"
      }
   },
   "color":{  
      "outputmode":3,
      "startup_color":"last",
      "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
   },
   "ota":{  
      "url":"http://rgbww.dronezone.de/release/version.json"
   },
   "sync":{  
      "clock_master_enabled":true,
      "clock_master_interval":30,
      "clock_slave_enabled":false,
      "clock_slave_topic":"home/led1/clock",
      "cmd_master_enabled":true,
      "cmd_slave_enabled":false,
      "cmd_slave_topic":"home/led1/command",
      "color_master_enabled":false,
      "color_master_interval_ms":0,
      "color_slave_enabled":false,
      "color_slave_topic":"home/led1/color"
   },
   "events":{  
      "color_interval_ms":500,
      "color_mininterval_ms":500,
      "server_enabled":true,
      "transfin_interval_ms":1000
   },
   "general":{  
      "device_name":"myLed",
      "pin_config":"13,12,14,5,4",
      "buttons_config":"",
      "buttons_debounce_ms":50
   }
}

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