HTTP Interface

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. The message can contain one or more 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 - reboot the controller
• reset - clear all config parameters (factory reset)
• forget_wifi - clear WiFi configuration (opens an access point)
• 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": {
    "url": "http://rgbww.dronezone.de/release/rom0.bin"
  },
  "spiffs": {
    "url": "http://rgbww.dronezone.de/release/spiff_rom.bin"
  }
}

Both elements rom and spiffs have to be present and both have to have a field url.

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

Return the current color values for the two modes HSV and RAW.

Response

200 OK (application/json)

{  
   "raw":{  
      "r":0,
      "g":0,
      "b":0,
      "ww":0,
      "cw":0
   },
   "hsv":{  
      "h":126.98,
      "s":96.97,
      "v":0.00,
      "ct":3180
   }
}

hsv

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

raw

• 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" }

POST /stop

POST /pause

POST /continue

POST /skip

These are all channel animation controls. They can either affect all channels or just the channels specified by the channels parameter (if specified).

• stop - Stops an animation and clears the animation queues.
• pause - Pauses an animation as it is but won't clear any queues. Animation can be continued by issuing continue.
• continue - Continue a paused animation.
• skip - Skips the currently running animation and executes the next animation in the queue (if any).

Optional parameters:

• channels - Channeles to affect

Request body

(application/json)

{
  "channels": ['h', 's']
}

Response

• In case of success 200 OK (application/json)

{ "success" : true }

POST /blink

Executes a blink on the controller.

Optional parameters:

• channels - channels to blink
• q - Queue flag
• r - Requeue flag
• t - Ramp time
• s - Speed

Request body

(application/json)

{
  "channels": ['h', 's'],
  "t": 1500
}

Response

• In case of success 200 OK (application/json)

{ "success" : true }

POST /toggle

Toggles the controller on/off.

Response

• In case of success 200 OK (application/json)

{ "success" : true }