jschlyter/ttls

Twinkly Twinkly Little Star

Twinkly Twinkly Little Star

ttls is a small package to help you make async requests to Twinkly LEDs. A command line tool (also called ttls) is also included, as well as some examples how to create both loadable movies and realtime sequences.

Written based on the excellent XLED documentation by @scrool.

ttls's Issues

Dependency conflict with Home Assistant

I am unable to install the latest release in Home Assistant, as it has dependency conflicts.

I believe this is the culprit:

From https://github.com/Olen/home-assistant/blob/dev/requirements.txt
aiohttp==3.8.1

From https://github.com/jschlyter/ttls/blob/main/pyproject.toml

[tool.poetry.dependencies]
(...)
aiohttp = "^3.8.3"

Is aiohttp 3.8.3 a strict requirement, or could it be downgraded to 3.8.1?
(I guess that is a simpler change than forcing Home Assistant to upgrade to 3.8.3...)

ETA for new version?

Do you have an ETA for when you might publish a new version that no longer has the print statement to PyPi? That's required to update the Home Assistant integration to complete the bug fix process.

Support RGBW-colors

When setting a static color, the current version only supports RGB-colors.
I have a PR to also support RGBW for static colors almost ready.

However, we need to agree on an architectural point before I submit it.

Devices with old software dont support the "set_static_colour()"-function, and must use the new "set_cycle_colours()" instead.
The "problem" is that Twinkly RGBW-frames have the colors in "WRGB"-order.
In HA, that uses RGBW internally, we just move the W to the first entry in the tuple for relevant devices before calling tha API.

But the function "set_static_colour()" does not handle RGBW at all today. It just ignores the W-part.

Now, I want to support RGBW for "set_static_colour()" as well. But should I stick to the rather odd "WRGB" order to make it consistent between the two functions, or should "set_static_colour()" use the more common "RGBW" order?

Another option is to introduce it as a breaking change in ttls, and have both functions use RGBW, and fix the order for the older devices directly in ttls.

I can handle both in HA, but I don't know about other implementations.

What do you suggest?

Support New Realtime Protocol

As mentioned here, it looks like the realtime protocol has either changed in a recent firmware update, or is different for devices that have > 255 lights. As I only have a 750 light Gen 2 device, I cannot confirm which.

However, I have confirmed that the protocol changes that I observed are correct for my device, and I am able to control it with the new format.

I can share the code, but it would be good if someone with an older (or smaller) device would be able to confirm if the original realtime protocol still works. This would inform whether it is best to update the current 'send_frame' or create a second variant.

License

Hey 👋🏻,

I am currently looking into the licenses at Home Assistant and apparently this dependency uses a non-OSI approved license. Please consider using a OSI approved license to support the Twinkly integration.

Twinkly unavailable after trying to set area group

After I tried to join 2 Twinkly devices as area my 2 Twinkly devices (from that group) are most of time unavailable for HomeAssistant. Even unjoining does not help.
Devices: Dots 60 + Curtain RGBW 210, I have 3x Icicles 190 RGBW groupped as normal group - these are working fine.

I have no problem with access using mobile app.

Logs based on: home-assistant/core#83076 (comment)

Unclosed client session
client_session: <aiohttp.client.ClientSession object at 0x000001540402FFA0>
Unclosed client session
client_session: <aiohttp.client.ClientSession object at 0x000001540402FA00>
Unclosed client session
client_session: <aiohttp.client.ClientSession object at 0x000001540402FD30>
== Details ==
{'bytes_per_led': 4,
 'code': 1000,
 'copyright': 'LEDWORKS 2021',
 'device_name': 'DEVICE NAME',
 'flash_size': 64,
 'frame_rate': 11.06,
 'fw_family': 'G',
 'hardware_version': '307',
 'hw_id': '793b14',
 'led_profile': 'RGBW',
 'led_type': 12,
 'mac': 'MAC',
 'max_movies': 55,
 'max_supported_led': 510,
 'measured_frame_rate': 13.33,
 'movie_capacity': 4786,
 'number_of_led': 210,
 'product_code': 'TWW210SPP2',
 'product_name': 'Twinkly',
 'uptime': '87031996',
 'uuid': 'F4946876-5A32-4DDC-8E30-9C8E16B8B5F3',
 'wire_type': 4}
== Setting color ==
Unclosed client session
client_session: <aiohttp.client.ClientSession object at 0x000001540402F400>
Unclosed client session
client_session: <aiohttp.client.ClientSession object at 0x000001540402F970>
Unclosed client session
client_session: <aiohttp.client.ClientSession object at 0x000001540402F280>
Unclosed client session
client_session: <aiohttp.client.ClientSession object at 0x000001540402F580>
== Setting color done ==
Unclosed client session
client_session: <aiohttp.client.ClientSession object at 0x000001540402F790>
== Installed movies ==
{'available_frames': 4786,
 'code': 1000,
 'max': 55,
 'max_capacity': 4786,
 'movies': []}
## Cant get current movie ##
400, message='Data after `Connection: close`:\n\n  bytearray(b\'{"code":1102}\')\n                ^', url=URL('http://192.168.0.207/xled/v1/movies/current')
Unclosed client session
client_session: <aiohttp.client.ClientSession object at 0x000001540402FD00>
## Movies are unavailable ##

