首页 ▸ Integrations ▸

Modbus

modbus 是一种用于控制 PLC（可编程逻辑控制器）和 RTU（远程终端单元）的通信协议。

该集成严格遵循协议规范，使用 pymodbus 实现协议。

modbus integration集成将 Home Assistant 与您的设备、服务等连接和集成。 [Learn more] 支持所有符合 modbus 标准的设备。设备之间的通信可以是串行（rs-485）、TCP 或 UDP 连接。modbus 集成允许多个通信通道，例如串口连接与一个或多个 TCP 连接的组合。

配置 modbus 通信

配置与 modbus 设备的通信。这是建立设备访问所需的一般设置。

modbus 集成允许您使用多个连接，每个连接可以包含多个传感器等。

modbus 集成提供了一些参数来帮助与“困难”设备通信，这些参数与通信类型无关。

要启用此集成，请将其添加到您的 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 文件中。在更改了configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 文件后，重启 Home Assistant 以应用更改。该集成现在显示在集成页面的 设置 > 设备与服务 下。其实体在集成卡片上以及实体标签上列出。

Configuration Variables

Looking for your configuration file?

delay integer (Optional, default: 0)

连接后发送消息的延迟时间（以秒为单位）。一些 modbus 设备在建立连接后需要通常 1-2 秒的延迟来准备通信。如果设备在连接后未响应消息，请尝试此参数。 备注： 仅影响第一条消息。

message_wait_milliseconds integer (Optional, default: 串行连接为 30，其他连接为 0。)

请求之间的等待时间（以毫秒为单位）。

name string Required

此集线器的名称。必须唯一。

timeout integer (Optional, default: 5)

等待响应的超时时间（以秒为单位）。

type list Required

modbus 的类型。

tcp

带有套接字帧的 TCP/IP 连接，用于支持以太网的设备。

udp

带有套接字帧的 UDP 连接，很少使用。

rtuovertcp

带有 rtu 帧的 TCP/IP 连接，用于连接到 modbus 转发器。

serial

带有 RTU 帧的串行连接，用于 TTY 端口或 USB rs485 转换器。

配置 tcp 连接

type: tcp 是必需的。用于直接提供 TCP/IP 接口的设备。

Configuration Variables

Looking for your configuration file?

host string Required

modbus 设备的 IP 地址或名称，例如 192.168.1.1。

port integer Required

通信的网络端口。

示例：典型的 tcp 配置

# 示例 yaml：典型的 tcp 连接
modbus:
  - name: modbus_hub
    type: tcp
    host: IP_ADDRESS
    port: 502

示例：完整的 tcp 配置

# 示例 yaml：完整的 tcp 连接
modbus:
  - name: modbus_hub
    type: tcp
    host: IP_ADDRESS
    port: 502

    delay: 0
    message_wait_milliseconds: 30
    timeout: 5

配置 TCP-RTU 连接

type: rtuovertcp 是必需的。用于直接提供 TCP/IP 接口的设备。

这通常用于与 modbus 转发器通信，modbus 转发器具有向上的 TCP/IP 连接和一个或多个向下的串行连接。让我们在这里写更多内容，看看错误是否移动。

Configuration Variables

Looking for your configuration file?

host string Required

modbus 设备的 IP 地址或名称，例如 192.168.1.1。

port integer Required

通信的网络端口。

示例：典型的 TCP-RTU 配置

# 示例 yaml：典型的 tcp-rtu 连接
modbus:
  - name: modbus_hub
    type: rtuovertcp
    host: IP_ADDRESS
    port: 502

示例：完整的 TCP-RTU 配置

# 示例 yaml：完整的 tcp-rtu 连接
modbus:
  - name: modbus_hub
    type: rtuovertcp
    host: IP_ADDRESS
    port: 502

    delay: 0
    message_wait_milliseconds: 30
    timeout: 5

配置 UDP 连接

type: udp 是必需的。这很少使用，仅用于非常特殊的配置。

Configuration Variables

Looking for your configuration file?

host string Required

modbus 设备的 IP 地址或名称，例如 192.168.1.1。

port integer Required

通信的网络端口。

示例：典型的 udp 配置

# 示例 yaml：典型的 udp 连接
modbus:
  - name: modbus_hub
    type: udp
    host: IP_ADDRESS
    port: 502

示例：完整的 UDP 配置

