你的硬件。共同的生态。

01 / 从只读接入开始

在支持此接口的独立基础版中，用设备登记界面创建 HTTP 设备并记录 device_id、generation 和仅展示一次的 token。字段映射必须与登记一致。先使用测试设备验证；不要连接加热、补水或换水输出。受管 AQUA 权限投影尚未完成，此入口暂不开放。

02 / 声明设备档案

档案为纯 JSON，不执行脚本，也不授予输出权限。文件上限 24 KB；template 为 sensor 或 plug，mappings 为 1–8 项。sensor 可映射 temperature / level，plug 可映射 power / switch；同一用途与字段键不可重复。字段键须以小写字母开头，仅含小写字母、数字或下划线，最长 64 字符。

temperature 使用 °C，power 使用 W；scale 与 offset 用于换算，范围均为 −10000 到 10000。level 为 0/1 接点，wet_low 可反转湿/干含义，不是水位百分比；switch 为只读 0/1，其他读值为未知。接入旧连接时，字段键须存在且不能属于另一台设备。

二值点的 scale 必须为 1、offset 必须为 0；wet_low 只能用于 level。JSON Schema 描述结构约束，重复用途、重复键和连接归属仍由运行端校验。

{
  "schema_version": "revdev.local-profile.1",
  "model_id": "example.dual-sensor",
  "name": "Example temperature and contact sensor",
  "template": "sensor",
  "mappings": [
    {
      "purpose": "temperature",
      "key": "water_temp",
      "scale": 1,
      "offset": 0,
      "wet_low": false
    },
    {
      "purpose": "level",
      "key": "water_contact",
      "scale": 1,
      "offset": 0,
      "wet_low": false
    }
  ]
}

03 / 发送遥测

由固件或可信网关发送 POST，请求需携带 Bearer 设备 token、application/json 与 Content-Length。禁止从浏览器直接上报：带 Origin 的请求会被拒绝。跨不可信网络须使用可信证书的 HTTPS；不要把 token 写进网址、公开仓库或日志。

POST /api/device-ingest/v1/telemetry
Authorization: Bearer <DEVICE_TOKEN>
Content-Type: application/json
Content-Length: <UTF8_BODY_BYTE_LENGTH>

sequence 必须持久化并单调递增，最大 2^53−1；sent_at 为当前 Unix 秒，允许约 30 秒时钟偏差。建议每 5 秒一次，上限 1 Hz、8 KB。values 必须包含全部已登记字段，数值应有限；缺失读值使用 null。字符串、布尔值、NaN 与重复 JSON 键均不可用。

下面是结构示例：替换设备标识、登记代次、持久化序号和时间戳后再发送，不要直接重放示例。

{
  "device_id": "REPLACE_WITH_REGISTERED_DEVICE_ID",
  "generation": 1,
  "sequence": 1,
  "sent_at": 0,
  "values": {
    "water_temp": 25.4,
    "water_contact": 1
  }
}

04 / 新鲜度与错误处理

同序号、同内容的精确重复会返回 duplicate，但不会延长读值新鲜度；同序号不同内容或旧序号返回 409。30 秒后数据过期，服务重启后也需新的遥测。停用再启用会变更 generation，轮换 token 会重置序号状态；按设备登记界面返回的新凭据处理。

401：凭据无效；403：停用或代次不匹配；409：序号冲突；422：格式、字段或时间校验失败；429：发送过快。先修正原因，避免无间隔重试。

05 / 接入，不等于任意控制

HTTP 遥测和本地档案不开放输出控制。现有串口、MQTT、Tuya、MiIO 驱动的低风险手动操作需单独授权；请求被接受不等于设备已执行，结果未知时不得盲目重试。跨设备自动补水、换水、加热等高风险自动化未开放。硬件须具备独立的失效保护，不能依赖网页状态保障生命安全。