After the encouraging results of our integration of Yoctopuce sensors in Home Assistant via the MQTT gateway, we could not resist the temptation to integrate our actuator modules as well. But to do so, we had to start by improving our MQTT support by enabling MQTT to send commands to the modules. Here is a presentation of these improvements.
Until now, VirtualHub and the Yoctopuce network interfaces (YoctoHub-Ethernet, YoctoHub-Wireless-n, and so on) only published the main state changes of the connected sensors and actuators to the MQTT broker. To enable more extensive use, they are now capable of:
- receiving command messages (e.g. to switch a relay)
- receiving configuration messages
- publishing their entire configuration when a parameter is changed
- publishing availability changes (connected/disconnected)
The corresponding MQTT messages are described below.
Common part
The topic of all messages starts with a common part, which identifies the Yoctopuce module and the particular function of this module concerned by the message. It has the following structure:
root_topic/deviceName/functionName
The root_topic can be freely configured, for example to the yoctopuce value. If you connect several hubs to the same MQTT broker, you can either use the same root_topic for all of them or a different topic per hub. Using a separate root_topic is recommended if you send a lot of commands to a hub via MQTT.
deviceName is the logical name you gave to the designated Yoctopuce module. If no logical name has been configured, the serial number of the module is used instead of the logical name (e.g. METEOMK2-012345).
functionName is the logical name you gave to the designated function. If no logical name has been configured, the function identifier is used (for example genericSensor1).
The advantage of using logical names rather than hardware names in the topic root is that you can identify modules and functions by their role and you don't have to explicitly tell the hardware ID of each module to the MQTT client that has to interact with these modules. The disadvantage is that if you decide to change the logical name of your modules or functions without thinking about it, the MQTT topics used must be changed accordingly.
Topic /api: complete state of the function
Under root_topic/deviceName/functionName/api, each function publishes a JSON structure describing the complete state of the function, including all attributes. In this JSON encoding,
- booleans are represented by 0 and 1
- enumerated types are represented by numeric constants
- real numbers such as measures are represented as integers, after multiplication by 65536. They must therefore be divided by 65536.0 to obtain the actual value.
This message is issued when one of the following conditions occurs
- when the connection between the hub and the MQTT broker is established
- every five minutes
- after a change in the module configuration
- in response to the reception of a command by this function
- for the module function, when the beacon is activated or deactivated
Base topic: current state
Under root_topic/deviceName/functionName, each function publishes a textual summary of its status. This is not JSON but a simple string, corresponding to the value of the advertisedValue attribute of the function. For example, for a sensor, it corresponds to the current value of the sensor, while for a relay it corresponds to the letter A or B depending on the switching state.
This message is issued when one of the following conditions occurs
- when the connection between the hub and the MQTT broker is established
- every five minutes
- every time the advertisedValue attribute changes
To avoid overloading the MQTT broker with changes in the current values of the sensors, it is possible to globally disable the sending of current value messages for the sensors only, in the MQTT configuration.
Topics /avg, /min, /max: average and extreme values
Under root_topic/deviceName/functionName/avg, the sensor functions (subclasses of Sensor) periodically publish the average value observed during the previous time interval directly as a real number.
Under root_topic/deviceName/functionName/min, the minimum value observed during the previous time interval.
Under root_topic/deviceName/functionName/max, the maximum value observed during the previous time interval.
These messages are the direct equivalent of the timed reports documented in the manual of these modules. The time interval must have been previously configured in the reportFrequency attribute. Otherwise, these messages are not sent.
Topics /set/attributeName: command sending and configuration
Under root_topic/deviceName/functionName/set/attributeName, it is possible to send messages to modify the attributes of functions, in order to change a function state or configuration. The value of the message corresponds to the new desired value, as is. The format is identical to the one used for the REST API available in all Yoctopuce modules.
For example, we could switch a relay by sending a message to the topic
yoctopuce/PumpRelay/relay1/set/state
with value 1.
We could also trigger a 1500ms pulse on the same relay by sending a message to the topic
yoctopuce/PumpRelay/relay1/set/pulseTimer
with value 1500.
To receive commands and configuration changes via MQTT, you must have explicitly enabled it in the MQTT configuration on the Yoctopuce hub. For safety, the basic behavior of the MQTT mode remains read-only.
Topic /rdy: availability status
Under root_topic/deviceName/module/rdy, the module function publishes a binary indication of the availability status of the device. The value is 1 when the device is online, and 0 when it is offline.
This message is published by the hub for its own module when one of the following conditions occurs
- when the hub establishes a connection with the MQTT broker
- when the hub disconnects from the MQTT broker
This message is published for the devices other than the hub when one of the following conditions occurs
- when establishing the hub connection with the MQTT broker
- when a device is connected to the hub
- when a device is disconnected from the hub
To determine if a module is really reachable, it is therefore necessary to check its own /rdy topic, to know if it has been disconnected, and the /rdy topic of the hub, to know if the MQTT connection is active.
MQTT discovery
In addition, special messages are published under the topic homeassistant/ just after the connection of the hub with the MQTT broker is established, and repeated every 5 minutes, to allow the automatic detection of the proposed features, thanks to the MQTT discovery mechanism supported by Home Assistant and openHab.
Conclusion
This extended MQTT support opens many possibilities, which we will have the opportunity to explore in future posts. In the meantime, don't hesitate to contact Yoctopuce support if you have any questions about its use...
