Skip to content

B.4 Command definition

Jump to bottom
Roland Jax edited this page Sep 26, 2026 · 1 revision

B.4 Command definition

The command definition describes the structure and parameters required for configuring commands. This definition provides a comprehensive framework that enables efficient command execution, integration with Home Assistant, and the management of values ​​such as temperature and other sensor data.

Command Struct JSON Field Descriptions

The following outlines each field in the Command struct along with its corresponding JSON representation and data type.

Command fields

  • key (string): A unique identifier for the command.

  • name (string): The name of the command, typically used as an MQTT topic.

  • read_cmd (string): The command used to read data, represented as a hexadecimal string.

  • write_cmd (string, optional): The command used to write data, also represented as a hexadecimal string.

  • active (boolean): Indicates whether the command is currently active.

  • interval (integer): Specifies the minimum delay in seconds between command executions.

Data fields

  • master (boolean): Indicates if the value of interest is in the master component.

  • position (integer): The starting index for accessing data bytes, beginning at 1.

  • datatype (string): The data type used for processing, defined by the eBUS standard.

  • divider (number, optional): A factor used for converting values.

  • min (number, optional): The minimum acceptable value for the command.

  • max (number, optional): The maximum acceptable value for the command.

  • digits (integer, optional): Specifies the number of decimal points to display for the value.

  • unit (string, optional): The unit of measurement for the command (e.g., degrees Celsius).

Home Assistant

  • ha (boolean): Indicates support for Home Assistant auto-discovery.

  • ha_component (string): Specifies the type of component represented in Home Assistant.

  • ha_device_class (string): Classifies this command as a specific device category within Home Assistant (e.g., temperature).

  • ha_entity_category (string, optional): Specifies the entity category in Home Assistant.

  • ha_mode (string, optional): Describes the operating mode, defaults to "auto".

  • ha_key_value_map (object, optional): A mapping of keys to values for additional configurations in Home Assistant.

  • ha_default_key (integer, optional): The default key for options in Home Assistant.

  • ha_payload_on (integer, optional): The payload value representing the ON state.

  • ha_payload_off (integer, optional): The payload value representing the OFF state.

  • ha_state_class (string, optional): Defines the state class for the command in Home Assistant.

  • ha_step (number, optional): The incremental step value used for operations in Home Assistant.

This structured overview provides clear insight into each JSON field's purpose, data type, and example values, making it easier for developers to implement and utilize the Command struct effectively.

Available eBUS data types:

  • numeric: BCD, DATA1B, DATA1C, DATA2B, DATA2C, UINT8, INT8, UINT16, INT16, UINT32, INT32, FLOAT4 (IEEE 754)
  • reversed endian: DATA2BR, DATA2CR, UINT16R, INT16R, UINT32R, INT32R, FLOAT4R
  • character: CHAR1 - CHAR8, HEX1 - HEX8

Example Command Overview

The following example illustrates a command that can upload data via both HTTP and MQTT protocols. It defines parameters for reading information regarding outdoor temperature. Below is a structural breakdown of the command in JSON format.

{
  "key": "01",
  "name": "Outside_Temperature",
  "read_cmd": "fe070009",
  "write_cmd": "",
  "active": false,
  "interval": 0,
  "master": true,
  "position": 1,
  "datatype": "DATA2B",
  "divider": 1,
  "min": 0,
  "max": 0,
  "digits": 2,
  "unit": "°C",
  "ha": true,
  "ha_component": "sensor",
  "ha_device_class": "temperature",
  "ha_entity_category": "",
  "ha_mode": "",
  "ha_key_value_map": {},
  "ha_default_key": 0,
  "ha_payload_on": 0,
  "ha_payload_off": 0,
  "ha_state_class": "",
  "ha_step": 1
}