----


Unclosed client session
client_session: <aiohttp.client.ClientSession object at 0x0000020C8402F820>
Unclosed client session
client_session: <aiohttp.client.ClientSession object at 0x0000020C8402FA30>
Unclosed client session
client_session: <aiohttp.client.ClientSession object at 0x0000020C8402FD30>
== Details ==
{'bytes_per_led': 3,
 'code': 1000,
 'copyright': 'LEDWORKS 2021',
 'device_name': 'DEVICE NAME',
 'flash_size': 64,
 'frame_rate': 40,
 'fw_family': 'S',
 'hardware_version': '601',
 'hw_id': '2e3258',
 'led_profile': 'RGB',
 'led_type': 33,
 'mac': 'MAC',
 'max_movies': 55,
 'max_supported_led': 500,
 'measured_frame_rate': 40,
 'movie_capacity': 21141,
 'number_of_led': 60,
 'product_code': 'TWD060STP',
 'product_name': 'Twinkly',
 'uptime': '86889260',
 'uuid': '449B7CD1-7B02-4D76-A1C5-AE11AA808DD6',
 'wire_type': 4}
== Setting color ==
Unclosed client session
client_session: <aiohttp.client.ClientSession object at 0x0000020C8402F430>
Unclosed client session
client_session: <aiohttp.client.ClientSession object at 0x0000020C8402F9A0>
Unclosed client session
client_session: <aiohttp.client.ClientSession object at 0x0000020C8402F580>
Unclosed client session
client_session: <aiohttp.client.ClientSession object at 0x0000020C8402F5E0>
== Setting color done ==
Unclosed client session
client_session: <aiohttp.client.ClientSession object at 0x0000020C8402F6D0>
== Installed movies ==
{'available_frames': 21141,
 'code': 1000,
 'max': 55,
 'max_capacity': 21141,
 'movies': []}
## Cant get current movie ##
400, message='Data after `Connection: close`:\n\n  bytearray(b\'{"code":1102}\')\n                ^', url=URL('http://192.168.0.57/xled/v1/movies/current')
Unclosed client session
client_session: <aiohttp.client.ClientSession object at 0x0000020C8402F7F0>
## Movies are unavailable ##

Support a Repeating Color Sequence

The current ' set_static_colour' method sets the device to a only single color. I have a variant of that code which takes a list of RGB values, and repeats it to fill up the frame. I use it to apply a static "multicolor tree" effect.

I'm happy to share the code, but don't know whether to update the existing method or create a new one. Thoughts?

Support hardware where bytes per LED =! 3

All hardware I have access to are 3-byte LEDs (RGB, AWW). To support hardware where bytes_per_led != 3 one need to replace TwinklyColour with a class that respects both bytes_per_led and led_profile.

Bump to 1.8.1 or 1.9.0

I don't think I have any further changes in the pipeline for now.
Maybe you could do another release to pip?

Enhancement request - music mode support by HA

you script is perfect to control by code the twinkly devices .. and I know that some capabilities is integrated in HA.
I kindly ask you to check if it's possible to extend the support to full capabilities (music mode included)

Thank you in advance

Question: Should this be a "thicker" client?

Currently, this is a very thin layer between the application and the API. We are basically not doing any validation of either input or output. We are blindly sending whatever the application give us, and just return whatever the API returns.

E.g.

ttls/ttls/client.py

Lines 262 to 263 in a0e64e2

	async def set_name(self, name: str) -> Any:
	return await self._post("device_name", json={"name": name})

ttls/ttls/client.py

Lines 300 to 301 in a0e64e2

	async def set_mode(self, mode: str) -> Any:
	return await self._post("led/mode", json={"mode": mode})

• No validation of the name or the mode we receieve from an application.

And

ttls/ttls/client.py

Lines 289 to 290 in a0e64e2

	async def get_brightness(self) -> Any:
	return await self._get("led/out/brightness")

ttls/ttls/client.py

Lines 271 to 272 in a0e64e2

	async def get_firmware_version(self) -> Any:
	return await self._get("fw/version")

• No validation of the data we send back to the application.

In some ways, that is fine. This makes ttls very simple and we probably do not need to make many changes even if the API changes somewhat.
But in other ways, it makes a bigger burden for the applications to validate input and output, and all applications need to be updated if the API changes, instead of making the change only here in ttls.

So this is more of a design discussion than an issue. But something I wanted to raise.

Playlist mode

Hello,

currently this client seems to be hardcoded to start lights in the movie mode:

ttls/ttls/client.py

Line 261 in 707e860

return await self.set_mode("movie")

Can it be possible to start the lights in playlist mode instead if that was last selected mode (mode where you set up a playlist in the Twinkly app and then lights follow that sequence)? Or maybe to allow to choose in with mode it should start?

Update to newer firmware version

Especially for "movies", the newer versions allow for more control.

https://xled-docs.readthedocs.io/en/latest/rest_api.html#create-new-movie-entry

Currently, if you upload a movie, it will overwrite all other movies on the device, With the "new" api you can append movies to the existing list, among other useful features.