05 MQTT and Home Assistant - Resinchem/TM1638-MQTT GitHub Wiki
MQTT
Listed below are the original MQTT topics available for use. There may be additions and/or changes in future releases. Please see the release notes for any changes not listed here. The values MQTT_TOPIC_SUB and MQTT_TOPIC_PUB shown will be substituted with the topics you define in the Settings.h file. See the Settings and Credentials page for more information on defining your own MQTT topics.
Command Topics - issued TO the the controller to control the TM1638. 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/mode |
0 - 2 | Sets the active display mode (you can add your additional own modes if desired) |
MQTT_TOPIC_SUB/brightness |
0 - 7 | Set the brightness of the display |
MQTT_TOPIC_SUB/cleardisplay |
1 | Clear the 7-segment display |
MQTT_TOPIC_SUB/reset |
1 | Clears the 7-segment display and turns off all LEDs |
MQTT_TOPIC_SUB/displaytext |
'cccccccc' | Display any combination of letters and numbers. Text will be left justified. You can include spaces. If you include a decimal, the dot for that segment will be enabled. |
MQTT_TOPIC_SUB/displaychar |
n, c | Display a single character at position 'n' |
MQTT_TOPIC_SUB/displaychardot |
n, c | Displays a single character with decimal dot at position 'n' |
MQTT_TOPIC_SUB/setled |
nn | Turn individual LED on or off. First number indicates LED position, second number indicate on (1) or off (0). Use '99' to turn on all LEDs or '00' to turn all off |
MQTT_TOPIC_SUB/setleds |
nnnnnnnn | Release 0.51+: Send an eight character string where 0 indicates LED off and 1 indicates LED on. Example: Turn on LEDs 3 and 7 send payload: '00100010'. Sending all '1's will turn all LEDs on (same as setled with payload of 99) and all '0's will turn them all off (same as setled with payload of 00) |
MQTT_TOPIC_SUB/blinkleds |
nnnnnnnn | Release 0.52+: Same payload as /setleds, but the LEDs will blink with a frequency as specified by blinkInterval in Settings.h. Send payload of '00000000' to stop blinking and turn off all LEDs. |
MQTT_TOPIC_SUB/hatime |
hh:mm | Display the time as 12-hour w A/P. Payload should be in 24-hour military time |
MQTT_TOPIC_SUB/hadate |
yyy-mm-dd | Display the date as a 3-character month and one or two digit day (e.g. Dec 25) |
Here are a few examples using the default MQTT subscribe topic, cmnd/tm1638. (A _ indicates a blank segment display)
Topic: cmnd/tm1638/displaytext Payload: "ACD 123" Displays: ACD_123_
Topic: cmnd/tm1638/displaychar Payload: 5,A Displays: ____A____
Topic: cmnd/tm1638/hatime Payload: 14:37 Displays: 2.23 P
State Topics - issued FROM the controller to the MQTT broker. These states can then be used by Home Assistant or other automation platforms.
| TOPIC | PAYLOAD | NOTES |
|---|---|---|
MQTT_TOPIC_PUB/buttons |
nnn | Returns value of button(s) pressed. See below |
MQTT_TOPIC_PUB/mode |
n | Returns the current mode of the display (e.g. 1 for time, 2 for date) |
MQTT_TOPIC_PUB/brightness |
0-7 | Returns the current brightness setting |
Processing button presses.
It's importaint to understand how the TM1638 and the TM1638Plus library reports button presses. It is not as if pressing button 3 returns 3, button 7 returns 7, etc. Instead when the buttons are read, a byte is returned in binary format:
0000 0000
Button 1 is represented by the right-most bit. So, if the left-most button (S1) (and only button 1) is pressed, the return value is: 0000 0001, which is decimal value 1. However, if button 3 is pressed, the return value is: 0000 0100, which is decimal value 4. Therefore, the values returned for the eight individual buttons, from left-to-right are:
| Button | Byte Value | Decimal value returned |
|---|---|---|
| S1 | 0000 0001 | 1 |
| S2 | 0000 0010 | 2 |
| S3 | 0000 0100 | 4 |
| S4 | 0000 1000 | 8 |
| S5 | 0001 0000 | 16 |
| S6 | 0010 0000 | 32 |
| S7 | 0100 0000 | 64 |
| S8 | 1000 0000 | 128 |
So, if button 7 is pressed, an MQTT message will be published with a payload value of 64. Note that this also allows multiple simultaneous button presses to be detected and used. For example, if buttons S1, S3 and S6 are pressed simultanously, the byte value is 0010 0101 or a decimal value of 37 (and 37 is published to MQTT).
This is an important concept to understand if you are going to process button presses via MQTT in an application like Home Asssistant.
Home Asssistant use
Most likely, you are going to want to put out values of entities from Home Assistant to the display. This can be done in automations or scripts, using the service: mqtt.pubish service call. This can be done in YAML or via the Home Assistant automation UI. However, it will normally be necessary to use templates to convert the entity value to a payload.
For example, if you have a temperature sensor, called sensor.br_temp in Home Assistant, you might render a templated payload like this:
topic: "cmnd/tm1638/displaytext"
payload: "{{ stetes('sensor.br_temp') }}"
This will display the value of that sensor on the TM1638, and if included in an automation based on the state of the sensor, the temperature on the TM1638 will update any time the value of the sensor changes.
TM1638 isplays: 72.4
You can also add static text or values to the display by including them outside of the template:
payload: "BR {{ states('sensor.br_temp') }} F"
TM1638 displays: br 72.4 F
(Just be sure the total length of the payload doesn't exceed 8 total characters. Any characters beyond 8 will simply be truncated. The decimal point does not count as a character, as it is toggled off or on for the appropriate segment - the '2' digit in the above example)
See the homeassistant folder in this repo for more example automations using the TM1638, including automations for using date and time.