Repository navigation
B.1 MQTT
Roland Jax edited this page Sep 26, 2026
·
1 revision
MQTT support can be enabled globally on the configuration webpage. For a minimal configuration, at least the IP address or hostname of the MQTT server must be specified. At the configuration web page you can set
- server IP address or hostname
- user name
- password
Warning: The current implementation does not support TLS encryption. The MQTT server should therefore be run in a secure environment!
- The device's MQTT root topic begins with ebus/,
- followed by the last 6 characters of its MAC address as a unique device ID
- and a trailing slash.
- Example root topic:
ebus/8406ac/.
The following sub topics are available on any device and are published regularly. Every topic is JSON-encoded.
| topic | description |
|---|---|
| available | indicates status for Home Assistant |
| state | system health metrics (uptime, heap, wifi,...) |
| state/counter | providing all counters |
| state/timing | time required by internal routines |
| values/... | received values of installed commands |
The MQTT command interface is divided into two topics for bidirectional communication.
- Commands can be sent to the request topic.
- After processing, a response is sent to the response topic.
- Only JSON-encoded messages are processed.
- To distinguish between commands, each message contains a unique ID.
| communication | description |
|---|---|
| request | JSON encoded request |
| response | JSON encoded response / error message |
Available MQTT commands.
| command | description |
|---|---|
| restart | Restarting of the device |
| insert | Inserting (Installing) of new commands |
| remove | Removing installed commands |
| publish | Publishing installed commands |
| load | Loading (Installing) saved commands |
| save | Saving the currently installed commands |
| wipe | Wiping of the saved commands |
| scan | Scanning of ebus participants |
| devices | Publishing scanned ebus devices |
| send | Sending ebus commands once |
| forward | Activate/deactivate data forwarding (including filtering) |
| reset | Resetting counter and timing values |
| read | Reading the value of a stored command |
| write | Writing a value using a stored command |
The provided examples were created using Mosquitto in a Linux shell. The server IP address or hostname and unique device ID must be adjusted to your environment.
- server IP address or hostname =
server - unique device ID =
8406ac - request topic =
ebus/8406ac/request - response topic =
ebus/8406ac/response
Restarting of the device
payload:
{
"id": "restart"
}
mosquitto_pub -h server -t 'ebus/8406ac/request' -m '{"id":"restart"}'
Inserting (Installing) of new commands
payload:
{
"id": "insert",
"commands": [
{
...
},
{
...
}
]
}
Specific examples:
payload: - sensor
{
"id": "insert",
"commands": [
{
"key": "01", // unique key of command
"name": "outdoor/temperature", // mqtt topic below "values/"
"read_cmd": "fe070009", // read command as vector of "ZZPBSBNNDBx"
"active": false, // active sending of command
"interval": 0, // minimum interval between two commands in seconds
"master": true, // value of interest is in master or slave part
"position": 1, // starting position in the interested part
"datatype": "DATA2B", // ebus datatype
"divider": 1, // divider for value conversion
"digits": 2, // deciaml digits of value
"unit": "°C", // unit of the interested part
"ha": true, // home assistant support for auto discovery
"ha_component": "sensor", // home assistant component type
"ha_device_class": "temperature" // home assistant device class
}
]
}
mosquitto_pub -h server -t 'ebus/8406ac/request' -m '{"id":"insert","commands":[{"key":"01","read_cmd":"fe070009","active":false,"interval":0,"master":true,"position":1,"datatype":"DATA2B","divider":1,"digits":2,"topic":"outdoor/temperature","unit":"°C","ha":true,"ha_component":"sensor","ha_device_class":"temperature"}]}'
payload: - number
{
"id": "insert",
"commands": [
{
"key": "55", // unique key of command
"name": "desired_temp_low", // mqtt topic below "values/"
"read_cmd": "50b509030d3300", // read command as vector of "ZZPBSBNNDBx"
"write_cmd": "50b509040e3300", // write command as vector of "ZZPBSBNNDBx"
"active": true, // active sending of command
"interval": 60, // minimum interval between two commands in seconds
"master": false, // value of interest is in master or slave part
"position": 1, // starting position in the interested part
"datatype": "DATA1C", // ebus datatype
"divider": 1, // divider for value conversion
"min": 15, // minimum value
"max": 20, // maximum value
"digits": 2, // deciaml digits of value
"unit": "°C", // unit of the interested part
"ha": true, // home assistant support for auto discovery
"ha_component": "number", // home assistant component type
"ha_device_class": "temperature", // home assistant device class
"ha_step": 1, // home assistant step value
"ha_mode": "box" // home assistant mode
}
]
}
mosquitto_pub -h server -t 'ebus/8406ac/request' -m '{"id":"insert","commands":[{"key":"55","name":"desired_temp_low","read_cmd":"50b509030d3300","write_cmd":"50b509040e3300","active":true,"interval":60,"master":false,"position":1,"datatype":"DATA1C","divider":1,"min":15,"max":20,"digits":2,"unit":"°C","ha":true,"ha_component":"number","ha_device_class":"temperature","ha_step":1,"ha_mode":"box"}]}'
payload: - select
{
"id": "insert",
"commands": [
{
"key": "66", // unique key of command
"name": "operating_mode", // mqtt topic below "values/"
"read_cmd": "50b509030d2b00", // read command as vector of "ZZPBSBNNDBx"
"write_cmd": "50b509040e2b00", // write command as vector of "ZZPBSBNNDBx"
"active": true, // active sending of command
"interval": 60, // minimum interval between two commands in seconds
"master": false, // value of interest is in master or slave part
"position": 1, // starting position in the interested part
"datatype": "UINT8", // ebus datatype
"ha": true, // home assistant support for auto discovery
"ha_component": "select", // home assistant component type
"ha_device_class": "enum", // home assistant device class
"ha_entity_category": "config", // home assistant entity category
"ha_options_list":{"1":"On","2":"Off","3":"Auto","4":"Eco","5":"Night"}, // home assistant possible options
"ha_options_default": 3 // home assistant default option
}
]
}
mosquitto_pub -h server -t 'ebus/8406ac/request' -m '{"id":"insert","commands":[{"key":"66","name":"operating_mode","read_cmd":"50b509030d2b00","write_cmd":"50b509040e2b00","active":true,"interval":60,"master":false,"position":1,"datatype":"UINT8","ha":true,"ha_component":"select","ha_device_class":"enum","ha_entity_category":"config","ha_options_list":{"1":"On","2":"Off","3":"Auto","4":"Eco","5":"Night"},"ha_options_default":3}]}'
payload: - binary_sensor
{
"id": "insert",
"commands": [
{
"key": "88", // unique key of command
"name": "compressor", // mqtt topic below "values/"
"read_cmd": "08b509030d1d00", // read command as vector of "ZZPBSBNNDBx"
"active": true, // active sending of command
"interval": 60, // minimum interval between two commands in seconds
"master": false, // value of interest is in master or slave part
"position": 1, // starting position in the interested part
"datatype": "UINT8", // ebus datatype
"ha": true, // home assistant support for auto discovery
"ha_component": "binary_sensor", // home assistant component type
"ha_device_class": "running", // home assistant device class
"ha_payload_on": 1, // home assistant payload for ON state
"ha_payload_off": 0 // home assistant payload for OFF state
}
]
}
mosquitto_pub -h server -t 'ebus/8406ac/request' -m '{"id":"insert","commands":[{"key":"77","name":"compressor","read_cmd":"08b509030d1d00","active":true,"interval":60,"master":false,"position":1,"datatype":"UINT8","ha":true,"ha_component":"binary_sensor","ha_device_class":"running","ha_payload_on":1,"ha_payload_off":0}]}'
payload: - switch
{
"id": "insert",
"commands": [
{
"key": "88", // unique key of command
"name": "cooling_supported", // mqtt topic below "values/"
"read_cmd": "50b509030d8601", // read command as vector of "ZZPBSBNNDBx"
"write_cmd": "50b509040e8601", // write command as vector of "ZZPBSBNNDBx"
"active": true, // active sending of command
"interval": 60, // minimum interval between two commands in seconds
"master": false, // value of interest is in master or slave part
"position": 1, // starting position in the interested part
"datatype": "UINT8", // ebus datatype
"ha": true, // home assistant support for auto discovery
"ha_component": "switch", // home assistant component type
"ha_payload_on": 1, // home assistant payload for ON state
"ha_payload_off": 0 // home assistant payload for OFF state
}
]
}
mosquitto_pub -h server -t 'ebus/8406ac/request' -m '{"id":"insert","commands":[{"key":"88","name":"cooling_supported","read_cmd":"50b509030d8601","write_cmd":"50b509040e8601","active":true,"interval":60,"master":false,"position":1,"datatype":"UINT8","ha":true,"ha_component":"switch","ha_payload_on":1,"ha_payload_off":0}]}'
Removing installed commands
payload:
{
"id": "remove",
"keys": [ // optional
"UNIQUE_KEY",
...
]
}
mosquitto_pub -h server -t 'ebus/8406ac/request' -m '{"id":"remove","keys":["01","02"]}'
Publishing installed commands
payload:
{
"id": "publish"
}
mosquitto_pub -h server -t 'ebus/8406ac/request' -m '{"id":"publish"}'
Loading (Installing) saved commands
payload:
{
"id": "load"
}
mosquitto_pub -h server -t 'ebus/8406ac/request' -m '{"id":"load"}'
Saving the currently installed commands
payload:
{
"id": "save"
}
mosquitto_pub -h server -t 'ebus/8406ac/request' -m '{"id":"save"}'
Wiping of the saved commands
payload:
{
"id": "wipe"
}
mosquitto_pub -h server -t 'ebus/8406ac/request' -m '{"id":"wipe"}'
Scanning of ebus participants
payload:
{
"id": "scan",
"full": false, // optional
"vendor": false, // optional
"addresses": [ // optional
"ZZ",
...
]
}
mosquitto_pub -h server -t 'ebus/8406ac/request' -m '{"id":"scan","full":false,"vendor":false,"addresses":["05","15"]}'
Publishing scanned ebus devices
payload:
{
"id": "devices"
}
mosquitto_pub -h server -t 'ebus/8406ac/request' -m '{"id":"devices"}'
Sending ebus commands once
payload:
{
"id": "send",
"commands": [
"ZZPBSBNNDBx",
...
]
}
mosquitto_pub -h server -t 'ebus/8406ac/request' -m '{"id":"send","commands":["05070400","15070400"]}'
Activate/deactivate data forwarding (including filtering)
payload:
{
"id": "forward",
"enable": true,
"filters": [ // optional
"DB(x)",
...
]
}
mosquitto_pub -h server -t 'ebus/8406ac/request' -m '{"id":"forward","enable":true,"filters":["0700","fe"]}'
mosquitto_pub -h server -t 'ebus/8406ac/request' -m '{"id":"forward","enable":false}'
Resetting counter and timing values
payload:
{
"id": "reset"
}
mosquitto_pub -h server -t 'ebus/8406ac/request' -m '{"id":"reset"}'
Reading the value of a stored command
payload:
{
"id": "read",
"key": "01"
}
mosquitto_pub -h server -t 'ebus/8406ac/request' -m '{"id":"read","key":"01"}'
Writing a value using a stored command
- It only works for simple data types AND the specified data is always appended to the end of the configured write_cmd.
- Complex data types are not supported by the underlying data processing mechanism.
payload:
{
"id": "write",
"key": "01",
"value": 1.25 // character types within quotation marks
}
mosquitto_pub -h server -t 'ebus/8406ac/request' -m '{"id":"write","key":"01","value":1.25}'