Modbus Sub-Device

fastbeeAbout 5 min

Modbus Sub-Device

Synchronized Device Documentation

This page corresponds to the synchronized Chinese source. Commands, JSON examples, API paths, field names, and screenshots are kept aligned with the Chinese device-side source documentation.

What This Page Covers

Peripheral capability, supported device types, and wiring constraints.
Web console configuration fields and recommended parameter values.
PeriphExec integration, validation steps, and troubleshooting notes.

Source Reference

The detailed operational source is preserved below so implementation details stay exact while the English navigation, titles, and reading path remain available.

Modbus 子设备

功能说明

Modbus 子设备外设用于通过 RS485 总线控制外部 Modbus 从站设备，如继电器模块、PWM 控制器、PID 控制器、电机驱动器等。支持线圈写入（FC05）和寄存器写入（FC06）两种控制协议。

支持的外设类型

类型	type值	说明
MODBUS_DEVICE	51	Modbus RS485 子设备

通信方式

物理层：RS485 半双工
协议：Modbus RTU
控制方式：通过 UART 外设配置的 RS485 端口发送命令

Modbus 子设备不占用 GPIO 引脚（通过已配置的 UART/RS485 端口通信）

配置方式

方式1：Web界面配置（推荐）

Modbus 子设备还需要先在通信协议页确认 Modbus RTU 串口参数、从站地址和波特率。

Modbus RTU 主站轮询链路

Modbus 子设备的外设对象只描述“从站和寄存器怎么映射到系统”，底层串口、波特率和总线连线仍以通信协议页配置为准。

步骤1：进入外设管理页面

打开浏览器访问 ESP32 IP 地址
登录后点击左侧菜单 外设配置

步骤2：添加Modbus子设备外设

点击 新增外设 按钮

填写配置：

字段	填写内容	说明
外设ID	`mb_relay` 或 `mb_pwm`	唯一标识符
名称	`4路继电器` 或 `4路PWM调光`	显示名称
外设类型	Modbus设备 (type: 51)	RS485控制
从站地址	`1` 或 `2`	Modbus地址(1-247)
通道数量	`4`	继电器路数或PWM路数
控制协议	线圈(FC05) 或寄存器(FC06)	根据设备类型
设备类型	relay 或 pwm	继电器或PWM

点击保存

步骤3：验证配置

在外设列表中找到刚添加的外设
点击启用开关
使用控制面板测试控制

⚠️ 重要：Modbus设备依赖UART外设提供RS485物理通道，需先配置UART

方式2：JSON配置文件导入

将以下配置添加到 data/config/peripherals.json 的 peripherals 数组中：

4路继电器模块

{
  "id": "mb_relay",
  "name": "4路继电器",
  "type": 51,
  "enabled": false,
  "pins": [],
  "params": {
    "slaveAddress": 1,
    "channelCount": 4,
    "coilBase": 0,
    "ncMode": false,
    "controlProtocol": 0,
    "deviceType": 0,
    "deviceIndex": 0,
    "batchRegister": 0,
    "pwmRegBase": 0,
    "pwmResolution": 0,
    "motorRegs": [0, 0, 0, 0, 0],
    "motorDecimals": 0,
    "sensorId": ""
  }
}

PWM 调光模块

{
  "id": "mb_pwm",
  "name": "4路PWM调光",
  "type": 51,
  "enabled": false,
  "pins": [],
  "params": {
    "slaveAddress": 2,
    "channelCount": 4,
    "coilBase": 0,
    "ncMode": false,
    "controlProtocol": 1,
    "deviceType": 1,
    "deviceIndex": 1,
    "batchRegister": 0,
    "pwmRegBase": 100,
    "pwmResolution": 10,
    "motorRegs": [0, 0, 0, 0, 0],
    "motorDecimals": 0,
    "sensorId": ""
  }
}

参数说明

参数	说明
slaveAddress	Modbus 从站地址（1-247）
channelCount	通道数量
coilBase	线圈/寄存器基地址
ncMode	NC 常闭模式（true=常闭，控制逻辑反转）
controlProtocol	控制协议：0=线圈(FC05), 1=寄存器(FC06)
deviceType	设备类型：0=relay, 1=pwm, 2=pid, 3=motor
deviceIndex	在 ModbusHandler config 中的索引
batchRegister	位图批量寄存器地址（0=不使用）
pwmRegBase	PWM 寄存器基地址
pwmResolution	PWM 分辨率(bits)
motorRegs	电机寄存器地址 [正转,反转,停止,速度,脉冲数]
motorDecimals	电机参数小数位
motorMinPosition	电机/滑台软限位最小位置，单位为步数
motorMaxPosition	电机/滑台软限位最大位置；当 `motorMaxPosition > motorMinPosition` 时启用软限位
motorCurrentPosition	当前估算位置，回零或人工校准后应更新为对应步数
motorMoveStep	`forward`/`reverse` 默认相对移动步数；未设置时使用最近一次 `setPulse` 值
motorLastPulse	最近一次脉冲数，运行时会更新
sensorId	传感器标识符（用于数据采集上报）

Modbus 电机滑台软限位

当子设备 deviceType 为 motor 时，可以通过以下字段限制滑台行程：

{
  "deviceType": "motor",
  "motorRegs": [0, 1, 2, 5, 7],
  "motorMinPosition": 0,
  "motorMaxPosition": 10000,
  "motorCurrentPosition": 0,
  "motorMoveStep": 1600,
  "motorLastPulse": 1600
}

启用后，forward 会向 motorMaxPosition 方向移动，reverse 会向 motorMinPosition 方向移动。若本次移动会超过边界，系统会先把脉冲数缩小到边界内再发送方向命令；若已在边界或缺少可用脉冲数，则拒绝执行并返回 MOTOR_SOFT_LIMIT。

软限位依赖当前估算位置，首次上电、手动移动或回零后，需要把 motorCurrentPosition 校准到实际位置。真正的左右极限仍建议接硬件限位开关或急停，软件限位用于减少误操作和规则越界。

与外设执行联动

Web界面配置步骤

创建Modbus继电器控制规则

切换到 外设执行管理 标签
点击 新增规则 按钮
配置触发器（如平台触发、事件触发）
添加Modbus动作：
- 动作类型：Modbus线圈写入
- 目标外设：mb_relay
- 动作值：{"ch":0,"val":1}（通道0，开启）
点击保存

💡 提示：线圈写入(FC05)用于继电器，寄存器写入(FC06)用于PWM

JSON配置示例

Modbus 线圈写入（ACTION_MODBUS_COIL_WRITE = 16）

{
  "targetPeriphId": "mb_relay",
  "actionType": 16,
  "actionValue": "{\"ch\":0,\"val\":1}",
  "useReceivedValue": false,
  "syncDelayMs": 0,
  "execMode": 0
}

Modbus 寄存器写入（ACTION_MODBUS_REG_WRITE = 17）

{
  "targetPeriphId": "mb_pwm",
  "actionType": 17,
  "actionValue": "{\"reg\":100,\"val\":512}",
  "useReceivedValue": false,
  "syncDelayMs": 0,
  "execMode": 0
}

Modbus 轮询采集（ACTION_MODBUS_POLL = 18）

{
  "targetPeriphId": "modbus-task:0",
  "actionType": 18,
  "actionValue": "{\"poll\":[0]}",
  "useReceivedValue": false,
  "syncDelayMs": 0,
  "execMode": 0
}

注意事项

UART 前提：Modbus 设备依赖 UART 外设提供 RS485 物理通道，需先配置 UART
地址唯一：同一总线上每个设备地址必须唯一
通信间隔：连续命令间建议 ≥50ms 间隔（pollInterPollDelay 参数控制）
超时重试：默认响应超时 1000ms，最大重试 2 次
pinCount=0：Modbus 设备不使用 GPIO 引脚