142 lines
6.5 KiB
Markdown
142 lines
6.5 KiB
Markdown
# DOC-08 设备数据字典 V1.0 草案
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 文档编号 | DOC-08 |
|
||
| 文档名称 | 设备数据字典 |
|
||
| 版本 | V1.0 草案 |
|
||
| 状态 | 草案（Draft） |
|
||
| 适用系统 | 机器人智慧服务系统 |
|
||
| 编写日期 | 2026-08-10 |
|
||
| 关联文档 | DOC-09 控制命令字典、机器人能力模型 V1.0 |
|
||
|
||
---
|
||
|
||
## 1. 文档目的
|
||
|
||
统一机器人智慧服务系统中**设备接入服务 Alpha** 与 **状态服务 Alpha** 所涉及的全部设备数据语义，明确设备类型、字段定义、类型约束、取值范围与单位，作为设备接入、状态上报、前端展示与测试验收的唯一数据依据。
|
||
|
||
## 2. 设备类型定义（DEVICE-TYPE）
|
||
|
||
| 编码 | 类型名 | 中文名 | 说明 |
|
||
|------|--------|--------|------|
|
||
| `inspection_robot` | 巡检机器人 | 地面巡检机器人 | 光伏场区地面行走巡检，支持移动/拍照/避障 |
|
||
| `drone` | 无人机 | 巡检无人机 | 空中巡检，支持航线任务/悬停/云台控制 |
|
||
| `charging_pile` | 充电桩 | 机器人充电桩 | 为机器人/无人机提供自动充电 |
|
||
| `gateway` | 网关 | 接入网关 | 汇聚传感器数据，协议转换上行 |
|
||
| `sensor` | 传感器 | 环境/设备传感器 | 温湿度、辐照度、风速等采集节点 |
|
||
|
||
## 3. 设备基础属性（DEVICE-BASE）
|
||
|
||
设备注册时由 **设备接入服务 Alpha** 记录，字段定义如下：
|
||
|
||
| 字段 | 类型 | 必填 | 约束 / 取值 | 说明 |
|
||
|------|------|------|-------------|------|
|
||
| `deviceId` | string | ✅ | 1~64 字符，`^[A-Za-z0-9_\-]+$` | 全局唯一设备标识（序列号） |
|
||
| `type` | enum | ✅ | 见 §2 DEVICE-TYPE | 设备类型 |
|
||
| `name` | string | ❌ | ≤64 字符 | 设备显示名，缺省 = deviceId |
|
||
| `secret` | string | ❌ | 16 位 hex | 设备接入密钥（注册时签发，不对外展示） |
|
||
| `capabilities` | string[] | ❌ | 能力编码列表，见 §5 | 设备能力声明 |
|
||
| `location` | object | ❌ | `{x,y,z,yaw}` 或 `{lng,lat}` | 安装/部署位置 |
|
||
| `meta` | object | ❌ | 键值对 | 厂商、型号、固件版本等扩展信息 |
|
||
| `status` | enum | ✅ | `inactive` / `online` / `offline` | 设备生命周期状态 |
|
||
| `registeredAt` | datetime | ✅ | ISO 8601 | 注册时间（平台写入） |
|
||
| `lastHeartbeat` | datetime | ✅ | ISO 8601 | 最近一次心跳时间 |
|
||
|
||
## 4. 在线状态规则（DEVICE-ONLINE）
|
||
|
||
| 规则项 | 值 | 说明 |
|
||
|--------|-----|------|
|
||
| 心跳周期 | ≤30s | 设备主动上报心跳，30s 一次为推荐值 |
|
||
| 在线判定 | 最近心跳 < 30s | 30s 内有心跳视为在线 |
|
||
| 离线判定 | 心跳超时 ≥60s | 60s 无心跳，设备接入服务置为 `offline` |
|
||
| 离线扫描 | 30s 周期 | 服务端定时扫描心跳超时设备 |
|
||
|
||
## 5. 能力编码（CAPABILITY-CODE）
|
||
|
||
与 **机器人能力模型 V1.0** 保持一致，设备通过 `capabilities` 声明自身能力：
|
||
|
||
| 编码 | 能力名 | 说明 |
|
||
|------|--------|------|
|
||
| `cap.move` | 移动 | 支持前进/后退/转向/速度控制 |
|
||
| `cap.rotate` | 原地转向 | 支持原地旋转/航向调整 |
|
||
| `cap.photo` | 拍照 | 支持相机拍照回传 |
|
||
| `cap.video` | 视频回传 | 支持实时视频流 |
|
||
| `cap.patrol` | 自主巡检 | 支持航线/任务式自动巡检 |
|
||
| `cap.charging` | 自动充电 | 支持自主对接充电桩 |
|
||
| `cap.emergency_stop` | 急停 | 支持紧急停机 |
|
||
| `cap.thermal` | 热成像 | 支持红外热成像采集 |
|
||
|
||
## 6. 状态数据模型（STATUS-MODEL）
|
||
|
||
状态服务 Alpha 接收的上报结构（`POST /api/status/report`）：
|
||
|
||
| 字段 | 类型 | 必填 | 约束 / 单位 | 说明 |
|
||
|------|------|------|-------------|------|
|
||
| `deviceId` | string | ✅ | 见 DEVICE-BASE | 设备标识 |
|
||
| `position` | object | ❌ | `{x,y,z,yaw}`，单位 m / ° | 位姿：坐标与航向 |
|
||
| `battery` | integer | ❌ | 0~100，单位 % | 电量百分比 |
|
||
| `mode` | enum | ❌ | `idle`/`patrol`/`charging`/`working`/`emergency` | 运行模式 |
|
||
| `speed` | number | ❌ | ≥0，单位 m/s | 移动速度 |
|
||
| `sensors` | object | ❌ | 键值对 | 传感器读数（见 §7） |
|
||
| `alarms` | string[] | ❌ | 告警编码 | 当前激活告警 |
|
||
| `ts` | datetime | ❌ | ISO 8601 | 设备侧采集时间 |
|
||
| `receivedAt` | datetime | ✅ | ISO 8601 | 平台接收时间（服务写入） |
|
||
|
||
### 6.1 运行模式枚举（STATUS-MODE）
|
||
|
||
| 编码 | 中文 | 说明 |
|
||
|------|------|------|
|
||
| `idle` | 待机 | 空闲待命 |
|
||
| `patrol` | 巡检中 | 正在执行巡检任务 |
|
||
| `charging` | 充电中 | 对接充电桩充电 |
|
||
| `working` | 作业中 | 执行清洗/维修等作业 |
|
||
| `emergency` | 急停 | 紧急停机状态 |
|
||
|
||
## 7. 传感器数据点表（SENSOR-POINT）
|
||
|
||
巡检机器人 / 网关常见传感器数据点：
|
||
|
||
| 数据点 | 类型 | 单位 | 取值范围 | 说明 |
|
||
|--------|------|------|----------|------|
|
||
| `temperature` | number | ℃ | -40~85 | 环境温度 |
|
||
| `humidity` | number | %RH | 0~100 | 环境湿度 |
|
||
| `irradiance` | number | W/m² | 0~2000 | 太阳辐照度 |
|
||
| `wind_speed` | number | m/s | 0~60 | 风速 |
|
||
| `wind_direction` | integer | ° | 0~359 | 风向角 |
|
||
| `wheel_odom` | number | m | ≥0 | 轮式里程计累计 |
|
||
| `gps_lat` | number | ° | -90~90 | GPS 纬度 |
|
||
| `gps_lng` | number | ° | -180~180 | GPS 经度 |
|
||
| `gps_alt` | number | m | -500~10000 | GPS 海拔 |
|
||
| `obstacle_distance` | number | m | 0~20 | 前方障碍距离（0=碰撞） |
|
||
| `panel_temp_max` | number | ℃ | -40~200 | 热成像面板最高温 |
|
||
|
||
## 8. 告警编码（ALARM-CODE）
|
||
|
||
| 编码 | 中文 | 级别 | 说明 |
|
||
|------|------|------|------|
|
||
| `ALM-001` | 低电量 | warning | 电量 < 20% |
|
||
| `ALM-002` | 电量临界 | critical | 电量 < 10% |
|
||
| `ALM-003` | 通信中断 | critical | 心跳超时 |
|
||
| `ALM-004` | 碰撞风险 | warning | 障碍距离 < 0.5m |
|
||
| `ALM-005` | 电机过热 | warning | 电机温度 > 85℃ |
|
||
| `ALM-006` | GPS 丢失 | warning | 定位失效 |
|
||
| `ALM-007` | 急停触发 | critical | 急停按钮/指令触发 |
|
||
| `ALM-008` | 任务失败 | warning | 巡检任务执行失败 |
|
||
|
||
## 9. 与服务的映射关系
|
||
|
||
| 数据 | 归属服务 | 接口 |
|
||
|------|----------|------|
|
||
| 设备注册/心跳/在线 | 设备接入服务 Alpha (3010) | `/api/devices/*` |
|
||
| 状态上报/查询/订阅 | 状态服务 Alpha (3020) | `/api/status/*` |
|
||
| 命令下发/ACK/结果 | 命令服务 Alpha (3030) | `/api/commands/*` |
|
||
|
||
---
|
||
|
||
**变更记录**
|
||
|
||
| 版本 | 日期 | 变更内容 | 作者 |
|
||
|------|------|----------|------|
|
||
| V1.0 草案 | 2026-08-10 | 初稿：设备类型/属性/状态模型/传感器点表/告警编码 | 系统组 |
|