跳转到内容
ESPHome - 让智能家居更简单2026.7.0

Modbus Controller Number

modbus_controller 平台从 modbus_controller 创建一个数字。当数字更新时，会创建并发送一条 modbus 写命令到设备。

配置变量

Section titled “配置变量”

  • address（必需，int）：范围中第一个寄存器的起始地址（可以是十进制或十六进制）。

  • value_type（必需）：modbus 寄存器数据的数据类型。modbus 的默认数据类型是大端格式的 16 位整数（最高有效位在前）：

    • U_WORD（1 个寄存器 = 16 位的无符号 16 位整数）
    • S_WORD（1 个寄存器 = 16 位的有符号 16 位整数）
    • U_DWORD（2 个寄存器 = 32 位的无符号 32 位整数）
    • S_DWORD（2 个寄存器 = 32 位的有符号 32 位整数）
    • U_DWORD_R（2 个寄存器低字节在前的无符号 32 位整数）
    • S_DWORD_R（2 个寄存器低字节在前的有符号 32 位整数）
    • U_QWORD（4 个寄存器 = 64 位的无符号 64 位整数）
    • S_QWORD（4 个寄存器 = 64 位的有符号 64 位整数）
    • U_QWORD_R（4 个寄存器低字节在前的无符号 64 位整数）
    • S_QWORD_R（4 个寄存器低字节在前的有符号 64 位整数）
    • FP32（2 个寄存器的 32 位 IEEE 754 浮点数）
    • FP32_R（32 位 IEEE 754 浮点数——与 FP32 相同但低字节在前）

  • min_value（可选，float）：此数字可以的最小值。

  • max_value（可选，float）：此数字可以的最大值。

  • step（可选，float）：设置数字的粒度。默认为 1。

  • multiply（可选，float）：在发送请求之前，将新值乘以该因子。如果定义了 lambda 则忽略。

  • use_write_multiple（可选，boolean）：默认情况下，如果仅设置一个寄存器，则使用 modbus 命令 功能码 6（预设单个寄存器） 来设置保持寄存器。如果你的设备仅支持 功能码 16（预设多个寄存器），请将此选项设为 true。

  • skip_updates（可选，int）：默认情况下，modbus_controller 的所有传感器一起更新。对于不太频繁更改的数据点，可以跳过更新。值为 5 将仅在每 6 个更新周期中更新一次此传感器范围。注意：modbus_controller 按地址范围对组件进行分组，以减少交易次数。所有具有相同起始地址的组件将在一个请求中更新。skip_updates 适用于同一范围中的所有组件。

  • register_count（可选，int）：此读取请求应在单条命令中跨越或跳过的连续寄存器数量。默认为 1。更多详情参见优化 modbus 通信。

  • response_size（可选）：寄存器响应的字节大小。默认为 register_count*2。

  • force_new_range（可选，boolean）：如果可能，具有连续地址的传感器会被组合在一起并在一个范围中请求。设置 force_new_range: true 强制在该地址开始新范围。

  • offset（可选，int）：距起始地址的字节偏移（仅在不常见的响应编码时需要）。如果一条命令写入多个寄存器，则使用此值相对于起始地址查找此数据点的起始位置。组件根据偏移和值类型的大小计算范围大小。

  • custom_command（可选，list of bytes）：modbus 命令的原始字节。这允许使用非标准命令。如果使用 custom_command，则不能使用 address 和 register_type。自定义数据必须包含所有必需的字节，包括 modbus 设备地址。CRC 会自动计算并附加到命令中。有关如何使用 custom_command，参见使用 custom_command。

  • lambda（可选，lambda）：每个更新间隔求值以获取传感器新值的 lambda。

    传入 lambda 的参数：

    • x（float）：modbus 数据的解析浮点值

    • data（std::vector<uint8_t>）：包含此传感器完整原始 modbus 响应字节的向量 注意：因为响应包含同一范围中所有寄存器的数据，所以你必须使用 data[item->offset] 来获取传感器的第一个响应字节。

    • item（指向 SensorItem 派生对象的 const 指针）：传感器对象本身。

    lambda 的可能返回值：

    • return <FLOATING_POINT_NUMBER>; 传感器的新值。
    • return NAN; 如果应将状态视为无效以指示错误（高级用法）。

  • write_lambda（可选，lambda）：发送前调用的 lambda。在创建 modbus 写命令之前对 lambda 进行求值。

    传入 lambda 的参数：

    • x（float）：要发送到 modbus 设备的浮点值

    • payload（std::vector<uint16_t> &payload）：空的有效载荷向量。lambda 可以添加 16 位原始 modbus 寄存器字。 注意：因为响应包含同一范围中所有寄存器的数据，所以你必须使用 data[item->offset] 来获取传感器的第一个响应字节。

    • item（指向 SensorItem 派生对象的 const 指针）：传感器对象本身。

    lambda 的可能返回值：

    • return <FLOATING_POINT_NUMBER>; 传感器的新值。
    • return <anything>; and fill payload with data 如果从 lambda 中添加有效载荷，则这些 16 位字将被发送
    • return {}; 如果你不想将命令写入设备（或从 lambda 中执行）。

  • 数字 的所有其他选项。

示例

Section titled “示例”
number:
  - platform: modbus_controller
    modbus_controller_id: modbus1
    id: battery_capacity_number
    name: "Battery Cap Number"
    address: 0x9001
    value_type: U_WORD
    multiply: 1.0


  - platform: modbus_controller
    modbus_controller_id: modbus1
    id: battery_capacity_number
    name: "Battery Cap Number"
    address: 0x9001
    value_type: U_WORD
    lambda: "return  x * 1.0; "
    write_lambda: |-
      ESP_LOGD("main","Modbus Number incoming value = %f",x);
      uint16_t b_capacity = x ;
      payload.push_back(b_capacity);
      return x * 1.0 ;

参见

Section titled “参见”