# 示例 yaml：完整的 udp 连接
modbus:
  - name: modbus_hub
    type: udp
    host: IP_ADDRESS
    port: 502

    delay: 0
    message_wait_milliseconds: 30
    timeout: 5

配置串行连接

type: serial 是必需的。这用于提供串行 rs485 接口的设备。

物理接口通常是 USB 串行-rs485 转换器或连接到串行端口的 rs232-rs485。

Configuration Variables

Looking for your configuration file?

baudrate integer Required

串行连接的速度，速度越高性能越好。

bytesize list Required

每字节的数据大小（以位为单位）。

5 位数据，很少使用。

6 位数据，很少使用。

7 位数据，用于非常旧的设备。

8 位数据，标准。

method list Required

与 modbus 的连接方法。

rtu

二进制数据传输，前面是从机 ID，后面是 CRC，标准。

ascii

ASCII 数据传输，前面是从机 ID，后面是 CRC，用于少数设备。

parity list Required

数据字节的奇偶校验。

偶校验位。

奇校验位。

无校验位，标准。

port string Required

modbus 设备连接到 Home Assistant 主机的串口或 USB 设备。

stopbits list Required

数据字节的停止位。

1 个停止位。

2 个停止位，标准。

示例：典型的串行配置

# 示例 yaml：典型的串行连接
modbus:
  - name: modbus_hub
    type: serial
    port: /dev/ttyUSB0
    baudrate: 9600
    bytesize: 8
    method: rtu
    parity: E
    stopbits: 1

示例：完整的串行配置

# 示例 yaml：完整的串行连接
modbus:
  - name: modbus_hub
    type: serial
    port: /dev/ttyUSB0
    baudrate: 9600
    bytesize: 8
    method: rtu
    parity: E
    stopbits: 1

    delay: 0
    message_wait_milliseconds: 30
    timeout: 5

配置多个连接

多个连接可以自由混合不同的通信方式：

# 示例 yaml：多个 tcp 连接
modbus:
  - name: modbus_hub
    type: tcp
    host: IP_ADDRESS_1
    port: 2020

  - name: modbus_hub2
    type: tcp
    host: IP_ADDRESS_2
    port: 502

# 示例 yaml：tcp 连接和串行连接
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

配置 modbus 实体

modbus 实体分组在每个 modbus 通信条目下。

备注每个 modbus 设备必须至少定义一个实体，否则集成将不会加载。

请参阅参数使用了解冲突参数。

所有 modbus 实体具有以下参数：

Configuration Variables

Looking for your configuration file?

address integer Required

线圈/寄存器的地址。注意，这也可以用十六进制指定。例如：0x789A

name string Required

实体的名称，必须在实体类型内唯一。

scan_interval integer (Optional, default: 15)

更新间隔（以秒为单位）。 scan_interval = 0 表示不轮询。实体会在启动后短时间内读取，然后根据 scan_interval 读取。备注，当重新启动 HA 时，会恢复最后已知的值。

slave integer (Optional, default: 1)

与 device_address 相同

device_address integer (Optional, default: 1)

设备的 ID。用于在 rs485 总线上寻址多个设备或连接到 modbus 中继器的设备。0 是广播 ID。

unique_id string (Optional)

唯一标识此实体的 ID。从机将被赋予一个 unique_id 格式为 <<unique_id>>_<<slave_index>>。如果两个实体具有相同的唯一 ID，Home Assistant 将引发异常。

示例：实体分组

# 示例 yaml：实体分组
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

配置二进制传感器实体

Modbus 二进制传感器允许您从线圈中收集数据，根据标准，线圈的状态为 ON/OFF。

通常，一个寄存器包含 16 个线圈，给出不同的地址，具体取决于使用的请求。

寄存器 512：线圈 1 - 16
寄存器 513：线圈 17 - 32

input_type: coils 将使用 1 到 32 的地址，而 input_type: input 将使用 512 和 513 的地址。因此，许多设备（尤其是旧设备）不会与寄存器地址空间共享线圈地址空间，而这个 input 将从不同的地址空间读取，而不是 coil。问题存在于具有共享地址空间的设备中，并且在配置实体时经常引起问题。

请参阅参数使用了解冲突参数。

Configuration Variables

Looking for your configuration file?

binary_sensors map (Optional)

为此连接配置的所有二进制传感器的列表。

