设备管理协议
设备管理协议
为了方便对 IoT 设备维护，监控控和管理，本协议定义了多个通用的设备服务。
通用设备管理服务
下面列出了事物可用的通用设备管理服务，实现下面的服务即可通过管理后端统一设备。
| ID | NAME | FULL NAME | NOTE |
|---|---|---|---|
| 0 | security | Security | 设备加密和认证等安全服务 |
| 1 | server | Server | 服务器连接参数服务 |
| 2 | access | Access Control | 设备功能访问控制服务 |
| 3 | device | Device | 设备信息服务 |
| 4 | connectivity | Connectivity Monitoring | 网络连接信息服务 |
| 5 | firmware | Firmware Update | 设备固件信息服务 |
| 6 | location | Location | 设备位置信息服务 |
| 7 | statistics | Connectivity Statistics | 设备网络连接统计服务 |
| 8 | config | Parameter Configuration | 设备参数配置服务 |
Security 安全
通过这个服务读写设备的密钥等安全信息。
注意为了安全, 不能通过云端来读写这个服务，只能用配置工具读写。
| ID | NAME | TYPE | FULL NAME | VALUE | NOTE |
|---|---|---|---|---|---|
| 0 | uri | string | Server URI | 0~255 | 服务器的 URI |
| 1 | bootstrap | boolean | Bootstrap Server | - | 指出是否 Bootstrap 服务器 |
| 2 | mode | integer | Security Mode | 0~4 | 安全模式 |
| 3 | key | string | Public Key or Identity | - | 客户端的证书或公钥 |
| 4 | serverKey | string | Server Public Key | - | 服务器的证书或公钥 |
| 5 | secret | string | Secret Key | - | 客户端的私钥 |
mode - 安全模式
- 1 密钥模式
- 2 公钥模式
- 3 没有安全模式
Server 服务器
通过这个服务读写设备的服务器地址等信息。
注意为了安全, 不能通过云端来读写这个服务，只能用配置工具读写。
| ID | NAME | TYPE | FULL NAME | VALUE | NOTE |
|---|---|---|---|---|---|
| 0 | serverId | integer | Short Server ID | - | 服务器 ID |
| 1 | lifetime | integer | Lifetime | - | 注册有效期，单位为秒 |
| 2 | minPeriod | integer | Default Minimum Period | - | 观察模式默认最小周期 |
| 3 | maxPeriod | integer | Default Maximum Period | - | 观察模式默认最大周期 |
| 4 | disable | action | Disable | - | 是否禁止 |
| 5 | timeout | integer | Disable Timeout | - | 禁止超时时间 |
| 8 | update | action | Registration Update | - | 立即更新注册 |
| 9 | request | action | Registration Request | - | 立即重新启动并注册 |
| 12 | bootstrapped | time | Last Bootstrapped | - | 最后一次启动和注册时间 |
| 17 | retryCount | integer | Communication Retry Count | - | 连接重试次数 |
| 18 | retryTimer | integer | Communication Retry Timer | - | 连接重试间隔 |
Access Control 访问控制
暂时没有实现
Device 设备
可通过这个服务读取设备信息，重启设备，恢复出厂设置等
| ID | NAME | TYPE | FULL NAME | VALUE | NOTE |
|---|---|---|---|---|---|
| 0 | manufacturer | string | Manufacturer | XXX | 制造商名称 |
| 1 | modelNumber | string | Model Number | DT01 | 设备型号字符串 |
| 2 | serialNumber | string | Serial Number | 345000123 | 序列号 |
| 3 | firmwareVersion | string | Firmware Version | 1.0 | 固件版本 |
| 4 | reboot | action | Reboot | - | 重启系统 |
| 5 | factoryReset | action | Factory Reset | - | 恢复出厂设置 |
| 6 | powerSources | integer | Available Power Sources | 0 | 可用的电源 |
| 7 | powerVoltage | integer | Power Source Voltage | 3800 | 3800mV, 当前电压 |
| 8 | powerCurrent | integer | Power Source Current | 125 | 125mA, 当前电流 |
| 9 | batteryLevel | integer | Battery Level | 100 | 100%, 电池电量 |
| 10 | memoryFree | integer | Memory Free | 15 | 15KB，空闲内存 |
| 11 | errorCode | integer | Error Code | 0 | 错误码 |
| 12 | errorReset | action | Reset Error Code | - | 重置错误码 |
| 13 | currentTime | integer | Current Time | 1367491215 | 可写, 当前 UINT 时间 |
| 14 | utcOffset | string | UTC Offset | +02:00 | 可写, 和 UTC 时间的偏移量 |
| 15 | timezone | string | Timezone | - | 可写, 时区 |
| 16 | supportedMode | string | Supported Binding and Modes | U | - |
| 17 | deviceType | string | Device Type | camera | 设备类型 |
| 18 | hardwareVersion | string | Hardware Version | 1.0 | 硬件版本 |
| 19 | softwareVersion | string | Software Version | 1.0 | 软件版本 |
| 20 | batteryStatus | integer | Battery Status | 0 | 电池状态 |
| 21 | memoryTotal | integer | Memory Total | 256 | 256KB, 总共内存大小 |
| 30 | cpuUsage | integer | CPU Usage | 10 | 10%, CPU 使用率 |
| 31 | execute | action | Shell Execute | - | 执行命令 |
| 32 | logLevel | integer | Log Level | 3 | 日志输出级别 |
| 33 | log | action | Read Log | - | 查询日志 |
Log Level - 日志级别
- 0: debug 调试信息
- 1: info 普通日志信息
- 2: warn 警告信息
- 3: error 错误信息
- 4: fatal 严重错误信息
Error Code - 错误码
- 没有错误
- 低电量
- 外部电源关闭
- 定位模式失败
- 信号强度低
- 内存不足
- 短信异常
- IP 连接异常
- 外围设备异常
- 配置参数加载错误
Battery Status - 电池状态
- 正常
- 正在充电中
- 充电完成
- 损坏
- 低电量
- 没有安装
- 未知状态
Connectivity 网络连接
可通过这个服务读取设备网络连接信息等
| ID | NAME | TYPE | FULL NAME | VALUE | NOTE |
|---|---|---|---|---|---|
| 0 | bearer | integer | Network Bearer | 7 | 当前使用的网络 |
| 1 | availableBearer | integer | Available Network Bearer | 0 | 可用的网络列表 |
| 2 | signalStrength | integer | Radio Signal Strength | 92 | 无线信号强度 |
| 3 | linkQuality | integer | Link Quality | 2 | NRSRQ for NB-IoT |
| 4 | ip | string | IP Addresses | 192.168.0.100 | 分配给这个网口的 IP 地址 |
| 5 | router | string | Router IP Addresses | 192.168.0.1 | 下一跳的网关地址 |
| 6 | utilization | integer | Link Utilization | 5 | 5%, 到下一跳的平均链路利用率 |
| 7 | apn | string | APN | internet | - |
| 8 | cellId | Integer | Cell ID | - | - |
| 9 | SMNC | Integer | SMNC | 0 | Serving Mobile Network Code |
| 10 | SMCC | Integer | SMCC | 0 | Serving Mobile Country Code |
Network Bearer 网络类型
- 0: GSM
- 5: LTE-TDD
- 6: LTE-FDD
- 7: NB-IoT
- 21: WLAN
- 22: Bluetooth
Signal Strength 信号强度
GSM: RSSI, UMTS: RSCP, LTE: RSRP, NB-IoT:NRSRP
Link Quality 链路质量
LQI for IEEE 802.15.4 (range 0...255), RxQual Downlink for GSM (range 0...7, refer to [3GPP 44.018] for more details on Network Measurement Report encoding), RSRQ for LTE, (refer to [3GPP 36.214]), NRSRQ for NB-IoT (refer to [3GPP 36.214]).
Firmware 固件
可以通过这个服务更新设备固件，读取当前升级状态
| ID | NAME | TYPE | FULL NAME | VALUE | NOTE |
|---|---|---|---|---|---|
| 0 | package | buffer | Package | - | 固件文件 |
| 1 | uri | string | Package URI | http://test.com/test.bin | 固件文件路径 |
| 2 | update | action | Update | - | 更新 |
| 3 | state | integer | State | 0 | 状态 |
| 5 | result | integer | Update Result | 0 | 更新结果 |
| 6 | name | string | Package Name | test.bin | 包名 |
| 7 | version | string | Package Version | 1.0 | 版本 |
| 8 | protocol | integer | Firmware Update Protocol Support | 0 | 设备支持的固件传输协议 |
| 9 | delivery | integer | Firmware Update Delivery Method | 0 | 设备支持的固件分发模式 |
State 状态
- 0：空闲状态
- 1：正在下载
- 2：完成下载
- 3：正在更新
Update Result 更新结果
- 0：初始状态
- 1：固件更新成功
- 2：没有足够的 Flash 空间
- 3：没有足够的内存空间
- 4：下载过程中连接断开
- 5：固件验证失败
- 6：不支持的固件类型
- 7：无效的 URI
- 8：固件更新失败
- 9：不支持的通信协议
Protocol 支持的协议
- 0：CoAP
- 1：CoAPs
- 2：HTTP
- 3：HTTPS
- 4：CoAP over TCP
- 5：CoAP over TLS
Delivery 支持的分发模式
- 0：只支持拉取模式
- 1：只支持推送模式
- 2：两者都支持
Location 位置
可以通过这个服务读取设备的位置信息
| ID | NAME | TYPE | FULL NAME | VALUE | NOTE |
|---|---|---|---|---|---|
| 0 | latitude | number | Latitude | 度 | 经度 |
| 1 | longitude | number | Longitude | 度 | 纬度 |
| 2 | atitude | number | Altitude | 米 | 高度 |
| 3 | radius | number | Radius | 米 | 精度 |
| 4 | velocity | integer | Velocity | - | - |
| 5 | timestamp | date | Timestamp | - | 时间戳 |
| 6 | speed | number | Speed | 米/秒 | 速度 |
Connectivity Statistics 统计
可以通过这个服务统计这个设备的网络连接信息
| ID | NAME | TYPE | FULL NAME | VALUE | NOTE |
|---|---|---|---|---|---|
| 0 | txPackets | integer | Tx Counter | - | 总共发送的数据包 |
| 1 | rxPackets | integer | Rx Counter | - | 总共接收的数据包 |
| 2 | txBytes | integer | Tx Data | KB | 总共发送的数据 |
| 3 | rxBytes | integer | Rx Data | KB | 总共接收的数据 |
| 4 | maxMessageSize | integer | Max Message Size | 字节 | 最大的消息长度 |
| 5 | avgMessageSize | integer | Average Message Size | 字节 | 平均消息长度 |
| 6 | start | action | Start | - | 开始采集 |
| 7 | stop | action | Stop | - | 停止采集 |
| 8 | period | integer | Collection Period | 秒 | 采集周期 |
Configuration 参数配置
可以通过这个服务读写设备的配置参数信息
| ID | NAME | TYPE | FULL NAME | VALUE | NOTE |
|---|---|---|---|---|---|
| 0 | read | action | Read | - | 读取配置 |
| 1 | write | action | Write | - | 修改配置 |
Result 更新结果
- 0 初始状态
- 1 参数配置成功
- 2 无效的配置参数
- 3 参数保存失败
- 4 参数配置失败
错误代码
| CODE | ERROR | NOTE |
|---|---|---|
| 400 | Bad request | 错误的请求消息格式 |
| 500 | Internal error | 设备内部错误 |
| 405 | Method not allow | 不支持的操作方法 |
| 4002 | Parameter error | 参数错误 |
| 503 | Service unavailable | 服务不可用 |
| 403 | Permission denied | 禁止访问 |
| 4001 | Miss required parameter | 缺失必需的参数 |
| 408 | Request timeout | 请求超时 |
| 409 | Conflict | 发生冲突 |
| 5001 | Flash access error | 数据存储失败 |