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' http://192.168.4.1/command | json_pp
> POST /command HTTP/1.1
> Host: 10.9.8.147
> 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.

• switch - string - Must be “on” or “off”.
• frequency - integer - Pulse width modulation frequency of the lights, in Hz between 1 and 1000, inclusive. An ideal value would be four times the value of your country’s electricity grid; 240 for 60Hz countries or 200 for 50Hz countries.
• fadetime - integer - Length of time for transitions, in milliseconds between 0 and 10000, inclusive. For example, the transition between off and on, or one color to another. 0 will make transitions instantaneous.
• hue, saturation - float - Hue and saturation of the set color, between 0.0 and 100.0, inclusive. The values returned when set may be slightly different, due to float conversions.
• level - float - Luminance value of the set color, between 0.0 and 100.0, inclusive.
• gamma - float - Gamma correction, default 1.0. If orange is set on your lights (100% red, 50% green, 0% blue) and they look more yellow than orange, try applying a gamma of 2.8 and adjusting from there.
• red, green, blue - integer - RGB values, between 0 and 255, inclusive. The values returned when set will be slightly different, as DemiRGB internally stores HSV rather than RGB.
• hex - string - A read-only representation of the RGB value, if level were at 100%. For this reason, it is not the same as the hex version of red/green/blue; level would then be applied to each of the channels to determine the true channel values.
• brnorm - bool - Brightness normalization. If enabled, the total luminance output will never exceed 100% of a single channel. For example, if pure red is set, the red channel will be at 100% and green/blue at 0%. If pure white is set without brightness normalization, all three channels would be set to 100%, and the overall luminance output would be 300% of red. If pure white is set with brightness normalization, each channel would be recalculated to 33.3%, so the overall lumaninance of pure white would be the same as pure red.

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' http://192.168.4.1/command

• demo - Plays a short rotating color wheel demo for approximately 8 seconds, then returns to the previous state.
• savestate - Saves the current running state to flash, to be applied upon power-on.
• reset - Reboots the device.

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:

• 1 - 2 bytes, unsigned, 0-1023 (inclusive) - Red channel
• 2 - 2 bytes, unsigned, 0-1023 (inclusive) - Green channel
• 3 - 2 bytes, unsigned, 0-1023 (inclusive) - Blue channel
• 4 - arbitrary length - Device password (optional)

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.