🔵 新手版 · 会一点编程，最快把设备接上来

如果你：会写一点代码、用过命令行（curl），但第一次接触这个平台——就读这一版。它默认你懂「请求 / 响应、JSON、HTTP」这些基本概念，只讲平台特有的约定。

读完这一版你能做到：用 3 个 HTTP 接口把任意设备接入平台，完成「心跳保活 → 属性上报 → 指令拉取与执行回传」的完整闭环，并知道如何接入规则引擎和可视化应用。

最快的接入路径：注册 → 设备管理创建设备（拿 device_id + token）→ 用下面 curl 样例跑通心跳与上报 → 平台设备详情确认数据 → 接入你自己的程序循环。全程约 10 分钟。

1.1 平台特有概念（与普通 Web API 不同的地方）

1.2 接入全流程（五步）

1. 注册登录：打开平台官网注册，自动获得独立租户空间。
2. 创建设备：设备管理 → 新建，填 device_id 与名称，保存后拿到 token（32 位随机串；可随时重置，重置后旧令牌立即失效）。
3. 设备侧联网：实现三个动作——定时心跳（推荐 30s）、定时上报属性（推荐 20s）、定时拉取指令（推荐 15s），三个定时互相独立。
4. 联调验证：curl 跑通后，到平台「设备详情 → 属性快照 / 设备日志」确认数据真实到达。
5. 进阶：配规则引擎做自动化；把属性绑到可视化应用并发布公开链接（可选对接公开 JSON 子接口，见老手版）。

1.3 三个核心接口速查

统一入口：https://www.hjyiot.cn/api.php，用 ?action=xxx 区分接口。

heartbeat —— 心跳 / 上线

curl -u "device_id:token" -X POST "https://www.hjyiot.cn/api.php?action=heartbeat"
# => {"code":0,"msg":"成功","data":{"online":1,"server_ts":1728000000,"last_seen":1728000000,"rate":null}}

report —— 属性上报

curl -u "device_id:token" -X POST -H 'Content-Type: application/json' \
  -d '{"ts":1728000000,"props":{"temperature":26.5,"humidity":58}}' \
  "https://www.hjyiot.cn/api.php?action=report"
# => {"code":0,"msg":"成功","data":{"accepted":1,"props":{"temperature":26.5,"humidity":58},"server_ts":1728000000,"online":1}}

command —— 拉取待执行指令

curl -u "device_id:token" "https://www.hjyiot.cn/api.php?action=command"
# => {"code":0,"msg":"成功","data":{"online":1,"server_ts":...,"commands":[
#       {"id":"65f1a2b3c4d5e6f7","type":"command","payload":{"fan_on":1},"source":"rule:8","status":"sent","ts":...,"sent_at":...} ]}}

无待执行指令时 commands 为空数组。已 sent 的指令不会重复出现，请勿反复只拉不执行。

固件下载另见老手版 2.11：需租户 OTA 已开启、云盘未封禁、任务未被冻结且处于「可推送 / 已推送」状态，并且要在最近一次推送后 24 小时内；失败返回 JSON 错误码 1002 / 1003 / 1004 / 1006。

1.4 鉴权（二选一，均与网页登录态无关）

凭据错误、设备不存在或已停用，统一返回 code=1001（HTTP 401），且提示不区分具体原因——这是平台的安全设计，避免探测有效设备。

1.5 通用约定

• 请求与响应均为 UTF-8 JSON；上报接口请带 Content-Type: application/json。
• 统一返回结构 {"code":0,"msg":"成功","data":{...}}；code=0 成功，判断结果以业务字段 code 为准（HTTP 状态码仅供参考）。注意字段名是 msg 不是 message。
• 建议所有请求携带 Unix 秒级 ts（设备侧做好 NTP 校时）。当前版本把 ts 记入设备日志供回溯，尚未强制差值拒收；请保持携带以兼容后续强校验版本。
• 频率限制：按来源 IP 与设备双重限流（阈值见老手版），超限返回 code=1005。

1.6 一条龙 curl 联调（把下面的值换成你自己的）

DEVICE_ID="your-device-001"
DEVICE_TOKEN="你的设备token"
API="https://www.hjyiot.cn/api.php"

# 1) 心跳上线
curl -u "$DEVICE_ID:$DEVICE_TOKEN" -X POST "$API?action=heartbeat"

