jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-19 15:26:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

Rework modbus documentation. (#17874)

Browse Source 
Co-authored-by: Klaas Schoute <klaas_schoute@hotmail.com>
Co-authored-by: Franck Nijhof <frenck@frenck.nl>
This commit is contained in:
jan iversen 2021-05-25 17:18:23 +02:00 committed by GitHub
parent 8ff0f1770c
commit b62714bfd4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 368 additions and 250 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

616
source/_integrations/modbus.markdown
View File

@ -18,85 +18,96 @@ ha_platforms:
- switch - switch
--- ---
[Modbus](http://www.modbus.org/) is a serial communication protocol to control PLCs (Programmable Logic Controller). [Modbus](http://www.modbus.org/) is a serial communication protocol to control PLCs (Programmable Logic Controller) and RTUs (Remote Terminal Unit). The integration adheres strictly to the [protocol specification](https://modbus.org/docs/Modbus_Application_Protocol_V1_1b3.pdf).
It supports various types of devices which can be controlled over serial, TCP, and UDP connections. Modbus supports all devices adhering to the Modbus standard. The communication between the device(s) can be serial (rs-485), TCP, or UDP connections. The Modbus integration allows multiple communications e.g. serial combined with TCP or different TCP connected devices.
## Configuration # Configuring Modbus
How to add modbus to your installation depends on the connection type, either a network or serial connection. First, you define how to communicate with your Modbus devices and after that you define the information being exchanged. The Modbus integration allows you to use multiple connections.
Platforms: ## Configuring Modbus common parameters
- 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). Part of the configuration is common for all types of communication. Add the following to your `configuration.yaml` file:
### Network connection ```yaml
modbus:
- name: "hub1"
close_comm_on_error: true
delay: 5
timeout: 5
type: tcp
```
For a network connection, add the following to your `configuration.yaml` file: {% configuration %}
close_comm_on_error:
description: Determines if the device connection is closed when an error occurs, default is true. Some serial-rs485 adapters deliver garble when opened, this leads to a disconnect and a new connect, which can continue. If in a running communication the debug log contains a message from pymodbus, with the text "cleaning....", then try this parameter.
required: false
default: true
type: boolean
delay:
description: "Time to delay sending messages in seconds after connecting. Some Modbus devices need a delay of typically 1-2 seconds after established connection to prepare the communication. If a device does not respond to messages after connecting, this parameter might help. Remark: the delay is solely between connect and the first message."
required: false
default: 0
type: integer
name:
description: Name for this hub. Must be unique, so it is required when setting up multiple instances.
required: false
default: "modbus_hub"
type: string
timeout:
description: "Timeout while waiting for a response in seconds. Remark: a timeout of fewer than 5 seconds will be automatically adjusted to 5 seconds."
required: false
default: 5
type: integer
type:
description: Type of communication. Possible values are `tcp` Modbus messages with Modbus TCP frame on TCP/IP, `udp` Modbus messages with Modbus TCP frame on UDP, `rtuovertcp` Modbus messages with a wrapper TCP/IP simulating a serial line.
required: true
type: string
{% endconfiguration %}
## Configuring network connection
For a network (type: `tcp`/`udp`/`rtuovertcp`) connection, add the following to your `configuration.yaml` file, in addition to the [common parameters](#configuring-modbus-common-parameters):
```yaml ```yaml
# Example configuration.yaml entry for a TCP connection # Example configuration.yaml entry for a TCP connection
modbus: modbus:
- name: hub1 - name: "hub1"
type: tcp type: tcp
host: IP_ADDRESS host: IP_ADDRESS
port: 502 port: 502
``` ```
{% configuration %} {% configuration %}
close_comm_on_error:
description: Determines if the modbus communication is closed when an error occurs, default is true. Some serial-rs485 adapters send garble to HA when opened, this leads to a disconnect and a new connect, which can continue. If in a running communication the debug log contains a message from pymodbus, with the text "cleaning....", then try this parameter.
required: false
default: true
type: boolean
delay:
description: Time to delay messages in seconds after connecting. Some modbus devices need a delay typically 1-2 seconds after connection is established in order to prepare the communication. If a device accepts connecting with no response to the requests sent or the device disconnects, this parameter might help.
required: false
default: 0
type: integer
host: host:
description: The IP address of your Modbus device, e.g., 192.168.1.1. description: The IP address of your Modbus device, e.g., `192.168.1.1`.
required: true required: true
type: string type: string
name:
description: Name for this hub. Must be unique, so it is required when setting up multiple instances.
required: false
default: modbus_hub
type: string
port: port:
description: The network port for the communication. description: The network port for the communication.
required: true required: true
type: integer type: integer
timeout:
description: Timeout for slave response in seconds.
required: false
default: 3
type: integer
type: type:
description: 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.). description: "Type of the connection to Modbus, needs to be `tcp` or `udp` or `rtuovertcp` for this setup."
required: true required: true
type: string type: string
{% endconfiguration %} {% endconfiguration %}
### Serial connection ## Configuring serial connection
For a serial connection, add the following to your `configuration.yaml` file: For a serial connection, add the following to your `configuration.yaml` file, in addition to the [common parameters](#configuring-modbus-common-parameters):
```yaml ```yaml
# Example configuration.yaml entry for a serial connection # Example configuration.yaml entry for a serial connection
modbus: modbus:
- name: hub1 - name: hub1
type: serial type: serial
method: rtu
port: /dev/ttyUSB0
baudrate: 9600 baudrate: 9600
stopbits: 1
bytesize: 8 bytesize: 8
parity: N method: rtu
parity: E
port: /dev/ttyUSB0
stopbits: 1
``` ```
{% configuration %} {% configuration %}
@ -108,20 +119,10 @@ bytesize:
description: "The bytesize for the serial connection; can be `5`, `6`, `7` or `8`." description: "The bytesize for the serial connection; can be `5`, `6`, `7` or `8`."
required: true required: true
type: integer type: integer
delay:
description: 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.
required: false
default: 0
type: integer
method: method:
description: "Method of the connection to Modbus, either `rtu` or `ascii`." description: "Method of the connection to Modbus, either `rtu` or `ascii`."
required: true required: true
type: string type: string
name:
description: Name for this hub. Must be unique, so it is required when setting up multiple instances.
required: false
default: modbus_hub
type: string
parity: parity:
description: "The parity for the serial connection; can be `E`, `O` or `N`." description: "The parity for the serial connection; can be `E`, `O` or `N`."
required: true required: true
@ -134,22 +135,95 @@ stopbits:
description: "The stopbits for the serial connection, either `1` or `2`." description: "The stopbits for the serial connection, either `1` or `2`."
required: true required: true
type: integer type: integer
timeout:
description: Timeout for slave response in seconds.
required: false
default: 3
type: integer
type: type:
description: "Type of the connection to Modbus, needs to be `serial` for this setup." description: "Type of the connection to Modbus, needs to be `serial` for this setup."
required: true required: true
type: string type: string
{% endconfiguration %} {% endconfiguration %}
## Configuring multiple connections
Multiple connections are possible with identical/different `type:`.
```yaml
# Example configuration.yaml entry for multiple TCP connections
modbus:
- type: tcp
host: IP_ADDRESS_1
port: 2020
name: "hub1"
- type: udp
host: IP_ADDRESS_2
port: 501
name: hub2
```
Remark: `name:`is required for multiple connections, because it needs to be unique.
## Modbus services
The Modbus integration provides two generic 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) |
| unit | Slave address (1-255, defaults to 0) |
| 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 |
# configure Modbus platforms
Modbus platform entities are configured within the Modbus configuration.
## Configuring platform common parameters
All modbus platforms share a set of common parameters.
```yaml
# Example configuration.yaml entry for platform common parameters
modbus:
- type: tcp
host: IP_ADDRESS_1
port: 2020
name: "hub1"
sensors:
- name: sensor1
scan_interval: 999
slave: 0
```
{% configuration %}
name:
description: Name for the platform entity which must be unique within the platform.
required: true
type: string
scan_interval:
description: Defines the update interval of the entity in seconds. If scan_interval is lower than `timeout` or 5 seconds it is automatically adjusted to `timeout` (default 5 seconds).
required: false
type: integer
default: 10
slave:
description: The number of the slave.
required: false
type: integer
default: 0
{% endconfiguration %}
### Configuring platform binary sensor ### Configuring platform binary sensor
The `modbus` binary sensor allows you to gather data from [Modbus](http://www.modbus.org/) coils with state ON/OFF. The Modbus binary sensor allows you to gather data from coils which as per standard have state ON/OFF.
To use your Modbus binary sensors in your installation, add the following to your `configuration.yaml` file, in addition to the [common parameters](#configuring- platform-common-parameters):
To use your Modbus binary sensors in your installation, add the following to your `configuration.yaml` file:
```yaml ```yaml
# Example configuration.yaml entry for binary_sensor configuration # Example configuration.yaml entry for binary_sensor configuration
modbus: modbus:
@ -158,51 +232,41 @@ modbus:
host: IP_ADDRESS host: IP_ADDRESS
port: 502 port: 502
binary_sensors: binary_sensors:
- name: Sensor1 - name: "binary_sensor1"
slave: 1
address: 100 address: 100
- name: Sensor2 scan_interval: 20
slave: 1
- name: "binary_ensor2"
address: 110 address: 110
device_class: door
input_type: discrete_input input_type: discrete_input
``` ```
{% configuration %} {% configuration %}
binary_sensors: binary_sensors:
description: A list of all binary_sensors available in this modbus instance. description: A list of all binary_sensors available in this modbus instance, omit if there are no binary_sensors.
required: false required: false
type: [map] type: [map]
keys: keys:
device_class:
description: Device class to be used for the UI (e.g. "door").
required: false
type: string
input_type:
description: type of adddress (discrete/coil)
required: false
default: coil
type: string
name:
description: Name for this binary_sensor. Must be unique.
required: true
type: string
scan_interval:
description: Defines the update interval of the sensor in seconds.
required: false
type: integer
default: 15
slave:
description: The number of the slave.
required: false
type: integer
address: address:
description: Address of the Register. description: Address of the Register.
required: true required: true
type: integer type: integer
device_class:
description: The [type/class](/integrations/binary_sensor/#device-class) to be used for the UI (e.g. "door").
required: false
type: string
input_type:
description: type of adddress (discrete_input/coil)
required: false
default: coil
type: string
{% endconfiguration %} {% endconfiguration %}
### Configuring platform climate ### Configuring platform climate
To use your Modbus thermostat in your installation, add the following to your `configuration.yaml` file: The Modbus climate platform allows you to monitor your thermostat as well as set a target temperature.
To use your Modbus thermostat in your installation, add the following to your `configuration.yaml` file, in addition to the [common parameters](#configuring- platform-common-parameters):
```yaml ```yaml
# Example configuration.yaml entry # Example configuration.yaml entry
@ -212,18 +276,21 @@ modbus:
host: IP_ADDRESS host: IP_ADDRESS
port: 502 port: 502
climates: climates:
- name: Watlow F4T - name: "Watlow F4T"
slave: 1 current_temp_register: 27586
data_type: uint current_temp_register_type: holding
data_count: 1 data_count: 1
scale: 0.1 data_type: custom
max_temp: 35
min_temp: 15
offset: 0 offset: 0
precision: 1 precision: 1
scale: 0.1
max_temp: 30 max_temp: 30
min_temp: 15 structure: ">f"
temp_step: 1
target_temp_register: 2782 target_temp_register: 2782
current_temp_register: 27586 temp_step: 1
temperature_unit: C
``` ```
{% configuration %} {% configuration %}
@ -233,11 +300,11 @@ climates:
type: [map] type: [map]
keys: keys:
current_temp_register: current_temp_register:
description: Register number for current temperature (Process value). description: Register address for current temperature (process value).
required: true required: true
type: integer type: integer
current_temp_register_type: current_temp_register_type:
description: Modbus register type (holding, input) for current temperature, default holding. description: Modbus register type (`holding`, `input`) for current temperature.
required: false required: false
type: string type: string
default: holding default: holding
@ -247,19 +314,20 @@ climates:
type: integer type: integer
default: 2 default: 2
data_type: data_type:
description: Response representation (int, uint, float, custom). If float selected, value will converted to IEEE 754 floating point format. description: Response representation (`int`, `uint`, `float`, `custom`). If `float` selected, value will converted to IEEE 754 floating point format. If `custom`is selected `structure`must de defined.
required: false required: false
type: string type: string
default: float default: float
min_temp: max_temp:
description: Maximum setpoint temperature. description: Maximum setpoint temperature.
required: false required: false
type: integer type: integer
default: 35
min_temp:
description: Minimum setpoint temperature.
required: false
type: integer
default: 5 default: 5
name:
description: Name of the device
required: true
type: string
offset: offset:
description: Final offset (output = scale * value + offset). description: Final offset (output = scale * value + offset).
required: false required: false
@ -275,22 +343,13 @@ climates:
required: false required: false
type: float type: float
default: 1 default: 1
scan_interval:
description: Defines the update interval of the sensor in seconds.
required: false
type: integer
default: 15
slave:
description: The number of the slave (Optional for tcp and upd Modbus, use 1).
required: true
type: integer
structure: structure:
description: "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`." description: "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`."
required: false required: false
type: string type: string
default: ">f" default: ">f"
target_temp_register: target_temp_register:
description: Register number for target temperature (Setpoint). description: Register address for target temperature (Setpoint).
required: true required: true
type: integer type: integer
temp_step: temp_step:
@ -305,9 +364,7 @@ climates:
default: C default: C
{% endconfiguration %} {% endconfiguration %}
## Services #### Service `modbus.set-temperature`
### Service `modbus.set-temperature`
| Service | Description | | Service | Description |
| ------- | ----------- | | ------- | ----------- |
@ -315,15 +372,15 @@ climates:
### Configuring platform cover ### Configuring platform cover
The `modbus` cover platform allows you to control [Modbus](http://www.modbus.org/) covers (such as blinds, a roller shutter, or a garage door). The `modbus` cover platform allows you to control 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. 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 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`. 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, 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 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. 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: To use Modbus covers in your installation, add the following to your `configuration.yaml` file, in addition to the [common parameters](#configuring- platform-common-parameters):
```yaml ```yaml
# Example configuration.yaml entry # Example configuration.yaml entry
@ -335,20 +392,16 @@ modbus:
covers: covers:
- name: Door1 - name: Door1
device_class: door device_class: door
scan_interval: 1 coil: 117
coil: 0
- name: Door2
device_class: door 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_open: 1
state_opening: 2
state_closed: 0 state_closed: 0
state_closing: 3
status_register: 119
status_register_type: holding
- name: "Door2"
register: 117
``` ```
{% configuration %} {% configuration %}
@ -358,51 +411,37 @@ covers:
type: map type: map
keys: keys:
coil: coil:
description: 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. description: Coil address; `coil` and `register` attributes are mutually exclusive and you need to add one of them.
required: true required: false
type: integer type: integer
device_class: device_class:
description: The [type/class](/integrations/cover/#device-class) of the cover to set the icon in the frontend. description: The [type/class](/integrations/cover/#device-class) of the cover to set the icon in the frontend.
required: false required: false
type: device_class type: device_class
default: None default: None
name:
description: Name of the switch.
required: true
type: string
register: register:
description: 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. description: Holding register address; `coil` and `register` attributes are mutually exclusive, and you need to add one of them.
required: true required: true
type: integer type: integer
scan_interval:
description: Defines the update interval of the sensor in seconds.
required: false
type: integer
default: 15
slave:
description: The number of the slave (can be omitted for tcp and udp Modbus).
required: false
default: 1
type: integer
state_open: state_open:
description: 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. 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 required: false
default: 1 default: 1
type: integer type: integer
state_closed: state_closed:
description: 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. 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 required: false
default: 0 default: 0
type: integer type: integer
state_opening: state_opening:
description: 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. description: A value in `status_register` or `register` representing a 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 required: false
default: 2 default: 2
type: integer type: integer
state_closing: state_closing:
description: 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. 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 won't reeport the state, this state won't be detected.
required: false required: false
default: 2 default: 3
type: integer type: integer
status_register: status_register:
description: 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. description: 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.
@ -506,14 +545,185 @@ modbus:
state_closed: 0 state_closed: 0
``` ```
### Configuring platform fan
The `modbus` fan platform allows you to control [Modbus](http://www.modbus.org/) coils or registers.
To use your Modbus fans in your installation, add the following to your `configuration.yaml` file, in addition to the [common parameters](#configuring- platform-common-parameters):
```yaml
# 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
```
{% configuration %}
fans:
description: The array contains a list of all your Modbus fans.
required: true
type: map
keys:
address:
description: Coil number or register.
required: true
type: integer
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 address (holding/coil).
required: false
default: holding
type: string
name:
description: Name of the fan.
required: true
type: string
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
input_type:
description: Type of adddress (holding/coil/discrete/input).
required: false
default: write_type
type: integer
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 %}
### Configuring platform light
The `modbus` light platform allows you to control [Modbus](http://www.modbus.org/) coils or registers.
To use your Modbus lights in your installation, add the following to your `configuration.yaml` file, in addition to the [common parameters](#configuring- platform-common-parameters):
```yaml
# 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
```
{% configuration %}
lights:
description: The array contains a list of all your Modbus lights.
required: true
type: map
keys:
address:
description: Coil number or register.
required: true
type: integer
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 light.
required: false
default: 0x00
type: integer
write_type:
description: Type of address (holding/coil).
required: false
default: holding
type: string
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: write address
type: integer
input_type:
description: Type of address (holding/coil/discrete/input).
required: false
default: write_type
type: integer
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 %}
### Configuring platform sensor ### Configuring platform sensor
The `modbus` cover platform allows you to control [Modbus](http://www.modbus.org/) covers (such as blinds, a roller shutter, or a garage door).
The `modbus` sensor allows you to gather data from [Modbus](http://www.modbus.org/) registers. The `modbus` sensor allows you to gather data from [Modbus](http://www.modbus.org/) registers.
To use your Modbus sensors in your installation, add the following to your `configuration.yaml` file: To use your Modbus sensors in your installation, add the following to your `configuration.yaml` file, in addition to the [common parameters](#configuring- platform-common-parameters):
```yaml ```yaml
# Example configuration.yaml entry # Example configuration.yaml entry
@ -647,7 +857,7 @@ modbus:
The `modbus` switch platform allows you to control [Modbus](http://www.modbus.org/) coils or registers. The `modbus` switch platform allows you to control [Modbus](http://www.modbus.org/) coils or registers.
To use your Modbus switches in your installation, add the following to your `configuration.yaml` file: To use your Modbus switches in your installation, add the following to your `configuration.yaml` file, in addition to the [common parameters](#configuring- platform-common-parameters):
```yaml ```yaml
# Example configuration.yaml entry # Example configuration.yaml entry
@ -700,20 +910,6 @@ switches:
required: false required: false
default: holding default: holding
type: string type: string
name:
description: Name of the switch.
required: true
type: string
scan_interval:
description: Defines the update interval of the sensor in seconds.
required: false
type: integer
default: 15
slave:
description: The number of the slave (can be omitted for tcp and udp Modbus).
required: false
type: integer
default: 0
verify: verify:
description: Read from modbus device to verify switch. If used without attributes it uses the toggle register configuration. If omitted no verification is done, but the state of the switch is set with each toggle. description: Read from modbus device to verify switch. If used without attributes it uses the toggle register configuration. If omitted no verification is done, but the state of the switch is set with each toggle.
required: false required: false
@ -741,84 +937,6 @@ switches:
type: integer type: integer
{% endconfiguration %} {% endconfiguration %}
#### Full example
Example switches, for which the state is not polled.
```yaml
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:
```yaml
# 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
```
### Service `modbus.write_register`
| Service | Description |
| ------- | ----------- |
| write_register | Write register. Requires `hub`, `unit`, `address` and `value` fields. `value` can be either single value or an array |
Description:
| 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]` |
### Service `modbus.write_coil`
| Service | Description |
| ------- | ----------- |
| write_coil | Write coil. Requires `hub`, `unit`, `address` and `state` fields. `state` can be either single bolean or an array |
Description:
| 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) |
| state | A single boolean or an array of booleans. Single boolean will call modbus function code 6. Array will call modbus function code 16.
..
## 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 ## Opening an issue
When opening an issue, please add your current configuration (or a scaled down version), with at least: When opening an issue, please add your current configuration (or a scaled down version), with at least: