Modbus RTU 配置
固件提供 UART/RS485 Modbus RTU 主站，由既有协议实例、总线仲裁与外设执行采集规则处理读取和受检输出。默认 FASTBEE_MODBUS_SLAVE_ENABLE=0，不能因源码含从站枚举就按本机从站配置。
接线与基础配置
ESP32 UART TX ── DI RS485 收发器 A ── 从站 A
ESP32 UART RX ── RO B ── 从站 B
方向 GPIO ── DE/RE
地/隔离参考按收发器、供电和现场总线方案连接UART TX/RX 不能直接连接 RS485 差分 A/B。确认 3.3V 逻辑兼容、收发器供电、共地或隔离、线缆与终端；自动方向模块在表单选择无 DE，持久化以设备保存结果为准。TTL 直连仅用于电平兼容的 TTL Modbus 设备，接收/发送交叉连接，不套用 RS485 A/B。
外设配置先保存启用的 UART 或 RS485 资源，协议页引用实际 peripheralId。波特率、数据位、校验及停止位须与从站一致；GPIO 按芯片与板卡资源选择，不能把 GPIO16/17/14 视为所有 ESP32 板的统一接线。
开发环境功能默认关闭，协议修改、控制等操作按需密码确认开启。保存响应和当前实例状态分别核对，若接口要求重启则先备份本机配置；不要把保存按钮当作已完成总线通信。
任务、控制设备与虚拟 ID
| 项目 | 当前用途 |
|---|---|
modbusRtu.master.tasks | 读取任务：地址、功能码、范围、周期与映射 |
modbusRtu.master.devices | 控制设备：relay、pwm、pid、motor |
modbus-task:N | 读取任务 N 的外设执行引用 |
modbus:N | 控制设备 N 的虚拟引用 |
虚拟资源由通信协议配置注册，不在普通外设页手动新增旧类型 51。任务索引、控制设备索引与总线从站地址是三个不同标识。普通目标地址为 1～247，0 广播和厂商自定义地址不能默认为当前普通读写支持。
当前周期采集由外设执行调度；仅保存任务不代表已有对应周期规则。创建读取规则前核对任务及启用状态，示例见Modbus 监控。
读取与寄存器映射
pollInterval 为秒，responseTimeout/interPollDelay 为毫秒。读取支持 FC01/02/03/04，写入支持的 FC05/06/0F/10 仍须满足对应配置与接口边界。FCB0、厂家批量寄存器、延时寄存器等是型号专用协议，不能按标准功能码套用。
| 映射字段 | 含义 |
|---|---|
regOffset | 相对任务起始地址的零基偏移，32 位值需两个有效寄存器 |
dataType | 0 uint16、1 int16、2 uint32、3 int32、4 float32 |
wordOrder | 32 位寄存器字序：0 高字先、1 低字先；不是单字节交换，16 位只用 0 |
scaleFactor | 数值倍率，0 是有效显式配置，不应回退为 1 |
decimalPlaces | 格式化 0～6 位，不提高测量精度 |
sensorId/unit | 平台字段与单位，分别最多 15/7 个 UTF-8 字节 |
按确切型号和手册核对零基地址、数量、字序及倍率；40001 通常是手册编号，不应直接当作代码里的起始地址。短读、非有限值与解码失败保留无效，不补零。相邻兼容任务可能合并读取，范围、缓存和采样时间仍须按实际结果核对。
JSON 模式有 hash、死区与心跳上报决策：deadband=0 只关闭死区，未变化数据仍可能被 hash 抑制。读取成功情况下超约 60 秒未上报会请求心跳，不能承诺断线期间平台仍收到数据。连续错误自适应延长间隔，成功可逐步恢复，读数实际变化可恢复原间隔；不能把故障恢复时限固定写成 30 秒。
RAW 透传模式转发已验证的原始 RTU 响应，不重建或拆成 JSON 工程量。模式由当前协议配置决定，不能把 RAW 收到帧当作有本地数值缓存和映射成功。
配置结构示例
以下仅示范 protocol.json 中的 Modbus 节，未包含设备已有 MQTT 等其他配置，不能整文件覆盖现场：
{
"modbusRtu": {
"enabled": false,
"mode": "master",
"peripheralId": "uart_rs485",
"dePin": 255,
"transferType": 0,
"master": {
"responseTimeout": 1000,
"maxRetries": 2,
"interPollDelay": 100,
"tasks": [
{
"name": "temperature",
"slaveAddress": 1,
"functionCode": 3,
"startAddress": 0,
"quantity": 1,
"pollInterval": 10,
"enabled": false,
"mappings": [
{
"regOffset": 0,
"dataType": 1,
"wordOrder": 0,
"scaleFactor": 0.1,
"decimalPlaces": 1,
"sensorId": "temperature",
"unit": "°C"
}
]
}
],
"devices": []
}
}
}dePin=255 表示本例不使用独立方向 GPIO，须有匹配的实际接口。倍率、地址与温度单位纯属结构演示，不能替代真实设备手册。
规则动作与启动补报
动作 16 目标 modbus:N，值为 "通道:状态" 或 "状态"，按保存控制协议使用 FC05/FC06；动作 17 值为 "寄存器地址:值" 或 "值"。值须为完整有效十进制/布尔参数，不接受自造 {"ch":0,"val":1} 格式。
动作 18 采集参数为 {"poll":[0,1]}；支持的控制项使用 ctrl 数组和已实现 d/a/c 字段，不把它改成 type/idx/val。读取与输出分开配，启动状态补报只处理 poll，忽略 ctrl，不因上报重放继电器、电机等输出。见动作。
已注册 API
所有路径须先核对登录、开发模式、目标实例和资源状态；下表区分读取与输出，不代表可越过来源和行程保护。
| 方法与路径 | 用途 |
|---|---|
GET /api/modbus/status | 主站和采集统计 |
GET /api/modbus/register/read | one-shot FC03/04，参数为 slaveAddress/startAddress/quantity/functionCode |
GET /api/modbus/coil/status、/api/modbus/device/inputs | 线圈/离散输入读取 |
POST /api/modbus/coil/control、/coil/batch、/coil/delay | 单路、批量、延时控制 |
POST /api/modbus/write、/register/write、/register/batch-write | 保持寄存器受检写入 |
POST /api/modbus/device/address、/device/baudrate | 设备特定参数操作，先核对确切型号 |
POST /api/modbus/motor/control | 电机提交与操作查询 |
GET /api/modbus/motor/state | 电机状态读取 |
缩略路径都带 /api/modbus 前缀。/write 单写参数名为 regAddress，/register/write 使用 registerAddress，不混用。字段与错误格式详见API 参考，实际控制页能列出的目标也须重新检查版本。
输出确认与故障
控制写入绑定实际实例、配置、从站、准确帧及调用来源。协议 ACK 不是继电器触点、实际电压或机械运动；报告 physicalOutputVerified=false。未知结果、已尝试失败和未尝试分别记录；首败保留已确认前缀，不自动重发整批或补偿回滚。
电机返回操作号只表示受理，继续查询 pending/success/outputSteps。attemptKnown=false, attempted=null 表示写入是否发生尚未知，不当作“未执行”再次提交。TRAVEL_REFERENCE_REQUIRED 需要核对参考位置和行程条件，不能取消保护重试启动。
延时反向命令依当前配置与精确回执，配置变化、停止或重启退休旧计划；前序 ACK、延时已安排、到期写入和物理结果是不同阶段。细节见控制结果与来源。
通信超时先查收发器、A/B、方向、供电、共地、串口参数和从站；CRC/异常查线路、准确帧和型号映射。BUSY/503 按提示退避，写入超时先查询是否已尝试，不能高频重试。保存日志与完整响应，再分别安排真实通信、负载反馈及长期稳定验证，本页不构成设备验收结论。