# 2) 属性上报
curl -u "$DEVICE_ID:$DEVICE_TOKEN" -X POST -H 'Content-Type: application/json' \
  -d '{"ts":'$(date +%s)',"props":{"temperature":26.5,"humidity":58}}' "$API?action=report"

# 3) 拉取待执行指令
curl -u "$DEVICE_ID:$DEVICE_TOKEN" "$API?action=command"

# 4) 执行完成回传结果（示例：last_cmd 记最近指令 ID、cmd_ts 记时间、业务状态 fan_on）
curl -u "$DEVICE_ID:$DEVICE_TOKEN" -X POST -H 'Content-Type: application/json' \
  -d '{"ts":'$(date +%s)',"props":{"fan_on":1,"last_cmd":"65f1a2b3c4d5e6f7","cmd_ts":'$(date +%s)'}}' "$API?action=report"

1.7 推荐节奏与指令闭环

参考节奏（互相独立的三个定时器）：心跳 30s / 属性上报 20s / 拉取指令 15s。若设备是电池供电 / 低频场景，可自行放宽，但至少保证周期性心跳维持在线判定。

指令闭环四步：① 平台产生指令入队（手动 / 规则 / 公开页按钮）；② 设备 command 拉取（拉取即标记 sent 并返回全部待执行指令）；③ 设备逐条执行 type + payload 对应业务动作；④ 执行结果用 report 回写为属性，建议使用 last_cmd（最近指令 ID）+ cmd_ts（执行时间）+ 业务状态键（如 fan_on）。这样规则 / 页面 / 快照都能看到执行结果，形成完整闭环。

指令字段：id（16 位十六进制，用于去重与回传关联）、type（自定义，默认 command）、payload（参数对象）、source（来源：manual / rule:<ID> / public_app:<ID>）。平台保留最近 200 条已发送记录供追溯。

1.8 规则引擎与可视化应用（快速入门）

规则引擎：登录后「规则引擎 → 新建规则」，可视化配置即可。触发器 4 类：设备属性上报 / 设备状态变化（上线）/ 定时 cron / Webhook；条件支持 > < >= <= == !=、contains、startswith、endswith、matches；动作 5 类：下发设备指令 / 触发链式规则 / HTTP 请求外部接口 / 站内通知 / 修改设备属性。执行历史在「执行日志」可查。

可视化应用：「应用工作台 → 新建应用」，拖组件（文本 / 指标 / 仪表盘 / 折线图 / 开关 / 按钮 / 分隔线）→ 绑定设备属性或配置指令模板 → 保存发布 → 得到免登录公开链接，可分享、可重置密钥、可下架。开关 / 按钮组件在公开页可直接点击，平台会把指令写入目标设备队列。

如果你在自研前端 / 大屏，想直接读公开页数据或触发按钮，公开页提供 JSON 子接口（&data=1 读快照、&cmd=1 白名单指令下发），细节见 老手版 2.6。

1.9 常见报错排查

1.10 再进一步

• 需要完整协议细节（限流阈值、错误码全表、公开页子接口、Webhook、ESP32 示例）→ 看 老手版。
• 需要把真实开发板接进来 → 老手版附 ESP32 Arduino 最小示例（心跳 30s / 上报 20s / 拉指令 15s）。
• 遇到平台页面使用问题 → 回顶部切「零基础版」看对应功能说明，或直接联系官方客服 QQ。

⚫ 老手版 · 协议细节直读

面向有嵌入式 / 后端经验的开发者。假设你熟悉 HTTP、Basic Auth、JSON 与队列语义。本版只给「规格」和「坑」，不再做科普。

2.1 端点总览

2.2 鉴权与安全语义

• 设备通道每次请求必须携带凭据：Authorization: Basic base64(device_id:token)，或双 Header X-Device-ID + X-Device-Token。
• 凭据错误 / 设备不存在 / 设备停用 / 租户停用：统一 code=1001（HTTP 401），不区分原因。
• IP 级限流先于鉴权执行（防爆破），凭据错误同样计数。
• token 为 32 位随机串，可由用户重置；重置后旧 token 立即失效。
• 公开页以 app_id + share_key 为凭据；重置 share_key 使旧链接立即失效。

2.3 设备接口规格

统一返回 {"code":0,"msg":"成功","data":{...}}；以业务字段 code 判断结果（注意 msg 而非 message）。请求 / 响应 UTF-8 JSON；上报带 Content-Type: application/json。