device_class string (Optional)

用于 UI 的类型/类。

input_type string (Optional, default: coil)

请求类型 discrete_input、coil、holding 或 input

slave_count integer (Optional)

与 virtual_count 相同。

virtual_count integer (Optional)

生成 count+1 个二进制传感器（主 + 从）。地址会自动递增。该参数简化了配置，并通过不使用 count+1 请求而是单个请求提供了更好的性能。

unique_id string (Optional)

唯一标识实体的 ID。从机将自动获得格式为 <<unique_id>>_<<slave_index>> 的 unique_id。如果两个传感器具有相同的唯一 ID，Home Assistant 将引发异常。

示例：典型的二进制传感器配置

# 示例 yaml：典型的 binary_sensor
modbus:
  - name: hub1
    type: tcp
    host: IP_ADDRESS
    port: 502
    binary_sensors:
      - name: my_relay
        address: 100
        slave: 1

示例：完整的二进制传感器配置

# 示例 yaml：带有所有选项的 binary_sensor
modbus:
  - name: hub1
    type: tcp
    host: IP_ADDRESS
    port: 502
    binary_sensors:
      - name: my_relay
        address: 100
        device_class: door
        input_type: coil
        scan_interval: 15
        slave: 1
        slave_count: 0
        unique_id: my_relay

示例：多个相同的二进制传感器配置

# 示例 10 个相同的 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

此配置将每 15 秒轮询一次线圈地址 100 到 110，并更新 binary_sensors：my_relay 和 my_relay_1 到 my_relay_10。

主配置（如 device_class）会自动复制到从机。

配置气候实体

Modbus 气候平台允许您监控恒温器或加热器，并设置目标温度、HVAC 模式、摆动模式和风扇状态。

请参阅参数使用了解冲突参数。

Configuration Variables

Looking for your configuration file?

climates map (Optional)

此 modbus 实例中所有气候实体的列表。

temperature_unit list (Optional, default: C)

温度单位：C 或 F。

摄氏度

华氏度

precision integer (Optional, default: 0)

温度的有效小数位数。

temp_step float (Optional, default: 0.5)

目标温度的步长。

max_temp integer (Optional, default: 35)

目标温度的最大设定值。

min_temp integer (Optional, default: 5)

目标温度的最小设定值。

count integer (Optional)

读取当前温度所需的寄存器数量。 仅对 data_type: custom 和 data_type: string 有效，对于其他数据类型，count 会自动计算。

data_type list (Optional, default: int16)

读取当前温度寄存器时的响应表示。

custom

用户定义的格式，必须配置 structure: 和 count:。

float16

16 位有符号浮点数（1 个寄存器包含 1 个值）。

float32

32 位有符号浮点数（2 个寄存器包含 1 个值）。

float64

64 位有符号浮点数（4 个寄存器包含 1 个值）。

int

已弃用 会被静默转换为 int16

int16

16 位有符号整数（1 个寄存器包含 1 个值）。

int32

32 位有符号整数（2 个寄存器包含 1 个值）。

int64

64 位有符号整数（4 个寄存器包含 1 个值）。

string

一组 8 位字符，必须配置 count:。

uint

已弃用 会被静默转换为 uint16

uint16

16 位无符号整数（1 个寄存器包含 1 个值）。

uint32

32 位无符号整数（2 个寄存器包含 1 个值）。

uint64

64 位无符号整数（4 个寄存器包含 1 个值）。

input_type list (Optional, default: holding)

当前温度的 Modbus 寄存器类型。

holding

保持寄存器。

input

输入寄存器。

offset float (Optional, default: 0)

当前温度的最终偏移量（输出 = scale * value + offset）。

target_temp_register integer | list Required

目标温度（设定值）的寄存器地址。使用列表，可以为每个可用的 HVAC 模式定义一个寄存器。列表必须有 7 个寄存器，分别对应 7 个可用的 HVAC 模式，如下所示：寄存器 1：HVAC 自动模式；寄存器 2：HVAC 制冷模式；寄存器 3：HVAC 干燥模式；寄存器 4：HVAC 仅风扇模式；寄存器 5：HVAC 加热模式；寄存器 6：HVAC 加热制冷模式；寄存器 7：HVAC 关闭模式。对于没有相关寄存器的模式，可以设置重复的值。

