Skip to content
Get started

Modbus Controller Binary Sensor

The modbus_controller binary sensor platform creates a binary 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. Read and Write access. 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. Read and Write access. 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).

  • bitmask (Optional, int): sometimes multiple values are packed in a single register’s response. The bitmask is used to determined if the result is true or false. See Bitmasks.

  • 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 the poll reads to cover this binary sensor. For the register types (holding/read) it defaults to 2 (one register); raise it only when the bit you are reading sits in a wider response, such as a custom_pdu reply spanning several registers. It sets the size of the read, not which bit is published — the bit is always selected by offset and bitmask. It has no effect on the coil and discrete_input types, which are always read as a single bit.

  • 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 binary sensor. Parameters:

    • x (bool): The parsed boolean value of the modbus data
    • data (std::span<const uint8_t>): span containing the complete raw modbus response bytes for this binary sensor
    • item (pointer to a ModbusBinarySensor object): The binary sensor object itself.

    Possible return values for the lambda:

    • return true/false; the new value for the binary sensor.

  • 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 the 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. If a binary_sensor is created from an input register, the offset is in bytes. For coil and discrete input resisters, the LSB of the first data byte contains the coil addressed in the request. The other coils follow toward the high-order end of this byte and from low order to high order in subsequent bytes. For registers, the offset is the position of the relevant bit. To get the value of the coil register, 2 can be retrieved using address: 2 / offset: 0 or address: 0 / offset 2.

  • All other options from Binary Sensor.

Example

Section titled “Example”
binary_sensor:
- platform: modbus_controller
  modbus_controller_id: modbus1
  name: "Error status"
  register_type: input
  address: 0x3200
  bitmask: 0x80 #(bit 8)

See Also

Section titled “See Also”