DemiRGB API Command Reference

JSON HTTP server

The DemiRGB firmware uses a JSON API over HTTP. Here is an example curl command to turn the DemiRGB on:

$ curl -v --data-binary '{"state":{"switch":"on"}}' -H 'Content-Type: application/json' | json_pp
> POST /command HTTP/1.1
> Host:
> User-Agent: curl/7.55.1
> Accept: */*
> Content-Type: application/json
> Content-Length: 25
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8
< Content-Length: 349
   "state" : {
      "switch" : "on",
      "blue" : 84,
      "fadetime" : 1000,
      "hex" : "#E0E8FF",
      "saturation" : 11.7647,
      "green" : 76,
      "frequency" : 240,
      "red" : 74,
      "hue" : 62.7778,
      "level" : 33,
      "brnorm": False
   "sysinfo" : {
      "version" : "v1.9.3-8-g63826ac5c on 2017-11-01",
      "release" : "2.0.0(5a875ba)",
      "id" : "ab790600",
      "freq" : "80000000",
      "machine" : "DemiRGB with ESP8266"

The request must be a POST to /command, with a Content-Type of application/json. The result is a Content-Type of application/json.

If a device password is set, any request must include HTTP Basic authentication. The username is ignored and the password is checked against the device password.

sysinfo object

The sysinfo object contains information about the system. This information is read-only (sysinfo in a request will be ignored).

state object

The state object contains information about the state of the lights. Most keys in this object may be set, with the exception of hex.

If set by the command, red/green/blue will calculate and update hue/saturation/level and vice versa (but if both sets are given in a command, red/green/blue take precendence).

cmd object

A one-off command may be sent to the device, for example:

$ curl -v --data-binary '{"cmd":"demo"}' -H 'Content-Type: application/json'

UDP JTLVI server

In addition to the JSON HTTP server, DemiRGB firmware v0.3 and above includes a UDP server. This server listens on port 26079, and accepts JTLVI-formatted messages, with the following tags:

The UDP JTLVI server is designed to be able to apply color changes as quickly as possible with minimal processing. For example, no gamma correction or brightness normalization is applied; set red to 1023, red channel is at full red. Set all channels to 0, strip is turned off.

Note that in firmware v0.3, this mode completely bypasses the JSON HTTP server, so if changes are made via UDP JTLVI, a state request to the HTTP server will still return the old values. (Changed in v0.4 so the HTTP API will recalculate on JTLVI changes.)

A sample client to send JTLVI-formatted UDP messages is available in the demirgb-contrib repository.