target_temp_write_registers boolean (Optional, default: false)

如果 true 使用 write_registers 设置目标温度（target_temp_register），否则使用 write_register。

scale float (Optional, default: 1)

设置目标温度的比例因子（输出 = scale * value + offset）。

structure string (Optional)

如果指定了 data_type: custom，则需要一个双引号的 Python 结构体字符串，用于格式化字符串以解包值。请参阅 Python 文档了解详细信息。示例：>i。

Default:

f

swap list (Optional, default: none)

交换字节/字的顺序，不适用于 custom 和 datatype: string 设置目标温度时

byte

交换字节 AB -> BA。

word

交换字 ABCD -> CDAB，不适用于数据类型：int16、uint16

word_byte

交换字 ABCD -> DCBA，不适用于数据类型：int16、uint16

hvac_mode_register map (Optional)

HVAC 模式寄存器的配置

address integer Required

HVAC 模式寄存器的地址。

write_registers boolean (Optional, default: false)

设置 HVAC 模式的请求类型，如果为 true 使用 write_registers，否则使用 write_register。如果为特定模式指定了多个值，则仅使用第一个值写入寄存器。

values map Required

寄存器值与 HVAC 模式之间的映射

state_off integer | list (Optional)

对应 HVAC 关闭模式的值。如果 On/Off 状态在不同的地址和/或寄存器上处理，则应省略 state_off 状态。

state_heat integer | list (Optional)

对应 HVAC 加热模式的值。

state_cool integer | list (Optional)

对应 HVAC 制冷模式的值。

state_auto integer | list (Optional)

对应 HVAC 自动模式的值。

state_dry integer | list (Optional)

对应 HVAC 干燥模式的值。

state_fan_only integer | list (Optional)

对应 HVAC 仅风扇模式的值。

state_heat_cool integer | list (Optional)

对应 HVAC 加热/制冷模式的值。

fan_mode_register map (Optional)

风扇模式寄存器的配置

address integer | list Required

风扇模式寄存器的地址。（int 调用 write_register，1 个 int 的列表调用 write_registers）

values map Required

寄存器值与风扇模式之间的映射这通常用于控制以下之一：速度、方向或开/关状态。

state_fan_on integer (Optional)

对应风扇开启模式的值。

state_fan_off integer (Optional)

对应风扇关闭模式的值。

state_fan_low integer (Optional)

对应风扇低速模式的值。

state_fan_medium integer (Optional)

对应风扇中速模式的值。

state_fan_high integer (Optional)

对应风扇高速模式的值。

state_fan_auto integer (Optional)

对应风扇自动模式的值。

state_fan_top integer (Optional)

对应风扇顶部模式的值。

state_fan_middle integer (Optional)

对应风扇中间模式的值。

state_fan_focus integer (Optional)

对应风扇聚焦模式的值。

state_fan_diffuse integer (Optional)

对应风扇扩散模式的值。

hvac_onoff_coil integer (Optional)

开/关状态的线圈地址。仅在 On/Off 状态未作为 HVAC 模式处理时使用此设置。当从该线圈读取到零时，HVAC 状态设置为关闭，否则 hvac_mode_register 决定 HVAC 的状态。如果未定义此类线圈，则默认为自动。当 HVAC 模式设置为关闭时，值 0 写入线圈，否则值 1 写入。 不能与 hvac_onoff_register 一起使用。

hvac_onoff_register integer (Optional)

开/关状态的寄存器地址。仅在 On/Off 状态未作为 HVAC 模式处理时使用此设置。当从该寄存器读取到零时，HVAC 状态设置为关闭，否则 hvac_mode_register 决定 HVAC 的状态。如果未定义此类寄存器，则默认为自动。当 HVAC 模式设置为关闭时，值 0 写入寄存器，否则值 1 写入寄存器。

hvac_on_value integer (Optional)

写入 hvac_onoff_register 以打开 HVAC 系统的值。如果未指定，默认值为 1。

hvac_off_value integer (Optional)

写入 hvac_onoff_register 以关闭 HVAC 系统的值。如果未指定，默认值为 0。

swing_mode_register map (Optional)

摆动模式寄存器的配置

address integer | list Required

摆动模式寄存器的地址。（int 调用 write_register，1 个 int 的列表调用 write_registers）。 - 通过保持寄存器读取

values map Required

寄存器值与摆动模式之间的映射

