Modbus


Modbus is a serial communication protocol to control PLCs (Programmable Logic Controller). It supports various types of devices which can be controlled over serial, TCP, and UDP connections.

Configuration

How to add modbus to your installation depends on the connection type, either a network or serial connection.

Platforms:

  • binary_sensor
  • climate
  • cover
  • sensor
  • switch

are all defined as part of the modbus configuration. The old configuration style, (having each outside the modbus configuration is still supported, but will cause a warning, and will be removed in a later release).

Network connection

For a network connection, add the following to your configuration.yaml file:

# Example configuration.yaml entry for a TCP connection
modbus:
  - name: hub1
    type: tcp
    host: IP_ADDRESS
    port: 502

Configuration Variables

delay integer (Optional, default: 0)

Time to sleep in seconds after connecting and before sending messages. Some modbus-tcp servers need a short delay typically 1-2 seconds in order to prepare the communication. If a server accepts connecting, but there is no response to the requests send, this parameter might help.

host string Required

The IP address of your Modbus device, e.g., 192.168.1.1.

name string (Optional, default: modbus_hub)

Name for this hub. Must be unique, so it is required when setting up multiple instances.

port integer Required

The network port for the communication.

timeout integer (Optional, default: 3)

Timeout for slave response in seconds.

type string Required

Type of the connection to Modbus. Possible values are tcp (Modbus TCP protocol according to “MODBUS Messaging Implementation Guide version 1.0b” provided by Schneider Automation.), udp(Modbus TCP form, but using UDP for transport. It removes the overheads required for TCP.) and rtuovertcp (Modbus RTU message transmitted with a TCP/IP wrapper and sent over a network instead of serial lines.).

Serial connection

For a serial connection, add the following to your configuration.yaml file:

# Example configuration.yaml entry for a serial connection
modbus:
  - name: hub1
    type: serial
    method: rtu
    port: /dev/ttyUSB0
    baudrate: 9600
    stopbits: 1
    bytesize: 8
    parity: N

Configuration Variables

baudrate integer Required

The speed for the serial connection.

bytesize integer Required

The bytesize for the serial connection; can be 5, 6, 7 or 8.

delay integer (Optional, default: 0)

Time to sleep in seconds after connecting and before sending messages. Some modbus servers need a short delay typically 1-2 seconds in order to prepare the communication. If a server accepts connecting, but there is no response to the requests send, this parameter might help.

method string Required

Method of the connection to Modbus, either rtu or ascii.

name string (Optional, default: modbus_hub)

Name for this hub. Must be unique, so it is required when setting up multiple instances.

parity string Required

The parity for the serial connection; can be E, O or N.

port string Required

The port where your Modbus device is connected to your Home Assistant host.

stopbits integer Required

The stopbits for the serial connection, either 1 or 2.

timeout integer (Optional, default: 3)

Timeout for slave response in seconds.

type string Required

Type of the connection to Modbus, needs to be serial for this setup.

Configuring platform binary sensor

The modbus binary sensor allows you to gather data from Modbus coils with state ON/OFF.

To use your Modbus binary sensors in your installation, add the following to your configuration.yaml file:

# Example configuration.yaml entry for binary_sensor configuration
modbus:
  - name: hub1
    type: tcp
    host: IP_ADDRESS
    port: 502
    binary_sensors:
      - name: Sensor1
        slave: 1
        address: 100
      - name: Sensor2
        address: 110
        input_type: discrete_input

Configuration Variables

binary_sensors map (Optional)

A list of all binary_sensors available in this modbus instance.

device_class string (Optional)

Device class to be used for the UI (e.g. “door”).

input_type string (Optional, default: holding)

type of adddress (holding/discrete/coil)

name string Required

Name for this binary_sensor. Must be unique.

scan_interval integer (Optional, default: 15)

Defines the update interval of the sensor in seconds.

slave integer (Optional)

The number of the slave.

address integer Required

Address of the Register.

Configuring platform climate

To use your Modbus thermostat in your installation, add the following to your configuration.yaml file:

# Example configuration.yaml entry
modbus:
  - name: hub1
    type: tcp
    host: IP_ADDRESS
    port: 502
    climates:
      - name: Watlow F4T
        slave: 1
        data_type: uint
        data_count: 1
        scale: 0.1
        offset: 0
        precision: 1
        max_temp: 30
        min_temp: 15
        temp_step: 1
        target_temp_register: 2782
        current_temp_register: 27586

