---
layout: page
title: "Modbus"
description: "Instructions on how to integrate Modbus within Home Assistant."
date: 2015-04-25 9:16
sidebar: true
comments: false
sharing: true
footer: true
logo: modbus.png
ha_category: Hub
ha_release: pre 0.7
ha_iot_class: "Local Push"
---


[Modbus](http://www.modbus.org/) is a serial communication protocol to control PLCs (Programmable logic controller).
It currently supports sensors and switches which can be controlled over serial, TCP, and UDP connections.

## {% linkable_title Configuration %}

The configuration for adding modbus to your installation depends on the connection type, either a network or serial connection.

### {% linkable_title Network connection %}

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

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

{% configuration %}
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.).
  required: true
  type: string
host:
  description: The IP address of your Modbus device, e.g., 192.168.1.1.
  required: true
  type: string
port:
  description: The network port for the communication.
  required: true
  type: integer
name:
  description: Name for this hub. Must be unique, so it is required when setting up multiple instances.
  required: false
  default: default
  type: string
timeout:
  description: Timeout for slave response in seconds.
  required: false
  default: 3
  type: integer
{% endconfiguration %}

### {% linkable_title Serial connection %}

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

```yaml
# 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 %}
type:
  description: "Type of the connection to Modbus, needs to be `serial` for this setup."
  required: true
  type: string
method:
  description: "Method of the connection to Modbus, either `rtu` or `ascii`."
  required: true
  type: string
port:
  description: The port where your Modbus device is connected to your Home Assistant host.
  required: true
  type: string
baudrate:
  description: The speed for the serial connection.
  required: true
  type: integer
stopbits:
  description: "The stopbits for the serial connection, either `1` or `2`."
  required: true
  type: integer
bytesize:
  description: "The bytesize for the serial connection; can be `5`, `6`, `7` or `8`."
  required: true
  type: integer
parity:
  description: "The parity for the serial connection; can be `E`, `O` or `N`."
  required: true
  type: string
name:
  description: Name for this hub. Must be unique, so it is required when setting up multiple instances.
  required: false
  default: default
  type: string
timeout:
  description: Timeout for slave response in seconds.
  required: false
  default: 3
  type: integer
{% endconfiguration %}

### {% linkable_title 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
    hub: hub1
    
  - type: tcp
    host: IP_ADDRESS_2
    port: 501
    hub: hub2
```

### {% linkable_title Services %}


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

#### {% linkable_title Service Data Attributes %}

| Attribute | Description |
| --------- | ----------- |
| hub       | Hub name (defaults to 'default' when omitted) |
| unit      | Slave address (set to 255 you talk to Modbus via TCP) |
| address   | Address of the Register (e.g., 138) |
| value     | An array of 16-bit values. Might need reverse ordering. E.g., to set 0x0004 you might need to set `[4,0]` |

## {% linkable_title Building on top of Modbus %}

 - [Modbus Binary Sensor](/components/binary_sensor.modbus/)
 - [Modbus Sensor](/components/sensor.modbus/)
 - [Modbus Switch](/components/switch.modbus/)