Set Up Your Ulanzi TC002 for Home Assistant Data and Voice

Connect the Ulanzi TC002 to Home Assistant with AWTRIX NG, MQTT and Assist. Build a sensor display, configure voice and make text easier to read.
ShareFacebook X Pinterest
A Ulanzi TC002 pixel clock displays a music station on a wooden desk beside green plants

A Ulanzi TC002 can put Home Assistant sensor readings on your desk and let you speak to Assist through its microphone and speaker. With AWTRIX NG, the useful approach is to build the setup in stages: install the firmware, connect MQTT, add one sensor display, then configure voice. That gives you a clear way to check each connection before adding more apps.

This walkthrough follows Smart Home Junkie's TC002 installation and Home Assistant demonstration, with current AWTRIX documentation used where the software has changed. The goal is a display you can read at a glance, with a few useful controls close to hand. A working Home Assistant installation supplies the data and actions; the clock becomes another place to see and use them.

What Changes When You Install AWTRIX NG?

The Ulanzi TC002 Pixbar Smart Pixel Clock II has a 52 × 16 pixel matrix containing 832 LEDs, plus a microphone, speaker, rotary knob and three top buttons. AWTRIX NG replaces the software running on the clock with a community-developed environment for rotating apps, local scripts, notifications and smart-home connections. It is a software choice for this workflow, rather than a requirement for using the clock's standard features.

Think of the finished setup as three separate connections. Wi-Fi lets your browser reach the clock. MQTT carries Home Assistant display data and discovery messages through a broker. The voice connection links the clock to a Home Assistant voice assistant. Getting one connection working does not prove the others are ready, which is why a clock showing the correct time can still have no sensor apps or spoken answers.

TC001 and TC002 pixel matrices side by side

The larger panel is useful, but display settings determine how much text actually fits. Coming from the TC001, you may notice that ordinary apps use enlarged text on TC002 and begin scrolling sooner than expected. Comparing the TC001 and TC002 display formats helps explain the hardware difference; later in this walkthrough, the Enlarge apps setting explains the software behavior.

Choose a small set of information you regularly need: a room temperature, an energy reading, an upcoming appointment or a doorbell notification. A dedicated desk information display earns its place when those items stay easy to notice while your phone handles other tasks. Filling every app slot immediately makes it harder to decide whether the display is helping.

Prepare the Clock, Network and Home Assistant

For installation, have the TC002, a USB-C cable that carries data, and a Windows, macOS or Linux computer ready. A charging-only cable can power the clock while leaving it invisible to the installer. The demonstrated setup uses the supplied data cable. Keep the clock powered and the computer available for the entire installation rather than starting just before you need to disconnect everything.

Prepare a 2.4 GHz Wi-Fi network and its password. The video specifies 2.4 GHz for this clock, so check that your router offers that band. Also make sure the computer or phone used for setup can reach devices on the clock's network. If your network separates devices, local browser access is a useful first test before investigating Home Assistant.

For Home Assistant data, you need an MQTT broker and the MQTT integration. Mosquitto is the example used in the demonstration. Record the broker address, port and credentials you intend to use for the clock. These belong to the broker connection; they are separate from the access token used later for voice. Keeping those two authentication steps distinct prevents a common source of confusion.

Voice is optional. It needs a Home Assistant voice assistant configured with speech-to-text and text-to-speech. Whisper and Piper are examples from the tutorial, alongside a cloud-backed option. Choose the pipeline according to how you want speech processed. Running AWTRIX locally does not make a cloud-backed voice service local, nor does it make every external data source available without internet access.

If you plan to use Smart Home Junkie's blueprints, check the current TC002 blueprint manual before downloading files. It currently specifies Home Assistant 2025.2.0 or newer and AWTRIX NG 1.2.2 or newer. The TC002-specific files are distinct from the TC001 set, so choose by device and installed version rather than assuming an older automation is interchangeable.

Install AWTRIX NG Over USB