Configuration Variables

climates map (Optional)

A list of all climates available in this modbus instance.

current_temp_register integer Required

Register number for current temperature (Process value).

current_temp_register_type string (Optional, default: holding)

Modbus register type (holding, input) for current temperature, default holding.

data_count integer (Optional, default: 2)

Number of registers to read.

data_type string (Optional, default: float)

Response representation (int, uint, float, custom). If float selected, value will converted to IEEE 754 floating point format.

min_temp integer (Optional, default: 5)

Maximum setpoint temperature.

name string Required

Name of the device

offset float (Optional, default: 0)

Final offset (output = scale * value + offset).

precision integer (Optional, default: 1)

Number of valid decimals.

scale float (Optional, default: 1)

Scale factor (output = scale * value + offset).

scan_interval integer (Optional, default: 15)

Defines the update interval of the sensor in seconds.

slave integer Required

The number of the slave (Optional for tcp and upd Modbus, use 1).

structure string (Optional)

If data_type is custom specified a double-quoted Python struct is expected here, to format the string to unpack the value. See Python documentation for details. Example: >i.

Default:

f

target_temp_register integer Required

Register number for target temperature (Setpoint).

temp_step float (Optional, default: 0.5)

The supported step size a target temperature can be increased/decreased.

temperature_unit string (Optional, default: C)

Temperature unit reported by the current_temp_register. C or F

Services

Service Description
set_temperature Set Temperature. Requires value to be passed in, which is the desired target temperature. value should be in the same type as data_type

Configuring platform cover

The modbus cover platform allows you to control Modbus covers (such as blinds, a roller shutter, or a garage door).

At the moment, we support the opening and closing of a cover. You can control your covers either using coils or holding registers.

Cover that uses the coil attribute is not able to determine intermediary states such as opening and closing. Coil stores only two states — “0” means cover closed, and “1” implies cover open. To allow detecting intermediary states, we added an optional status_register attribute. It will enable you to write your command (e.g., to open a cover) into a coil, and read current cover status back through the register. Additionally, you can specify values for state_open, state_opening, state_closed, and state_closing attributes. These will be matched with the value read from the status_register.

If your cover uses holding register to send commands (defined by the register attribute), it can also read the intermediary states. To adjust which value represents what state, you can fine-tune the optional state attributes, like state_open. These optional state values are also used for specifying values written into the register. If you specify an optional status_register attribute, cover states will be read from status_register instead of the register used for sending commands.

To use Modbus covers in your installation, add the following to your configuration.yaml file:

# Example configuration.yaml entry
modbus:
  - name: hub1
    type: tcp
    host: IP_ADDRESS
    port: 502
    covers:
      - name: Door1
        device_class: door
        scan_interval: 1
        coil: 0
      - name: Door2
        device_class: door
        scan_interval: 1
        coil: 1
        status_register: 1
      - name: Door3
        slave: 2
        device_class: door
        scan_interval: 1
        register: 0
        state_open: 1
        state_closed: 0

Configuration Variables

covers map Required

The array contains a list of all your Modbus covers.

coil integer Required

Coil address; can be omitted if a register attribute is specified. Coil and register attributes are mutually exclusive, and you need to always specify one of them.

device_class device_class (Optional, default: None)

The type/class of the cover to set the icon in the frontend.

name string Required

Name of the switch.

register integer Required

Holding register address; can be omitted if a coil attribute is specified. Coil and register attributes are mutually exclusive, and you need to always specify one of them.

scan_interval integer (Optional, default: 15)

Defines the update interval of the sensor in seconds.

slave integer (Optional, default: 1)

The number of the slave (can be omitted for tcp and udp Modbus).

state_open integer (Optional, default: 1)

A value in status_register or register representing an open cover. If your configuration uses an register attribute, this value will be also written into a holding register to open the cover.

state_closed integer (Optional, default: 0)

A value in status_register or register representing a closed cover. If your configuration uses an register attribute, this value will be also written into a holding register to close the cover.

state_opening integer (Optional, default: 2)