report 细则

• 属性值仅接受标量 / null（数字 / 字符串 / 布尔）；嵌套对象 / 数组被丢弃。
• 推荐统一 {"ts":...,"props":{...}}；兼容平铺写法（如 {"temperature":23.5}），但平铺时除属性外的字段（含 ts）也会并入快照，不建议混用。
• 按「新增或值变化」的键触发属性类规则；同值重复上报不重复触发。
• 单包上限 256KB（超限 HTTP 413 / code=1004）；空体 / 非对象 / props 非对象均 code=1004。

command 队列语义

• 指令字段：id（16 位十六进制，执行去重与回传关联；字段名是 id 不是 command_id）、type（下发方自定义，默认 command）、payload、source（manual / rule:<ID> / public_app:<ID>）、status（返回即 sent）、ts（入队）、sent_at（标记 sent 时间）。
• 已 sent 指令不会在后续拉取中重复出现；平台保留最近 200 条已发送记录供追溯。
• 执行完成后用 report 回传建议键：last_cmd=最近指令 ID、cmd_ts=执行时间、叠加业务状态键。

ota_download 细则

• 成功响应不是 {"code":0,...} 包裹，而是固件字节流；请先判 Content-Type 再决定「按流处理」还是「按 JSON 解析错误」。
• 平台校验顺序：租户 OTA 已开启 → 云盘未被封禁 → 任务存在且属于本设备 → 未被平台冻结 → 状态为 ready / pushed → 处于推送后 24 小时窗口内 → 固件文件存在。
• 失败码：1002（OTA 功能停用 / 云盘封禁 / 固件被冻结）、1003（任务不存在，两种原因同一提示以防跨设备探测）、1004（缺 job_id / 固件未就绪 / 下载窗口过期）、1006（固件文件缺失或读取失败）。
• 下载计入设备级限流（120 次 / 分钟）；固件响应 Cache-Control: no-store，不做缓存。

2.4 限流与错误码（全站统一规范）

2.5 规则引擎语义

规则 = 触发器 + 条件（0..N）+ 动作（最多 10 条顺序执行）。

执行结果（命中与否、每动作成败）见「规则引擎 → 执行日志」。

2.6 Webhook 触发示例

规则选「Webhook」触发器后，编辑页会生成专属地址（含 tenant_id / key / path）。任意第三方 POST JSON 即可命中，条件可用 payload 字段求值：

curl -X POST -H 'Content-Type: application/json' \
  -d '{"event":"alarm","level":2}' \
  "http://www.hjyiot.cn/webhook.php?tenant_id=<租户ID>&key=<规则密钥>&path=<触发路径>"
# => { "code":0, "msg":"成功", "data":{ "accepted":1, "server_ts":... } }

2.7 公开页 JSON 子接口（自研前端 / 大屏对接）

# 读数据
curl "http://www.hjyiot.cn/app.php?app=<app_id>&k=<share_key>&data=1"

# 下发指令（component_id 为配置了 command 模板的组件，如 btn_fan）
curl -X POST -H 'Content-Type: application/json' \
  -d '{"component_id":"btn_fan","payload":{"fan_on":1}}' \
  "http://www.hjyiot.cn/app.php?app=<app_id>&k=<share_key>&cmd=1"

公开数据接口为只读语义；请勿把敏感属性绑定到已发布应用的画布。公开页交互（开关 / 按钮）点击后平台校验 share_key 并把指令写入目标设备队列，设备按 command 拉取节奏收到。

2.8 ESP32 Arduino 最小示例（HTTP 接入）

HTTP Basic 鉴权；三独立定时器：心跳 30s / 上报 20s / 拉指令 15s。需安装 ArduinoJson 库。替换 DEVICE_ID / DEVICE_TOKEN / WIFI_SSID / WIFI_PASS。

#include <WiFi.h>
#include <HTTPClient.h>
#include <ArduinoJson.h>

const char* WIFI_SSID = "你的WiFi名";
const char* WIFI_PASS = "你的WiFi密码";
const char* DEVICE_ID  = "your-device-001";
const char* DEVICE_TOKEN = "你的设备token";
const char* API_BASE = "http://www.hjyiot.cn/api.php";
const unsigned long HEARTBEAT_MS = 30000, REPORT_MS = 20000, PULLCMD_MS = 15000;
unsigned long tH = 0, tR = 0, tP = 0;