swing_mode_state_on integer (Optional)

对应摆动模式开启的值。

swing_mode_state_off integer (Optional)

对应摆动模式关闭的值。

swing_mode_state_horizontal integer (Optional)

对应摆动模式水平的值。

swing_mode_state_vertical integer (Optional)

对应摆动模式垂直的值。

swing_mode_state_both integer (Optional)

对应摆动模式两者的值。

write_registers boolean (Optional, default: false)

如果 true 使用 write_registers 控制 On/Off 状态（hvac_onoff_register），否则使用 write_register。请注意，目前尚无法通过线圈控制 On/Off 状态。

示例：气候配置

# 示例 configuration.yaml 条目
modbus:
  - name: hub1
    type: tcp
    host: IP_ADDRESS
    port: 502
    climates:
      - name: "Watlow F4T"
        address: 0x6BC2
        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

配置覆盖实体

modbus 覆盖平台允许您控制覆盖物（如百叶窗、卷帘门或车库门）。

目前，平台覆盖支持打开和关闭覆盖。您可以使用线圈或保持寄存器控制覆盖。

使用 input_type: coil 的覆盖无法确定中间状态，例如打开和关闭。线圈仅存储两个状态 - “0” 表示覆盖关闭，“1” 表示覆盖打开。为了允许检测中间状态，有一个可选的 status_register 属性。它允许您将命令（例如打开覆盖）写入线圈，并通过寄存器读取当前覆盖状态。此外，您可以为 state_open、state_opening、state_closed 和 state_closing 属性指定值。这些值将与从 status_register 读取的值匹配。

如果您的覆盖使用 input_type: holding（默认）发送命令，它也可以读取中间状态。要调整哪个值表示什么状态，您可以微调可选的状态属性，如 state_open。这些可选状态值也用于指定写入寄存器的值。如果您指定了可选的 status_register 属性，覆盖状态将从 status_register 读取，而不是用于发送命令的寄存器。

请参阅参数使用了解冲突参数。

Configuration Variables

Looking for your configuration file?

covers map Required

为此连接配置的所有覆盖实体的列表。

device_class device_class (Optional, default: None)

设置前端图标的覆盖类型/类。

input_type list (Optional, default: holding)

覆盖寄存器类型。

holding

保持寄存器。

input

输入寄存器。

state_open integer (Optional, default: 1)

在 status_register 或 register 中表示覆盖打开的值。如果您的配置使用 register 属性，此值将写入保持寄存器以打开覆盖。

state_closed integer (Optional, default: 0)

在 status_register 或 register 中表示覆盖关闭的值。如果您的配置使用 register 属性，此值将写入保持寄存器以关闭覆盖。

state_opening integer (Optional, default: 2)

在 status_register 或 register 中表示覆盖打开的值。请注意，此状态也应在连接的 Modbus 覆盖上支持。如果它不会报告状态，则不会检测到此状态。

state_closing integer (Optional, default: 3)

在 status_register 或 register 中表示覆盖关闭的值。请注意，此状态也应在连接的 Modbus 覆盖上支持。如果它不会报告状态，则不会检测到此状态。

status_register integer (Optional)

从中读取所有覆盖状态的寄存器地址。如果您指定了 register 属性，而未指定 status_register 属性，您的主寄存器也将用作状态寄存器。

status_register_type list (Optional)

覆盖状态寄存器类型（保持，输入），默认保持。

holding

保持寄存器。

input

输入寄存器。

示例：Modbus 覆盖

# 示例 configuration.yaml 条目
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

示例：由线圈控制的 Modbus 覆盖

此示例显示了使用线圈控制的 Modbus 覆盖的配置。不支持中间状态，如打开/关闭。覆盖状态每 10 秒从 Modbus 轮询一次。

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

示例：由线圈控制的 Modbus 覆盖，其状态从寄存器读取

此示例显示了使用线圈控制的 Modbus 覆盖的配置。实际覆盖状态从 status_register 读取。我们还指定了与状态打开/打开/关闭/关闭匹配的寄存器值。覆盖状态每 10 秒从 Modbus 轮询一次。

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

示例：由保持寄存器控制的 Modbus 覆盖

此示例显示了使用保持寄存器控制的 Modbus 覆盖的配置，从中我们还读取当前覆盖状态。我们还指定了与状态打开/打开/关闭/关闭匹配的寄存器值。覆盖状态每 10 秒从 Modbus 轮询一次。

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

