4.8MQTT client

The MQTT client lets the gateway talk to other systems over MQTT. You can map topics to KNX group addresses or to system values, and you can let Home Assistant find your lights, switches and fans automatically. You find it under Server > Interfaces > MQTT Client.

#What it does

• Connects to a broker: either the gateway's own MQTT broker or an external one such as Home Assistant's Mosquitto.
• Topic bindings forward a message that arrives on a topic to a KNX group address, and publish a KNX group address or system value to a topic whenever it changes.
• Home Assistant discovery publishes one Home Assistant entity for every switch, dimmer light, RGB lamp and ceiling fan that has a Voice Command Phrase.

#Before you enable it

• For the Local Broker choice, enable MQTT broker as well. The client does not start a broker itself.
• For an External Broker, you need its address and port, and a username and password if it requires them.
• Bindings that use KNX need the KNX engine running.
• Deploy the project after any change. The client reconnects when its settings change.

#Settings

#Topic Bindings dialog

The list on the left shows each binding as number-topic. Add creates a binding with the topic veltnova/binding1 (then binding2 and so on). Clone copies the selected binding and adds -copy to its topic. Remove deletes the selected one. Changes apply as you type: Cancel and Save Changes both only close the dialog.

#How it works on the gateway

• Subscribe to the topic when the client connects. Each message is written to the KNX group address with the datatype you set. The payload is the value as text.
• Publish checks every 3 seconds. When the value has changed, it is published with the binding's QoS and the retain flag set, so a new subscriber gets the current value at once. After a reconnect, all publish values are sent again.
• A publish binding sends nothing until the gateway has seen a value for that KNX address. The read sweep after a deploy covers addresses used by canvas objects, not addresses that only appear in an MQTT binding.
• KNX switching values (DPT 1) are published as 1 or 0, not ON or OFF.
• With JSON, a subscribe binding follows the dot path through nested objects, for example state.temperature. A publish binding wraps the value in an object with one key that is the whole path text, so state.temperature publishes {"state.temperature":21.5}, not a nested object.
• The client reconnects by itself every 5 seconds if the broker is unreachable.

#Home Assistant discovery

When on, the gateway publishes a retained discovery message for each switch, dimmer light, RGB lamp and ceiling fan that has a Voice Command Phrase. It does not check the Voice Gateway switch. The entity name is the phrase (or the label if the phrase is empty). Home Assistant shows them under one device called Veltnova Gateway.

The state of each entity is published to veltnova/<object id>/state, and commands arrive on veltnova/<object id>/set (fan speed uses .../percentage/state and .../percentage/set). The gateway never sends removal messages: delete an entity in Home Assistant yourself if you turn discovery off.

#Example

Show a KNX temperature in another system and let it switch a light.

With Broker set to External Broker, Host 192.168.1.20 and IP Port 1883, a temperature of 21.5 is published as 21.5. Publishing 1 to site/hall/light/set switches 1/1/10 on, 0 switches it off.

#Tips and common problems

• Client shows Offline. In Diagnostics > Other Engines, the MQTT card shows Connected to ... or Configured but not connected with the last error. Check host, port, credentials and that the broker is running.
• Nothing is published. Check that the group address has produced a telegram since the gateway started. Use the gateway console's Monitor tab (see KNX engine).
• Home Assistant shows no entities. Confirm the discovery prefix matches, the objects have a Voice Command Phrase, and Home Assistant is connected to the same broker.

#See also

• MQTT broker
• KNX engine
• Zigbee
• Switch
• Diagnostics