Start at the TC002 installation documentation and download the installer for your computer. Select the TC002 path rather than a package intended for another clock. In the Windows demonstration, the installer is a standalone executable. Open it and wait for the firmware preparation to finish before connecting and switching on the clock. You do not need to configure the Ulanzi app first for this method.

  1. Open the installer and wait until it indicates that it is ready.
  2. Connect the TC002 with the USB data cable and switch it on.
  3. Enter your home Wi-Fi details if you want the installer to configure the network.
  4. Start installation and leave the cable connected, the clock powered and the installer open.
  5. Wait for verification and the automatic restart, then open the clock when the installer offers that action.
AWTRIX NG TC002 installer with Home Wi-Fi fields

If the clock is not detected before installation begins, check the cable and try a USB port directly on the computer. Smart Home Junkie needed a port on the motherboard in the demonstrated setup. That observation is a useful diagnostic lead, not a rule that every hub or front-panel port fails. Change one connection at a time so you know what restored detection.

Once writing has started, follow the installer's recovery message if it is interrupted. Keep the clock powered and use Reconnect & finish installation in the same window when offered. Do not apply the earlier power-cycle troubleshooting step in the middle of a firmware write. The correct action depends on whether the installer is still trying to detect the device or has already started modifying it.

After a successful restart, the clock shows firmware information and an IP address. Open that address in a browser on your network. Reaching the web interface is the first milestone: it confirms that the clock has booted and that your browser can communicate with it. Save the address somewhere convenient before moving on to integrations.

Set Up the Web Interface and Physical Controls

Begin with the time zone under System and Time. The demonstration uses Use my zone. Then review the app rotation: enable only the items you need, arrange their order and choose a comfortable display duration. A correct clock and a predictable rotation give you a simple baseline for noticing what changes when you add your first Home Assistant app.

AWTRIX NG Apps tab with Time and Status in the rotation

The dashboard provides a live view of the pixels on the clock, along with display controls. Other areas manage apps, scripts, icons, audio, palettes, display settings and system connections. Use the live preview to compare a change with the physical panel. Menu labels can move between releases, so follow the setting's purpose as well as the names shown in the video.

Turn the knob to access brightness and volume; a short press switches between the two bars in the demonstrated controls. The left and right buttons step through apps. Holding the middle button opens a menu for items such as games and radio. Learn these controls before adding automations so an accidental button press does not look like a software problem.

The TC002 has no physical light sensor. Set a comfortable brightness for where it sits, then check it again in the evening. The video mentions a community script based on sun elevation, but that estimates a schedule-related condition rather than measuring light at the clock. A room with closed blinds or bright task lighting can still need a different level.

Connect TC002 to Home Assistant Through MQTT

The MQTT broker is the intermediary for this part of the setup. Home Assistant and AWTRIX connect to it, and discovery lets Home Assistant create the clock's device and entities. Confirm that the broker is running before entering settings on the clock. The Home Assistant MQTT integration documentation is the right reference for establishing or repairing the broker side.

  1. Open the clock's web interface and find System, then MQTT.
  2. Enable MQTT and enter the broker address and port.
  3. Enter the broker credentials required for this device.
  4. Enable HA Discovery, save the settings and reboot when requested.
  5. In Home Assistant, open Settings, Devices & services, then MQTT and look for the clock.
AWTRIX NG MQTT settings with HA discovery enabled

The demonstration exposes display controls, indicator lights, volume settings, app-navigation buttons and battery information. The knob and buttons can also act as automation triggers. Start with one obvious action, such as changing display brightness from Home Assistant. An observable change on the clock is more useful than simply seeing a device name in a list.

If the device does not appear, check that both sides use the same broker and that discovery is enabled on the clock. Verify the entered address, port and login before changing unrelated display settings. If the web interface still opens, you already know local browser access works; concentrate on the broker connection and discovery rather than reinstalling the firmware immediately.

After discovery works, inspect the clock's device page and note the available entities. Those are the controls and data your automations can use. Their names may differ from another installation, so select your own discovered device instead of copying an entity name from a screenshot. Keep the first test small, then build on a connection you have actually observed working.