示例：由保持寄存器控制的 Modbus 覆盖，其状态从状态寄存器读取

此示例显示了使用保持寄存器控制的 Modbus 覆盖的配置。但是，覆盖状态从 status_register 读取。在这种情况下，我们只为 state_open 和 state_closed 指定了值，对于其余的，使用默认值。覆盖状态每 10 秒从 Modbus 轮询一次。

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

配置风扇实体

modbus 风扇平台允许您控制 Modbus 线圈或寄存器。

请参阅参数使用了解冲突参数。

Configuration Variables

Looking for your configuration file?

fans map Required

此 modbus 实例中所有风扇实体的列表。

command_on integer (Optional, default: 1)

写入的值以打开风扇。

command_off integer (Optional, default: 0)

写入的值以关闭风扇。

write_type list (Optional, default: holding)

写请求的类型。

holding

调用 write_register。

holdings

调用 write_registers。

coil

调用 write_coil。

coils

调用 write_coils。

verify map (Optional)

从 Modbus 设备读取以验证风扇。如果不使用属性，则使用切换寄存器配置。如果省略，则不进行验证，但风扇的状态会在每次切换时设置。

address integer (Optional, default: 写入地址)

读取的地址。

delay integer (Optional, default: 0)

写入和验证之间的延迟。

input_type list (Optional)

地址的类型。

Default:

与 write_type 相同

coil

线圈（1 位继电器）。

discrete

离散输入（1 位继电器）。

holding

保持寄存器。

input

输入寄存器。

state_on integer (Optional)

风扇打开时的值。

Default:

与 command_on 相同

state_off integer (Optional)

风扇关闭时的值。

Default:

与 command_off 相同

示例：风扇配置

# 示例 configuration.yaml 条目
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

配置灯光实体

modbus 灯光平台允许您控制 Modbus 线圈或寄存器。

请参阅参数使用了解冲突参数。

Configuration Variables

Looking for your configuration file?

lights map Required

此 modbus 实例中所有灯光实体的列表。

command_on integer (Optional, default: 1)

写入的值以打开灯光。

command_off integer (Optional, default: 0)

写入的值以关闭灯光。

write_type list (Optional, default: holding)

写请求的类型。

holding

调用 write_register。

holdings

调用 write_registers。

coil

调用 write_coil。

coils

调用 write_coils。

verify map (Optional)

从 Modbus 设备读取以验证灯光。如果不使用属性，则使用切换寄存器配置。如果省略，则不进行验证，但灯光的状态会在每次切换时设置。

address integer (Optional)

读取的地址。

Default:

与 address 相同

delay integer (Optional, default: 0)

写入和验证之间的延迟。

input_type list (Optional)

地址的类型（holding/coil/discrete/input）。

Default:

与 write_type 相同

coil

线圈（1 位继电器）。

discrete

离散输入（1 位继电器）。

holding

保持寄存器。

input

输入寄存器。

state_on integer (Optional)

灯光打开时的值。

Default:

与 command_on 相同

state_off integer (Optional)

灯光关闭时的值。

Default:

与 command_off 相同

示例：灯光配置

# 示例 configuration.yaml 条目
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

配置传感器实体

modbus 传感器允许您从 Modbus 寄存器中收集数据。

请参阅参数使用了解冲突参数。

Configuration Variables

Looking for your configuration file?

sensors map Required

此 modbus 实例中所有传感器的列表。

count integer (Optional)

要读取的寄存器数量。 仅对 data_type: custom 和 data_type: string 有效，对于其他数据类型，count 会自动计算。

data_type list (Optional, default: int16)

响应表示。

custom

用户定义的格式，必须配置 structure: 和 count:。

float16

16 位有符号浮点数（1 个寄存器包含 1 个值）。

float32

32 位有符号浮点数（2 个寄存器包含 1 个值）。

float64

64 位有符号浮点数（4 个寄存器包含 1 个值）。

int

已弃用 会被静默转换为 int16

int16

16 位有符号整数（1 个寄存器包含 1 个值）。

int32

32 位有符号整数（2 个寄存器包含 1 个值）。

int64

64 位有符号整数（4 个寄存器包含 1 个值）。

string

一组 8 位字符，必须配置 count:。

