2026年10月27日 · 周二 · 数据实时更新

设备态势总览

掌握设备在线状态、配置同步与固件升级进展。

设备总数

2,4863.2%

较昨日新增 18 台

当前在线

1,9421.8%

78.1% 在线率 · 5 分钟内活跃

配置同步率

96.8%1.2%

2,406 / 2,486 台已同步

OTA 成功率

98.6%近 30 天

失败 42 台 · 待重试 12 台

在线设备趋势

过去 24 小时 · 每 2 小时采样

在线设备配置已同步

峰值 2,106 台在线率较昨日同期提升 1.8%

固件版本分布

按当前运行版本统计

设备总数 2,486 台

591 台设备正在升级至 v2.4.0

实时上线

LIVE

IMEI / devid	分组	固件	信号	上线时间	状态

待处理事项

3 项需要关注

3

信号质量

最近一次上报 CSQ

强信号

51.6%

中等

33.1%

弱信号

15.3%

56 台设备低于 -95 dBm，建议检查安装位置。

FLEET MANAGEMENT

设备管理

查看设备档案、上行参数与配置同步状态。

全部设备2,486+18 今日

在线1,94278.1%

配置待下发803.2%

升级异常7需处理

	IMEI / devid	硬件 KEY	配置分组	版本	信号	最后上线	状态	操作

DEVICE TYPES · KEY

设备类型

KEY 代表一类硬件，12 位编码由平台自动生成。创建后即可添加设备、上传固件和按 KEY 升级。

设备类型2个 KEY

覆盖设备2,486台

固件包5个

启用中2全部正常

设备类型 / KEY	名称	默认配置分组	设备数量	固件	升级开关	状态	操作

01

创建设备类型

定义 KEY 编码、名称与默认配置分组

02

上传对应固件

固件绑定 KEY，只能下发给同类设备

03

添加设备

按 IMEI 建档，选择该 KEY 与分组

04

发起升级

整个 KEY 或指定 IMEI 均可

CONNECTIVITY LOG

上线记录

每次上报都会更新上线会话，断线重连生成独立记录。

实时接收

今日上报3,482+12.4% 较昨日

独立设备1,942覆盖 78.1% 设备

平均在线时长18h 24m近 7 日

异常断连120.34% 占比

上线时间	IMEI / devid	会话 ID	来源 IP	固件 / 配置	信号	在线时长	结果

CONFIGURATION GROUPS

配置分组

按区域或设备型号管理参数版本，设备下次上报时自动同步。

华

华东 · 居民表 A

v28 已发布

YS-Meter-B2 · 862 台设备 · 最后更新 2026-10-26 14:20

通信参数

选择一种连接方式，设备下一次上报时会同步这组参数。

草稿 v29

TCP 参数

上报周期控制数据发送频率，心跳周期用于保持连接。

4 个参数

MQTT 参数

主题支持 {imei} 占位符；用户名、密码可留空使用匿名接入。

7 个参数

切换连接方式会改变下发结构；设备收到 8002 后应以完整 params 替换旧配置。

下发预览

配置版本v29

校验和sha256:8f2a…c41d

影响设备862 台

配置为不可变快照。发布后旧版本将被归档，可一键回滚。

版本	状态	参数变更	发布人	发布时间

IMEI / devid	固件	配置版本	信号	最后上线	同步状态

FIRMWARE REPOSITORY

固件仓库

管理固件包、校验完整性，并创建可控的灰度升级任务。

5个固件包

3个稳定版本

1个灰度版本

所有下载链接 5 分钟签名有效

OTA ORCHESTRATION

升级任务

从灰度到全量，跟踪每一台设备的升级进度与失败原因。

3进行中

覆盖 2,612 台

1待开始

今晚 02:00

18本月完成

成功率 98.6%

6m 42s平均耗时

较上月 -18%

DEVELOPER CENTER

接口文档

