Controller - Home Assistant (openHAB) MQTT


Controller details

Type: Controller

Name: Home Assistant (openHAB) MQTT

Status: NORMAL

GitHub: C005.cpp

Maintainer: .


The Home Assistant (openHAB) MQTT controller is one of the most standard “MQTT” controllers. It has a very basic way of interacting with a MQTT broker and thus is not limited to “Home Assistant” or “OpenHAB”.

Command Handling

This controller can also be used to receive commands via the broker. For this, there are several syntax formats to receive these commands:

  • Subscribe to the configured subscription topic, with /cmd as the last part of the topic. For example:

    • Topic: ESP_Easy/Bathroom_pir_env/cmd

    • Message: gpio,14,0

    • Full command: gpio,14,0

  • Format the command as part of the topic, with the last parameter as data. For example:

    • Topic: ESP_Easy/Bathroom_pir_env/GPIO/14

    • Message: 0 or 1

    • Full command: gpio,14,0

  • Format the command as part of the topic, with a specific parameter as data. (added: 2022-03-01) This format allows the message to be a single parameter which will be inserted at the indicated position. For example:

    • Topic: ESP_Easy/Bathroom_pir_env/cmd_arg1/GPIO/0

    • Message: 14

    • Full command: gpio,14,0

These topics used to receive commands do rely on the topic wildcard /# at the end of the subscribed topic string. This wildcard is used in the default subscription topic for this MQTT controller. If the format of the subscription topic is changed by the user, make sure to keep this wildcard in place for the command handling to work.


The value of N in cmd_argN can also be 0. The sent message is then the command, where the values in the topic are parameters.

Sending Events

Added: 2022/05/02

It can be useful to send events with 0 or more event values in the topic and the message as one of the event values. For example with a message like these sent as a retained message, one can let the broker send out a message to the ESPEasy node as soon as it connects.

  • Topic: ESP_Easy/Bathroom_pir_env/cmd_arg2/event/myevent/2/3

  • Message: 1

  • Full event: myevent=1,2,3

Since a MQTT topic cannot contain a # sign in topics (at least, you shouldn’t use it), the event sent via MQTT cannot contain a # character.

Please note that the nr in cmd_argN is the argument of the command, not the event.

For example sending an event with the event name as message and the values part of the topic:

  • Topic: ESP_Easy/Bathroom_pir_env/cmd_arg1/event/1/2/3

  • Message: myevent

  • Full event: myevent=1,2,3

Change log

Changed in version 2.0:

added Major overhaul for 2.0 release.

New in version 1.0:

added Initial release version.