424 lines
14 KiB
Markdown
424 lines
14 KiB
Markdown
# DLD960 TCP 接口协议（JSON）
|
||
|
||
> 基于《DLD960 串口通信协议》V1.01，提供以太网 TCP 通道的 JSON 交互协议。
|
||
> 适用于上位机、调试工具等直接 TCP 连接场景。
|
||
|
||
---
|
||
|
||
# 1 通信说明
|
||
|
||
## 1.1 连接参数
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 传输层 | TCP |
|
||
| 默认端口 | 5960 |
|
||
| 编码 | UTF-8 |
|
||
| 序列化 | JSON |
|
||
| 帧分隔 | 换行符 `\n`（每个 JSON 对象占一行） |
|
||
| 最大帧长 | 4096 字节 |
|
||
|
||
## 1.2 通信模式
|
||
|
||
- **请求-响应**：客户端发送命令，设备返回响应（同步或异步）
|
||
- **主动推送**：设备可主动推送数据（线圈数据、事件）
|
||
- **连接保持**：支持长连接，60 秒无数据心跳超时断开
|
||
|
||
## 1.3 连接流程
|
||
|
||
```
|
||
Client Device (DLD960)
|
||
| |
|
||
|--- TCP Connect ------------------>|
|
||
| |
|
||
|--- pwd_verify (鉴权) ------------>|
|
||
|<-- 鉴权成功 / 失败 ---------------|
|
||
| |
|
||
|--- 命令 1 ----------------------->|
|
||
|<-- 响应 1 ------------------------|
|
||
| |
|
||
|--- 命令 2 ----------------------->|
|
||
|<-- 响应 2 ------------------------|
|
||
| |
|
||
|<-- 主动推送 (loop_data/event) ----|
|
||
| |
|
||
|--- TCP Close / 超时 ------------->|
|
||
```
|
||
|
||
---
|
||
|
||
# 2 JSON 消息格式
|
||
|
||
## 2.1 请求帧
|
||
|
||
```json
|
||
{"msg_id":1,"cmd":"dev_info_query","ts":1719000000,"data":{...}}
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `msg_id` | uint32 | 是 | 消息序列号，递增，用于请求-响应匹配 |
|
||
| `cmd` | string | 是 | 命令标识符 |
|
||
| `ts` | uint32 | 否 | Unix 时间戳（秒） |
|
||
| `data` | object | 否 | 命令参数 |
|
||
|
||
## 2.2 响应帧
|
||
|
||
```json
|
||
{"msg_id":1,"cmd":"dev_info_query","ts":1719000001,"code":0,"msg":"success","data":{...}}
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `msg_id` | uint32 | 是 | 对应请求的 msg_id |
|
||
| `cmd` | string | 是 | 命令标识符（与请求一致） |
|
||
| `ts` | uint32 | 否 | 响应时间戳 |
|
||
| `code` | int | 是 | 0=成功，非0=错误码 |
|
||
| `msg` | string | 是 | 结果描述 |
|
||
| `data` | object | 否 | 响应数据 |
|
||
|
||
## 2.3 主动推送帧
|
||
|
||
```json
|
||
{"msg_id":100,"cmd":"loop_data","ts":1719000100,"data":{...}}
|
||
```
|
||
|
||
> 设备主动推送无 `code`/`msg` 字段，由 `cmd` 区分类型。
|
||
|
||
## 2.4 错误码
|
||
|
||
| code | 说明 |
|
||
|------|------|
|
||
| 0 | 成功 |
|
||
| 1 | 参数错误（格式/范围不正确） |
|
||
| 2 | 密码验证失败 / 未鉴权 |
|
||
| 3 | 设备忙 |
|
||
| 4 | 不支持的命令 |
|
||
| 5 | 内部错误 |
|
||
| 6 | 数据超长 |
|
||
| 7 | 连接未鉴权（需先执行 pwd_verify） |
|
||
|
||
---
|
||
|
||
# 3 命令详表
|
||
|
||
| cmd | 说明 | 需鉴权 | 对应串口 |
|
||
|-----|------|--------|----------|
|
||
| `pwd_verify` | 验证设备密码（连接鉴权） | 否 | 0x1C |
|
||
| `dev_serial_set` | 更改设备序列码 | 是 | 0x09 |
|
||
| `dev_info_query` | 查询设备信息 | 是 | 0x10 |
|
||
| `ssc_net_set` | 设置 SSC 网络配置 | 是 | 0x11 |
|
||
| `ssc_net_query` | 查询 SSC 网络配置 | 是 | 0x12 |
|
||
| `iot_net_set` | 设置 IoT 网络配置 | 是 | 0x13 |
|
||
| `iot_net_query` | 查询 IoT 网络配置 | 是 | 0x14 |
|
||
| `iot_topic_set` | 设置设备 Topic | 是 | 0x15 |
|
||
| `iot_topic_query` | 查询设备 Topic | 是 | 0x16 |
|
||
| `pwd_set` | 设置设备密码 | 是 | 0x1D |
|
||
| `factory_reset` | 设备出厂初始化 | 是 | 0x1E |
|
||
| `device_reset` | 设备复位 | 是 | 0x1F |
|
||
| `loop_param_set` | 设置车检器多路参数 | 是 | 0x63 |
|
||
| `loop_param_query` | 读取车检器多路参数 | 是 | 0x64 |
|
||
| `report_config` | 设置主动上报 | 是 | 0xC5 |
|
||
| 主动推送 | | | |
|
||
| `loop_data` | 线圈传感数据（设备→客户端） | — | 0xC0 |
|
||
| `event_report` | 事件上报（设备→客户端） | — | — |
|
||
|
||
---
|
||
|
||
# 4 命令详情
|
||
|
||
## 4.1 验证设备密码 `pwd_verify`
|
||
|
||
> 连接后首个命令，鉴权通过后才能执行其他命令。
|
||
> 60 秒内未鉴权则断开连接。
|
||
|
||
**请求：**
|
||
|
||
```json
|
||
{"msg_id":1,"cmd":"pwd_verify","ts":1719000000,"data":{"password":"123456"}}
|
||
```
|
||
|
||
| data 字段 | 类型 | 说明 |
|
||
|-----------|------|------|
|
||
| `password` | string | 6 位数字密码 |
|
||
|
||
**响应（成功）：**
|
||
|
||
```json
|
||
{"msg_id":1,"cmd":"pwd_verify","ts":1719000001,"code":0,"msg":"success"}
|
||
```
|
||
|
||
**响应（失败）：**
|
||
|
||
```json
|
||
{"msg_id":1,"cmd":"pwd_verify","ts":1719000001,"code":2,"msg":"password incorrect"}
|
||
```
|
||
|
||
连续 3 次密码错误，设备断开连接并锁定 60 秒。
|
||
|
||
## 4.2 更改设备序列码 `dev_serial_set`
|
||
|
||
**请求：**
|
||
|
||
```json
|
||
{"msg_id":2,"cmd":"dev_serial_set","ts":1719000002,"data":{"dev_serial":"A1B2C3D4E5F6"}}
|
||
```
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{"msg_id":2,"cmd":"dev_serial_set","ts":1719000003,"code":0,"msg":"success"}
|
||
```
|
||
|
||
## 4.3 查询设备信息 `dev_info_query`
|
||
|
||
**请求：**
|
||
|
||
```json
|
||
{"msg_id":3,"cmd":"dev_info_query","ts":1719000004}
|
||
```
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{"msg_id":3,"cmd":"dev_info_query","ts":1719000005,"code":0,"msg":"success","data":{"dev_serial":"A1B2C3D4E5F6","hard_ver":"1.1","soft_ver":"1.1","model":"DLD960","product_code":"960001","sub_code":{"net":true,"iot":true},"bus":{"bus1":0,"bus2":0,"bus3":0,"bus4":0}}}
|
||
```
|
||
|
||
## 4.4 设置 SSC 网络配置 `ssc_net_set`
|
||
|
||
**请求：**
|
||
|
||
```json
|
||
{"msg_id":4,"cmd":"ssc_net_set","ts":1719000006,"data":{"dev_ip":"192.168.1.100","subnet_mask":"255.255.255.0","route_ip":"192.168.1.1","lssc_ip":"192.168.1.200","dns":"8.8.8.8","port":502}}
|
||
```
|
||
|
||
**响应：** 标准成功/失败。
|
||
|
||
## 4.5 查询 SSC 网络配置 `ssc_net_query`
|
||
|
||
**请求：**
|
||
|
||
```json
|
||
{"msg_id":5,"cmd":"ssc_net_query","ts":1719000008}
|
||
```
|
||
|
||
**响应：** `data` 字段同 4.4。
|
||
|
||
## 4.6 设置 IoT 网络配置 `iot_net_set`
|
||
|
||
**请求：**
|
||
|
||
```json
|
||
{"msg_id":6,"cmd":"iot_net_set","ts":1719000010,"data":{"host":"mqtt.example.com","port":1883,"client_id":"dld960_A1B2C3D4E5F6","username":"admin","password":"secret"}}
|
||
```
|
||
|
||
## 4.7 查询 IoT 网络配置 `iot_net_query`
|
||
|
||
**请求：**
|
||
|
||
```json
|
||
{"msg_id":7,"cmd":"iot_net_query","ts":1719000012}
|
||
```
|
||
|
||
## 4.8 设置设备 Topic `iot_topic_set`
|
||
|
||
**请求：**
|
||
|
||
```json
|
||
{"msg_id":8,"cmd":"iot_topic_set","ts":1719000014,"data":{"client_id_enable":true,"topic_pub":"dld960/data/A1B2C3D4E5F6","topic_sub":"dld960/cmd/A1B2C3D4E5F6"}}
|
||
```
|
||
|
||
## 4.9 查询设备 Topic `iot_topic_query`
|
||
|
||
**请求：**
|
||
|
||
```json
|
||
{"msg_id":9,"cmd":"iot_topic_query","ts":1719000016}
|
||
```
|
||
|
||
## 4.10 设置设备密码 `pwd_set`
|
||
|
||
**请求：**
|
||
|
||
```json
|
||
{"msg_id":10,"cmd":"pwd_set","ts":1719000018,"data":{"old_password":"123456","new_password":"654321"}}
|
||
```
|
||
|
||
## 4.11 设备出厂初始化 `factory_reset`
|
||
|
||
**请求：**
|
||
|
||
```json
|
||
{"msg_id":11,"cmd":"factory_reset","ts":1719000020}
|
||
```
|
||
|
||
> 执行后所有配置恢复出厂值，连接可能断开。
|
||
|
||
## 4.12 设备复位 `device_reset`
|
||
|
||
**请求：**
|
||
|
||
```json
|
||
{"msg_id":12,"cmd":"device_reset","ts":1719000022}
|
||
```
|
||
|
||
> 无响应，设备立即复位。
|
||
|
||
## 4.13 设置车检器多路参数 `loop_param_set`
|
||
|
||
**请求：**
|
||
|
||
```json
|
||
{"msg_id":13,"cmd":"loop_param_set","ts":1719000024,"data":{"auto_mode":false,"channels":[{"ch":1,"sensitivity":7,"freq_level":"high","loop_delay":0,"output_mode":"exist","exist_mode":0,"direction_mode":0,"safe_mode":0,"function_mode":0},{"ch":2,"sensitivity":7,"freq_level":"mid_high","loop_delay":5,"output_mode":"enter_pulse","exist_mode":10,"direction_mode":0,"safe_mode":0,"function_mode":0},{"ch":3,"sensitivity":5,"freq_level":"mid_low","loop_delay":0,"output_mode":"exist","exist_mode":0,"direction_mode":1,"safe_mode":5,"function_mode":0},{"ch":4,"sensitivity":8,"freq_level":"low","loop_delay":10,"output_mode":"leave_pulse","exist_mode":15,"direction_mode":0,"safe_mode":0,"function_mode":0}]}}
|
||
```
|
||
|
||
| `channels[]` 字段 | 类型 | 范围 | 说明 |
|
||
|-------------------|------|------|------|
|
||
| `ch` | uint8 | 1~4 | 通道号 |
|
||
| `sensitivity` | uint8 | 0~9 | 灵敏度，默认 7 |
|
||
| `freq_level` | string | 见下 | 线圈高低频档位 |
|
||
| `loop_delay` | uint8 | 0~200 | 延时 ×0.1s，最大 20s |
|
||
| `output_mode` | string | 见下 | 输出方式 |
|
||
| `exist_mode` | uint8 | 0~255 | 0=永久，非0=分钟 |
|
||
| `direction_mode` | uint8 | 0~6 | 0=触发，1~6=方向输出 |
|
||
| `safe_mode` | uint8 | 0~255 | 0=关闭，非0=分钟 |
|
||
| `function_mode` | uint8 | 0~15 | 功能模式 |
|
||
|
||
**freq_level 枚举：**
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| `"high"` | 高频 (33nF) |
|
||
| `"mid_high"` | 中高频 (43nF) |
|
||
| `"mid_low"` | 中低频 (66nF) |
|
||
| `"low"` | 低频 (76nF) |
|
||
|
||
**output_mode 枚举：**
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| `"exist"` | 存在输出 |
|
||
| `"enter_pulse"` | 进入脉冲 |
|
||
| `"leave_pulse"` | 离开脉冲 |
|
||
| `"direction"` | 方向判别 |
|
||
|
||
## 4.14 读取车检器多路参数 `loop_param_query`
|
||
|
||
**请求：**
|
||
|
||
```json
|
||
{"msg_id":14,"cmd":"loop_param_query","ts":1719000026}
|
||
```
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{"msg_id":14,"cmd":"loop_param_query","ts":1719000027,"code":0,"msg":"success","data":{"auto_mode":false,"channels":[{"ch":1,"sensitivity":7,"freq_level":"high","loop_delay":0,"output_mode":"exist","exist_mode":0,"direction_mode":0,"safe_mode":0,"function_mode":0,"freq_initial":105300,"freq_current":105280,"freq_diff":20},{"ch":2,"sensitivity":7,"freq_level":"mid_high","loop_delay":5,"output_mode":"enter_pulse","exist_mode":10,"direction_mode":0,"safe_mode":0,"function_mode":0,"freq_initial":100200,"freq_current":98700,"freq_diff":1500},{"ch":3,"sensitivity":5,"freq_level":"mid_low","loop_delay":0,"output_mode":"exist","exist_mode":0,"direction_mode":1,"safe_mode":5,"function_mode":0,"freq_initial":78100,"freq_current":0,"freq_diff":0},{"ch":4,"sensitivity":8,"freq_level":"low","loop_delay":10,"output_mode":"leave_pulse","exist_mode":15,"direction_mode":0,"safe_mode":0,"function_mode":0,"freq_initial":62100,"freq_current":62095,"freq_diff":5}]}}
|
||
```
|
||
|
||
| 额外字段 | 类型 | 单位 | 说明 |
|
||
|----------|------|------|------|
|
||
| `freq_initial` | uint32 | Hz | 初始频率 |
|
||
| `freq_current` | uint32 | Hz | 当前实时频率（线圈断开时为 0） |
|
||
| `freq_diff` | uint32 | Hz | 频率变化量 |
|
||
|
||
## 4.15 设置主动上报 `report_config`
|
||
|
||
**请求：**
|
||
|
||
```json
|
||
{"msg_id":15,"cmd":"report_config","ts":1719000028,"data":{"sensor_type":12,"enable":true,"once":false,"env_eval":false,"interval":5,"ack_required":false,"timeout":0}}
|
||
```
|
||
|
||
| data 字段 | 类型 | 说明 |
|
||
|-----------|------|------|
|
||
| `sensor_type` | uint8 | 传感器类型，12=多路线圈（0x0C） |
|
||
| `enable` | bool | 使能主动上报 |
|
||
| `once` | bool | 仅上报一次 |
|
||
| `env_eval` | bool | 环境评估模式 |
|
||
| `interval` | uint8 | 上报间隔（秒），0=实时 |
|
||
| `ack_required` | bool | 上报是否需要客户端确认 |
|
||
| `timeout` | uint8 | 超时（分钟），0=无限制 |
|
||
|
||
---
|
||
|
||
# 5 设备主动推送
|
||
|
||
主动推送帧与请求-响应共用同一条 TCP 连接，由设备在任意时刻发出。
|
||
|
||
## 5.1 线圈传感数据 `loop_data`
|
||
|
||
```json
|
||
{"msg_id":100,"cmd":"loop_data","ts":1719000100,"data":{"channels":[{"ch":1,"freq_level":"high","has_car":false,"loop_ok":true,"freq_current":105280,"freq_diff":20,"sensitivity":7,"condition":0,"misc":{"type":"time","value":0}},{"ch":2,"freq_level":"mid_high","has_car":true,"loop_ok":true,"freq_current":98700,"freq_diff":1500,"sensitivity":7,"condition":2,"misc":{"type":"time","value":350}},{"ch":3,"freq_level":"mid_low","has_car":false,"loop_ok":false,"freq_current":0,"freq_diff":0,"sensitivity":5,"condition":0,"misc":{"type":"cut_count","value":3}},{"ch":4,"freq_level":"low","has_car":false,"loop_ok":true,"freq_current":62095,"freq_diff":5,"sensitivity":8,"condition":0,"misc":{"type":"flow_count","value":128}}]}}
|
||
```
|
||
|
||
| 通道字段 | 类型 | 说明 |
|
||
|----------|------|------|
|
||
| `ch` | uint8 | 通道号 1~4 |
|
||
| `freq_level` | string | 高低频档位 |
|
||
| `has_car` | bool | 有车/无车 |
|
||
| `loop_ok` | bool | 线圈正常/断开 |
|
||
| `freq_current` | uint32 | 当前频率 (Hz) |
|
||
| `freq_diff` | uint32 | 频率变化量 (Hz) |
|
||
| `sensitivity` | uint8 | 灵敏度等级 |
|
||
| `condition` | uint8 | 环境评估值 |
|
||
| `misc.type` | string | `"time"` / `"cut_count"` / `"flow_count"` |
|
||
| `misc.value` | uint32 | 对应数值 |
|
||
|
||
## 5.2 事件上报 `event_report`
|
||
|
||
```json
|
||
{"msg_id":101,"cmd":"event_report","ts":1719000200,"data":{"events":[{"type":"car_enter","ch":2,"value":0},{"type":"car_leave","ch":2,"value":350}]}}
|
||
```
|
||
|
||
| 事件类型 `type` | 说明 | `value` |
|
||
|----------------|------|---------|
|
||
| `car_enter` | 车辆进入 | 0 |
|
||
| `car_leave` | 车辆离开 | 通过时间 (×5ms) |
|
||
| `loop_cut` | 线圈断开 | 0 |
|
||
| `loop_restore` | 线圈恢复 | 断开持续时长 (×5ms) |
|
||
|
||
---
|
||
|
||
# 6 交互示例
|
||
|
||
## 6.1 完整会话
|
||
|
||
```
|
||
>>> {"msg_id":1,"cmd":"pwd_verify","ts":1719000000,"data":{"password":"123456"}}
|
||
<<< {"msg_id":1,"cmd":"pwd_verify","ts":1719000001,"code":0,"msg":"success"}
|
||
|
||
>>> {"msg_id":2,"cmd":"dev_info_query","ts":1719000002}
|
||
<<< {"msg_id":2,"cmd":"dev_info_query","ts":1719000003,"code":0,"msg":"success","data":{...}}
|
||
|
||
>>> {"msg_id":3,"cmd":"loop_param_query","ts":1719000004}
|
||
<<< {"msg_id":3,"cmd":"loop_param_query","ts":1719000005,"code":0,"msg":"success","data":{...}}
|
||
|
||
>>> {"msg_id":4,"cmd":"report_config","ts":1719000006,"data":{"sensor_type":12,"enable":true,"interval":5}}
|
||
<<< {"msg_id":4,"cmd":"report_config","ts":1719000007,"code":0,"msg":"success"}
|
||
|
||
... (5 秒后设备主动推送) ...
|
||
|
||
<<< {"msg_id":100,"cmd":"loop_data","ts":1719000012,"data":{...}}
|
||
<<< {"msg_id":101,"cmd":"loop_data","ts":1719000017,"data":{...}}
|
||
<<< {"msg_id":102,"cmd":"event_report","ts":1719000020,"data":{"events":[{"type":"car_enter","ch":1,"value":0}]}}
|
||
```
|
||
|
||
---
|
||
|
||
# 7 帧解析说明
|
||
|
||
- 每个 JSON 对象为一行，以 `\n` (0x0A) 结尾
|
||
- 解析时按行读取，提取完整 JSON 后解析
|
||
- JSON 内部不含换行符（紧凑格式）
|
||
- 收到非 JSON 行则丢弃并返回错误
|
||
- 帧长超过 4096 字节则断开连接
|
||
|
||
---
|
||
|
||
# 修订记录
|
||
|
||
| 版本 | 修订时间 | 修订说明 | 修订人 |
|
||
|------|----------|----------|--------|
|
||
| V1.00 | 2026-06-22 | 初始版本，基于串口协议 V1.01 | wangfq |
|