Wenn der Jahresurlaub ansteht, ist das nicht nur ein guter Zeitpunkt um das Jahr ausklingen zu lassen - auch technische Spielereien dürfen nicht zu kurz kommen. Eine solche Spielerei sind die programmierbaren RGB-Lichterketten von Twinkly. Diese gibt es in verschiedenen Formen (Sterne, Herzen, Kerzen, Perlen) und Längen (100, 250, 400 oder 600 LEDs) und können über WLAN gesteuert werden.

Bedauerlicherweise hat der Hersteller hierfür nur den Weg über die eigene App vorgesehen. Diese übernimmt die erste WLAN-Konfiguration und steuert die Lichterkette über eine HTTP API. Eine weitere Funktion ist das Erstellen eigener Animationen. Leider wird hierfür unverständlicherweise ein Account vorausgesetzt.

Zum Glück werden die Produkte schon seit einiger Zeit produziert, weswegen die API via Reverse Engineering dokumentiert wurde. Das xled-Projekt hat neben der API auch weitere technische Details dokumentiert und Kommandozeilen-Anwendungen entwickelt, um die Benutzung ohne Hersteller-App zu ermöglichen.

Onboarding

Eine Option ist es, die initiale WLAN-Konfiguration über BLE (Bluetooth Low Energy) vorzunehmen. Hierfür muss zunächst die MAC-Adresse der Bluetooth-Schnittstelle ausgelesen werden. Durch 5-sekündiges Gedrückthalten der Taste auf dem Controller sollte diese gefunden werden:

1# bluetoothctl 
2[bluetooth]# scan on
3[bluetooth]# SetDiscoveryFilter success
4[bluetooth]# hci0 type 7 discovering on
5[bluetooth]# Discovery started
6[bluetooth]# [NEW] Device xx:xx:xx:xx:xx:xx Twinkly_xxxxxD

Im xled-shell-Repository findet sich eine Anwendung zur Konfiguration des Netzwerks:

 1$ ./configure-wifi-over-bluetooth-sta xx:xx:xx:xx:xx:xx 'SSID' 'PASSPHRASE'
 2#1 Getting the Wi-Fi list.
 3#2 ?
 4#3 Setting opmode to WiFi
 5#4 Gettting WiFi status
 6#5 ?
 7#6 Sending SSID
 8#7 Sending password
 9#8 Switching to STA mode
10#9 Switching WiFi status
11#10 Disconnecting from BLE GATT link

Bei manchen Geräten funktioniert das nicht zuverlässig. Hier kann es helfen, das Gerät auf Werkseinstellungen zurückzusetzen um einen integrierten Access Point zu aktivieren. Hierzu muss das Gerät mit gedrücktem Knopf eingesteckt werden - der Knopf muss solange gedrückt werden, bis die LED den Vorgang bestätigt.

Anschließend sollte ein WLAN-Netzwerk Twinkly_xxxx erscheinen - das Standard-Passwort ist Twinkly2019. Nachdem die Verbindung hergestellt wurde, muss die MAC-Adresse des WLAN-Adapters ausgelesen werden:

1$ ./get 192.168.4.1 gestalt | jq -r .mac
2xx:xx:xx:xx:xx:xx

Über ein weiteres Skript wird nun die MAC-Adresse für die Verschlüsselung der SSID und der Passphrase benutzt:

1$ ./encrypt.py 'xx:xx:xx:xx:xx:xx' 'SSID' 'PASSPHRASE'
2Encrypted SSID: ...
3Encrypted password: ...

Die verschlüsselten Informationen müssen nun nur noch per POST-Request zum Controller gesendet werden:

1$ echo '{"mode":1,"station":{"dhcp":1,"encssid":"XXX","encpassword":"XXX"}}' | ./post-json 192.168.4.1 network/status
2POST network/status
3{
4"code": 1000
5}

Anschließend sollte das Gerät im WLAN-Netzwerk auftauchen.

Home Assistant-Integration

Für Home Assistant gibt es eine Twinkly-Integration, die jedoch einen recht störenden Bug aufweist: das Gerät wird als offline angezeigt, sofern keine eigene Animation (Movie) erstellt wurde.

Der Workaround besteht darin, eine Animation anzulegen. Wenn man die App nicht benutzen möchte, hilft es das xled_plus-Paket zu installieren. In diesem finden sich einige fertige Animationen - durch Ausführen werden diese auf dem Controller angelegt:

1$ pip3 install --user xled_plus
2$ python3 -m xled_plus.samples.day8
3$ python3 -m xled_plus.samples.day12
4$ python3 -m xled_plus.samples.day13
5$ python3 -m xled_plus.samples.day24

Das Erstellen eigener Animationen gestaltet sich ohne die App schwieriger - ein Blick in den Quellcode der Beispiele kann als Inspirationsquelle dienen. Das colorsphere-Paket enthält außerdem einen rudimentären Editor:

1$ pip3 install --user colorsphere
2$ python3 -m xled_plus.xled_colorcontrol

Anschließend taucht der Controller in Home Assistant auf und kann von dort gesteuert werden. Neben der Helligkeit können einzelne Farben oder angelegte Animationen ausgewählt werden: