Twinkly christmas lights integration

It looks like they were able to get some significant progress over at Home Assistant (the guy who documented the private API is active over there too)


Also useful:

It’s beginning to look a little like christmas :wink: So i’m diving into the Twinkly lights and made a little progress.

What i can achieve in Openhab:

Turning ON the lights
Turning OFF the lights

What i can’t achieve is:

Setting (and reading) the brightness level.

I managed it by using the Python file from : (

I copied it to a location where i can run scripts from (in my case: /var/lib/openhab2) and called the python file via executecommand (executeCommandLine(“python3 THE_IP_ADDRESS on”). You can change on to off to turn it off :slight_smile:

I’m not a python programmer but i can image we can change the python file so we can send a brightness level or other things to the lights. I tried to change the python file but i only managed to turn the lights off when i send my own brighness command. I use this site as a reference for commands:

Maybe there is someone who knows how to change the python file to send a brightness command.

In the file i added:


and called it via: onRequest = urllib.request.Request(url = BRIGHT_URL, headers = HEADERS, data = formatData(BRIGHTNESS_DATA))

But this doesn’t work. Hope someone has a sollution!

1 Like

That’s great - this simple control (on/off) is great to have, and I’ve now implemented it in mys system to have the tree come on with the ‘wake up’ lights now.

I’m also not a python programmer, and if you haven’t already found it, I’m guessing more information on the twinkly API could be found here:
It’s for a different implementation of a twinkly python interface, but it should give clues.

[edit: I had replied to this post through email, thinking it was a direct message of sorts, thus not realizing this was in the thread where the various resources were discussed at length already - sorry for that!]

YES! I succeeded! I visited a Home assistant forum and there was a guy: David who made a python file for home assistant and he managed to change the brightness. Not sure why, but the syntax is different from the website.

Long story short, a made a python file which you guys could use. The syntax is simple, just call the file with brightness and it’s value at the end:

python3 192.168.x.x brightness 50

I use this in openhab in my sitemap and when the livingroom lights dim or go brighter. You can use the excuteCommandLine but you have to whitelist the command (exec.whitelist).

Because I use it this way, the value doesn’t change when i dim the light through the app or by voice command (google). I think it would be possible but then i have to create a timer or make a execute command thing with a timeout. I would have to change the python file so it can read the brightness, but i didn’t try that because it isn’t of any use in my situation.

Only problem is, where to drop the file? Just send me a PM or a location to put it and i will upload it there. I’m on github but I don’t know how to upload files there.

(forgot to press reply earlier this evening haha)

1 Like

Good for you!!

You can drop the code here on the forums - paste it within code fences (the button before the config gear above the message entry text box). The other linked is pretty short, and I imagine the addition of brightness control won’t lengthen it substantially.

Alternately, pastebin or a similar service, and leave the link here.

[for myself, the simple on/off is likely 90% of the benefit. The kids love playing with the app controlling the patterns/movies, so there wouldn’t be meaningful display of house information in the color/pattern/brightness. The last 10% would be a huge undertaking of time, as I’d want to create a fluctuating red blob that changes size with spoken voice - a la HAL from 2001 a Space Odyssey. I think that is one fantasy that is better in my head than seen by my wife after spending far too long isolated in my office working on it. This being said, … nah, I probably shouldn’t…].

1 Like

The code is pretty similar so i just paste it here, one could easily copy it and save it on their openhab setup.

That HAL idea is really awesome but almost impossible i think. Twinkly is very hard to control per LED i read so that’s a no for me. Our christmas tree is next to the TV, that’s the reason i want to dim it when we are watching tv.

So here is the code for anyone who want to use it:

import sys
import json
import urllib.request
import codecs

ARG_ON = 'on'
ARG_OFF = 'off'
ARG_STATE = 'state'
ARG_BRIGHT = 'brightness'

ARG_IP = sys.argv[1]
ARG_ACTION = sys.argv[2]

URL = "http://" + ARG_IP + "/xled/v1/"

LOGIN_URL = URL + "login"
VERIFY_URL = URL + "verify"
MODE_URL = URL + "led/mode"
BRIGHT_URL = URL + "led/out/brightness"

AUTH_HEADER = 'X-Auth-Token'

AUTHENTICATION_TOKEN = 'authentication_token'
CHALLENGE_RESPONSE = 'challenge-response'
MODE = 'mode'
MODE_ON = 'movie'
MODE_OFF = 'off'

HEADERS = {'Content-Type': 'application/json'}

if len(sys.argv) > 3: #check if the thirth argument is given, save it in a variable and create the brightness data variable
    ARG_ACTION2 = int(sys.argv[3])
    BRIGHTNESS_DATA = {'value': ARG_ACTION2, 'type': 'A'}

def formatData(data):
  return json.dumps(data).encode('utf8')

def processRequest(request):
  return urllib.request.urlopen(request)

def processRequestJSON(request):
  loginResponse = processRequest(request)
  reader = codecs.getreader("utf-8")
  return json.load(reader(loginResponse))

# login to api - get challenge response and auth token
loginRequest = urllib.request.Request(url = LOGIN_URL, headers = HEADERS, data = formatData(LOGIN_DATA))
loginData = processRequestJSON(loginRequest)

challengeResponse = loginData[CHALLENGE_RESPONSE]
authToken = loginData[AUTHENTICATION_TOKEN]

verifyData = {CHALLENGE_RESPONSE: challengeResponse}

# verify token by responding with challenge response
verifyRequest = urllib.request.Request(url = VERIFY_URL, headers = HEADERS, data = formatData(verifyData))
verifyData = processRequestJSON(verifyRequest)

def turnOn():
  onRequest = urllib.request.Request(url = MODE_URL, headers = HEADERS, data = formatData(TURN_ON_DATA))

def turnOff():
  offRequest = urllib.request.Request(url = MODE_URL, headers = HEADERS, data = formatData(TURN_OFF_DATA))
def setBrightness():
  brightRequest = urllib.request.Request(url = BRIGHT_URL, headers = HEADERS, data = formatData(BRIGHTNESS_DATA))

def getState():
  modeRequest = urllib.request.Request(url = MODE_URL, headers = HEADERS)
  modeData = processRequestJSON(modeRequest)

  if modeData[MODE] != MODE_OFF:

Use it like this:

python3 192.168.x.x on
Turn Twinkly on
python3 192.168.x.x off
Turn Twinkly off
python3 192.168.x.x brightness 50
Set brightness to 50


Hey Guys,
I’m reading and using a lot files from this database. Perfect and no questions… till now: Could someone create a jar-File? So I could try using my new twinklys via openhab…

Thank you,

Hi, this is not a binding or java so far. I just tried the python with my new twinkly - and even if I never worked with python, it worked somehow:
I’ve installed python3 on my NAS via the Qnap-App-Store. Then I copied the script in a .py-file and with running the command from above it switches the Twinkly.
Now I have to find out how to run a .py-file via the webserver and then it should work with the http-binding. There won’t be a state information available - I guess, but switching on/off will be a good first start.

Hm, thank you for your answer…
If I got you correct, there’s still missing one step to connect it to openhab?
I asked the twinkly support team, too. Almost same words like in the upper comment. Here‘s their answer…
“Certainly not this year, I’ll pass your suggestion to our developers team.”

Cause, to be honest… just switching on/off you could solve for the few xmas weeks by using a sonoff S20.

Hi Steffen,
You could use a sonoff/smart plug, but then your on/off times will be further delayed. The device would need to boot up and connect to wifi, then your app would need to find the twinkly dwevice, then you could control it.

It isn’t hard to set up.
Copy the script to a location accessable by openhab. If using Raspberry pi/ openhabian / linux, it is likely /var/lib/openhab2 . Finally, ensure you have python3 installed. You probably do if using openhabian.

Next, figure out the IP address of your twinkly device. I logged into my router to do this. If you can reserve that IP address within your router’s system, this may help ensure the IP address doesn’t change in the future.

Then, go to a rule. I use text rules, and can’t give direction to any of the graphical/new interfaces.
You can certainly get much more complicated (and I did a bit), but in the rule you can add:

executeCommandLine("python3 on")  // turn the christmas tree on

(replacing the with the IP address of your system)

For myself, I created a summy switch called twinklyTree, and then used the following rule to control the device in a much more ‘normal’ manner elsewhere:

default.items (or whatever .items file you wish, located in openhab’s items directory)

Switch twinklyTree "Twinkly Christmas Tree" <light>

yourRules.rules (or whatever .rules file you wish, located in openhabs rules directory. Remember to edit the IP address)

rule "Twinkly Christmas Tree Power State"
  Item twinklyTree received command
  if (receivedCommand == ON) {
    executeCommandLine("python3 on")  // turn the christmas tree on
  else {
    executeCommandLine("python3 off")  // turn the christmas tree off

Finally, I simply toggle the twinklyTree switch in PaperUI, HabPanel, or send a command with twinklyTree.sendCommand(ON) or twinklyTree.sendCommand(OFF).

This should provide a complete and working implementation.

It doesn’t take long at all, you don’t need to buy anything extra (and flash then configure it). Much faster overall. I have several other rules that then turn the tree on or off as needed. I have a simple 433mHz button for the kids to toggle it on / off, and my script to shut everything off at the end of the day turns its lights off. The wake up rule in the morning turns it on.

If you wanted to go above and beyond, you could change the item to be a dimmer instead of a switch, and then send the off command if brightness 0, and otherwise send on and the brightness for all other values - if using Jeroen’s modified twinkly script above.

Edit: updated the rule to use the receivedCommand to reliably use the new command, not the possibly old switch state.


I’m using the Twinkly v1 and tried to implement it into OH.

My approach is not via python, but via the OH rules.
For me the use case was mostly turning it OFF and ON.
Started with the dimmer part, but somehow the commands are not working yet.
I also stopped using the twinkly app, because it invalidates the token used in OH :wink:

If anyone is interested, here are my files:


String    TW_Token
Switch    TW_TokenValid

Switch    TW_Power


var String twinklyAddress = "http://ip.of.your.twinkly/xled/v1"
var Timer renewTokenTimer
var String token

rule "Token expiration"
    System started or
    Item TW_TokenValid changed to OFF

    if (renewTokenTimer !== null) {
        renewTokenTimer = null

    logDebug("rules.twinkly", "twinkly address: {}", twinklyAddress)
    val loginResponse = sendHttpPostRequest(twinklyAddress + "/login", "application/json", "{\"challenge\": \"AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=\"}")
    logDebug("rules.twinkly", "login response: {}", loginResponse)
    token = transform("JSONPATH", "$.authentication_token", loginResponse)
    val String challengeResponse = transform("JSONPATH", "$.challenge_response", loginResponse)
    val String tokenExpiration = transform("JSONPATH", "$.authentication_token_expires_in", loginResponse)
    val headers = newHashMap("X-Auth-Token" -> token)
    logDebug("rules.twinkly", "headers: {}", headers)
    val verifyResponse = sendHttpPostRequest(twinklyAddress + "/verify", "application/json", "{\"challenge-response\": \"" + challengeResponse + "\"}", headers, 1000)
    logDebug("rules.twinkly", "verify response: {}", verifyResponse)
    renewTokenTimer = createTimer(now.plusSeconds(Integer.parseInt(tokenExpiration))) [|


rule "Turn on christmas lights"
    Item TW_Power changed to ON
    logInfo("rules.twinkly", "Turn christmas lights on")

    if (token === null) {

    val headers = newHashMap("X-Auth-Token" -> token)
    logInfo("rules.twinkly", "headers: {}", headers)
    val response = sendHttpPostRequest(twinklyAddress + "/led/mode", "application/json", "{\"mode\": \"movie\"}", headers, 1000)
    logInfo("rules.twinkly", "response: {}", response)
    logInfo("rules.twinkly", "Christmas lights are on")

    val brightnessResponse = sendHttpGetRequest(twinklyAddress + "/led/out/brightness", headers, 1000)  
    logInfo("rules.twinkly", "brightness response: {}", brightnessResponse)
    TW_Brightness.postUpdate(transform("JSONPATH", "$.value", brightnessResponse))  

rule "Turn off christmas lights"
    Item TW_Power changed to OFF
    logInfo("rules.twinkly", "Turn christmas lights off")

    if (token === null) {
    val headers = newHashMap("X-Auth-Token" -> token)
    val response = sendHttpPostRequest(twinklyAddress + "/led/mode", "application/json", "{\"mode\": \"off\"}", headers, 1000)
    logInfo("rules.twinkly", "response: {}", response)
    logInfo("rules.twinkly", "Christmas lights are off")

    // update brightness value

Using the switch TW_Power turns your twinkly on / off


Interesting implementation, and it’s fascinating to see it fit entirely within openhab rules.

For what it’s worth, for any others deciding on which path to use, the Python script does not invalidate the twinkly app (at least for me).
I also just stumbled across this fascinating read:

Lots to go on here.

Hi Ben,

thank you very much for your detailed explanation.
You are right, it needs bit more time by using an sonoffS20, but its just for 4 weeks in that use;-)
but you are right, its much comfortable to communicate with twinkly directly.

My OH runs on a Synology, but no big problem to fit your explanation to this circumstances.

With this, it runs. On/off… next step will be to implement the brigthness.

Regards and have a relaxing xmas time,

“just for 4 weeks”

Do you mind if I use this rationale with my family? :laughing:
I can’t claim complete innocence, though, as I may have been involved in making some decorations more extravagant than they needed-to, per say.

All the best

Hi there!

Your implementation seems like an easy way to get some kind of ON / OFF functionality working without the hassle to get into python.

I tried to use the code pretty much as is, just replacing the IP to the twinkly and i seem to get a token. So far so good. But… It throws an error in the console and it’s not really working.

[ERROR] [untime.internal.engine.RuleEngineImpl] - Rule ‘Turn off christmas lights’: An error occurred during the script execution: Could not invoke method: org.eclipse.smarthome.model.script.actions.HTTP.sendHttpPostRequest(java.lang.String,java.lang.String,java.lang.String,int) on instance: null

Any ideas here?

Best regards,

Ah yes, forgot about that!

The sendHttpPostRequest method which includes the headers is available from OH 3.0
Since I am running 2.5 is used a work around.
You need to put the following jar in your addons folder:

Thanks to @JimT in this topic:

1 Like

Thank’s a bunch! I can confirm that works. Great! :+1:

1 Like

I copied the to /var/lib/openhab and /var/lib/openhab2 (I’m running openhab3 with openhabian).
Running the python command in the commandline works.
But from the rule I got an error:

2020-12-18 08:34:36.819 [WARN ] [] - Error occurred when executing commandLine '[python3 /var/lib/openhab/ on]' Cannot run program "python3 /var/lib/openhab/ on": error=2, No such file or directory

I tried it with and without fullpath.

Which is the starting folder if I don’t use a full path?
And what is not foud? python or the script?

Have you confirmed the paths that openhab uses in your installation?
It sounds like a case for those more familliar with openhab3, unfortunately.

For anybody who used my rule above, my initial post incorrectly used the twinklyTree.state, which doesn’t reliably get updated in time for the rule operation. I have now updated it to use receivedCommand instead, and the rule seems to reliably function as intended now.

rule "Twinkly Christmas Tree Power State"
  Item twinklyTree received command
  if (receivedCommand == ON) {
    executeCommandLine("python3 on")  // turn the christmas tree on
  else {
    executeCommandLine("python3 off")  // turn the christmas tree off