bool apiCall(const char* action, const char* body, String& resp) {
    HTTPClient http;
    http.begin(String(API_BASE) + "?action=" + action);
    http.setAuthorization(DEVICE_ID, DEVICE_TOKEN);
    http.setTimeout(5000);
    int code;
    if (body) { http.addHeader("Content-Type", "application/json"); code = http.POST(body); }
    else      { code = http.GET(); }
    if (code == 200) resp = http.getString();
    http.end();
    return code == 200;
}
void reportProps(JsonDocument& props) {
    String body = "{\"ts\":" + String((long)time(nullptr)) + ",\"props\":";
    serializeJson(props, body); body += "}";
    String r; apiCall("report", body.c_str(), r);
}
void setup() {
    Serial.begin(115200);
    configTime(0, 0, "pool.ntp.org", "ntp.aliyun.com");
    WiFi.begin(WIFI_SSID, WIFI_PASS);
    while (WiFi.status() != WL_CONNECTED) { delay(500); Serial.print("."); }
    String r; apiCall("heartbeat", nullptr, r);          // 上线
    JsonDocument d; d["temperature"] = 26.5; reportProps(d); // 首报
    tH = tR = tP = millis();
}
void loop() {
    unsigned long now = millis();
    if (now - tH >= HEARTBEAT_MS) { tH = now; String r; apiCall("heartbeat", nullptr, r); }
    if (now - tR >= REPORT_MS) {
        tR = now;
        JsonDocument d;
        d["temperature"] = 26.0 + random(0, 100) / 10.0;
        d["humidity"] = 55 + random(0, 20);
        reportProps(d);
    }
    if (now - tP >= PULLCMD_MS) {
        tP = now;
        String resp; if (!apiCall("command", nullptr, resp)) return;
        JsonDocument doc; deserializeJson(doc, resp);
        for (JsonObject c : doc["data"]["commands"].as<JsonArray>()) {
            // 按 c["type"] / c["payload"] 执行具体动作
            JsonDocument result;
            result["last_cmd"] = c["id"] | "";
            result["cmd_ts"] = (long)time(nullptr);
            result["done"] = 1;
            reportProps(result);   // 执行结果回传
        }
    }
    delay(100);
}

2.9 兼容性与易踩坑清单

• 响应字段是 msg 不是 message；指令字段是 id 不是 command_id。
• 属性名大小写敏感，规则条件与画布绑定需逐字一致。
• heartbeat 不处理请求体属性；要刷新属性走 report。
• 指令拉取即 sent，勿只拉不执行造成队列堆积（平台保留最近 200 条已发送记录）。
• 设备通道与公开页子接口各自独立限流；判断请以 code 为准，HTTP 状态仅供参考。
• 建议所有请求携带 ts（Unix 秒级），当前版本仅记录，未来版本可能强校验差值，请提前做好 NTP 校时。
• 公开页 cmd=1 仅允许白名单指令模板，需在画布组件配置模板后生效。
• ota_download 成功返回二进制流：按 Content-Type 分支处理，只有失败才是 JSON；不要用「先解析 JSON」的客户端直接读固件。
• OTA 指令与普通指令同一队列，type=ota，固件信息在 payload：version / job_id / size / sha256 / ts。
• 固件下载窗口 24 小时（自最近一次推送起算），过期返回 1004，需在网页端重新推送；重复推送会再入队一条 OTA 指令并刷新窗口。
• OTA 固件与云盘共享 10MB 配额，disk_stats.used 是「云盘文件 + 固件」合计；固件只能在「OTA 升级」页删除任务释放。

2.10 云盘接口（只读三接口 + report.fs 内容维护）

每个租户（账户）默认获得 10MB 共享云盘，与租户下全部设备联动共享配额；这 10MB 与 2.11 OTA 固件 合计计算（disk_stats.used = 云盘文件 + 固件），固件需在「OTA 升级」页删除任务释放。当前暂不支持扩容，配额写满后自动进入只读态。允许文件类型：txt（UTF-8 文本）、jpg（图片，仅支持读取 / 预览）。云盘不开放整文件上传与下载；设备对云盘的读取走三个独立只读动作，内容维护一律作为「数据伴随操作」随属性上报包执行。

2.10.1 只读三接口

