Skip to content
Get started

Modbus Controller Text Sensor

The modbus_controller sensor platform creates a text sensor from a modbus_controller component and requires Modbus Controller to be configured.

Configuration variables

Section titled “Configuration variables”

  • register_type (Required): type of the modbus register.

    • coil : Coils are 1-bit registers (on/off values) that are used to control discrete outputs. They may be read and/or written. Modbus Function Code 1 (Read Coil Status) will be used.
    • discrete_input : discrete input register (read only coil) are similar to coils but can only be read. Modbus Function Code 2 (Read Input Status) will be used.
    • holding : Holding Registers - Holding registers are the most universal 16-bit register. They may be read and/or written. Modbus Function Code 3 (Read Holding Registers) will be used.
    • input : Input Registers - 16-bit registers used for input; may only be read. Modbus Function Code 4 (Read Input Registers) will be used. read is an accepted alias for this value.

  • address (Required, int): start address of the first register in a range (can be decimal or hexadecimal).

  • skip_updates (Optional, int): Deprecated and no longer has any effect — every register range is polled on each update_interval. The key is still accepted (logging a config-time warning) and will be removed in 2027.3.0. To poll some registers less often, place those sensors on a second modbus_controller with the same address: and a slower update_interval:.

  • response_size (Optional, int): Number of bytes of the response. Defaults to 2 (one register); the text sensor spans response_size / 2 registers rounded up, so increase it for values that span more registers.

  • raw_encode (Optional, enum): If the response is binary it can’t be published directly. Since a text sensor only publishes strings the binary data can be encoded. Defaults to ANSI. Possible encodings are:

    • NONE : Don’t encode data.
    • HEXBYTES : 2 byte hex string. 0x2011 will be sent as “2011”.
    • COMMA : Byte values as integers, delimited by a coma. 0x2011 will be sent as “32,17”.
    • ANSI : Each byte is treated as an ANSI character. All control characters are ignored.

NOTE

From version 2024.7, default encoding is ANSI. Thus, all control characters are now ignored. If you need to receive all characters, use NONE encoding.

  • reuse_previous_range (Optional, boolean or auto): How this item relates to the register range built just before it (same register type, ascending address order). auto (default) joins when the addresses are adjacent and the item’s position in the reply is exact; true joins unconditionally, reading across address gaps and past registers with a non-standard response_size; false always starts a new range here (later items may still extend it). See Register ranges. Replaces the deprecated force_new_range and register_count options, which will be removed in 2027.3.0 — the linked section covers migration.

  • custom_pdu (Optional, list of bytes): The modbus PDU (function code + data) for a custom command. This allows using non-standard commands. The device address (taken from the controller’s address:) and the CRC are added automatically, so do not include a leading device-address byte. If custom_pdu is used, address and register_type can’t be used. Renamed from custom_command, which is now removed and raises a config-validation error. See Using custom_pdu for how to use custom_pdu

  • lambda (Optional, lambda): Lambda to be evaluated every update interval to get the new value of the text sensor. It is called after the encoding according to raw_encode.

    Parameters passed into the lambda

    • x (std::string): The parsed value of the modbus data according to raw_encode

    • data (std::span<const uint8_t>): span containing the complete raw modbus response bytes for this text sensor note: because the response contains data for all registers in the same range you have to use data[item->offset] to get the first response byte for your text sensor.

    • item (pointer to a SensorItem derived object): The text sensor object itself.

    Possible return values for the lambda:

    • return <std::string>; the new value for the text sensor.
    • return {}; uses the parsed value for the state (same as return x; ).

  • offset (Optional, int): Offset from start address in bytes (only required for uncommon response encodings). If more than one register is written in a command this value is used to find the start of this datapoint relative to start address. The component calculates the size of the range based on offset and size of the value type. The value for offset depends on the register type.

  • All options from Text Sensor.

Example

Section titled “Example”
text_sensor:
  - platform: modbus_controller
    modbus_controller_id: modbus_device
    id: reg_1002_text
    bitmask: 0
    register_type: holding
    address: 1002
    raw_encode: HEXBYTES
    name: Register 1002 (Text)
    lambda: |-
      uint16_t value = modbus::helpers::word_from_hex_str(x, 0);
      switch (value) {
        case 1: return std::string("ready");
        case 2: return std::string("EV is present");
        case 3: return std::string("charging");
        case 4: return std::string("charging with ventilation");
        default: return std::string("Unknown");
      }
      return x;

See Also

Section titled “See Also”