This is a binding to control an Ulanzi clock (Ulanzi TC001 Awtrix Smart Pixel Clock 2882 – ULANZI) flashed with the custom Awtrix Light firmware. This binding may also be used to controlled other devices (e.g. self-built) that use the same firmware.
Changelog
Version 0.7.1
Fixed pushIcon channel
Version 0.7
Brightness channel is writeable now, Autobrightness channel was added
Version 0.6
Don’t accept commands while synching
Channel improvements
Version 0.5.1
Fixed display command
Version 0.5
Smoother app initialisation for existing apps. Init will now take a bit longer now for newly created apps due to a longer timeout to receive the retained app message.
Version 0.4
Now initialising all app items when they are linked for convenience. Note that the initialised values do not always represent the actual values of the clock (some are actually undefined).
Version 0.3
Fixed thing actions: reboot, sound, upgrade
Fixed thing configuration reset by discovery. Note that the basetopic value cannot be changed as long as the clock still sends on the configured value
Sorted app channels in a more logical order
Removed buttonControlled channel for apps
Version 0.2
Fixed DiscoveryService “stealing” retained app messages. This change makes the recommended topic a requirement: MQTT prefix now always has to look like this: “awtrix/CLOCKNAME” where CLOCKNAME is a name of your choice.
Version 0.1
initial release (beta state). Known issues: Bridge config options (baseTopic, appLockTimeout, discoverDefaultApps) cannot be updated after bridge creation.
This binding is based on the mqtt binding so please make sure that you install the mqtt binding before you drop the jar file in your addon folder.
There is no documentation yet but here are some first steps to get you started:
Connect your clock to MQTT and set a mqtt prefix starting with “awtrix” followed by your clock name on the second level like this: awtrix/CLOCKNAME with CLOCKNAME being a name of your choice for your clock.
The clock should be autodiscovered in openHAB (as a bridge). Otherwise you can of course also add it manually with the prefix you chose in step 1 as baseTopic configuration.
If you have already added Apps to your clock before these Apps should be discovered automatically. Otherwise create a new app as a thing manually with a name of your choice.
Features:
The bridge thing mainly offers information about the integrated sensors and allows you to switch the display on or off. It also publishes button trigger events when the pyhsical buttons are pressed on the device
The app things can be used to display information on the screen. The main options are to display icons, text, bar/line graphs and a progress bar. Around these channels you will find lots of channels to style the app the way you want. You can use only the channels required to create the desired look of your app. Otherwise the default values of the firmware will be used.
You can also use apps to control other parts of openHAB: When you enable the “Button Controlled” config option the clock will allow to select the currently shown app by pushing the select key (middle button). The app rotation will stop when you selected an app (indicated by the red icon in the bottom right corner). All subsequent button pushes will also be emitted by the trigger channels of the selected app (note that the clock thing will also emit the same events). You can use this to create nice little controls for other things. See my example for a simple Spotify control (Uses: Icon, Text, Progress Bar, Button Controlled and Color customization for the progress bar) below:
Further details:
The clock itself does not report back any information for custom apps (except the name) so this binding relies on the use of retained mqtt messages as persistent storage (apps are deleted from the clock during a reboot). Therefore, when you added custom apps either through the http api or without retained messages the items will not be in sync with the clock display initially. If you create the app via OH the items will remain synchronized. Note that after an OH reboot some item states may be reset when there were invalid combinations of properties. For example: When you have set the blinkText and the rainbow property at the same time the rainbow property will not be sent to the clock because they are incompatible. Since the item states are restored from the retained mqtt message after reboot they will be reset to the default value after a reboot thus resynching the clock and the items.
There are some more options to change settings for the clock that are not (yet) exposed as channels. If needed I’m happy to add some more or all of them as channels. However the clock reports the current settings only once after startup. So synchronization from the clock to OH is possible but only by restarting the clock (there exists an Action to reboot). So this might be an option if you like to get states synchronized from the clock to your OH instance (this is not implemented yet) however.
The binding can also detect the built-in apps however it is not possible to control the apps beyond what can be configured globally for the clock. Therefore by default these apps will not be shown in the discovery results (config option “Discover buil-in Apps”).
The screen mirror channel is only sending the image once an app has changed. You can achieve a higher frame rate by sending RefreshType commands to the screen channel. However note that it is not ideal to stream the screen with a high framerate via mqtt. If you’re really interested in a more or less reliable screen streaming you should consider using the http api instead (should be possible through the http binding)
Be careful when deactivating apps: you can use this feature to temporarily deactivate an app and reuse it later. However note that if you reboot OH in between the binding will initialise the linked channels with the default settings.
If you want to delete an app permanently please proceed as follows:
Deactivate the app first via the “active”-channel: Link to a switch item and switch to off
Delete the thing
If you already deleted the thing before deactivating it: recreate the app with the same app name again and follow steps 1. and 2.