A value in status_register or register telling us that the cover is opening at the moment. Note that this state should be also supported on your connected Modbus cover. If it won’t write this intermediary state into the register, this state won’t be detected.

state_closing integer (Optional, default: 2)

A value in status_register or register telling us that the cover is closing at the moment. Note that this state should be also supported on your connected Modbus cover. If it won’t write this intermediary state into the register, this state won’t be detected.

status_register integer (Optional)

An address of an register, from which all the cover states will be read. If you specified register attribute, and not status_register attribute, your main register will also be used as a status register.

status_register_type string (Optional)

Modbus register type (holding, input), default holding.

Example: Modbus cover controlled by a coil

This example shows a configuration for a Modbus cover controlled using a coil. Intermediary states like opening/closing are not supported. The cover state is polled from Modbus every 10 seconds.

modbus:
  - name: hub1
    type: tcp
    host: IP_ADDRESS
    port: 502
    covers:
      - name: Door1
        slave: 1
        coil: 1
        device_class: door
        scan_interval: 10
      - name: Door2
        slave: 2
        coil: 2
        device_class: door
        scan_interval: 10

Example: Modbus cover controlled by a coil, it’s state is read from the register

This example shows a configuration for a Modbus cover controlled using a coil. Actual cover state is read from the status_register. We’ve also specified register values to match with the states open/opening/closed/closing. The cover state is polled from Modbus every 10 seconds.

modbus:
  - name: hub1
    type: tcp
    host: IP_ADDRESS
    port: 502
    covers:
      - name: Door1
        slave: 1
        device_class: door
        scan_interval: 10
        coil: 1
        status_register: 1
        status_register_type: input
        state_opening: 1
        state_open: 2
        state_closing: 3
        state_closed: 4

Example: Modbus cover controlled by a holding register

This example shows a configuration for a Modbus cover controlled using a holding register, from which we also read current cover state. We’ve also specified register values to match with the states open/opening/closed/closing. The cover state is polled from Modbus every 10 seconds.

modbus:
  - name: hub1
    type: tcp
    host: IP_ADDRESS
    port: 502
    covers:
      - name: Door1
        slave: 1
        device_class: door
        scan_interval: 10
        register: 1
        state_opening: 1
        state_open: 2
        state_closing: 3
        state_closed: 4

Example: Modbus cover controlled by a holding register, it’s state is read from the status register

This example shows a configuration for a Modbus cover controlled using a holding register. However, cover state is read from a status_register. In this case, we’ve specified only values for state_open and state_closed, for the rest, default values are used. The cover state is polled from Modbus every 10 seconds.

modbus:
  - name: hub1
    type: tcp
    host: IP_ADDRESS
    port: 502

    covers:
      - name: Door1
        slave: 1
        device_class: door
        scan_interval: 10
        register: 1
        status_register: 2
        register_type: holding
        state_open: 1
        state_closed: 0

Configuring platform sensor

The modbus cover platform allows you to control Modbus covers (such as blinds, a roller shutter, or a garage door).

The modbus sensor allows you to gather data from Modbus registers.

To use your Modbus sensors in your installation, add the following to your configuration.yaml file:

# Example configuration.yaml entry
modbus:
  - name: hub1
    type: tcp
    host: IP_ADDRESS
    port: 502
    sensors:
      - name: Sensor1
        unit_of_measurement: °C
        slave: 1
        address: 100
      - name: Sensor2
        unit_of_measurement: mg
        slave: 1
        address: 110
        count: 2
      - name: Sensor3
        unit_of_measurement: °C
        slave: 1
        address: 120
        input_type: input
        data_type: float
        scale: 0.01
        offset: -273.16
        precision: 2

Configuration Variables

sensors map Required

The array contains a list of all your Modbus sensors.

address integer Required

Register number.

count integer (Optional, default: 1)

Number of registers to read.

data_type string (Optional, default: int)

Response representation (int, uint, float, string, custom). If float selected, value will be converted to IEEE 754 floating point format.

device_class device_class (Optional, default: None)

The type/class of the sensor to set the icon in the frontend.

input_type string (Optional)

Modbus register type (holding, input), default holding.

name string Required

Name of the sensor.

offset float (Optional, default: 0)

Final offset (output = scale * value + offset).

