RESTful API reference
Overview
Twinkly rest API is primary way to get information about the device, configure network and modes of the device. It is a HTTP 1.1 based API sent over TCP port 80.
This API is used by mobile applications. It haven’t been made public yet so it may change at any time.
Request Authentication
Most API requests require valid authentication token. Except of:
login
gestalt
fw version
status
If API requires authentication but valid token wasn’t passed server returns HTTP status code 401 Unauthenticated and string Invalid Token. in the response body.
HTTP Responses
The HTTP response can be used to determine if the request was successful, and if not, whether the request should be retried.
- 200 Success
The request was successful.
- 401 Unauthenticated
Request requires authentication but authorization failed. Application didn’t handle the request.
- 404 Not Found
If a string Resource not found. is found in the response body check if API endpoint is implemented in the current firmware version.
Application hierarchy
Endpoints seem to be organized into hierarchy by applications. Overview of the hierarchy:
login
verify
logout
gestalt
status
device_name
echo
timer
led
layout
full
mode
color
effects
current
config
movie
full
config
out
brightness
saturation
driver_params
reset
reset2
rt
fw
version
update
0
update
1
update
movies
new
full
current
network
scan
scan_results
status
playlist
current
mqtt
config
mic
config
sample
music
drivers
sets
current
summary
Application responses
The API may return application status as code value of JSON. Returned will not necessarily “correspond” with the HTTP status code. For example, a HTTP status code 200 OK returned with an error application code indicates that the request successfully reached the server, but application cannot process the request.
- 1000
Ok
- 1001
Error
- 1101
Invalid argument value
- 1102
Error
- 1103
Error - value too long? Or missing required object key?
- 1104
Error - malformed JSON on input?
- 1105
Invalid argument key
- 1107
Ok?
- 1108
Ok?
- 1205
Error with firmware upgrade - SHA1SUM does not match
Login
Request access token.
Since firmware version 1.99.18.
HTTP request
POST /xled/v1/login
Parameters
Parameters as JSON object.
- challenge
Random 32 byte string encoded with base64.
Response
The response will be an object.
- authentication_token
Access token in format: 8 byte string base64 encoded. First authenticated API with this token must be Verify.
- challenge-response
41 byte string ([0-9a-h])
- code
(integer), application return code.
authentication_token_expires_in: integer. All the time 14400?
Example
Request:
POST /xled/v1/login HTTP/1.1
Host: 192.168.4.1
Content-Type: application/json
Content-Length: 61
{"challenge": "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8="}
Response:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 155
Content-Type: application/json
{"authentication_token":"5jPe+ONhwUY=","authentication_token_expires_in":14400,"challenge-response":"8d87f080947e343180da3f411df3997e3e9ae0cc","code":1000}
Verify
Verify the token retrieved by Login. Successful call invalidates previous token, if it existed.
Since firmware version 1.99.18.
HTTP request
POST /xled/v1/verify
- X-Auth-Token
Authentication token
Parameters
Parameters as JSON object.
- challenge-response
(optional) value returned by login request.
Response
The response will be an object.
- code
(integer), application return code.
Example
Request:
POST /xled/v1/verify HTTP/1.1
Host: 192.168.4.1
Content-Type: application/json
X-Auth-Token: 5jPe+ONhwUY=
Content-Length: 66
{"challenge-response": "8d87f080947e343180da3f411df3997e3e9ae0cc"}
Response:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 13
Content-Type: application/json
{"code":1000}
Logout
Probably invalidate access token. Doesn’t work.
Since firmware version 1.99.18.
HTTP request
POST /xled/v1/logout
- X-Auth-Token
Authentication token
Response
The response will be an object.
- code
(integer), application return code.
Example
Request:
POST /xled/v1/logout HTTP/1.1
Host: 192.168.4.1
Content-Type: application/json
X-Auth-Token: 5jPe+ONhwUY=
Content-Length: 2
{}
Response:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 13
Content-Type: application/json
{"code":1000}
Device details
Gets information detailed information about the device.
Since firmware version 1.99.18.
HTTP request
GET /xled/v1/gestalt
Response
The response will be an object.
For firmware family “D”:
- product_name
(string) Twinkly
- product_version
(numeric string), e.g. “2”
- hardware_version
(numeric string), e.g. “6”
- bytes_per_led
(number), 4
- flash_size
(number), e.g. 16
- led_type
(number), e.g. 6
- led_version
(string) “1”
- product_code
(string), e.g. “TW105SEUP06”
- device_name
(string), name of the device - see section Device Name in Protocol details.
- rssi
(number), Received signal strength indication. Since firmware version: 2.1.0.
- uptime
(string) number as a string. Seconds since start. E.g. “60”
- hw_id
(string), see section Hardware ID in Protocol details.
- mac
(string) MAC address as six groups of two hexadecimal digits separated by colons (:).
- uuid
(string) UUID of the device. Since firmware version: 2.0.8. Device in family “D” has value 00000000-0000-0000-0000-000000000000.
- max_supported_led
(number), e.g. firmware family “D”: 180 in firmware version 1.99.20, 224 in 1.99.24, 228 in 1.99.30, 255 in 2.0.0 and newer.
- base_leds_number
(number), e.g. 105
- number_of_led
(number), e.g. 105
- led_profile
(string) “RGB”
- frame_rate
(number), 25
- movie_capacity
(number), e.g. 719
- copyright
(string) “LEDWORKS 2017”
- code
(integer), application return code.
For firmware family “F” since firmware version 2.2.1:
- fw_family
(string) “F”,
- product_name
(string) Twinkly
- hardware_version
(numeric string), “100”
- bytes_per_led
(number), 3
- flash_size
(number), 64
- led_type
(number), 14
- product_code
(string), e.g. “TWS250STP”
- device_name
(string), name of the device - see section Device Name in Protocol details.
- uptime
(string) number as a string. Miliseconds since start. E.g. “60000”
- hw_id
(string), see section Hardware ID in Protocol details.
- mac
(string) MAC address as six groups of two hexadecimal digits separated by colons (:). Address of a device in access point mode.
- uuid
(string) UUID of the device
- max_supported_led
(number), e.g. 510, since firmware version 2.4.14: 1020, since 2.4.22: 1200
- number_of_led
(number), e.g. 250
- led_profile
(string) “RGB”
- frame_rate
(number), e.g. 30.3, since firmware version 2.4.14: 17.86, since 2.4.16: 23.81, since 2.4.22: 25, since 2.4.30: 25.64, since 2.5.6: 24.
- measured_frame_rate
(number), e.g. 23.26. Since firmware version 2.5.6.
- movie_capacity
(number), e.g. 1984, since firmware version 2.4.14: 992
- copyright
(string) “LEDWORKS 2018”
- code
(integer), application return code.
For firmware family “G” since firmware version 2.4.21:
- fw_family
(string) “G”,
- product_name
(string) Twinkly
- hardware_version
(numeric string), “100”
- flash_size
(number), 64
- led_type
(number), 12
- product_code
(string), e.g. “TWW210SPP” or “TWI190SPP”
- device_name
(string), name of the device - see section Device Name in Protocol details.
- uptime
(string) number as a string. Miliseconds since start. E.g. “60000”
- hw_id
(string), see section Hardware ID in Protocol details.
- mac
(string) MAC address as six groups of two hexadecimal digits separated by colons (:). Address of a device in access point mode.
- uuid
(string) UUID of the device
- max_supported_led
(number), e.g. 1200
- number_of_led
(number), e.g. 190 or 210
- led_profile
(string) “RGBW”
- frame_rate
(number), e.g. 28.57. Since firmware version 2.5.6: 24
- measured_frame_rate
(number), e.g. 27.78. Since firmware version 2.5.6.
- movie_capacity
(number), e.g. 992
- copyright
(string) “LEDWORKS 2018”
- wire_type
(integer), e.g. 1 or 4
- code
(integer), application return code.
Example
Request:
GET /xled/v1/gestalt HTTP/1.1
Host: 192.168.4.1
Response from firmware family “D”:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 406
Content-Type: application/json
{"product_name":"Twinkly","product_version":"2","hardware_version":"6","flash_size":16,"led_type":6,"led_version":"1","product_code":"TW105SEUP06","device_name":"Twinkly_33AAFF","uptime":"60","hw_id":"0033aaff","mac":"5c:cf:7f:33:aa:ff","max_supported_led":224,"base_leds_number":105,"number_of_led":105,"led_profile":"RGB","frame_rate":25,"movie_capacity":719,"copyright":"LEDWORKS 2017","code":1000}
Response from firmware family “G”:
HTTP/1.1 200 OK
Server: esp-httpd/0.5
Transfer-Encoding: chunked
Content-Type: application/json
{"product_name":"Twinkly","hardware_version":"100","bytes_per_led":4,"hw_id":"1cc190","flash_size":64,"led_type":12,"product_code":"TWI190SPP","fw_family":"G","device_name":"Twinkly_1CC190","uptime":"8107194","mac":"98:f4:ab:1c:c1:90","uuid":"E103C5A3-3398-4B77-AE1A-9D8998A5EB62","max_supported_led":1200,"number_of_led":190,"led_profile":"RGBW","frame_rate":28.57,"movie_capacity":992,"wire_type":4,"copyright":"LEDWORKS 2018","code":1000}
Get device name
Gets device name
Since firmware version 1.99.18.
HTTP request
GET /xled/v1/device_name
- X-Auth-Token
Authentication token
Response
The response will be an object.
- name
(string) Device name.
- code
(integer), application return code.
Example
Request:
GET /xled/v1/device_name HTTP/1.1
Host: 192.168.4.1
X-Auth-Token: 5jPe+ONhwUY=
Response:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 37
Content-Type: application/json
{"name":"Twinkly_33AAFF","code":1000}
Set device name
Sets device name
Since firmware version 1.99.18.
HTTP request
POST /xled/v1/device_name
- X-Auth-Token
Authentication token
Parameters
Parameters as JSON object.
- name
(string) Desired device name. At most 32 characters.
Response
The response will be an object.
- code
(integer), application return code. 1103 if too long.
Example
Request:
POST /xled/v1/device_name HTTP/1.1
Host: 192.168.4.1
Content-Type: application/json
X-Auth-Token: 5jPe+ONhwUY=
Content-Length: 26
{"name": "Twinkly_33AAFF"}
Response:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 37
Content-Type: application/json
{"name":"Twinkly_33AAFF","code":1000}
Echo
Responds with requested message.
Since firmware version 1.99.18.
HTTP request
POST /xled/v1/echo
- X-Auth-Token
Authentication token
Parameters
Parameters must be an JSON object. There doesn’t seem to be any requirement on a structure.
Response
The response will be an object.
- code
(integer), application return code. Returns 1001 on error.
- json
(object), contents is the same as the request.
Example
Request:
POST /xled/v1/echo HTTP/1.1
Host: 192.168.4.1
Content-Type: application/json
X-Auth-Token: 5jPe+ONhwUY=
Content-Length: 23
{"message": "Hello!"}}
Response:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 44
Content-Type: application/json
{"json":{"message":"Hello!"},"code":1000}
Get timer
Gets time when lights should be turned on and time to turn them off.
Since firmware version 1.99.18.
HTTP request
GET /xled/v1/timer
- X-Auth-Token
Authentication token
Response
The response will be an object.
- time_now
(integer) current time in seconds after midnight
- time_on
(number) time when to turn lights on in seconds after midnight. -1 if not set
- time_off
(number) time when to turn lights off in seconds after midnight. -1 if not set
- code
(integer), application return code. Since firmware family “D” version: 2.3.8 and family “F” version: 2.5.6.
Example
Request:
GET /xled/v1/timer HTTP/1.1
Host: 192.168.4.1
X-Auth-Token: 5jPe+ONhwUY=
Response:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 45
Content-Type: application/json
{"time_now":17083,"time_on":-1,"time_off":-1}
Set timer
Sets time when lights should be turned on and time to turn them off.
Since firmware version 1.99.18.
HTTP request
POST /xled/v1/timer
- X-Auth-Token
Authentication token
Parameters
Parameters as JSON object.
- time_now
(integer) current time in seconds after midnight
- time_on
(number) time when to turn lights on in seconds after midnight. -1 if not set
- time_off
(number) time when to turn lights off in seconds after midnight. -1 if not set
Example
Request to set current time to 2:00 AM, turn on lights at 1:00 AM and turn off at 4:00 AM:
POST /xled/v1/timer HTTP/1.1
Host: 192.168.4.1
Content-Type: application/json
X-Auth-Token: 5jPe+ONhwUY=
Content-Length: 51
{"time_now": 120, "time_on": 60, "time_off": 240}
Response:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 13
Content-Type: application/json
{"code":1000}
Get layout
Since firmware version 1.99.18.
HTTP request
GET /xled/v1/led/layout/full
- X-Auth-Token
Authentication token
Response
Parameters as JSON object.
- aspectXY
(integer), e.g. 0
- aspectXZ
(integer), e.g. 0
- coordinates
(array)
- source
(string enum)
- synthesized
(bool), e.g. false
- uuid
(string), e.g. “00000000-0000-0000-0000-000000000000”
Where each item of coordinates is an object:
- x
(number)
- y
(number)
- z
(number)
source is one of:
“linear”
“2d”
“3d”
Upload layout
Since firmware version 1.99.18.
HTTP request
POST /xled/v1/led/layout/full
- X-Auth-Token
Authentication token
Parameters
Parameters as JSON object.
- aspectXY
(integer), e.g. 0
- aspectXZ
(integer), e.g. 0
- coordinates
(array)
- source
(string enum)
- synthesized
(bool), e.g. false
Where each item of coordinates is an object:
- x
(number)
- y
(number)
- z
(number)
source is one of:
“linear”
“2d”
“3d”
Response
The response will be an object.
- code
(integer), application return code.
- parsed_coordinates
(integer)
Delete layout
HTTP request
DELETE /xled/v1/led/layout/full
- X-Auth-Token
Authentication token
Response
The response will be an object.
- code
(integer), application return code.
Get LED operation mode
Gets current LED operation mode.
Since firmware version 1.99.18.
HTTP request
GET /xled/v1/led/mode
- X-Auth-Token
Authentication token
Response
The response will be an object.
- code
(integer), application return code.
- mode
(string) mode of operation.
- shop_mode
(integer), by default 0. Since firmware version 2.4.21.
Mode can be one of:
off - lights are turned off
color - lights show a static color
demo - demo mode, cycles through pre-defined effects
effect - plays a predefined effect
movie - plays an uploaded movie
playlist - cycles through playlist of uploaded movies
rt - receive effect in real time
Example
Request:
GET /xled/v1/led/mode HTTP/1.1
Host: 192.168.4.1
X-Auth-Token: 5jPe+ONhwUY=
Response:
HTTP/1.1 200 OK
Connection: close
Content-Length: 28
Content-Type: application/json
{"mode":"movie","code":1000}
Set LED operation mode
Changes LED operation mode.
Since firmware version 1.99.18.
HTTP request
POST /xled/v1/led/mode
- X-Auth-Token
Authentication token
Parameters
Parameters as JSON object.
- mode
(string) mode of operation. See LED operating modes in Protocol details.
- effect_id
(int), id of effect, e.g. 0. Set together with mode: effect.
Response
The response will be an object.
- code
(integer), application return code.
Example
Request:
POST /xled/v1/led/mode HTTP/1.1
Host: 192.168.4.1
Content-Type: application/json
X-Auth-Token: 5jPe+ONhwUY=
Content-Length: 15
{"mode":"demo"}
Response:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 13
Content-Type: application/json
{"code":1000}
Get LED color
Gets the color shown when in color mode.
Since firmware version 2.7.1
HTTP request
GET /xled/v1/led/color
- X-Auth-Token
Authentication token
Response
The response will be an object.
- hue
(integer), hue component of HSV, in range 0..359
- saturation
(integer), saturation component of HSV, in range 0..255
- value
(integer), value component of HSV, in range 0..255
- red
(integer), red component of RGB, in range 0..255
- green
(integer), green component of RGB, in range 0..255
- blue
(integer), blue component of RGB, in range 0..255
- code
(integer), application return code.
Example
Request:
GET /xled/v1/led/color HTTP/1.1
Host: 192.168.4.1
Content-Type: application/json
X-Auth-Token: 5jPe+ONhwUY=
Response:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 84
Content-Type: application/json
{"hue":56,"saturation":105,"value":255,"red":255,"green":248,"blue":150,"code":1000}
Set LED color
Sets the color shown when in color mode.
Since firmware version 2.7.1
HTTP request
POST /xled/v1/led/color
- X-Auth-Token
Authentication token
Parameters
Parameters as JSON object.
Either the three HSV components:
- hue
(integer), hue component of HSV, in range 0..359
- saturation
(integer), saturation component of HSV, in range 0..255
- value
(integer), value component of HSV, in range 0..255
Or the three RGB components:
- red
(integer), red component of RGB, in range 0..255
- green
(integer), green component of RGB, in range 0..255
- blue
(integer), blue component of RGB, in range 0..255
Response
The response will be an object.
- code
(integer), application return code.
Example
Request:
POST /xled/v1/led/color HTTP/1.1
Host: 192.168.4.1
Content-Type: application/json
X-Auth-Token: 5jPe+ONhwUY=
Content-Length: 40
{"hue":300,"saturation":255,"value":255}
Response:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 13
Content-Type: application/json
{"code":1000}
Get LED effects
Retrieve the identities of all available predefined effects.
Since firmware version 1.99.18.
HTTP request
GET /xled/v1/led/effects
- X-Auth-Token
Authentication token
Response
The response will be an object.
- code
(integer), application return code.
- effects_number
(integer), e.g. 5 until firmware version 2.4.30 and 15 since firmware version 2.5.6.
- unique_ids
(array), since firmware version 2.5.6.
Item of unique_ids array is a UUID string. Default values are “00000000-0000-0000-0000-000000000001” up until “00000000-0000-0000-0000-00000000000F”.
Example
Request:
GET /xled/v1/led/effects HTTP/1.1
Host: 192.168.4.1
Content-Type: application/json
X-Auth-Token: 5jPe+ONhwUY=
Response:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 32
Content-Type: application/json
{"effects_number":5,"code":1000}
Get current LED effect
Gets the id of the effect shown when in effect mode.
Since firmware version 1.99.18.
HTTP request
GET /xled/v1/led/effects/current
- X-Auth-Token
Authentication token
Response
The response will be an object.
- code
(integer), application return code.
- unique_id
(string), UUID. Since firmware version 2.5.6.
- effect_id
(integer), e.g. 0
Example
Request:
GET /xled/v1/led/effects/current HTTP/1.1
Host: 192.168.4.1
Content-Type: application/json
X-Auth-Token: 5jPe+ONhwUY=
Response:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 27
Content-Type: application/json
{"effect_id":0,"code":1000}
Set current LED effect
Sets which effect to show when in effect mode.
Since firmware version 1.99.18.
HTTP request
POST /xled/v1/led/effects/current
- X-Auth-Token
Authentication token
Parameters
Parameters as JSON object.
- effect_id
(int), id of effect, e.g. 0.
Response
The response will be an object.
- code
(integer), application return code.
Example
Request:
POST /xled/v1/led/effects/current HTTP/1.1
Host: 192.168.4.1
Content-Type: application/json
X-Auth-Token: 5jPe+ONhwUY=
Content-Length: 15
{"effect_id":0}
Response:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 13
Content-Type: application/json
{"code":1000}
Get LED config
Since firmware version 1.99.18.
HTTP request
GET /xled/v1/led/config
- X-Auth-Token
Authentication token
Response
The response will be an object.
- strings
Array of objects
- code
(integer), application return code. Since firmware version: 1.99.20.
Item of strings array is object:
- first_led_id
(integer), e.g. 0
- length
(integer), e.g. 105
Example
Request:
GET /xled/v1/led/config HTTP/1.1
Host: 192.168.4.1
X-Auth-Token: 5jPe+ONhwUY=
Response from firmware family “D”:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 57
Content-Type: application/json
{"strings":[{"first_led_id":0,"length":105}],"code":1000}
Response from Icicle firmware family “G”:
HTTP/1.1 200 OK
Server: esp-httpd/0.5
Transfer-Encoding: chunked
Content-Type: application/json
{"strings":[{"first_led_id":0,"length":95},{"first_led_id":95,"length":95}],"code":1000}
Set LED config
Since firmware version 1.99.18.
HTTP request
POST /xled/v1/led/config
- X-Auth-Token
Authentication token
Parameters
Parameters as JSON object.
- strings
Array of objects
Item of strings array is object:
- first_led_id
(integer), e.g. 0
- length
(integer), e.g. 105
Response
The response will be an object.
- code
(integer), application return code.
Example
Request:
POST /xled/v1/led/config HTTP/1.1
Host: 192.168.4.1
X-Auth-Token: 5jPe+ONhwUY=
Content-Type: application/json
Content-Length: 45
{"strings":[{"first_led_id":0,"length":100}]}
Response:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 13
Content-Type: application/json
{"code":1000}
Upload full movie
Effect is sent in body of the request. If mode is movie it starts playing this effect.
Since firmware version 1.99.18.
HTTP request
POST /xled/v1/led/movie/full
- X-Auth-Token
Authentication token
- Content-Type
“application/octet-stream”
Response
The response will be an object.
- code
(integer), application return code.
- frames_number
(integer) number of received frames
Get LED movie config
Since firmware version 1.99.18.
HTTP request
GET /xled/v1/led/movie/config
- X-Auth-Token
Authentication token
Response
The response will be an object.
- frame_delay
(integer)
- leds_number
(integer) seems to be total number of LEDs to use
- loop_type
(integer), e.g. 0
- frames_number
(integer)
- sync
(object)
- mic
(object), since firmware family “G” version 2.4.21 until 2.4.30 and firmware family “F” version 2.4.14 until 2.4.30.
- code
(integer), application return code.
Contents of object sync:
- mode
(string)
- slave_id
(string), e.g. “”. Defined if mode is “slave”. Since firmware version 2.5.6 not present if empty
- master_id
(string), e.g. “”. Defined if mode is “slave” or “master”. Since firmware version 2.5.6 not present if empty
- compat_mode
(number), default 0. Since firmware version 2.5.6.
Contents of object mic:
- filters
array of objects
- brightness_depth
(integer)
- hue_depth
(integer)
- value_depth
(integer)
- saturation_depth
(integer)
Contents of mode is one of:
“none”
“master”
“slave”
Contents of compat_mode is one of:
0
1 - maybe if joined with older version, e.g. gen I device?
Example
Request:
GET /xled/v1/led/movie/config HTTP/1.1
Host: 192.168.4.1
X-Auth-Token: 5jPe+ONhwUY=
Response from firmware family “D”:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 134
Content-Type: application/json
{"frame_delay":40,"leds_number":105,"loop_type":0,"frames_number":325,"sync":{"mode":"none","slave_id":"","master_id":""},"code":1000}
Response from firmware family “G”:
HTTP/1.1 200 OK
Server: esp-httpd/0.5
Transfer-Encoding: chunked
Content-Type: application/json
{"frame_delay":0,"leds_number":0,"loop_type":0,"frames_number":0,"sync":{"mode":"none","slave_id":"","master_id":""},"mic":{"filters":[],"brightness_depth":0,"hue_depth":0,"value_depth":0,"saturation_depth":0},"code":1000}
Set LED movie config
Since firmware version 1.99.18.
HTTP request
POST /xled/v1/led/movie/config
- X-Auth-Token
Authentication token
Parameters
Parameters as JSON object.
- frame_delay
(integer) the delay in milliseconds between two consecutive frames. For n fps, this is 1000 / n.
- leds_number
(integer) seems to be total number of LEDs to use
- frames_number
(integer)
Response
The response will be an object.
- code
(integer), application return code.
Get brightness
Gets the current brightness level.
For devices with firmware family “D” since version 2.3.5.
For devices with firmware family “F” since 2.4.2.
For devices with firmware family “G” since version 2.4.21.
HTTP request
GET /xled/v1/led/out/brightness
- X-Auth-Token
Authentication token
Response
The response will be an object.
- code
(integer), application return code.
- mode
(string) one of “enabled” or “disabled”.
- value
(integer) brightness level in range of 0..100
Mode string displays if the dimming is applied. The led shines at full brightness regardless of what value is set if the mode is disabled. Brightness level value represents percent so 0 is dark and 100 is maximum brightness.
Example
Request:
GET /xled/v1/led/out/brightness HTTP/1.1
Host: 192.168.4.1
X-Auth-Token: 5jPe+ONhwUY=
Response:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 42
Content-Type: application/json
{"value":100,"mode":"enabled","code":1000}
Set brightness
Sets the brightness level.
For devices with firmware family “D” since version 2.3.5.
For devices with firmware family “F” since 2.4.2.
For devices with firmware family “G” since version 2.4.21.
HTTP request
POST /xled/v1/led/out/brightness
- X-Auth-Token
Authentication token
Parameters
Parameters as JSON object.
- mode
(string) one of “enabled”, “disabled”
- type
(string) either “A” for Absolute value or “R” for Relative value
- value
(signed integer) brightness level in range of 0..100 if type is “A”, or change of level in range -100..100 if type is “R”
When mode is “disabled” no dimming is applied and the led works at full brightness. It is not necessary to submit all the parameters, basically it would work if only value or mode is supplied. type parameter can be omitted (“A” is the default). The brightness level value is in percent so 0 is dark and maximum meaningful value is 100. Greater values are possible but don’t seem to have any effect.
Response
The response will be an object.
- code
(integer), application return code.
Example
Set the brightness level to 10%:
Request:
POST /xled/v1/led/out/brightness HTTP/1.1
Host: 192.168.4.1
X-Auth-Token: 5jPe+ONhwUY=
Content-Type: application/json
Content-Length: 41
{"mode":"enabled","type":"A","value":100}
Response:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 13
{"code":1000}
Get saturation
Gets the current saturation level.
For devices with firmware family “D” since version 2.3.5.
For devices with firmware family “F” since 2.4.2.
For devices with firmware family “G” since version 2.4.21.
HTTP request
GET /xled/v1/led/out/saturation
- X-Auth-Token
Authentication token
Response
The response will be an object.
- code
(integer), application return code.
- mode
(string) one of “enabled” or “disabled”.
- value
(integer) saturation level in range of 0..100
Mode string displays if desaturation is applied. The led shines with full color regardless of what value is set if the mode is disabled. Saturation level value represents percent so 0 is completely black-and-white and 100 is full color.
Example
Request:
GET /xled/v1/led/out/saturation HTTP/1.1
Host: 192.168.4.1
X-Auth-Token: 5jPe+ONhwUY=
Response:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 37
Content-Type: application/json
{"value":"100,"mode":"enabled","code":1000}
Set saturation
Sets the saturation level.
For devices with firmware family “D” since version 2.3.5.
For devices with firmware family “F” since 2.4.2.
For devices with firmware family “G” since version 2.4.21.
HTTP request
POST /xled/v1/led/out/saturation
- X-Auth-Token
Authentication token
Parameters
Parameters as JSON object.
- mode
(string) one of “enabled”, “disabled”
- type
(string) either “A” for Absolute value or “R” for Relative value
- value
(signed integer) saturation level in range of 0..100 if type is “A”, or change of level in range -100..100 if type is “R”
When mode is “disabled” no desaturation is applied and the led works at full color. It is not necessary to submit all the parameters, basically it would work if only value or mode is supplied. type parameter can be omitted (“A” is the default). The saturation level value is in percent so 0 is completely black-and-white and maximum meaningful value is 100. Greater values are possible but don’t seem to have any effect.
Response
The response will be an object.
- code
(integer), application return code.
Example
Decrease the saturation level with 20%:
Request:
POST /xled/v1/led/out/saturation HTTP/1.1
Host: 192.168.4.1
X-Auth-Token: 5jPe+ONhwUY=
Content-Type: application/json
Content-Length: 43
{"mode":"enabled","type":"R","value":-20}
Response:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 13
{"code":1000}
Set LED driver parameters
Since firmware version 1.99.18.
HTTP request
POST /xled/v1/led/driver_params
- X-Auth-Token
Authentication token
Parameters
Parameters as JSON object.
- t0h
(integer)
- t0l
(integer)
- t1h
(integer)
- t1l
(integer)
- tendh
(integer)
- tendl
(integer)
Response
The response will be an object.
- code
(integer), application return code
Reset LED
HTTP request
GET /xled/v1/led/reset
- X-Auth-Token
Authentication token
Response
The response will be an object.
- code
(integer), application return code.
Reset2 LED
Maybe reboot?
HTTP request
GET /xled/v1/led/reset2
- X-Auth-Token
Authentication token
Response
The response will be an object.
- code
(integer), application return code.
Send Realtime Frame
Used by application during lights mapping.
Frame without any header is sent in the request body.
HTTP request
POST /xled/v1/led/rt/frame
- X-Auth-Token
Authentication token
- Content-Type
“application/octet-stream”
Response
The response will be an object.
- code
(integer), application return code.
Get firmware version
Note: no authentication needed.
Since firmware version 1.99.18.
HTTP request
GET /xled/v1/fw/version
Response
The response will be an object.
- code
(integer), application return code.
- version
(string)
Example
Request:
GET /xled/v1/fw/version HTTP/1.1
Host: 192.168.4.1
Accept: */*
Response:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 33
Content-Type: application/json
{"version":"1.99.24","code":1000}
Get Status
Since firmware version 1.99.18.
HTTP request
GET /xled/v1/status
Response
The response will be an object.
- code
(integer), application return code.
Example
Request:
GET /xled/v1/status HTTP/1.1
Host: 192.168.4.1
Content-Type: application/json
Response:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 13
Content-Type: application/json
{"code":1000}
Update firmware
Initiates firmware update.
Since firmware version 1.99.18.
HTTP request
POST /xled/v1/fw/update
- X-Auth-Token
Authentication token
Parameters
Parameters as JSON object.
- checksum
(object)
Checksum object parameters for generation I devices:
- stage0_sha1sum
(string) SHA1 digest of first stage
- stage1_sha1sum
(string) SHA1 digest of second stage
Checksum object parameters for generation II devices:
- stage0_sha1sum
(string) SHA1 digest of first stage
Response
The response will be an object.
- code
(integer), application return code.
Example
Request for generation I device:
POST /xled/v1/fw/update HTTP/1.1
X-Auth-Token: 5jPe+ONhwUY=
Content-Type: application/json
Content-Length: 134
Host: 192.168.4.1
{"checksum":{"stage0_sha1sum":"1c705292285a1a5b8558f7b39abd22c5550606b5","stage1_sha1sum":"ac691b8d4563dcdbb3f837bf3db2ebf56fe77fbe"}}
Response:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 13
Content-Type: application/json
{"code":1000}
Upload first stage of firmware
First stage of firmware is uploaded in body of the request.
Since firmware version 1.99.18.
HTTP request
POST /xled/v1/fw/0/update
- X-Auth-Token
Authentication token
- Content-Type
“application/octet-stream”
Response
The response will be an object.
- code
(integer), application return code.
- sha1sum
SHA1 digest of uploaded firmware.
Upload second stage of firmware
Second stage of firmware is uploaded in body of the request.
Since firmware version 1.99.18.
Used only for generation I devices.
HTTP request
POST /xled/v1/fw/1/update
- X-Auth-Token
Authentication token
- Content-Type
“application/octet-stream”
Response
The response will be an object.
- code
(integer), application return code.
- sha1sum
SHA1 digest of uploaded firmware.
Get list of movies
Retrieve the identities and parameters of all uploaded movies.
Available since firmware version 2.5.6.
HTTP request
GET /xled/v1/movies
- X-Auth-Token
Authentication token
Response
The response will be an object.
- code
(integer), application return code.
- movies
Array of objects
- available_frames
(integer), e.g. 992
- max_capacity
(integer), e.g. 992
Where each item of movies is an object.
- id
(integer), e.g. 0
- name
(string)
- unique_id
(string), UUID
- descriptor_type
(string), e.g “rgbw_raw” for firmware family “G” or “rgb_raw” for firmware family “F”
- leds_per_frame
(integer), e.g. 210
- frames_number
(integer), e.g. 4
- fps
(integer), e.g. 0
Example
Request:
GET /xled/v1/movies HTTP/1.1
Host: 192.168.1.2
X-Auth-Token: 5jPe+ONhwUY=
Response with empty list of movies:
HTTP/1.1 200 OK
Server: esp-httpd/0.5
Transfer-Encoding: chunked
Content-Type: application/json
{"movies":[],"available_frames":992,"max_capacity":992,"code":1000}
Delete movies
Remove all uploaded movies.
Any existing playlist will be removed as well. This call only works if the device is not in movie or playlist mode.
Available since firmware version 2.5.6.
HTTP request
DELETE /xled/v1/movies
- X-Auth-Token
Authentication token
Response
The response will be an object.
- code
(integer), application return code.
Create new movie entry
Available since firmware version 2.5.6.
HTTP request
POST /xled/v1/movies/new
- X-Auth-Token
Authentication token
Parameters
Parameters as JSON object.
- name
(string)
- unique_id
(string), UUID
- descriptor_type
(string), e.g “rgbw_raw”,
- leds_per_frame
(integer), e.g. 210
- frames_number
(integer), e.g. 4
- fps
(integer), e.g. 0
Response
The response will be an object.
- code
(integer), application return code.
Upload new movie to list of movies
Available since firmware version 2.5.6.
Effect is received in body of the request. This call must be preceeded by a call to movies/new.
HTTP request
POST /xled/v1/movies/full
- X-Auth-Token
Authentication token
- Content-Type
“application/octet-stream”
Response
The response will be an object.
- code
(integer), application return code.
Get current movie
Gets the id of the movie shown when in movie mode.
Since firmware version 2.5.6.
HTTP request
GET /xled/v1/led/movies/current
- X-Auth-Token
Authentication token
Response
The response will be an object.
- code
(integer), application return code.
- id
(integer), numeric id of movie, in range 0 .. 15
- unique_id
(string), UUID of movie.
- name
(string), name of movie.
Example
Request:
GET /xled/v1/led/movies/current HTTP/1.1
Host: 192.168.4.1
Content-Type: application/json
X-Auth-Token: 5jPe+ONhwUY=
Response:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 81
Content-Type: application/json
{"id":0,"unique_id":"00000000-0000-0000-0000-800000000000","name":"","code":1000}
Set current movie
Sets which movie to show when in movie mode.
Since firmware version 2.5.6.
HTTP request
POST /xled/v1/led/movies/current
- X-Auth-Token
Authentication token
Parameters
Parameters as JSON object.
- id
(int), id of movie, in range 0 .. 15.
Response
The response will be an object.
- code
(integer), application return code.
Example
Request:
POST /xled/v1/led/movies/current HTTP/1.1
Host: 192.168.4.1
Content-Type: application/json
X-Auth-Token: 5jPe+ONhwUY=
Content-Length: 8
{"id":0}
Response:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 13
Content-Type: application/json
{"code":1000}
Initiate WiFi network scan
Since firmware version 1.99.18.
HTTP request
GET /xled/v1/network/scan
- X-Auth-Token
Authentication token
Response
The response will be an object.
- code
(integer), application return code.
Get results of WiFi network scan
Since firmware version 1.99.18.
HTTP request
GET /xled/v1/network/scan_results
- X-Auth-Token
Authentication token
Response
The response will be an object.
- code
(integer), application return code.
- networks
Array of objects
Item of networks array is object:
- ssid
(string)
- mac
(string)
- rssi
(number) negative number
- channel
(integer)
- enc
One of numbers 0 (Open), 1 (WEP), 2 (WPA-PSK), 3 (WPA2-PSK), 4 (WPA-PSK + WPA2-PSK), 5 (WPA2-EAP).
Response seems to correspond with AT command CWLAP.
Get network status
Gets network mode operation.
Since firmware version 1.99.18.
HTTP request
GET /xled/v1/network/status
- X-Auth-Token
Authentication token
Response
The response will be an object.
- mode
(enum) 1 or 2
- station
(object)
- ap
(object)
- code
(integer), application return code.
Contents of object station for firmware family “D”:
- ssid
(string), SSID of a WiFi network to connect to
- ip
(string), IP address of the device
- gw
(string), IP address of the gateway
- mask
(string), subnet mask
- status
(integer), status of the network connection: 5 = connected, 255 = AP is used
Contents of object station for firmware family “G” since firmware version 2.4.21 and “F” since 2.2.1:
- ssid
(string), SSID of a WiFi network to connect to. If empty string is passed it defaults to prefix ESP_ instead of Twinkly_.
- ip
(string), IP address of the device
- gw
(string), IP address of the gateway
- mask
(string), subnet mask
Contents of object ap:
- ssid
(string), SSID of the device
- channel
(integer), channel number
- ip
(string), IP address
- enc
(enum), 0 for no encryption, 2 for WPA1, 3 for WPA2, 4 for WPA1+WPA2
- ssid_hidden
(integer), default 0. Since firmware version 2.4.25.
- max_connection
(integer), default 4. Since firmware version 2.4.25.
- password_changed
(integer), either hidden or set to 1 if default password for AP was changed.
Example
Request:
GET /xled/v1/network/status HTTP/1.1
Host: 192.168.1.2
X-Auth-Token: 5jPe+ONhwUY=
Response:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 187
Content-Type: application/json
{"mode":1,"station":{"ssid":"home","ip":"192.168.1.2","gw":"192.168.1.1","mask":"255.255.255.0","status":5},"ap":{"ssid":"Twinkly_33AAFF","channel":11,"ip":"0.0.0.0","enc":0},"code":1000}
Set network status
Sets network mode operation.
Since firmware version 1.99.18.
HTTP request
POST /xled/v1/network/status
- X-Auth-Token
Authentication token
Parameters
Parameters as JSON object.
- mode
(enum), required: 1 or 2
- station
(object) optional, if mode set to 1 this parameter could provide additional details.
- ap
(object) optional, if mode set to 2 this parameter could provide additional details.
station object parameters:
- dhcp
(integer) 1
- ssid
(string) SSID of a WiFi network until firmare version 2.4.25
- encssid
(string) encrypted SSID of a WiFi network since firmare version 2.4.30.
- encpassword
(string) encrypted password.
ap object parameters:
- ssid
(string), required SSID of a WiFi network
- encpassword
(string), optional encrypted password.
- password
(string), optional plaintext password. Since firmware version 2.4.25 (?).
- enc
(enum), optional type of encryption. See above in Get network status. Defaults to 0 if not part of the request. If a request has enc value 1, get will return 0 as well.
- channel
(integer), optional
- ssid_hidden
(integer), optional, 0 to broadcast SSID, 1 to hide. Since firmware version 2.4.25.
- max_connection
(integer), optional, value from 1 to 4. Since firmware version 2.4.25.
Response
The response will be an object.
- code
(integer), application return code.
Example
Request to change network mode to client and connect to SSID “home” with password “Twinkly”. Encoded with MAC address ‘5C:CF:7F:33:AA:FF’:
POST /xled/v1/network/status HTTP/1.1
Host: 192.168.4.1
Content-Type: application/json
X-Auth-Token: 5jPe+ONhwUY=
Content-Length: 150
{"mode":1,"station":{"ssid":"home","encpassword":"e4XXiiUhg4J1FnJEfUQ0BhIji2HGVk1NHU5vGCHfyclFdX6R8Nd9BSXVKS5nj2FXGU6SWv9CIzztfAvGgTGLUw==","dhcp":1}}
Request to change network mode to AP:
POST /xled/v1/network/status HTTP/1.1
Host: 192.168.1.100
Content-Type: application/json
X-Auth-Token: 5jPe+ONhwUY=
Content-Length: 10
{"mode":2}
Get MQTT configuration
For devices with firmware family “D” since version 2.0.22.
For devices with firmware family “F” since version 2.4.2.
For devices with firmware family “G” since version 2.4.21.
HTTP request
GET /xled/v1/mqtt/config
- X-Auth-Token
Authentication token
Response
The response will be an object.
For firmware family “D”:
- code
(integer), application return code.
- broker_host
(string), hostname of broker. By default mqtt.twinkly.com.
- broker_port
(integer), destination port of broker. By default “1883”.
- client_id
(string), see section MQTT Client ID in Protocol details.
- encryption_key_set
(bool), by default “False”
- keep_alive_interval
(integer), by default “180”.
- user
(string), by default “twinkly_noauth”
For firmware family “G” since firmware version 2.4.21 and “F” since 2.4.2:
- code
(integer), application return code.
- broker_host
(string), hostname of broker. By default mqtt.twinkly.com.
- broker_port
(integer), destination port of broker. By default “8883”.
- client_id
(string), see section MQTT Client ID in Protocol details.
- keep_alive_interval
(integer), by default “60”.
- user
(string), by default “twinkly32”
- password
(string), only in firmware family “F” since 2.4.2 until 2.4.14.
Example
Request:
GET /xled/v1/mqtt/config HTTP/1.1
Host: 192.168.4.1
Content-Type: application/json
X-Auth-Token: mfqEJHHKJR8=
Response from firmware family “D”:
HTTP/1.1 200 Ok
Connection: close
Content-Length: 169
Content-Type: application/json
{"broker_host":"mqtt.twinkly.com","broker_port":1883,"client_id":"5CCF7F33AAFF","user":"twinkly_noauth","keep_alive_interval":180,"encryption_key_set":false,"code":1000}
Response from firmware family “G”:
HTTP/1.1 200 OK
Server: esp-httpd/0.5
Transfer-Encoding: chunked
Content-Type: application/json
{"broker_host":"mqtt.twinkly.com","broker_port":8883,"client_id":"98F4AB1CC190","user":"twinkly32","keep_alive_interval":60,"code":1000}
Set MQTT configuration
Since firmware version: 2.0.22
HTTP request
POST /xled/v1/mqtt/config
- X-Auth-Token
Authentication token
Parameters
Parameters as JSON object.
For firmware family “D” since firmware version 2.0.22 and firmware family “G” since firmware version 2.4.21 and firmware family “F” since version 2.4.2:
- broker_host
(string), optional hostname of a broker
- client_id
(string), optional
- keep_alive_interval
(integer), optional
- user
(string), optional
Response
The response will be an object.
- code
(integer), application return code.
Get playlist
Available since firmware version 2.5.6.
HTTP request
GET /xled/v1/playlist
- X-Auth-Token
Authentication token
Response
The response will be an object.
- code
(integer), application return code.
- entries
Array of objects
Where each item of entries is an object.
- duration
(integer), in seconds, e.g. 10
- unique_id
(string), UUID
Example
Request:
GET /xled/v1/movies HTTP/1.1
Host: 192.168.1.2
X-Auth-Token: 5jPe+ONhwUY=
Response:
HTTP/1.1 200 OK
Server: esp-httpd/0.5
Transfer-Encoding: chunked
Content-Type: application/json
{"entries":[],"code":1000}
Create playlist
Available since firmware version 2.5.6.
HTTP request
POST /xled/v1/playlist
- X-Auth-Token
Authentication token
Parameters
Parameters as JSON object.
- entries
Array of objects
Where each item of entries is an object.
- duration
(integer), in seconds, e.g. 10
- unique_id
(string), UUID
Response
The response will be an object.
- code
(integer), application return code.
Delete playlist
Available since firmware version 2.5.6.
HTTP request
DELETE /xled/v1/playlist
- X-Auth-Token
Authentication token
Response
The response will be an object.
- code
(integer), application return code.
Get current playlist entry
Gets which movie is currently played in playlist mode.
Available since firmware version 2.5.6.
HTTP request
GET /xled/v1/playlist/current
- X-Auth-Token
Authentication token
Response
The response will be an object.
- id
(integer), 0
- unique_id
(string), UUID
- name
(string)
- code
(integer), application return code.
Set current playlist entry
Sets which movie to jump to when in playlist mode.
When entering playlist mode, it always starts from the first entry in the playlist, so this call is only useful when already in playlist mode.
Available since firmware version 2.5.6.
HTTP request
POST /xled/v1/led/playlist/current
- X-Auth-Token
Authentication token
Parameters
Parameters as JSON object.
- id
(int), id of movie to jump to, e.g. 0.
Response
The response will be an object.
- code
(integer), application return code.
Get mic config
Since firmware version 2.4.2 until 2.4.30.
HTTP request
GET /xled/v1/mic/config
- X-Auth-Token
Authentication token
Response
The response will be an object.
- filters
array of objects
- silence_threshold
(integer), default 0
- active_range
(integer), default 0
- brightness_depth
(integer), default 255
- hue_depth
(integer), default 255
- value_depth
(integer), default 255
- saturation_depth
(integer), default 255
- code
(integer), application return code.
Example
Request:
GET /xled/v1/mic/config HTTP/1.1
Host: 192.168.4.1
X-Auth-Token: 5jPe+ONhwUY=
Response:
HTTP/1.1 200 OK
Server: esp-httpd/0.5
Transfer-Encoding: chunked
Content-Type: application/json
{"filters":[],"silence_threshold":0,"active_range":0,"brightness_depth":255,"hue_depth":255,"value_depth":255,"saturation_depth":255,"code":1000}
Get mic sample
Since firmware version 2.4.2 until 2.4.30.
HTTP request
GET /xled/v1/mic/sample
- X-Auth-Token
Authentication token
Response
The response will be an object.
- sampled_value
(integer), e.g. 0
- code
(integer), application return code.
Example
Request:
GET /xled/v1/mic/sample HTTP/1.1
Host: 192.168.4.1
X-Auth-Token: 5jPe+ONhwUY=
Response:
HTTP/1.1 200 OK
Server: esp-httpd/0.5
Transfer-Encoding: chunked
Content-Type: application/json
{"sampled_value":0,"code":1000}
Get summary
Since firmware version 2.5.6.
HTTP request
GET /xled/v1/summary
- X-Auth-Token
Authentication token
Response
The response will be an object.
- led_mode
(object) corresponds to response of Get LED operation mode without code.
- timer
(object) corresponds to response of Get Timer without code.
- music
(object)
- filters
Array of objects
- group
(object) corresponds to sync object from response of Get LED movie config without code.
- layout
(object)
- color
(object) corresponds to response of Get LED color without code. Since firmware version 2.7.1
- code
(integer), application return code.
Where music contains:
- enabled
(integer), e.g. 1
- active
(integer), e.g. 0
- current_driverset
(integer), e.g. 1
Where each item of filters is an object:
- filter
(string), one of “brightness”, “hue”, “saturation”
- config
(object)
Where config consists of:
- value
(integer), e.g. 0
- mode
(string), e.g. “disabled”
Object layout consists of:
- uuid
(string) UUID
Get music drivers
Since firmware version 2.5.6.
HTTP request
GET /xled/v1/music/drivers
- X-Auth-Token
Authentication token
Response
The response will be an object.
- drivers_number
(integer), e.g. 26
- unique_ids
(array), each entry is UUID string
- code
(integer), application return code.
Get music drivers sets
Since firmware version 2.5.6.
HTTP request
GET /xled/v1/music/drivers/sets
- X-Auth-Token
Authentication token
Response
The response will be an object.
- current
(integer), e.g. 26
- count
(integer), e.g. 3
- driversets
(array)
- code
(integer), application return code.
Where each item of driversets is an object:
- id
(integer)
- count
(integer)
- unique_ids
(array), each entry is UUID string
Get current music driverset
Since firmware version 2.5.6.
HTTP request
GET /xled/v1/music/drivers/sets/current
- X-Auth-Token
Authentication token
Response
The response will be an object.
- driverset_id
(integer), e.g. 0
- code
(integer), application return code.