Add Home Assistant Voice Through the Knob

For the demonstrated voice setup, first make sure your Home Assistant voice pipeline can process speech and return spoken output. Then create a long-lived access token from your Home Assistant user profile under Security. Copy it when it is shown and enter it only in the clock's intended token field. It is a credential for the voice connection, not the MQTT password.

In current AWTRIX releases, open System and Voice assistant, choose Home Assistant, enter the server's base address and paste the token. The video shows the earlier Home Assistant Voice label. Use the address and port without a dashboard or device-page path. Connect, wait for Ready, and use the default Home Assistant voice assistant or select another configured one where the interface allows it.

To make the first request, hold the knob for about half a second. Wait until the Home Assistant house animation opens its mouth before speaking. Starting too early can lose the beginning of the sentence. Try a short command for a device you already control successfully in Home Assistant, then listen for the response through the clock's speaker.

TC002 displaying the Home Assistant house and voice animation

The tutorial demonstrates knob-triggered voice. Current voice assistant documentation also describes an optional experimental Hey AWTRIX wake word. Treat that as a separate feature to evaluate after the basic connection works: experimental activation can miss a call or start unexpectedly. The knob remains a clear way to begin a deliberate request without depending on wake-word detection.

For room-aware commands, the tutorial uses a Home Assistant device from the same room. Copy that device page's address into Room device in the clock's voice settings. The selected device needs an assigned area. This gives commands such as turning on the lights room context; test it with the intended room before relying on a general phrase.

If the clock listens but gives no useful response, separate recognition, action and playback. Did Home Assistant understand the words? Can it perform that action? Is the clock's volume audible? Testing those parts individually makes the next adjustment clearer than changing the token, broker and display configuration together.

Build One Useful Sensor App

A room-temperature reading is a manageable first app because its source entity and expected value are easy to check. The video uses Smart Home Junkie's Create Sensor App blueprint. Start with a sensor already working in Home Assistant, then decide on a short label and an optional icon. Avoid beginning with a complex template when the goal is to verify the display path.

Create a toggle helper in Home Assistant and give it a name that identifies the display and the reading. Create an automation from the matching sensor-app blueprint, select your discovered clock, choose the helper and choose the sensor. The helper gives you a simple way to show or remove that app without deleting the automation.

Home Assistant sensor app blueprint with clock, helper and sensor fields

For an uploaded icon, use the identifier expected by the blueprint. In the demonstration, an uploaded file named 2422.gif is entered as 2422, without the extension. Confirm that the icon exists on the clock before troubleshooting its appearance in the automation. You can also begin without an icon to keep the first display test focused on the sensor value.

Save the automation and turn the helper on. Compare the value on the panel with the sensor in Home Assistant, then turn the helper off and check that the app disappears. This tests the whole chain: helper, automation, MQTT and display. Once that works, add color thresholds, backgrounds or scrolling options one at a time.

The current TC002 blueprint manual describes a dedicated set with richer layout options than the version shown in the video. Use its device-specific instructions when installing those files. Keep your first app name distinct from other apps so separate automations do not unintentionally target the same display item. Follow the manual for the fields in your downloaded version.

Fix Scrolling and Choose What Deserves Screen Time

For ordinary apps and notifications, Enlarge apps draws content at double size on TC002. In the demonstration, roughly six characters fit, or about four beside an icon. Turning Enlarge apps off in the Display tab's text settings fits roughly thirteen characters. Those are practical examples rather than a guarantee for every font, icon and layout.

Choose larger text for a short value viewed from farther away. Choose smaller text when a useful label or longer reading needs to remain visible. Check the result from your normal seat, not just in the browser preview. A layout that fits technically can still be too small to read comfortably, while a large scrolling label may take too long to deliver a simple number.

TC002 showing a temperature reading beside a thermometer icon

