Developer Docs · Quickstart

快速开始：设备注册 → 首条数据 → 看板可见

目标是最短路径：注册一台设备、发一条真实遥测、在控制台看到它。示例只依赖公开 SDK 与命令行工具，不夹带内部脚本。全程约 8 分钟，其中等待设备上线的时间占一半。

适用版本BSP v2.4.x · huayun-cli ≥ 2.4.0 · hy-rt ≥ 2.4.1

端点约定：本文档中的 mqtt.huayuniot.com.cn、api.huayuniot.com.cn、get.huayuniot.com.cn、manifest.huayuniot.com.cn 为接入点命名约定；正式环境地址以交付时随附的《接入信息表》为准。命令名 huayun-cli / hy-rt / huayun-bsp-info 沿用历史命名，以保证客户既有脚本向后兼容。

适用板型HY-Edge X1 · HY-Gateway G3 · HY-DevKit C1

最近更新2026-09-10 · 对应固件 v2.4.0

反馈入口contact@huayuniot.com.cn · 1 个工作日

Prerequisites · 前置条件

开始之前先确认三件事

这三件事没确认，后面 80% 的失败都出在这里：设备时间、出方向端口、账号权限。

01 HARDWARE

硬件与固件

一台支持 BSP v2.4.x 的设备，已烧录出厂镜像并完成上电自检。

串口可见登录提示，波特率 115200
huayun-bsp-info --json 能输出五层版本
网口或 4G 已连通，能解析平台域名

02 ACCOUNT

账号与权限

控制台账号需要「设备管理 + 数据查询」两项权限，只读账号无法注册设备。

已创建产品空间（ProductKey）
持有 API Token，或已在 CLI 完成 huayun auth login
Token 有效期 90 天，过期后命令返回 401

03 NETWORK

网络与端口

只需出方向放行，不需要公网入方向端口，也不需要固定公网 IP。

TCP 8883（MQTT over TLS）、TCP 443（HTTPS 与 OTA）
UDP 123（NTP 对时，偏差需 <5 分钟）
现场有代理时，把代理地址写进 /etc/hy/agent.conf

主机侧工具

host — 安装并自检Ubuntu 22.04 / macOS 13+

# 1) 安装 CLI
curl -fsSL https://get.huayuniot.com.cn/cli | bash

# 2) 校验宿主机依赖与目标板型支持
huayun env check
huayun board list --supported v2.4

# 3) 登录（Token 从控制台「账号 - API 访问」生成）
huayun auth login --token "$HUAYUN_TOKEN"
huayun auth whoami        # 应回显租户与权限项

版本不匹配时：CLI 低于 2.4.0 无法识别 v2.4 的 manifest 字段，命令会报 unknown manifest field。升级用 huayun upgrade --channel stable；固件低于 2.3.0 请先按 BSP 文档升级到 2.4.x 再做接入。

测试机架前，工程师把一根蓝色网线插入仪表端口，机架上是分层安装的通信设备与监视器 — 接入联调工位：先确认链路与仪表读数，再谈平台侧配置。

Path · 四步路径

每一步都有可验证的成功标志

不要跳过第二步去查看板：设备没发数据，看板一定是空的。

注册设备

在产品空间下创建设备，拿到三要素。控制台或 CLI 二选一，约 1 分钟。

建立连接

用 MQTT 客户端连上接入域名，观察返回码。约 3 分钟，含证书校验。

发首条数据

向 <pk>/<dn>/up 发一条 JSON 遥测，QoS 0 即可。

看板验证

在控制台按设备 SN 查询最近一条数据，确认时间戳与数值。

Step 1 · 注册设备

拿到三要素，并只保存一次

DeviceSecret 只在创建时完整展示一次，之后控制台只保留指纹。丢了就重新生成，重新生成会立即吊销旧密钥。

CLI — 创建设备推荐

# 列出可用的产品空间
huayun product list

# 创建一台设备（名字用安装位置，别用日期）
huayun device create \
  --product pk_hy_gw_01 \
  --name gw-line3-cabinet \
  --model hy-gateway-g3

# 输出（一次性展示密钥）
# product_key   pk_hy_gw_01
# device_name   gw-line3-cabinet
# device_secret 5f3c...9a2b   ← 只展示这一次

# 写入设备本地配置文件，权限 600
huayun device bind --sn HYG3-2408-0193 \
  --secret-stdin --write /data/hy/device.json

REST — 等价调用HTTPS 443

curl -sS -X POST \
  https://api.huayuniot.com.cn/v1/products/pk_hy_gw_01/devices \
  -H "Authorization: Bearer $HUAYUN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device_name": "gw-line3-cabinet",
    "model": "hy-gateway-g3",
    "tags": {"line": "L3", "cabinet": "A12"}
  }'

# 201 Created
# {"device_id":"dev_8f21", "device_secret":"5f3c...9a2b",
#  "status":"inactive", "created_at":"2026-09-10T07:21:44Z"}

命名约定：device_name 用「位置-用途」写法（如 gw-line3-cabinet），长度 4~32，只允许小写字母、数字与连字符。设备台账里 SN 与 device_name 必须一一对应，现场换板卡时改 SN、不改名字，历史曲线才连得上。