uint

已弃用 会被静默转换为 uint16

uint16

16 位无符号整数（1 个寄存器包含 1 个值）。

uint32

32 位无符号整数（2 个寄存器包含 1 个值）。

uint64

64 位无符号整数（4 个寄存器包含 1 个值）。

device_class device_class (Optional, default: None)

设置前端图标的传感器类型/类。

input_type list (Optional, default: holding)

传感器的 Modbus 寄存器类型。

holding

保持寄存器。

input

输入寄存器。

min_value float (Optional)

传感器的最小允许值。如果值 < min_value –> min_value。可以是浮点数或整数

max_value float (Optional)

传感器的最大允许值。如果值 > max_value –> max_value。可以是浮点数或整数

nan_value string (Optional)

如果 Modbus 传感器有定义的 NaN 值，可以将此值设置为以 0x 开头的十六进制字符串，包含一个或多个字节（例如，0xFFFF 或 0x80000000），或直接提供为整数。如果触发，传感器将变为 unavailable。请注意，nan_value 的十六进制到整数转换目前不遵循 home-assistant 的 Modbus 编码，使用 data_type、structure 或 swap 参数。

zero_suppress float (Optional)

抑制接近零的值。如果 -zero_suppress <= value <= +zero_suppress –> 0。可以是浮点数或整数

offset float (Optional, default: 0)

最终偏移量（输出 = scale * value + offset）。

precision integer (Optional, default: 0)

有效小数位数。

scale float (Optional, default: 1)

比例因子（输出 = scale * value + offset）。

slave_count integer (Optional)

与 virtual_count 相同。

virtual_count integer (Optional)

生成 x-1 个从传感器，允许通过单个读取消息读取多个寄存器。

state_class string (Optional)

传感器的 state_class。

structure string (Optional)

如果指定了 data_type: custom，则需要一个双引号的 Python 结构体字符串，用于格式化字符串以解包值。请参阅 Python 文档了解详细信息。示例：>i。

Default:

f

swap list (Optional, default: none)

交换字节/字的顺序，不适用于 custom 和 datatype: string

byte

交换字节 AB -> BA。

word

交换字 ABCD -> CDAB，不适用于数据类型：int16、uint16

word_byte

交换字 ABCD -> DCBA，不适用于数据类型：int16、uint16

unit_of_measurement string (Optional)

附加到值的单位。

unique_id string (Optional)

唯一标识实体的 ID。如果两个传感器具有相同的唯一 ID，Home Assistant 将引发异常。

Note

如果您将 scale 或 offset 指定为浮点值，将使用双精度浮点运算来计算最终值。这可能会导致值大于 2^53 时的精度损失。

示例：传感器配置

# 示例 configuration.yaml 条目
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

示例：传感器完整配置

示例温度传感器，默认扫描间隔：

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

配置开关实体

modbus 开关平台允许您控制 Modbus 线圈或寄存器。

请参阅参数使用了解冲突参数。

Configuration Variables

Looking for your configuration file?

switches map Required

此 modbus 实例中所有开关的列表。

command_on integer (Optional, default: 1)

写入的值以打开开关。

command_off integer (Optional, default: 0)

写入的值以关闭开关。

write_type list (Optional, default: holding)

写请求的类型。

holding

调用 write_register。

holdings

调用 write_registers。

coil

调用 write_coil。

coils

调用 write_coils。

verify map (Optional)

从 Modbus 设备读取以验证开关。如果不使用属性，则使用切换寄存器配置。如果省略，则不进行验证，但开关的状态会在每次切换时设置。

address integer (Optional)

读取的地址。

Default:

与 write address 相同

delay integer (Optional, default: 0)

写入和验证之间的延迟。

input_type list (Optional)

地址的类型。

Default:

与 write_type 相同

coil

线圈（1 位继电器）。

discrete

离散输入（1 位继电器）。

holding

保持寄存器。

input

输入寄存器。

state_on integer | list (Optional)

开关打开时的值。值必须是 integer 或整数列表。

Default:

与 command_on 相同

state_off integer | list (Optional)

开关关闭时的值。值必须是 integer 或整数列表。

Default:

与 command_off 相同

示例：开关配置

# 示例 configuration.yaml 条目
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

示例：开关完整配置

# 示例 configuration.yaml 条目
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

参数使用矩阵

