252 lines
7.6 KiB
Markdown
252 lines
7.6 KiB
Markdown
# Modbus 接口规范
|
||
|
||
## 1. 文档用途
|
||
|
||
本文档用于指导主项目接入已完成现场实测的 24 路继电器、电压采集和电流采集设备。
|
||
|
||
配套文件：
|
||
|
||
- `device-profile.json`：设备协议与通道映射的唯一权威配置。
|
||
- `appsettings.Modbus.example.json`：主项目默认配置字段示例。
|
||
- `接入验收清单.md`：开发完成后的测试和验收要求。
|
||
|
||
主项目实现时必须读取配置，不得在业务代码中硬编码从站地址、线圈、寄存器、量程、公式或通道映射。
|
||
|
||
## 2. 实测资料与结论
|
||
|
||
本规范依据以下现场结果整理：
|
||
|
||
- `结果_Modbus-接口-电流-电压对应表.txt`：逐个物理插位手动测量得到的采集页通道对应关系。
|
||
- `结果_modbus-tuner-20260618-131814.json`：调试程序于 2026-06-18 导出的已调通通讯参数。
|
||
|
||
编号含义必须严格区分：
|
||
|
||
| 名称 | 含义 |
|
||
|---|---|
|
||
| `physicalSlot` | 机器上的物理接口位置，也是主项目业务层唯一使用的通道号，范围 1～24 |
|
||
| `relayChannel` | 调试程序继电器控制页按钮号；实测与物理插位一致 |
|
||
| `sourceDisplayChannel` | 调试程序采集页面上出现读数的通道号，仅保留作实测追溯 |
|
||
| `registerOffset` | 在本次 24 寄存器回包数据区中的零基位置，主项目实际解析使用 |
|
||
|
||
主项目不得把 `sourceDisplayChannel` 当作物理插位，也不得直接用它计算字节偏移。
|
||
|
||
## 3. 总线与串口参数
|
||
|
||
所有模块共用一条 RS485 总线。
|
||
|
||
| 参数 | 实测值 |
|
||
|---|---|
|
||
| 协议 | Modbus RTU |
|
||
| 波特率 | 9600 |
|
||
| 数据位 | 8 |
|
||
| 校验 | None |
|
||
| 停止位 | 1 |
|
||
| 读取超时 | 500 ms |
|
||
| 失败重试 | 2 次 |
|
||
| CRC | CRC16-Modbus |
|
||
| CRC 字节序 | 低字节在前 |
|
||
| 地址、数量和寄存器数据 | 高字节在前 |
|
||
|
||
现场调试使用过 `COM9`，但 COM 号属于计算机本地设置。主项目应允许用户选择和保存，不得把 `COM9` 固定为设备协议的一部分。
|
||
|
||
同一串口的请求必须串行执行。不得让继电器写入、电压读取和电流读取同时向串口写帧。
|
||
|
||
## 4. 模块地址
|
||
|
||
| 模块 | 从站地址 |
|
||
|---|---:|
|
||
| 继电器板 1，负责物理插位 1～8 | 1 |
|
||
| 继电器板 2，负责物理插位 9～16 | 2 |
|
||
| 继电器板 3，负责物理插位 17～24 | 3 |
|
||
| 24 路电压采集模块 | 4 |
|
||
| 24 路电流采集模块 | 5 |
|
||
|
||
## 5. 继电器控制
|
||
|
||
使用功能码 `0x05` 写单个线圈。
|
||
|
||
- 开：`0xFF00`
|
||
- 关：`0x0000`
|
||
- 正常响应应回显请求中的从站、功能码、线圈地址和值。
|
||
- 响应必须检查长度、从站、功能码、回显内容和 CRC。
|
||
|
||
主项目业务接口建议：
|
||
|
||
```text
|
||
SetRelayAsync(int physicalSlot, bool isOn)
|
||
```
|
||
|
||
处理流程：
|
||
|
||
1. 校验 `physicalSlot` 为 1～24。
|
||
2. 从 `device-profile.json` 的 `channels` 查找该物理插位。
|
||
3. 取得 `relay.slave` 和 `relay.coil`。
|
||
4. 构造并发送 `0x05` 帧。
|
||
5. 验证回显后才更新业务状态。
|
||
|
||
不要在未确认当前硬件是否允许的情况下自动全开 24 路。
|
||
|
||
## 6. 电压采集
|
||
|
||
实测配置：
|
||
|
||
| 参数 | 值 |
|
||
|---|---|
|
||
| 从站 | 4 |
|
||
| 功能码 | `0x03` |
|
||
| 起始寄存器 | 0 |
|
||
| 寄存器数量 | 24 |
|
||
| 量程 | 100 V |
|
||
| 解析公式 | B |
|
||
| 公式 | `实际电压 = DATA / 100` |
|
||
| DATA 类型 | `UInt16` |
|
||
| 每通道字节数 | 2 |
|
||
| 数据字节序 | Big-Endian |
|
||
|
||
请求主体：
|
||
|
||
```text
|
||
04 03 00 00 00 18
|
||
```
|
||
|
||
追加 CRC16-Modbus 后发送。正常响应共 53 字节：
|
||
|
||
```text
|
||
[从站1][功能码1][字节数0x30][48字节数据][CRC2]
|
||
```
|
||
|
||
## 7. 电流采集
|
||
|
||
实测配置：
|
||
|
||
| 参数 | 值 |
|
||
|---|---|
|
||
| 从站 | 5 |
|
||
| 功能码 | `0x03` |
|
||
| 起始寄存器 | 0 |
|
||
| 寄存器数量 | 24 |
|
||
| 量程 | 60 A |
|
||
| 解析公式 | A |
|
||
| 公式 | `实际电流 = DATA / 10000 × 60` |
|
||
| DATA 类型 | `Int16` |
|
||
| 每通道字节数 | 2 |
|
||
| 数据字节序 | Big-Endian |
|
||
|
||
请求主体：
|
||
|
||
```text
|
||
05 03 00 00 00 18
|
||
```
|
||
|
||
这里的“带符号”按现场导出配置解释为：读取寄存器 0～23，并将每个 16 位原始值按二进制补码转换为 `Int16`。主项目不得自行把起始寄存器改成 24，也不得在映射地址上额外加 24。如后续更换硬件或重新标定，应修改配置版本并重新验收。
|
||
|
||
## 8. 采集回包解析
|
||
|
||
电压和电流共用以下流程：
|
||
|
||
1. 检查响应最小长度。
|
||
2. 检查响应从站等于配置从站。
|
||
3. 检查功能码。若最高位为 1，按 Modbus 异常响应处理。
|
||
4. 检查字节数为 `registerCount × registerBytes`，当前应为 48。
|
||
5. 验证 CRC16-Modbus。
|
||
6. 对每个物理插位读取对应的 `registerOffset`。
|
||
7. 字节位置为：
|
||
|
||
```text
|
||
position = dataStartOffset + registerOffset × channelBytes
|
||
```
|
||
|
||
当前 `dataStartOffset=3`，`channelBytes=2`。
|
||
|
||
8. 按 Big-Endian 合成原始 16 位值。
|
||
9. 根据 `signed` 转换为 `UInt16` 或 `Int16`。
|
||
10. 根据 `formula` 和 `range` 换算工程值。
|
||
|
||
公式定义：
|
||
|
||
```text
|
||
A: value = DATA / 10000.0 × range
|
||
B: value = DATA / range
|
||
```
|
||
|
||
## 9. 统一业务接口
|
||
|
||
主项目业务层只允许使用物理插位 1～24，建议公开以下抽象：
|
||
|
||
```text
|
||
ConnectAsync()
|
||
DisconnectAsync()
|
||
SetRelayAsync(int physicalSlot, bool isOn)
|
||
ReadAllVoltagesAsync()
|
||
ReadAllCurrentsAsync()
|
||
ReadMeasurementsAsync()
|
||
```
|
||
|
||
一次测量结果建议包含：
|
||
|
||
```text
|
||
PhysicalSlot
|
||
Voltage
|
||
Current
|
||
VoltageRaw
|
||
CurrentRaw
|
||
Timestamp
|
||
VoltageQuality
|
||
CurrentQuality
|
||
```
|
||
|
||
`ReadMeasurementsAsync()` 应分别完成一次电压整帧读取和一次电流整帧读取，再按 `physicalSlot` 合并。不要为每个物理插位单独读取一次寄存器；每种采集模块一次读取 24 个寄存器即可。
|
||
|
||
## 10. 配置加载与校验
|
||
|
||
程序启动时必须校验：
|
||
|
||
- `schemaVersion` 是程序支持的版本。
|
||
- 物理插位恰好覆盖 1～24，不重复、不缺失。
|
||
- 继电器从站和线圈组合不重复。
|
||
- 电压、电流的 `registerOffset` 均在 `0～registerCount-1`。
|
||
- 每类采集映射不得出现重复的 `registerOffset`。
|
||
- 从站地址范围为 1～247。
|
||
- `registerBytes=2`、`channelBytes=2`。
|
||
- 公式只能是 `A` 或 `B`。
|
||
- 字节序和 CRC 类型为程序支持值。
|
||
|
||
配置错误时应阻止通讯并给出具体字段，不要静默使用代码默认值。
|
||
|
||
## 11. 超时、重试和线程规则
|
||
|
||
- 一次请求从发送到收到完整响应视为一个事务。
|
||
- 失败后最多重试配置中的次数；当前为 2 次，即最多发送 3 次。
|
||
- CRC 错误、响应超时、从站错误、功能码错误和响应长度错误都应记录原始 HEX。
|
||
- 重试前应清理串口输入缓冲区，避免残帧与下一帧拼接。
|
||
- 串口操作使用互斥锁或单消费者队列串行化。
|
||
- 断开和应用退出时安全关闭串口。
|
||
|
||
## 12. 主项目配置建议
|
||
|
||
建议将机器本地参数放在主项目配置，将设备协议和映射放在独立配置：
|
||
|
||
```text
|
||
主项目配置
|
||
└─ Modbus
|
||
├─ Enabled
|
||
├─ PortName
|
||
├─ DeviceProfilePath
|
||
└─ PollIntervalMs
|
||
|
||
device-profile.json
|
||
├─ 串口通讯默认参数
|
||
├─ Modbus 帧规则
|
||
├─ 模块协议
|
||
└─ 24 路权威映射
|
||
```
|
||
|
||
`device-profile.json` 应随主程序发布并复制到输出目录。主项目可以提供配置界面修改 COM 口，但协议和通道映射只应由经过授权的维护流程更新。
|
||
|
||
## 13. AI 编程强制要求
|
||
|
||
将本目录交给主项目 AI 时，应附加以下要求：
|
||
|
||
> 严格按《Modbus接口规范.md》和 `device-profile.json` 实现。业务层统一使用 `physicalSlot` 1～24。所有从站、线圈、寄存器、量程、公式及映射从配置读取，不得硬编码。`sourceDisplayChannel` 仅用于追溯现场实测，不参与解析寻址。实现配置启动校验、串口事务串行化、CRC及响应完整校验，并按《接入验收清单.md》完成测试。
|
||
|