MQTT \ Home Assistant Integration - Resinchem/3D-LED-Clock GitHub Wiki

MQTT General Use

The clock currently reports over 30 states. This includes items such as the currently active mode, defined colors for various modes, countdown start time and running status, scoreboard scores, etc.

In addition, the clock accepts over 20 MQTT commands for controlling various features, options and settings. MQTT commands include changing display modes; changing various color options; setting, starting and stopping the countdown timer, updating scores on the scoreboard, etc. In fact, MQTT offers many more settings and control options than the built-in web server.

If you are unfamiliar with MQTT, there are a plethora of tutorials and guides on YouTube and other sites. I'd encourage you to get an understanding of at least the basics before attempting to use MQTT to monitor and control your clock.

MQTT can be used via various automation platforms, such as Home Assistant, openHAb, NodeRed, etc. to interact with the clock and to potentially utilize in automation routines. Home Assistant is the focus here, but the methods used should be easily adaptable to other systems.

MQTT Prerequisites

  • An accessible MQTT broker. This may be the Home Assistant MQTT/Mosquito add-on, or a separate broker. It should be possible to utilize a cloud-based broker, but this has not been tested. Regardless, the clock and broker must be able to talk to each other on your network.
  • The Settings.h file must be have MQTTMODE = 1 and the MQTTSERVER and MQTTPORT must be set to match your broker.
  • The Credentials.h file must be updated with the MQTT user and password.

MQTT Topics and Payloads

A full list of available MQTT topics and payloads are available in the MQTT_Topics pdf, also available in the MQTT folder of the repository. This document also lists the format and valid values for the various payloads.

  • The clock publishes all states using a root topic of stat/ledclock
  • The clock subscribes to all command topics beginning with cmnd/ledclock

If you wish to change the root topics, you currently must edit all of the topics in the callback function for commands and all of the updateMQTT procedures for states in the clock_main.ino file. In a later version, I hope to make setting the root topics an option in the settings file.

Home Assistant Integration

clock_ha_scoreboard_small

Currently, the clock does not support MQTT Discovery within Home Assistant. This means that the state sensors have to be manually setup via YAML in your configuration files. There are sample YAML files in the repository's \homeassistant folder, along with additional information on how you might use these as samples or guidelines in your own Home Assistant instance.

I would love to eventually make the clock available via MQTT discovery, so that there isn't a need to manually create all the YAML code for the various state sensors. I would welcome any assistance anyone may offer if they have some experience in this area.

Regardless of how the sensors get into Home Assistant right now, once the entities are defined, they can be used like any other Home Assistant entities in automations, scripts, Loveless dashboards, etc. And of course commands can also be issues to the clock from Home Assistant automations and scripts as well.