precision integer (Optional, default: 0)

Number of valid decimals.

reverse_order boolean (Optional, default: false)

Reverse the order of registers when count >1.

scale float (Optional, default: 1)

Scale factor (output = scale * value + offset).

scan_interval integer (Optional, default: 15)

Defines the update interval of the sensor in seconds.

slave integer Required

The number of the slave (Optional for tcp and upd Modbus).

structure string (Optional)

If data_type is custom specified a double-quoted Python struct is expected here, to format the string to unpack the value. See Python documentation for details. Example: >i.

unit_of_measurement integer (Optional)

Unit to attach to value.

If you specify scale or offset as floating point values, double precision floating point arithmetic will be used to calculate final value. This can cause loss of precision for values that are larger than 2^53.

Full example

Example temperature sensor with a default scan interval:

modbus:
  - name: hub1
    type: tcp
    host: IP_ADDRESS
    port: 502
    sensors:
      - name: Room_1
        slave: 10
        address: 0
        input_type: holding
        unit_of_measurement: °C
        count: 1
        scale: 0.1
        offset: 0
        precision: 1
        data_type: integer

Configuring platform switch

The modbus switch platform allows you to control Modbus coils or registers.

To use your Modbus switches in your installation, add the following to your configuration.yaml file:

# Example configuration.yaml entry
modbus:
  - name: hub1
    type: tcp
    host: IP_ADDRESS
    port: 502
    switches:
      - name: Switch1
        address: 13
        input_type: coil
      - name: Switch2
        slave: 2
        address: 14
        input_type: coil
      - name: Register1
        address: 11
        command_on: 1
        command_off: 0

Configuration Variables

switches map Required

The array contains a list of all your Modbus switches.

address integer Required

Coil number or register

command_on integer Required

Value to write to turn on the switch.

command_off integer Required

Value to write to turn off the switch.

input_type string (Optional, default: holding)

type of adddress (holding/input/coil)

name string Required

Name of the switch.

scan_interval integer (Optional, default: 15)

Defines the update interval of the sensor in seconds.

slave integer Required

The number of the slave (can be omitted for tcp and udp Modbus).

state_on integer (Optional, default: same as command_on)

Register value when switch is on.

state_off integer (Optional, default: same as command_off)

Register value when switch is off.

verify_register string (Optional, default: same as register)

Register to readback.

verify_state boolean (Optional, default: true)

Define if is possible to readback the status of the switch.

Full example

Example switches, for which the state is polled from Modbus every 15 seconds (default).

modbus:
  - name: hub1
    type: tcp
    host: IP_ADDRESS
    port: 502
    switches:
      - name: Switch1
        slave: 1
        address: 13
        input_type: coil
      - name: Switch2
        slave: 2
        address: 14

Multiple connections

Multiple connections are possible, add something like the following to your configuration.yaml file:

# Example configuration.yaml entry for multiple TCP connections
modbus:
  - type: tcp
    host: IP_ADDRESS_1
    port: 2020
    name: hub1

  - type: tcp
    host: IP_ADDRESS_2
    port: 501
    name: hub2

Services

Service Description
write_register Write register. Requires hub, unit, address and value fields. value can be either single value or an array

Service Data Attributes

Attribute Description
hub Hub name (defaults to ‘default’ when omitted)
unit Slave address (1-255, mostly 255 if you talk to Modbus via TCP)
address Address of the Register (e.g., 138)
value A single value or an array of 16-bit values. Single value will call modbus function code 6. Array will call modbus function code 16. Array might need reverse ordering. E.g., to set 0x0004 you might need to set [4,0]

Log warning (v1.0.8 and onwards)

Pymodbus (which is the implementation library) was updated and issues a warning:

  • “Not Importing deprecated clients. Dependency Twisted is not Installed”

This warning can be safely ignored, and have no influence on how the integration works!

Opening an issue

When opening an issue, please add your current configuration (or a scaled down version), with at least:

  • the Modbus configuration lines
  • the entity (sensor, etc.) lines

In order for the developers better to identify the problem, please add the following lines to configuration.yaml:

logger:
  logs:
    homeassistant.components.modbus: debug
    pymodbus.client: debug

and restart Home Assistant, reproduce the problem, and include the log in the issue.

Building on top of Modbus