51 KiB
title, description, ha_category, ha_release, ha_iot_class, ha_codeowners, ha_domain, ha_platforms, ha_quality_scale, ha_integration_type
| title | description | ha_category | ha_release | ha_iot_class | ha_codeowners | ha_domain | ha_platforms | ha_quality_scale | ha_integration_type | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Modbus | Instructions on how to integrate modbus and platforms. |
|
pre 0.7 | Local Polling |
|
modbus |
|
gold | integration |
modbus is a communication protocol to control PLCs (Programmable Logic Controller) and RTUs (Remote Terminal Unit).
The integration adheres strictly to the protocol specification using pymodbus for the actual protocol implmentation.
The modbus integration supports all devices adhering to the modbus standard. The communication to the device/devices can be serial (rs-485), TCP, or UDP connections. The modbus integration allows multiple communication channels e.g. a serial port connection combined with one or more TCP connections.
Configuring modbus communication
Configure the modbus communication with modbus devices. This is a general setup needed establish access to the device.
The modbus integration allows you to use multiple connections each with multiple sensors etc.
The modbus integration provides a number of parameters to help communicate with "difficult" devices, these parameters are independent of the type of communication.
{% configuration %} delay: description: "Time to delay sending messages in seconds after connecting. Some modbus devices need a delay of typically 1-2 seconds after connection is established to prepare the communication. If a device does not respond to messages after connecting, then try this parameter. Remark: solely affect the first message." required: false default: 0 type: integer message_wait_milliseconds: description: "Time to wait in milliseconds between requests." required: false default: 30 for serial connection, 0 for all other connections. type: integer name: description: "Name of this hub. Must be unique." required: true type: string retries: description: "Number of times to retry a request." required: false default: 3 type: integer timeout: description: "Timeout while waiting for a response in seconds." required: false default: 5 type: integer type: description: "Type of modbus." required: true type: list keys: tcp: description: "TCP/IP connection with socket framer, used with Ethernet enabled devices." udp: description: "UDP connection with socket framer, rarely used." rtuovertcp: description: "TCP/IP connection with rtu framer, used when connection to modbus forwarders." serial: description: "Serial connection with RTU framer, used with TTY port or USB rs485 converter."
{% endconfiguration %}
Configuring tcp connection
type: tcp is required. Used for devices providing a TCP/IP interface directly.
{% configuration %}
host:
description: "IP address or name of your modbus device, e.g., 192.168.1.1."
required: true
type: string
port:
description: "Network port for the communication."
required: true
type: integer
{% endconfiguration %}
Example: typical tcp configuration
# Example yaml: typical tcp connection
modbus:
- name: modbus_hub
type: tcp
host: IP_ADDRESS
port: 502
Example: full tcp configuration
# Example yaml: full tcp connection
modbus:
- name: modbus_hub
type: tcp
host: IP_ADDRESS
port: 502
close_comm_on_error: true
delay: 0
message_wait_milliseconds: 30
retries: 3
timeout: 5
Configuring a TCP-RTU connection
type: rtuovertcp is required. Used for devices providing a TCP/IP interface directly.
This is typically used, when communicating with a modbus-forwarder, a device that has a TCP/IP connection upwards, and one or more serial connections downwards. lets also write more here, to see if the error moves.
{% configuration %}
host:
description: "IP address or name of your modbus device, e.g., 192.168.1.1."
required: true
type: string
port:
description: "Network port for the communication."
required: true
type: integer
{% endconfiguration %}
Example: typical TCP-RTU configuration
# Example yaml: typical tcp-rtu connection
modbus:
- name: modbus_hub
type: rtuovertcp
host: IP_ADDRESS
port: 502
Example: full TCP-RTU configuration
# Example yaml: full tcp-rtu connection
modbus:
- name: modbus_hub
type: rtuovertcp
host: IP_ADDRESS
port: 502
close_comm_on_error: true
delay: 0
message_wait_milliseconds: 30
retries: 3
timeout: 5
Configuring a UDP connection
type: udp is required. This is rarely used, and only for very special configurations.
{% configuration %}
host:
description: "IP address or name of your modbus device, e.g., 192.168.1.1."
required: true
type: string
port:
description: "Network port for the communication."
required: true
type: integer
{% endconfiguration %}
Example: typical udp configuration
# Example yaml: typical udp connection
modbus:
- name: modbus_hub
type: udp
host: IP_ADDRESS
port: 502
Example: full UDP configuration
# Example yaml: full udp connection
modbus:
- name: modbus_hub
type: udp
host: IP_ADDRESS
port: 502
close_comm_on_error: true
delay: 0
message_wait_milliseconds: 30
retries: 3
timeout: 5
Configuring serial connection
type: serial is required. This is used for devices providing a serial rs485 interface.
The physical interface is typically a USB serial-rs485 converter or an rs232-rs485 connected to a serial port.
{% configuration %} baudrate: description: "Speed of the serial connection, higher speed gives better performance." required: true type: integer bytesize: description: "Data size in bits of each byte." required: true type: list keys: "5": description: "5 bit for data, rarely used." "6": description: "6 bit for data, rarely used." "7": description: "7 bit for data, used for very old devices." "8": description: "8 bit for data, standard." method: description: "Method of the connection to modbus." required: true type: list keys: rtu: description: "Binary data transmission preceded by slave id and followed by a crc, standard." ascii: description: "ASCII data transmission preceded by slave id and followed by a crc, used for few devices." parity: description: "Parity of the data bytes." required: true type: list keys: E: description: "Even parity bit." O: description: "Odd parity bit." N: description: "No parity bit, standard." port: description: "Serial port or USB device where your modbus device is connected to your Home Assistant host." required: true type: string stopbits: description: "Stopbits of the data bytes." required: true type: list keys: '1': description: "1 stop bit." '2': description: "2 stop bits, standard."
{% endconfiguration %}
Example: typical serial configuration
# Example yaml: typical serial connection
modbus:
- name: modbus_hub
type: serial
port: /dev/ttyUSB0
baudrate: 9600
bytesize: 8
method: rtu
parity: E
stopbits: 1
Example: full serial configuration
# Example yaml: full udp connection
modbus:
- name: modbus_hub
type: serial
port: /dev/ttyUSB0
baudrate: 9600
bytesize: 8
method: rtu
parity: E
stopbits: 1
close_comm_on_error: true
delay: 0
message_wait_milliseconds: 30
retries: 3
timeout: 5
Configuring multiple connections
Multiple connections can freely mix different communications:
# Example yaml: multiple tcp connections
modbus:
- name: modbus_hub
type: tcp
host: IP_ADDRESS_1
port: 2020
- name: modbus_hub2
type: tcp
host: IP_ADDRESS_2
port: 502
# Example yaml: tcp connection and serial connection
modbus:
- name: modbus_hub
type: tcp
host: IP_ADDRESS_1
port: 2020
- name: modbus_hub2
type: serial
port: /dev/ttyUSB0
baudrate: 9600
bytesize: 8
method: rtu
parity: E
stopbits: 1
Configuring modbus entities
modbus entities are grouped below each modbus communication entry.
All modbus entities have the following parameters:
Please refer to Parameter usage for conflicting parameters.
{% configuration %}
address:
description: "Address of coil/register."
required: true
type: integer
lazy_error_count:
description: "Number of errors before entity becomes unavailable.
Is used to prevent spontaneous errors affecting statistic graphs.
A succesfull request resets the error count."
required: false
type: integer
default: 0
name:
description: "Name of the entity which must be unique within the entity type."
required: true
type: string
scan_interval:
description: "Update interval in seconds.
scan_interval = 0 for no polling.
Entities are unavailable until the first scan interval is passed,
except for entities with scan_interval = 0, which are read at startup and not updated."
required: false
type: integer
default: 15
slave:
description: "Identical to device_address"
required: false
type: integer
default: 0
device_address:
description: "Id of the device. Used to address multiple devices on a rs485 bus or devices connected to a modbus repeater."
required: false
type: integer
default: 0
unique_id:
description: "ID that uniquely identifies this entity.
Slaves will be given a unique_id of <<unique_id>>_<<slave_index>>.
If two enities have the same unique ID, Home Assistant will raise an exception."
required: false
type: string
{% endconfiguration %}
Example: entities grouping
# Example yaml: entities grouping
modbus:
- type: tcp
host: IP_ADDRESS_1
port: 2020
name: "modbus_hub"
binary_sensors:
- name: binary_sensor1
address: 100
climates:
- name: "Watlow F4T"
address: 200
covers:
- name: Door1
address: 300
fans:
- name: Fan1
address: 400
lights:
- name: light1
address: 500
sensors:
- name: sensor1
address: 600
switches:
- name: Switch1
address: 700
The different types of entities are detailed in the following.
Configuring binary sensor entities
The Modbus binary sensor allows you to gather data from coils which as per standard have state ON/OFF.
Normally, a register contains 16 coils, giving different addresses depending on the request used.
Register 512: Coil 1 - 16
Register 513: Coil 17 - 32
input_type: coils would use addresses from 1 through 32, while input_type: input would use addresses 512 and 513.
For that reason, many devices (especially older ones) do not share the coil address space with the register address space,
and this input would read from a different address space than coil. The problem is present in devices with
shared address space and are a frequent cause of problems when configuring entities.
Please refer to Parameter usage for conflicting parameters.
{% configuration %}
binary_sensors:
description: "A list of all binary sensors configured for this connection."
required: false
type: map
keys:
device_class:
description: "The type/class to be used for the UI."
required: false
type: string
input_type:
description: "Type of request discrete_input, coil, holding or input"
required: false
default: coil
type: string
slave_count:
description: "Identical to virtual_count."
required: false
type: integer
virtual_count:
description: "Generate count+1 binary sensors (master + slaves).
Addresses are automatically incremented.
The parameter simplifies configuration and provides a much better performance by not using count+1 requests but a single request."
required: false
type: integer
unique_id:
description: "ID that uniquely identifies the entity. Slaves will automatically be given a unique_id of <<unique_id>>_<<slave_index>>. If two sensors have the same unique ID, Home Assistant will raise an exception."
required: false
type: string
{% endconfiguration %}
Example: typical binary sensor configuration
# Example yaml: typical binary_sensor
modbus:
- name: hub1
type: tcp
host: IP_ADDRESS
port: 502
binary_sensors:
- name: my_relay
address: 100
slave: 1
Example: full binary sensor configuration
# Example yaml: binary_sensor with all options
modbus:
- name: hub1
type: tcp
host: IP_ADDRESS
port: 502
binary_sensors:
- name: my_relay
address: 100
device_class: door
input_type: coil
lazy_error_count: 0
scan_interval: 15
slave: 1
slave_count: 0
unique_id: my_relay
Example: multiple identical binary sensor configuration
# Example of 10 identical binary_sensor
modbus:
- name: hub1
type: tcp
host: IP_ADDRESS
port: 502
binary_sensors:
- name: my_relay
address: 100
slave: 1
slave_count: 10
unique_id: my_relay
This configuration will poll coil addresses 100 to 110 every 15 seconds and update the binary_sensors: my_relay
and my_relay_1 to my_relay_10.
The master configuration like device_class are automatically copied to the slaves.
Configuring climate entities
The Modbus climate platform allows you to monitor a thermostat or heaters as well as set a target temperature.
Please refer to Parameter usage for conflicting parameters.
{% configuration %}
climates:
description: "A list of all climate entities in this modbus instance."
required: false
type: map
keys:
count:
description: "Number of registers to read.
only valid for data_type: custom and data_type: string, for other data types count is automatically calculated."
required: false
type: integer
data_type:
description: "Response representation."
required: false
default: int16
type: list
keys:
custom:
description: "user defined format, structure: and count: must be configured."
float16:
description: "16 bit signed float (1 register holds 1 value)."
float32:
description: "32 bit signed float (2 registers holds 1 value)."
float64:
description: "64 bit signed float (4 register holds 1 value)."
int:
description: "DEPRECATED is silently converted to int16"
int8:
description: "8 bit signed integer (1 register holds 1 value in lower byte)."
int16:
description: "16 bit signed integer (1 register holds 1 value)."
int32:
description: "32 bit signed integer (2 registers holds 1 value)."
int64:
description: "64 bit signed integer (4 registers holds 1 value)."
string:
description: "set of 8 bit characters, count: must be configured."
uint:
description: "DEPRECATED is silently converted to uint16"
uint8:
description: "8 bit unsigned integer (1 register holds 1 value in lower byte)."
uint16:
description: "16 bit unsigned integer (1 register holds 1 value)."
uint32:
description: "32 bit unsigned integer (2 registers holds 1 value)."
uint64:
description: "64 bit unsigned integer (4 registers holds 1 value)."
hvac_mode_register:
description: "Configuration of register for HVAC mode"
required: false
type: map
keys:
address:
description: "Address of HVAC mode register."
required: true
type: integer
write_registers:
description: "Request type, use write_registers if true else write_register.
If more than one value is specified for a specific mode, only the first one is used for writing to the register."
required: false
type: boolean
default: false
values:
description: "Mapping between the register values and HVAC modes"
required: true
type: map
keys:
state_off:
description: "Value corresponding to HVAC Off mode."
required: false
type: [integer, list]
state_heat:
description: "Value corresponding to HVAC Heat mode."
required: false
type: [integer, list]
state_cool:
description: "Value corresponding to HVAC Cool mode."
required: false
type: [integer, list]
state_auto:
description: "Value corresponding to HVAC Auto mode."
required: false
type: integer
state_dry:
description: "Value corresponding to HVAC Dry mode."
required: false
type: [integer, list]
state_fan_only:
description: "Value corresponding to HVAC Fan only mode."
required: false
type: [integer, list]
state_heat_cool:
description: "Value corresponding to HVAC Heat/Cool mode."
required: false
type: [integer, list]
hvac_onoff_register:
description: "Address of On/Off state.
When zero is read from this register, the HVAC state is set to Off, otherwise the hvac_mode_register
dictates the state of the HVAC. If no such register is defined, it defaults to Auto.
When the HVAC mode is set to Off, the value 0 is written to the register, otherwise the
value 1 is written."
required: false
type: integer
input_type:
description: Modbus register type for current temperature.
required: false
default: holding
type: list
keys:
holding:
description: "Holding register."
input:
description: "Input register."
max_temp:
description: "Maximum setpoint temperature."
required: false
type: integer
default: 35
min_temp:
description: "Minimum setpoint temperature."
required: false
type: integer
default: 5
offset:
description: "Final offset (output = scale * value + offset)."
required: false
type: float
default: 0
precision:
description: "Number of valid decimals."
required: false
type: integer
default: 0
scale:
description: "Scale factor (output = scale * value + offset)."
required: false
type: float
default: 1
structure:
description: "If data_type: custom is specified a double-quoted Python struct is expected,
to format the string to unpack the value. See Python documentation for details.
Example: >i."
required: false
type: string
default: ">f"
swap:
description: "Swap the order of bytes/words, not valid with custom and datatype: string"
required: false
default: none
type: list
keys:
none:
description: "No swapping."
byte:
description: "Swap bytes AB -> BA."
word:
description: "Swap word ABCD -> CDAB, not valid with data types: int8, uint8, int16, uint16"
word_byte:
description: "Swap word ABCD -> DCBA, not valid with data types: int8, uint8, int16, uint16"
target_temp_register:
description: "Register address for target temperature (Setpoint)."
required: true
type: integer
target_temp_write_registers:
description: "If true use write_registers for target temperature."
required: false
type: boolean
default: false
temp_step:
description: "Step size target temperature."
required: false
type: float
default: 0.5
temperature_unit:
description: "Temperature unit reported by current_temp_register. C or F."
required: false
default: C
type: list
keys:
C:
description: "Celsius"
F:
description: "Fahrenheit"
write_registers:
description: "Request type, use write_registers if true else write_register."
required: false
type: boolean
default: false
{% endconfiguration %}
Example: climate configuration
# Example configuration.yaml entry
modbus:
- name: hub1
type: tcp
host: IP_ADDRESS
port: 502
climates:
- name: "Watlow F4T"
address: 27586
input_type: holding
count: 1
data_type: custom
max_temp: 35
min_temp: 15
offset: 0
precision: 1
scale: 0.1
max_temp: 30
structure: ">f"
target_temp_register: 2782
target_temp_write_registers: true
temp_step: 1
temperature_unit: C
Configuring cover entities
The modbus cover platform allows you to control covers (such as blinds, a roller shutter, or a garage door).
At the moment, platform cover support the opening and closing of a cover. You can control your covers either using coils or holding registers.
Cover that uses input_type: coil 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, there is 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 input_type: holding (default) to send commands, 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.
Please refer to Parameter usage for conflicting parameters.
{% configuration %}
covers:
description: "A list of all cover entities configured for this connection."
required: true
type: map
keys:
device_class:
description: "The type/class of the cover to set the icon in the frontend."
required: false
type: device_class
default: None
input_type:
description: "Cover register type."
default: holding
required: false
type: list
keys:
holding:
description: "Holding register."
input:
description: "Input register."
state_open:
description: "A value in status_register or register representing an open cover.
If your configuration uses the register attribute, this value will be written into the holding register to open the cover."
required: false
default: 1
type: integer
state_closed:
description: "A value in status_register or register representing a closed cover.
If your configuration uses the register attribute, this value will be written into the holding register to close the cover."
required: false
default: 0
type: integer
state_opening:
description: "A value in status_register or register representing an opening cover.
Note that this state should be also supported on your connected Modbus cover.
If it won't report the state, this state won't be detected."
required: false
default: 2
type: integer
state_closing:
description: "A value in status_register or register representing a closing cover.
Note that this state should be also supported on your connected Modbus cover.
If it will not report the state, this state won't be detected."
required: false
default: 3
type: integer
status_register:
description: "Address of 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."
required: false
type: integer
status_register_type:
description: Cover status register type (holding, input), default holding.
required: false
type: list
keys:
holding:
description: "Holding register."
input:
description: "Input register."
{% endconfiguration %}
Example: Modbus cover
# Example configuration.yaml entry
modbus:
- name: hub1
type: tcp
host: IP_ADDRESS
port: 502
covers:
- name: Door1
device_class: door
input_type: coil
address: 117
state_open: 1
state_opening: 2
state_closed: 0
state_closing: 3
status_register: 119
status_register_type: holding
- name: "Door2"
address: 118
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, its 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, its 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 fan entities
The modbus fan platform allows you to control Modbus coils or registers.
Please refer to Parameter usage for conflicting parameters.
{% configuration %}
fans:
description: "A list of all fan entities in this modbus instance."
required: true
type: map
keys:
command_on:
description: "Value to write to turn on the fan."
required: false
default: 0x01
type: integer
command_off:
description: "Value to write to turn off the fan."
required: false
default: 0x00
type: integer
write_type:
description: Type of write request.
required: false
default: holding
type: list
keys:
holding:
description: "write_register is called."
holdings:
description: "write_registers is called."
coil:
description: "write_coil is called."
coils:
description: "write_coils is called."
verify:
description: "Read from Modbus device to verify fan.
If used without attributes, it uses the toggle register configuration.
If omitted, no verification is done, but the state of the fan is set with each toggle."
required: false
type: map
keys:
address:
description: "Address to read from."
required: false
default: write address
type: integer
delay:
description: "Delay between write and verify."
required: false
default: 0
type: integer
input_type:
description: Type of address.
required: false
default: same as write_type
type: list
keys:
coil:
description: "Coil (1bit relay)."
discrete:
description: "Discret input (1bit relay)."
holding:
description: "Holding register."
input:
description: "Input register."
state_on:
description: "Value when the fan is on."
required: false
default: same as command_on
type: integer
state_off:
description: "Value when the fan is off."
required: false
default: same as command_off
type: integer
{% endconfiguration %}
Example: fan configuration
# Example configuration.yaml entry
modbus:
- type: tcp
host: IP_ADDRESS
port: 502
fans:
- name: "Fan1"
address: 13
write_type: coil
- name: "Fan2"
slave: 2
address: 14
write_type: coil
verify:
- name: "Register1"
address: 11
command_on: 1
command_off: 0
verify:
input_type: holding
address: 127
state_on: 25
state_off: 1
Configuring light entities
The modbus light platform allows you to control Modbus coils or registers.
Please refer to Parameter usage for conflicting parameters.
{% configuration %}
lights:
description: "A list of all light entities in this modbus instance."
required: true
type: map
keys:
command_on:
description: "Value to write to turn on the light."
required: false
default: 0x01
type: integer
command_off:
description: "Value to write to turn off the light."
required: false
default: 0x00
type: integer
write_type:
description: "Type of write request."
required: false
default: holding
type: list
keys:
holding:
description: "write_register is called."
holdings:
description: "write_registers is called."
coil:
description: "write_coil is called."
coils:
description: "write_coils is called."
verify:
description: "Read from Modbus device to verify the light.
If used without attributes, it uses the toggle register configuration.
If omitted no verification, is done, but the state of the light is set with each toggle."
required: false
type: map
keys:
address:
description: "Address to read from."
required: false
default: "Same as address"
type: integer
delay:
description: delay between write and verify.
required: false
default: 0
type: integer
input_type:
description: Type of address (holding/coil/discrete/input).
required: false
default: "Same as write_type"
type: list
keys:
coil:
description: "Coil (1bit relay)."
discrete:
description: "Discrete inout (1bit relay)."
holding:
description: "Holding register."
input:
description: "Input register."
state_on:
description: "Value when the light is on."
required: false
default: "Same as command_on"
type: integer
state_off:
description: "Value when the light is off."
required: false
default: "Same as command_off"
type: integer
{% endconfiguration %}
Example: light configuration
# Example configuration.yaml entry
modbus:
- type: tcp
host: IP_ADDRESS
port: 502
lights:
- name: "light1"
address: 13
write_type: coil
- name: "light2"
slave: 2
address: 14
write_type: coil
verify:
- name: "Register1"
address: 11
command_on: 1
command_off: 0
verify:
input_type: holding
address: 127
state_on: 25
state_off: 1
Configuring sensor entities
The modbus sensor allows you to gather data from Modbus registers.
Please refer to Parameter usage for conflicting parameters.
{% configuration %}
sensors:
description: "A list of all sensors in this modbus instance."
required: true
type: map
keys:
count:
description: "Number of registers to read.
only valid for data_type: custom and data_type: string, for other data types count is automatically calculated."
required: false
type: integer
data_type:
description: "Response representation."
required: false
default: int16
type: list
keys:
custom:
description: "user defined format, structure: and count: must be configured."
float16:
description: "16 bit signed float (1 register holds 1 value)."
float32:
description: "32 bit signed float (2 registers holds 1 value)."
float64:
description: "64 bit signed float (4 register holds 1 value)."
int:
description: "DEPRECATED is silently converted to int16"
int8:
description: "8 bit signed integer (1 register holds 1 value in lower byte)."
int16:
description: "16 bit signed integer (1 register holds 1 value)."
int32:
description: "32 bit signed integer (2 registers holds 1 value)."
int64:
description: "64 bit signed integer (4 registers holds 1 value)."
string:
description: "set of 8 bit characters, count: must be configured."
uint:
description: "DEPRECATED is silently converted to uint16"
uint8:
description: "8 bit unsigned integer (1 register holds 1 value in lower byte)."
uint16:
description: "16 bit unsigned integer (1 register holds 1 value)."
uint32:
description: "32 bit unsigned integer (2 registers holds 1 value)."
uint64:
description: "64 bit unsigned integer (4 registers holds 1 value)."
device_class:
description: "The type/class of the sensor to set the icon in the frontend."
required: false
type: device_class
default: None
input_type:
description: "Modbus register type for sensor."
required: false
default: holding
type: list
keys:
holding:
description: "Holding register."
input:
description: "Input register."
min_value:
description: "The minimum allowed value of a sensor. If value < min_value --> min_value. Can be float or integer"
required: false
type: float
max_value:
description: "The maximum allowed value of a sensor. If value > max_value --> max_value. Can be float or integer"
required: false
type: float
nan_value:
description: If a Modbus sensor has a defined NaN value, this value can be set as a hex string starting with 0x containing one or more bytes (for example, 0xFFFF or 0x80000000) or provided as an integer directly. If triggered, the sensor becomes unavailable. Please note that the hex to int conversion for nan_value does currently not obey home-assistants Modbus encoding using the data_type, structure, or swap arguments.
required: false
type: string
zero_suppress:
description: Suppress values close to zero. If -zero_suppress <= value <= +zero_suppress --> 0. Can be float or integer
required: false
type: float
offset:
description: "Final offset (output = scale * value + offset)."
required: false
type: float
default: 0
precision:
description: "Number of valid decimals."
required: false
type: integer
default: 0
scale:
description: "Scale factor (output = scale * value + offset)."
required: false
type: float
default: 1
slave_count:
description: "Identical to virtual_count."
required: false
type: integer
virtual_count:
description: "Generates x+1 sensors (master + slaves), allowing read of multiple registers with a single read messsage."
required: false
type: integer
state_class:
description: "The state_class of the sensor."
required: false
type: string
structure:
description: "If data_type: custom is specified a double-quoted Python struct is expected,
to format the string to unpack the value. See Python documentation for details.
Example: >i."
required: false
type: string
default: ">f"
slave_count:
description: "Identical to virtual_count."
required: false
type: integer
virtual_count:
description: Generates x-1 slave sensors, allowing read of multiple registers with a single read message.
required: false
type: integer
swap:
description: "Swap the order of bytes/words, not valid with custom and datatype: string"
required: false
default: none
type: list
keys:
none:
description: "No swapping."
byte:
description: "Swap bytes AB -> BA."
word:
description: "Swap word ABCD -> CDAB, not valid with data types: int8, uint8, int16, uint16"
word_byte:
description: "Swap word ABCD -> DCBA, not valid with data types: int8, uint8, int16, uint16"
unit_of_measurement:
description: "Unit to attach to value."
required: false
type: string
zero_suppress:
description: "Suppress values close to zero. If -zero_suppress <= value <= +zero_suppress --> 0. Can be float or integer"
required: false
type: float
{% endconfiguration %}
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.
Example: sensor configuration
# 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
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
Example: sensor full configuration
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
state_class: measurement
count: 1
scale: 0.1
offset: 0
precision: 1
data_type: integer
Configuring switch entities
The modbus switch platform allows you to control Modbus coils or registers.
Please refer to Parameter usage for conflicting parameters.
{% configuration %}
switches:
description: "A list of all switches in this modbus instance."
required: true
type: map
keys:
command_on:
description: "Value to write to turn on the switch."
required: false
default: 0x01
type: integer
command_off:
description: "Value to write to turn off the switch."
required: false
default: 0x00
type: integer
write_type:
description: Type of write request.
required: false
default: holding
type: list
keys:
holding:
description: "write_register is called."
holdings:
description: "write_registers is called."
coil:
description: "write_coil is called."
coils:
description: "write_coils is called."
verify:
description: "Read from Modbus device to verify fan.
If used without attributes, it uses the toggle register configuration.
If omitted, no verification is done, but the state of the fan is set with each toggle."
required: false
type: map
keys:
address:
description: "Address to read from."
required: false
default: "Same as write address"
type: integer
delay:
description: "Delay between write and verify."
required: false
default: 0
type: integer
input_type:
description: Type of address.
required: false
default: same as write_type
type: list
keys:
coil:
description: "Coil (1bit relay)."
discrete:
description: "Discret input (1bit relay)."
holding:
description: "Holding register."
input:
description: "Input register."
state_on:
description: "Value when switch is on."
required: false
default: "Same as command_on"
type: integer
state_off:
description: "Value when switch is off."
required: false
default: "Same as command_off"
type: integer
{% endconfiguration %}
### Example: switch configuration
# Example configuration.yaml entry
modbus:
- type: tcp
host: IP_ADDRESS
port: 502
switches:
- name: Switch1
address: 13
write_type: coil
- name: Switch2
slave: 2
address: 14
write_type: coil
verify:
- name: Register1
address: 11
command_on: 1
command_off: 0
verify:
input_type: holding
address: 127
state_on: 25
state_off: 1
### Example: switch full configuration
# Example configuration.yaml entry
modbus:
- type: tcp
host: IP_ADDRESS
port: 502
switches:
- name: Switch1
address: 13
write_type: coil
- name: Switch2
slave: 2
address: 14
write_type: coil
verify:
- name: Register1
address: 11
command_on: 1
command_off: 0
verify:
input_type: holding
address: 127
state_on: 25
state_off: 1
Parameters usage matrix
Some parameters exclude other parameters, the following tables show what can be combined:
| Datatype: | custom | string | *16 | *32 | *64 |
|---|---|---|---|---|---|
| count | Yes | Yes | No | No | No |
| structure | Yes | No | No | No | No |
| slave_count | No | No | Yes | Yes | Yes |
| virtual_count | No | No | Yes | Yes | Yes |
| swap: none | Yes | Yes | Yes | Yes | Yes |
| swap: byte | No | No | Yes | Yes | Yes |
| swap: word | No | No | No | Yes | Yes |
| swap: word_byte | No | No | No | Yes | Yes |
modbus services
The modbus integration provides two generic write services in addition to the platform-specific services.
| Service | Description |
|---|---|
| modbus.write_register | Write register or registers |
| modbus.write_coil | Write coil or coils |
Description:
| Attribute | Description |
|---|---|
| hub | Hub name (defaults to 'modbus_hub' when omitted) |
| slave | Slave address (0-255) |
| address | Address of the Register (e.g. 138) |
| value | (write_register) A single value or an array of 16-bit values. Single value will call modbus function code 0x06. Array will call modbus function code 0x10. Values might need reverse ordering. E.g., to set 0x0004 you might need to set [4,0], this depend on the byte order of your CPU |
| state | (write_coil) A single boolean or an array of booleans. Single boolean will call modbus function code 0x05. Array will call modbus function code 0x0F |
The modbus integration also provides communication stop/restart services. These services will not do any reconfiguring, but simply stop/start the modbus communication layer.
| Service | Description |
|---|---|
| modbus.stop | Stop communication |
| modbus.restart | Restart communication (Stop first if running) |
Description:
| Attribute | Description |
|---|---|
| hub | Hub name (defaults to 'modbus_hub' when omitted) |
Example: writing a float32 type register
To write a float32 datatype register use network format like 10.0 == 0x41200000 (network order float hexadecimal).
service: modbus.write_register
data:
address: <target register address>
slave: <target slave address>
hub: <hub name>
value: [0x4120, 0x0000]
Service modbus.set-temperature
| 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 |
Service modbus.set_hvac_mode
| Service | Description |
|---|---|
| set_hvac_mode | Set HVAC mode. Requires value to be passed in, which is the desired mode. value should be a valid HVAC mode. A mapping between the desired state and the value to be written to the HVAC mode register must exist. Calling this service will also set the On/Off register to an appropriate value, if such a register is defined. |
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:
default: warning
logs:
homeassistant.components.modbus: debug
pymodbus: debug
and restart Home Assistant, reproduce the problem, and include the log in the issue.