设备通过一次 HTTP 上报，完成身份校验、配置同步与升级指令获取。

完整设计文档 OpenAPI 规范

Production

Base URL

https://iot.yunshu.example.com/api/v1

协议HTTPS / JSON

设备识别IMEI · 唯一

硬件归类Device KEY

超时10s

01

设备上报

IMEI + KEY + 运行参数

02

IMEI 建档

按唯一 IMEI 更新档案

03

差异判定

比对配置与固件版本

04

返回指令

8000–8004 / 9001–9005

05

下次上报确认

版本号即执行结果

IDENT

设备身份

IMEI 唯一

设备请求不做鉴权。平台用 imei 唯一识别设备；devid 是 12 或 14 位业务编号，允许重复；key 是 12 位硬件类别，用于匹配固件，不是密钥。

字段	长度/唯一	说明	示例
`imei`	15 位 · 唯一	设备身份，平台按 IMEI 建档与查询	`861234567890123`
`devid`	12 / 14 位 · 可重复	设备编号/表号，允许产线默认值重复	`M20240000101`
`key`	12 位 · 不唯一	硬件类别，一类设备共享，用于匹配固件	`M8K2B7X4Q9A3`

设备接口没有 KEY 鉴权、签名、nonce。若后续需要防伪造，再增加设备级令牌；不要拿共享的硬件 KEY 做鉴权。

POST

设备上报

/device/report

唯一设备接口

设备按固定格式上报一次。平台只返回一个 code：无操作、升级、更新配置、未分配分组，或 9001–9005 异常。升级优先级最高。

请求字段

字段	类型	说明
`devid`	string	设备编号，12 或 14 位
`key`	string	12 位硬件 KEY
`imei`	string	设备唯一标识，15 位
`iccid`	string	SIM 卡 ICCID
`firmware_ver`	string	当前固件版本，如 1.2.0
`config_ver`	int	当前配置版本
`csq`	int	信号强度 0–31
`vbat`	int	电池电压，单位 mV

响应码

code	含义	data
`8000`	无操作	`null`
`8001`	需要升级（最高优先级）	版本、URL、CRC16、大小
`8002`	需要更新配置	`config_ver + params`
`8004`	设备未分配分组（需要绑定）	`group_id + group_name`
`9001–9005`	异常码，见下方说明	`null`

优先级：9004/9001/9002/9003 校验 > 8001 > 8004 > 8002 > 8000。若同时需要升级和配置更新，本次只返回 8001；升级完成后下一次上报再处理配置或分组。

POST /device/report · 请求示例

{
  "devid": "M20240000101",
  "key": "M8K2B7X4Q9A3",
  "imei": "861234567890123",
  "iccid": "89860012345678901234",
  "firmware_ver": "1.2.0",
  "config_ver": 12,
  "csq": 23,
  "vbat": 3600
}

8001 · 需要升级

{
  "code": 8001,
  "data": {
    "version": "1.3.0",
    "url": "https://cdn.xxx/fw/1.3.0.bin",
    "crc16": 1234,
    "size": 524288
  }
}

CODE

响应码与数据

code 统一为数字

8000 · 无操作

{
  "code": 8000,
  "data": null
}

8002 · 更新配置

{
  "code": 8002,
  "data": {
    "config_ver": 13,
    "params": {
      "protocol": "tcp",
      "host": "tcp.yunshu.example.com",
      "port": 9001,
      "report": 300,
      "heartbeat": 60
    }
  }
}

8004 · 设备未分配分组

{
  "code": 8004,
  "data": {
    "group_id": "cfg-east",
    "group_name": "华东 · 居民表 A"
  }
}

异常码

9001设备未登记：IMEI 不存在

9002KEY 与设备登记信息不匹配

9003设备已禁用

9004请求参数格式错误

9005无可用固件包

9000其他未知异常

异常响应统一格式

{
  "code": 9001,
  "data": null
}

