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 |
初稿：设备类型/属性/状态模型/传感器点表/告警编码 |
系统组 |
