06 ‐ MQTT and Home Assistant
The clock subscribes to MQTT topics to receive command and published to MQTT to report states. This page shows the valid MQTT topics and payloads. The values MQTT_TOPIC_SUB and MQTT_TOPIC_PUB shown will be substituted with the topics you define in the Settings.h file. There is one additional special topic, MQTT_TOPIC_SUB2 that is used by the clock to receive the date and time. This is described in more detail below.
By default, the MQTT_TOPIC_SUB is cmnd/aclock and the MQTT_TOPIC_PUB is stat/aclock
See the Settings and Credentials page for more information on changing the default MQTT topics.
While Home Assistant will be used as the source for sending commands and receiving states in this document, any system that can publish and receive MQTT topics can be used.
Command Topics - issued TO the the controller from Home Assistant to change clock options. As a general rule, these should be published with the retain flag set to false, but you may have reason to use a retained flag.
| TOPIC | PAYLOAD | NOTES |
|---|---|---|
MQTT_TOPIC_SUB/dispmode |
0 - 4 | Sets the active display mode (see the wiki page on display modes for description of the various display modes) |
MQTT_TOPIC_SUB/sweep |
ON or OFF | Enables or disables minute LED sweep mode (only applicable when display mode is 0. Ignored for other display modes) |
MQTT_TOPIC_SUB/blink |
ON or OFF | Enables or disables the blinking of the current minute LED (all modes) |
MQTT_TOPIC_SUB/leds |
ON or OFF | Turns all LEDs off or on. Clock continues to run when LEDs are off and current time will be displayed when LEDs are toggled back on. |
MQTT_TOPIC_SUB/test |
1 | New v1.02 - Run the LED test. Clock will return to previous time display after test. Payload can be any value. |
Special Command Topic (MQTT_TOPIC_SUB2) The default is: stat/tm1638
This is a special topic where the clock expects to receive the current date and time. It is split out as its own topic in the event that you already have a topic for date and time already published by Home Assistant. In my case, my TM1638 displays already receive the time via this topic.
If you do not already have a topic updated by Home Assistant, one should be created. An automation that uses the time sensor will update once per minute and can be used to update the clock by publishing an MQTT message to this topic. The date sensor will update once a day at midnight. You can use whatever topic you like, but you must update the Settings.h file with the topic you create.
| TOPIC | PAYLOAD | NOTES |
|---|---|---|
MQTT_TOPIC_SUB2/hadate |
yyyy-mm-dd | Date should be published by the source system (e.g. Home Assistant) in the format listed in the payload. Example: 2023-11-04 |
MQTT_TOPIC_SUB2/hadate |
hh:mm | Time should be published each minute in the format shown. Time can be 12 or 24 hour, but must not include any am/pm indicators. Example: 22:51 or 10:51 |
State Topics - issued FROM the controller to the MQTT broker. These states can then be used by Home Assistant for automations or shown on a dashboard. All topics are published as retained, unless otherwise noted.
| TOPIC | PAYLOAD | NOTES |
|---|---|---|
MQTT_TOPIC_PUB/mqtt |
connected | This is published once, at boot time, to validate the MQTT connection. It is primarily used for troubleshooting |
MQTT_TOPIC_PUB/lastboot |
yyyy-mm-dd hh:mm | The date and time the controller was last rebooted |
MQTT_TOPIC_PUB/dispmode |
0-4 | The current minute LED display mode |
MQTT_TOPIC_PUB/blink |
ON or OFF | Whether the last minute blink option is on or off |
MQTT_TOPIC_PUB/sweep |
ON or OFF | Whether sweep mode is enabled for display mode 0 |
MQTT_TOPIC_PUB/gettime |
1 | NOT RETAINED. Special topic used during boot to request the current time be published by the source system (e.g. Home Assistant) |
As currently written, MQTT and Home Assistant (or other automation system capable of publishing the time to MQTT each minute) is required. The clock does not have its own real-time clock module or other method of keeping time, other than the Arduino millis() function, which will not maintain time accuracy over longer periods. It would be a fairly minimal modification to the code to use something like an NTP server to get the time and to periodically re-sync it. If that change is made, then MQTT and Home Assistant would be entirely optional.
But Home Assistant does provide a nice interface for sending MQTT commands to control and change some of the options of the clock. See the /homeassistant folder for examples of integrating the clock and a sample dashboard, along with the YAML necessary to create it. This also includes some example automations, such as turning the LEDs off and on with the room lights, and an example of how to publish the time to MQTT each minute.