异常码先于 8001 判断；8004 不是异常，而是“设备尚未分配分组”，平台会返回可绑定的分组信息。

本版本不额外设计配置回执和 OTA 进度接口。设备下一次上报的 firmware_ver / config_ver 就是执行结果。

CONFIG

配置参数结构

8002 · data.params

每个配置分组只使用一种连接方式。设备收到 8002 后，用返回的 params 整体替换旧配置。

TCP

{
  "protocol": "tcp",
  "host": "tcp.yunshu.example.com",
  "port": 9001,
  "report": 300,
  "heartbeat": 60
}

hostIP / 域名

portTCP 端口

report上报周期（秒）

heartbeat心跳周期（秒）

MQTT

{
  "protocol": "mqtt",
  "host": "mqtt.yunshu.example.com",
  "port": 1883,
  "username": "meter",
  "password": "******",
  "sub_topic": "meter/{imei}/down",
  "pub_topic": "meter/{imei}/up",
  "heartbeat": 60
}

username / password可留空匿名接入

sub_topic平台 → 设备

pub_topic设备 → 平台

heartbeatMQTT KeepAlive（秒）

主题中的 {imei} 由设备替换为自身 IMEI；如果不需要动态主题，也可以下发固定主题。

ADMIN

管理接口

控制台使用

管理端使用登录态或服务端签名访问，不在设备固件中内置。完整字段定义见 OpenAPI 文件。

方法	路径	说明
GET	`/admin/devices`	设备列表，按 IMEI / devid / KEY 筛选
GET	`/admin/devices/{imei}`	设备详情、上线记录与升级记录
POST	`/admin/devices/import`	批量导入设备；IMEI 唯一，表号可重复
GET	`/admin/device-keys`	硬件 KEY 列表与同类设备数量
POST	`/admin/device-keys`	新建设备类型，服务端自动生成 12 位 KEY
POST	`/admin/config-groups/{id}/publish`	发布配置版本，生成不可变快照
POST	`/admin/firmware`	上传固件，异步校验 SHA-256
POST	`/admin/ota/tasks`	按 KEY 全量，或指定一个/多个 IMEI
POST	`/admin/ota/tasks/{id}:pause`	暂停任务，未开始设备不再收到指令

升级整个 KEY

{
  "name": "B2 全量升级",
  "firmwareId": "fw-240",
  "target": {
    "type": "key",
    "key": "M8K2B7X4Q9A3"
  }
}

指定 IMEI

{
  "name": "指定设备补升",
  "firmwareId": "fw-240",
  "target": {
    "type": "imeis",
    "imeis": [
      "862104068821907",
      "862104068822115"
    ]
  }
}

ERR

通用错误码

200正常

返回 8000/8001/8002/8004

400参数错误

devid、IMEI 或 KEY 格式不对

404未登记

IMEI 或 KEY 不存在

429频率超限

单设备上报过快，退避重试

500服务端错误

退避后重试

503暂不可用

维护中，保留旧固件

API PLAYGROUND

联调工具

模拟一次设备上报，查看 IMEI 建档、配置下发与 OTA 判定的完整响应。

沙箱环境 · 不会触发真实升级

模拟设备参数

选择一台示例设备，或手动修改上报字段。

示例设备设备编号 devid 12/14 位 硬件 KEY 12 位

IMEI 唯一标识 ICCID 固件版本 firmware_ver 配置版本 config_ver 信号 CSQ 电池电压 vbat mV 模拟设备尚未绑定配置分组（返回 8004）

设备通过 IMEI 识别；KEY 只表示硬件类别，不是密钥。

200 OK 38 ms

content-type: application/json; charset=utf-8
x-request-id: req_01J9X8Q2K7M3
x-ratelimit-remaining: 58
cache-control: no-store

可直接在终端执行

请求 ID：req_01J9X8Q2K7M3 2026-10-27 16:44:13