Step 2 & 3 · 首条数据

主题由 SDK 生成，Payload 按物模型写

手工拼主题容易拼错大小写。下面这张表是 SDK 实际使用的主题，排障时按它比对抓包即可。

主题	方向	QoS	用途	Payload 约定
`<pk>/<dn>/up`	设备 → 平台	0	周期遥测	JSON，字段名与物模型一致
`<pk>/<dn>/event`	设备 → 平台	1	告警与事件	JSON，带 `event_id` 供幂等
`<pk>/<dn>/down`	平台 → 设备	1	指令下发	JSON，带 `msg_id` 与超时秒数
`<pk>/<dn>/ack`	设备 → 平台	1	指令回执	`{"msg_id":"…","code":0}`
`<pk>/<dn>/shadow`	双向	1	设备影子读写	JSON，只写变化字段

host — 用 mosquitto 发一条最快验证

mosquitto_pub \
  -h mqtt.huayuniot.com.cn -p 8883 \
  --cafile /etc/ssl/certs/hy-ca.pem \
  -u pk_hy_gw_01 -P "$DEVICE_SECRET" \
  -t 'pk_hy_gw_01/gw-line3-cabinet/up' \
  -q 0 \
  -m '{"ts":1789000000,"temp_c":23.6,"hum_pct":41.2,"vib_mm_s":0.8}'

# 无输出即发送成功（QoS 0 不回执）
# 发送失败会返回 Connection Refused: not authorised.

板端 — Python 长连接hy-sdk ≥ 2.4

# 依赖：pip install hy-sdk  （板端已预装）
from hy_sdk import Device

dev = Device.from_file("/data/hy/device.json")
dev.connect(keepalive=60, retry_backoff=(1, 60))

# 上报周期 30s，本地队列在断网时自动缓存
dev.report({
    "ts": dev.timestamp_ms(),
    "temp_c": 23.6,
    "hum_pct": 41.2,
    "vib_mm_s": 0.8,
}, qos=0)

dev.on_command(lambda msg: print("cmd:", msg["msg_id"], msg["action"]))
dev.loop_forever()

Payload 三条硬规则：① ts 用毫秒时间戳，缺省时平台按接收时间补；② 字段名与物模型一致，平台不猜同义词（temperature 与 temp_c 会被当成两个点位）；③ 单包建议 ≤4KB，超过就走分段或改成批量主题。

Step 4 · 看板可见

先查数据，再看看板

看板是聚合视图，排障时先查原始数据点。查到点、再对时间戳，最后才看看板刷新。

host — 查询最近数据REST

# 查最近 5 分钟该设备的全部点位
huayun data query \
  --device gw-line3-cabinet \
  --from -5m --limit 20

# 预期输出（截断）
# ts=1789000000  temp_c=23.6  hum_pct=41.2  vib_mm_s=0.8
# ts=1788999970  temp_c=23.5  hum_pct=41.2  vib_mm_s=0.8

# 也可以直接打 REST 分页接口
curl -sS "https://api.huayuniot.com.cn/v1/devices/dev_8f21/data\
?from=1788999700000&limit=100&order=desc" \
  -H "Authorization: Bearer $HUAYUN_TOKEN"

数据点时间戳与设备本地时间差应 <2s；差得多先查 NTP 对时。
接入 P99 240ms、规则引擎 P99 45ms，常规链路 1s 内可见。
看板刷新间隔 5s，历史曲线按分钟聚合，最迟滞后一个聚合周期。

现象	先查什么	常见原因	处置
连接被拒 rc=4	控制台设备密钥指纹	密钥错误，或设备时间偏差 >5 分钟	重新绑定密钥；`chronyc makestep` 校时
连接被拒 rc=5	`huayun device show`	设备被禁用，或 ProductKey 与设备不匹配	启用设备；核对三要素来源
连接成功但查不到数据	抓包看主题大小写	主题拼错，或 payload 不是合法 JSON	按主题表比对；用 `jq .` 本地校验
字段缺失	物模型定义	字段名与物模型不一致	改字段名或补物模型点位定义
数据时间戳乱序	设备本地时间	设备未对时，或补传历史数据	开启 NTP；补传按原时间戳写入

Next · 下一步

跑通之后按需要接下去

首条数据只验证链路。要上真实点位、真实模型或真实批量，看这三页。

协议接入Modbus / MQTT / OPC UA 的寄存器、主题与轮询预算 端侧运行时与模型部署量化到在环的五段产物、目录约定与校验阈值 运维、OTA 与 SLA告警分级、灰度批次、回滚与可用性口径

本文档由平台研发组维护，最近复核 2026-09-10。发现命令与实物不符，请带上 huayun-bsp-info --json 输出与执行记录发至 contact@huayuniot.com.cn，修订后回填勘误记录。

2026-09-10：补充 rc=4 与设备时间偏差的关联说明；data query 增加 --limit 示例。
2026-08-12：主题表新增 /shadow 行；修正 mosquitto 示例的 CA 路径。