• 路径均为相对路径（根目录可用空串或 /），不分层级拼接最多 8 层；名称最长 120 字符，不允许以点号开头，不允许 / \ 与控制字符，杜绝 ../ 穿越。
• 账户被封禁（平台管控）时：即使只读也不放行——disk_stats / disk_list 返回 code=1002 并附封禁原因（disabled_reason），disk_read 统一返回 code=1002「云盘已被平台封禁」；满配额（quota_hit）不影响读取。
• jpg 仅支持读取 / 平台网页预览；其内容的新增由平台按业务策略维护，设备侧无法上传图片文件。需保存图片时请使用 txt（如 base64 文本流）或联系平台侧开通专属通道。

2.10.2 report.fs：云盘内容维护指令

发送 report 时在请求体顶层携带 fs 数组，平台会先将 fs 剥离（不落入属性存储），逐项执行后逐项回报；任一项失败不影响其它项，也不影响本次属性上报。单包 fs 最多 20 条；每条 write 的 content 上限 128KB；整体包仍受 256KB 单包限制。所有写操作都会写入平台审计（后台「云盘 → 审计记录」可查）。

POST https://www.hjyiot.cn/api.php?action=report
Authorization: Basic base64(device_id:token)
Content-Type: application/json

{
  "ts": 1788861130,
  "props": { "temperature": 26.5 },
  "fs": [
    { "op": "write", "path": "logs/2026-09-08.txt", "content": "温度 26.5℃\n", "mode": "append", "create": true },
    { "op": "delete_content", "path": "logs/2026-09-08.txt", "needle": "旧行", "all": false }
  ]
}
# => data.fs[]（逐项对应请求顺序）：
#    [ {"op":"write","path":"/logs/2026-09-08.txt","ok":true,"bytes":24,"created":1,"mode":"append"},
#      {"op":"delete_content","path":"/logs/2026-09-08.txt","ok":true,"removed":1,"bytes":19} ]

• 返回语义：成功项带 ok:true；失败项不中断批次，置 ok:false 并附 error 中文原因（真实文案如「目录不存在：/logs」「文件不存在：/logs/2026-09-08.txt」「该文件已被平台冻结，禁止修改 / 禁止删除」「云盘已被平台封禁，当前仅可查看」「文件中未找到指定内容：xxx」）。
• 文件级约束：txt/jpg 单文件均 ≤ 8MB；全盘条目总数 ≤ 5000；目录层级 ≤ 8；配额写满后所有 write 拒绝（可先用 disk_stats 判断 quota_hit / read_only）。
• 平台封禁为账户级（整盘只读且禁止读取）；平台冻结为文件 / 目录级（冻结目录下全部文件禁止修改与读取删除）。设备端应把这两类响应当业务异常处理并在本地重试策略中留出间隔。

2.11 OTA 固件下载（设备侧）

平台 OTA 升级闭环：网页端上传固件 / 源码 → 审查 / 编译 → 推送设备 → 设备下载并校验。设备侧只需实现「收到 type=ota 指令 → 调 ota_download 下载固件 → 校验 → 写入 OTA 分区重启」。固件与云盘共享账户 10MB 配额。

2.11.1 前置条件（平台逐项校验，任一不满足只返回 JSON 错误包）

• 租户 OTA 功能已开启（平台管理端可停用，停用原因对租户可见）；
• 租户云盘未被平台封禁（封禁期间 OTA 上传 / 编译 / 推送 / 删除与设备固件下载同步停用）；
• 任务存在且归属当前鉴权设备（任务不存在或不属于本设备，统一返回 1003 以防跨设备探测）；
• 任务未被平台冻结（返回 1002）；
• 任务状态为 ready（可推送）或 pushed（已推送）；
• 处于下载窗口内：自最近一次推送时间起 24 小时（从未推送则退化为任务可用时间）；
• 该任务对应的固件文件仍留存于平台。

2.11.2 请求与响应

GET  https://www.hjyiot.cn/api.php?action=ota_download&job_id=<任务ID>
POST https://www.hjyiot.cn/api.php?action=ota_download     Body: {"job_id":"<任务ID>"}