某些参数排除其他参数，以下表格显示了可以组合的内容：

数据类型：	custom	string	*16	*32	*64
count	是	是	否	否	否
structure	是	否	否	否	否
slave_count	否	否	是	是	是
virtual_count	否	否	是	是	是
swap: byte	否	否	是	是	是
swap: word	否	否	否	是	是
swap: word_byte	否	否	否	是	是

操作

modbus 集成提供了两个通用写操作，除了平台特定的操作。

操作	描述
modbus.write_register	写入寄存器或寄存器
modbus.write_coil	写入线圈或线圈

描述：

属性	描述
hub	集线器名称（省略时默认为 ‘modbus_hub’）
slave	从地址（0-255）
address	寄存器的地址（例如 138）
value	（write_register）单个值或 16 位值的数组。单个值将调用 modbus 功能码 0x06。数组将调用 modbus 功能码 0x10。值可能需要反向排序。例如，要设置 0x0004，您可能需要设置 `[4,0]`，这取决于 CPU 的字节顺序
state	（write_coil）单个布尔值或布尔值数组。单个布尔值将调用 modbus 功能码 0x05。数组将调用 modbus 功能码 0x0F

示例：写入 float32 类型寄存器

要写入 float32 数据类型寄存器，请使用网络格式，例如 10.0 == 0x41200000（网络顺序浮点十六进制）。

action: modbus.write_register
data:
  address: <目标寄存器地址>
  slave: <目标从地址>
  hub: <集线器名称>
  value: [0x4120, 0x0000]

操作 modbus.set-temperature

操作	描述
set_temperature	设置温度。需要传入 `value`，即所需的目标温度。`value` 应与 `data_type` 的类型相同

操作 modbus.set_hvac_mode

操作	描述
set_hvac_mode	设置 HVAC 模式。需要传入 `value`，即所需的模式。`value` 应为有效的 HVAC 模式。所需状态与写入 HVAC 模式寄存器的值之间必须存在映射。执行此操作还将设置 On/Off 寄存器为适当的值，如果定义了此类寄存器。

提交问题

提交问题时，请添加您当前的配置（或缩小版本），至少包括：

modbus 配置行
实体（传感器等）行

为了让开发人员更好地识别问题，请将以下行添加到 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more]：

logger:
  default: warning
  logs:
    homeassistant.components.modbus: debug
    pymodbus: debug

并重新启动 Home Assistant，重现问题，并在问题中包含日志。

基于 modbus 构建

唯一推荐的方法是继承所需的实体。

帮助我们改进翻译

建议编辑此页面，或提供/查看此页面的反馈。

编辑提供反馈查看待处理的反馈

配置 modbus 通信

Configuration Variables

配置 tcp 连接

Configuration Variables

示例：典型的 tcp 配置

示例：完整的 tcp 配置

配置 TCP-RTU 连接

Configuration Variables

示例：典型的 TCP-RTU 配置

示例：完整的 TCP-RTU 配置

配置 UDP 连接

Configuration Variables

示例：典型的 udp 配置

示例：完整的 UDP 配置

配置串行连接

Configuration Variables

示例：典型的串行配置

示例：完整的串行配置

配置多个连接

配置 modbus 实体

Configuration Variables

示例：实体分组

配置二进制传感器实体

Configuration Variables

示例：典型的二进制传感器配置

示例：完整的二进制传感器配置

示例：多个相同的二进制传感器配置

配置气候实体

Configuration Variables

示例：气候配置

配置覆盖实体

Configuration Variables

示例：Modbus 覆盖

示例：由线圈控制的 Modbus 覆盖

示例：由线圈控制的 Modbus 覆盖，其状态从寄存器读取

示例：由保持寄存器控制的 Modbus 覆盖

示例：由保持寄存器控制的 Modbus 覆盖，其状态从状态寄存器读取

配置风扇实体

Configuration Variables

示例：风扇配置

配置灯光实体

Configuration Variables

示例：灯光配置

配置传感器实体

Configuration Variables

示例：传感器配置

示例：传感器完整配置

配置开关实体

Configuration Variables

示例：开关配置

示例：开关完整配置

参数使用矩阵

操作

示例：写入 float32 类型寄存器

操作 modbus.set-temperature

操作 modbus.set_hvac_mode

提交问题

基于 modbus 构建

相关主题

帮助我们改进翻译