Ulanzi TC001 Desktop Clock - Awtrix

Intro ¶

Earlier this month, Blakadder did a review of the Ulanzi Desktop Pixel Clock TC001. Not much later, I saw some people on Twitter that were playing with it as well. This triggered me to have a look at this nice desktop clock as well.

Not soon after I ordered 2 of the Ulanzi TC001 Desktop Clocks, Blakadder tweeted about Awtrix Light going open source.

Having 2 of these clocks, I decided to flash one with the Atrix firmware and flash the other with ESPHome on a later date (blog post will follow).

This blog post will describe some of my first experiences flashing the TC001 and setting up some automations for it in Home Assistant.

If you want to follow along, you can check any of these three links to get yourself one (or more).

Flashing Awtrix on the Ulanzi TC001 ¶

Preparations for flashing ¶

As the USB-C port to charge the device’s battery (yes, it has a battery :)) is also connected to the serial connection of the ESP chip inside. This means we don’t need to open up the device to flash or read firmware on the device. Awesome!

The serial port should be recognised immediately when you connect the device and power it on. If not, you may need to install the serial driver first.

We’ll also be using esptool which you can install as a Python(3) module using pip:

python3 -m pip install esptool

Backup stock firmware ¶

We start of by backing up the stock firmware of the device. Should we ever want to return to the stock firmware (e.g. if you need to return it under warranty for a defect), we can restore this backup image and the device will act the way it did when it arrived at your doorstep.

1. Connect the desktop pixel clock with a proper USB-C cable to your system and turn it on by holding the < and > buttons for 3 seconds.

2. Check whether the device was properly detected and what serial/COM port it was assigned to.

3. Run the following command to take a backup of the firmware and save it as ulanzi_tc001_factory.bin:

   esptool -p COM12 -b 921600 read_flash 0x0 0x400000 ulanzi_tc001_factory.bin
   

4. Keep a copy of this bin at a safe location so you can retrieve if, if ever needed.

Note that the device will be beeping while you’re transferring data over serial.

Flashing Awtrix firmware ¶

This proces is super easy thanks to the Web Flasher provided by Blueforcer.

1. Visit the Web Flasher website with Chrome or Edge
2. Click on the Connect button and select the correct COM port
3. Select Install Awtrix Light and wait for the flashing to complete.
   I’d advise checking the box for erasing the device prior to flashing.

Once flashing is done, the device will play a tune (yes, it has a tiny speaker as well :)), and it will go into Access Point mode. The device will broadcast a WiFi network named AWTRIX LIGHT or awtrix_xxxxxx protected with the password 12345678.

when you connect your phone via WiFi to the Access Point of the device, it should open the device’s captive portal. If that does not happen automatically, open your phone’s web browser and go to http://192.168.4.1.

Enter your WiFi credentials to connect the device to your network. In the background the device will be looking for WiFi SSIDs, so give it a minute to populate the list if you don’t feel like typing your SSID.

The device will stop broadcasting its own WiFi network and will connect to yours.

Connecting to Home Assistant ¶

Check your router’s DHCP lease table to use a network scanner to check what IP the desktop clock has gotten. Then browse to that IP in your browser.

The connection between Awtrix Light and Home Assistant happens via MQTT. If you haven’t set up a MQTT broker in Home Assistant yet, you can have a look at some older blog posts. Since the Awtrix Light firmware is setup for MQTT autodiscovery, we won’t need to write any MQTT sensor config ourselves.

After saving, the device should be automatically discovered as a new MQTT integration. If not, verify your credentials and reboot the device.

Sending notifications to the TC001 ¶

The device will now cycle between the current date, time, battery percentage, humidity, temperature. This is useful information, but the whole idea of flashing it with custom firmware is to display our own data on it.

One of the use-cases I have is notifying me when some is at the door by sending a notification to the desktop clock. To do this, we need to send a MQTT message to the notify topic of the device including everything we want to be displayed and played.

Icon ¶

If you want to display an icon on the device, you can either download it from Lametric, or design your own.

To download one from Lametric, first get the ID from the icon you want at https://developer.lametric.com/icons. Then open the web dashboard of your TC001 desktop clock and go to the ICONS tab. Enter the ID of the icon and click Download.

You can also design your own pixel icons and upload them to the ICONS folder via the device’s filebrowser.

Melody ¶

Melodies are composed as Ring Tone Text Transfer Language (RTTTL) files. Grab a melody you like from the internet or design your own. Store the RTTTL string in a .txt file under the MELODIES folder using the device’s file browser.

For example, the following RTTTL string will play a snippet from “Are you sleeping, brother John?”. I stored this as MELODIES/john.txt.

John:d=4,o=5,b=125:c,d,e,c,c,d,e,c,d,e,f,p,d,e,f,p,8g,8a,8g,8f,e,c,8g,8a,8g,8f,e,c,c,g4,c,p,c,g4,c

Notification ¶

You can now test your ability to send a notification to the device manually using the MQTT Integration. In Home Assistant, go to Settings > Integrations > MQTT > Configure and enter this info (update to fit your config):

{
  "text": "DING DONG",
  "icon": "44330",
  "rainbow": true,
  "hold": true,
  "pushIcon": 0,
  "sound": "john"
}

You should notice the TC001 is playing your tune and displaying your notification.

To dismiss the notification, press the center button on top of the desktop clock or send an empty MQTT payload to [PREFIX]/notify/dismiss.

Automation ¶

Let’s not put this all together in an automation.

automation:
  - alias: Awtrix - doorbell notification
    description: Send a doorbell notification to the Ulanzi TC001
    id: awtrix_doorbell_notification
    mode: single
    trigger:
    - platform: state
      entity_id:
        - binary_sensor.doorbell_button
      to: "on"
      alias: Doorbell is pressed
    condition: []
    action:
    - alias: Publish notification
      service: mqtt.publish
      data:
        topic: "[PREFIX]/notify"
        payload: >-
          {
            "text": "DING DONG",
            "icon": "44330",
            "rainbow": true,
            "hold": true,
            "pushIcon": 0,
            "sound": "john"
          }          
    - delay:
        minutes: 1
    - alias: Dismiss notification
      service: mqtt.publish
      data:
        topic: "[PREFIX]/notify/dismiss"

This automation will send to doorbell notification (including melody, icon, and text) and will dismiss is 1 minute later so the desktop clock can go back to scrolling through its regular apps.

Closure ¶

There’s a lot more you can do with this device and with the Awtrix Light firmware. For example, you can use it as an alarm clock and display your own custom apps.

I will be playing around with this device a lot more in the near future, using it to showcase nice-to-know information and to alert me of important things. Think of also displaying air quality or CO2 levels or energy consumption. Or an “on-call” notification to alert your family members not to disturb you.