Field Descriptions

  • key: "01"
    A unique identifier for this command.

  • name: "Outside_Temperature"
    The command's name used as an MQTT topic.

  • read_cmd: "fe070009"
    The command used to read the outdoor temperature, formatted as a sequence of bytes.

  • write_cmd: ""
    This command is not applicable for writing (left empty).

  • active: false
    Indicates that the command is not currently active.

  • interval: 0
    Specifies no minimum interval between command executions.

  • master: true
    Indicates that the value of interest is in the master component.

  • position: 1
    Starting position within the data bytes, beginning at 1.

  • datatype: "DATA2B"
    Represents the data type for processing this command.

  • divider: 1
    Used for value conversion (no adjustment needed here).

  • min: 0
    The minimum value that is acceptable for this command.

  • max: 0
    No maximum value is specified (current setup indicates that it may only allow a specific reading).

  • digits: 2
    Specifies two decimal points for numerical representation.

  • unit: "°C"
    The unit for measurement, indicating degrees Celsius.

  • ha: true
    Indicates support for Home Assistant auto-discovery.

  • ha_component: "sensor"
    Specifies that this command represents a sensor component.

  • ha_device_class: "temperature"
    Classifying this device as a temperature sensor within Home Assistant.

  • ha_entity_category: ""
    No specific entity category has been defined (left empty).

  • ha_mode: ""
    No specific mode has been set for the Home Assistant integration.

  • ha_key_value_map: {}
    No additional key-value mappings have been specified.

  • ha_default_key: 0
    The default key for options in Home Assistant is set to 0.

  • ha_payload_on: 0
    The payload indicating the ON state (not applicable here).

  • ha_payload_off: 0
    The payload indicating the OFF state (not applicable here).

  • ha_state_class: ""
    No specific state class has been defined.

  • ha_step: 1
    The increment step value for the command.

read_cmd, write_cmd and active logic

In the eBUS protocol, every communication follows a strict byte-oriented sequence defined by the OSI Layers of the specification. The hexadecimal strings you see in read_cmd or write_cmd are actually partial segments of an eBUS Telegram.

To understand them byte-by-byte, we must break down the standard message format: ZZ PB SB NN [Data...].

Note: The source address QQ is handled automatically by the ESP firmware and is omitted from the stored command string itself. It is defined in the adapter configuration in the field eBUS address.

Read command

The active field determines the ESP's behavior:

  • Passive (false): Listens for the read_cmd to appear naturally on the bus (sent by another controller) and parses the data.
  • Active (true): The ESP initiates the request itself at the specified interval.

Byte-by-Byte Breakdown

Using the example : 08b509030d1700

Byte Hex Name Description
1 08 ZZ (Destination) In this case, address 08 is the primary heat generator (the boiler). When you run scan, you should see this address in the list.
2 b5 PB (Primary) Manufacturer Command. The b5h class is reserved for manufacturer-specific commands.
3 09 SB (Secondary) Data Operation. The sub-command used here to query or set internal values.
4 03 NN (Length) Data Length. This indicates that 3 bytes of data follow to specify the parameter.
5-7 0d1700 Data Exactly NN bytes must be defined. Here, 0d 17 00 is the specific ID for "Storage Temperature".

Anatomy of an eBUS Message

When the ESP sends this on the wire, the full sequence looks like this:

  1. SYN (aa): A special synchronization byte that starts every telegram.
  2. QQ (Source): Your adapter address (e.g., ff). This is used for "arbitration" to ensure two devices don't talk at once.
  3. ZZ PB SB NN D1 D2 ... Dn: The command string you defined (e.g., 08b509030d1700).
  4. CRC: A Checksum byte automatically calculated from all previous bytes to ensure no data was corrupted.
  5. ACK/Data: The slave (boiler/sensor) replies with an "Acknowledge" or the requested data.

You can see it in the logs like this (read from bottom):

16:48:57.390 DEBUG  '08b509030d1700' [storageTemp] 1d03 -> 49.813 °C
16:48:57.386 INFO  ff08b509030d1700 / 031d0300

Response Segment (031d0300):

  • 03: Slave is sending 3 bytes.
  • 1d 03: The raw data.
  • 00: Status byte.

The firmware converts the hex 1d03 using your datatype:

  • Hex: 1d 03 (Little Endian -> 031d)
  • Decimal: 797
  • Formula: 797 / 16 = 49.813 °C

Write Commands

The write_cmd acts as a template. When a new value is sent from a user interface, the firmware:

  1. Encodes the value into hex based on the datatype.
  2. Appends it after the write_cmd header.
  3. Broadcasts the full string to the boiler.

Clone this wiki locally