The newer TC002-specific blueprints can use full-panel layouts, so the ordinary-app enlargement behavior does not explain every layout option in that set. Follow the matching manual when switching between one large line and multiple lines. If an older configuration looks different after migration, check its blueprint version and display mode before assuming that the physical panel has less usable space.

For everyday use, distinguish rotating information from interruptions. A sensor app belongs in the rotation; a doorbell message may need a notification that interrupts it. Calendar, to-do and countdown blueprints offer other useful roles. Add one when you can describe the decision it helps you make, and keep its text short enough to understand during a normal glance.

Community scripts are a separate way to add content running on the clock itself. The video demonstrates finding compatible scripts in the AWTRIX Hub and sending them to the clock. Filter for your device and check that an installed script appears in the appropriate interface. Games start from the menu rather than behaving like a normal rotating sensor app.

Check the Finished Setup and Plan for Recovery

Before adding more features, confirm four outcomes: the browser opens the clock, Home Assistant controls an entity, one sensor app shows the expected value, and a knob-started voice request returns an audible response. If one fails, return to that connection's settings. Keeping a short record of the working addresses and selected entities makes later maintenance easier.

Plan for desk power. Ulanzi rates battery operation at up to two hours at maximum brightness, so the battery is useful for moving the clock rather than expecting long untethered service. Position the display where you can see the information and reach the knob. Recheck brightness and volume in the room conditions where you will actually use it.

Recovery actions have different consequences. Resetting AWTRIX settings, performing a factory reset and restoring Ulanzi firmware are separate operations. The current recovery documentation explains what each retains or erases. Holding the physical reset button for five seconds removes AWTRIX NG and reinstalls the stored Ulanzi firmware, erasing AWTRIX data. Back up anything you need before choosing a destructive reset.

For an existing Home Assistant user, this setup makes the TC002 a practical place for a few persistent readings and deliberate voice requests. The strongest result is a readable rotation you understand and can maintain. Begin with one useful sensor and one reliable command, then expand only when the extra information earns its place on the desk.

Common Questions About TC002 and Home Assistant

Q1. Do I need the Ulanzi app to install AWTRIX NG?

No. The demonstrated USB installation does not require setting up the Ulanzi app first. You need the correct TC002 installer, a data-capable cable and stable power. After installation, configure this workflow through the AWTRIX web interface and Home Assistant.

Q2. Does MQTT also configure voice control?

No. MQTT provides the broker connection used for discovery, controls and display data. Voice also needs a configured Home Assistant voice assistant, a reachable server address and an access token. Check each connection separately when display data works but speech does not.

Q3. Can I use the clock without a cloud voice service?

Yes. A Home Assistant pipeline using local speech processing is an option, with Whisper and Piper cited in the tutorial. Choose and test the complete pipeline in Home Assistant. External scripts, radio, weather sources or other selected services may still need internet access.

Q4. Why does text scroll on the larger TC002 display?

Enlarge apps is a common reason. Ordinary content is drawn larger, leaving room for fewer characters. Switch it off when text density matters more than large lettering, then inspect the result at your viewing distance. Dedicated TC002 blueprint layouts have their own layout controls.

Q5. Does TC002 adjust brightness automatically?

No. It has no physical light sensor for measuring room illumination. You can adjust brightness manually, and the tutorial mentions a sun-elevation script as an alternative approach. That script's estimate will not necessarily match light conditions at your desk.

Q6. Can I restore the original Ulanzi firmware?

Yes. Current AWTRIX recovery instructions describe holding the physical reset button for five seconds to restore the stored Ulanzi firmware. This erases AWTRIX settings and uploaded files, so preserve anything you need first and read the recovery instructions before proceeding.

Ulanzi TC002 Pixbar Smart Pixel Clock II Ulanzi TC002 Pixbar Smart Pixel Clock II ¥17,900 Ulanzi TC001 Smart Pixel Clock 2882 Ulanzi TC001 Smart Pixel Clock 2882 ¥7,500

More to Read

View all

Leave a comment

Please note, comments need to be approved before they are published.