# 成功：HTTP 200 + Content-Type: application/octet-stream（响应体即固件，不是 JSON）
#   X-OTA-Version: 1.2.0      （URL 编码，需 decode）
#   X-OTA-SHA256: 9f2c...     （64 位十六进制，下载后必须校验）
#   X-OTA-Size: 512000
#   X-OTA-Job: 65f1a2b3c4d5e6f7      （16 位十六进制任务 ID）
#   Cache-Control: no-store
# 失败：JSON 错误包 {"code":1002|1003|1004|1006,"msg":"...","data":{...}}

# 一行下载（-OJ 按响应头文件名落盘），下完比对 sha256：
curl -u "device_id:token" -OJ "https://www.hjyiot.cn/api.php?action=ota_download&job_id=<任务ID>"

2.11.3 与 command 指令联动（type=ota）

推送时平台向设备指令队列写入 type=ota 指令，source 形如 ota:<操作者用户名>，id 为 16 位十六进制指令 ID（与 2.3 的指令结构一致），payload 固定为：

{ "version":"1.2.0", "job_id":"65f1a2b3c4d5e6f7", "size":512000,
  "sha256":"9f2c...(64 位十六进制)", "ts":1788600000 }

设备侧推荐流程：① command 拉到 type=ota → ② 从 payload 取 job_id / version / size / sha256 → ③ 与本地版本比对（平台已保证版本递增，设备侧建议再判一次防回退）→ ④ ota_download 下载 → ⑤ 校验大小与 SHA-256 → ⑥ 写入 OTA 分区 → ⑦ 重启 → ⑧ 上线后用 report 回写新版本号，形成闭环。

2.11.4 任务状态机（11 态，含租户侧页面显示名）

• 上传限制：.ino ≤ 512KB、.bin ≤ 4MB，仅这两种扩展名；版本号须严格大于该设备已发布最高版本（v / V 前缀会被剥离），长度 ≤ 60；
• 编译额度：每租户免费 3 次；批量勾选多台设备时每台生成一条独立任务、各占 1 次（同批共用一次编译产物）；任务实际进入编译即扣（编译失败同样计费，审查未通过、源文件拉取失败不计费）；
• 其他上限：单次批量推送 ≤ 50 个任务、单租户任务 ≤ 200 个，每任务保留 20 条状态更新（对租户展示最近 10 条）；
• 配额：固件按设备份数计入账户 10MB（与云盘共享），空间不足时上传被拒并写 ota_quota_reject 审计。

2.11.5 任务删除规则

• 仅 queued（排队中）与 compiling（编译中）不可删除：流水线处理中，返回 code=1004，文案「任务当前状态为「排队中/编译中」，流水线处理中不可删除，请等待编译结束后再删除」；
• 其余状态（pending_review / reviewing / review_fail / need_payment / compile_fail / ready / pushed / canceled / frozen）均可删除；
• 删除为物理删除：该任务的源码与编译产物一并清理，并释放其占用的账户配额；页面二次确认会展示将释放的容量；
• 固件只能在「OTA 升级」页删除任务释放，云盘侧不可删除；设备侧不提供删除入口。

2.11.6 审计口径（仅平台管理员可见）

• OTA 全动作写入独立审计记录（与通用审计、云盘审计并行留存）；
• 审计仅平台管理端「OTA 审计」入口可读，租户侧与设备侧均不开放审计查询接口与入口；
• 常见 action：ota_upload / ota_quota_reject / ota_queued / ota_reviewing / ota_review_fail / ota_compile_fail / ota_ready / ota_need_payment / ota_push / ota_delete，以及平台侧 ota_admin_enable / disable / recharge / freeze / unfreeze / delete；每条含操作者与来源（web / admin / device / system）。

2.11.7 SDK 用法

# Python（hjyiot.py）
from hjyiot import HjyIot
dev = HjyIot("your-device-001", "你的token", base="https://www.hjyiot.cn/api.php")
r = dev.ota_download("65f1a2b3c4d5e6f7", "fw.bin")
# => {"version":"1.2.0","size":512000,"sha256":"9f2c...","sha256_match":true,"path":"fw.bin"}

// ESP32 Arduino（HjyIot.h，流式写入 OTA 分区并边写边算 SHA-256）
HjyIot dev(DEVICE_ID, DEVICE_TOKEN, API_BASE);
String out;
if (dev.otaDownload(jobId, out)) {
    Serial.println(out);   // 含 version / size / sha256 / match
    ESP.restart();
}

两类 SDK 均只做「下载 + 校验 + 落盘 / 落分区」；版本比对与重启时机由业务侧决定。