silk/物联网设备接口和数据格式.md

物联网设备接口和数据格式

一、MQTT Topic 结构

后端同时订阅 silk/+/+/+/up/telemetry 和 silk/+/+/+/down/cmd（部分设备 publish/subscribe 方向反配）。下行命令主题根据设备实际上报主题自动推导：

• 设备上报 /up/telemetry -> 命令发送到 /down/cmd
• 设备上报 /down/cmd -> 命令发送到 /up/telemetry（反配设备）

方向	主题格式	示例
上行（设备 -> 后端）	silk/{appId}/{roomKey}/{deviceKey}/up/telemetry	silk/default/room-001/sensor-001/up/telemetry
下行（后端 -> 设备）	silk/{appId}/{roomKey}/{deviceKey}/down/cmd	silk/default/room-001/sensor-001/down/cmd

路径段说明

段	说明	示例值
silk	系统前缀（固定）	silk
{appId}	应用标识	default
{roomKey}	房间标识	room-001
{deviceKey}	设备标识（MAC 或自定义 ID）	sensor-001、28562f8c35e8

注意：GSTMB1 设备的 deviceKey 在数据库中使用 MAC 地址（如 28562f8c35e8），但 topic 路径中仍使用配网时配置的名称（如 sensor-001）。后端通过消息体中的 mac 字段识别设备。

---

二、GSTMB1 温湿度传感器

设备信息

项目	值
型号	GSTMB1
厂商	GeekOpen / smart-bird.cn
通信协议	MQTT
设备标识	MAC 地址（如 28562f8c35e8）
上报指标	temperature、humidity、signal 等

1. 设备定时上报（遥测数据）

设备直接在 body 顶层放置数值字段，后端自动提取 temperature、humidity、signal、lux、co2 等字段。

{
  "type": "GSTMB1",
  "mac": "28562f8c35e8",
  "temperature": 28.24,
  "humidity": 57.83,
  "signal": -75,
  "ip": "192.168.1.56",
  "ssid": "GeekOpen",
  "version": "1.0.5"
}

2. 命令响应（设备 -> 后端）

source 字段为 "command" 表示是对下行命令的回复。

成功响应（info-all）：

{
  "commandName": "info-all",
  "mac": "28562f8c35e8",
  "source": "command",
  "success": true,
  "temperature": 28.24,
  "humidity": 57.83,
  "signal": "-75",
  "ip": "192.168.1.56",
  "ssid": "GeekOpen",
  "version": "1.0.5",
  "dhcpEnable": 1,
  "h_compensate": 0,
  "t_compensate": 0,
  "timerEnable": 1,
  "timerInterval": 15
}

错误响应：

{
  "commandName": "error",
  "mac": "28562f8c35e8",
  "source": "command",
  "success": false,
  "message": "MQTT消息缺少必要的type字段"
}

3. 下行命令（后端 -> 设备）

功能	API 端点	命令 JSON
获取设备信息	POST /api/v1/devices/:id/gstmb1/info	{"type":"info","messageId":"..."}
重启设备	POST /api/v1/devices/:id/gstmb1/restart	{"type":"setting","system":"restart"}
恢复出厂设置	POST /api/v1/devices/:id/gstmb1/command	{"type":"setting","system":"reset"}
设置上报间隔	POST /api/v1/devices/:id/gstmb1/interval	{"type":"setting","messageId":"...","timerEnable":1,"timerInterval":60}
自定义命令	POST /api/v1/devices/:id/gstmb1/command	任意 JSON 原样转发

参数说明：

字段	类型	说明
type	String	必填。命令类型：info（查询）、setting（设置）、event（控制）
messageId	String	消息 ID，设备响应时原样返回
system	String	restart（重启）、reset（恢复出厂）
timerEnable	int	定时上报开关：0（关闭）、1（开启）
timerInterval	int	上报间隔（秒），范围 5-86400

API 端点中的 :id 是数据库中设备的 UUID，不是 MAC 地址。需 JWT 认证。

4. 命令响应字段说明

字段	类型	说明
commandName	String	命令名称：info-all、device-timer-interval、controller-restart、controller-reset、error
mac	String	设备 MAC 地址
source	String	固定 "command"，表示命令响应
success	boolean	执行结果
message	String	执行返回结果或错误信息
temperature	Float	温度（摄氏度）
humidity	Float	湿度（%）
signal	String	WiFi 信号强度（dBm），0~-50 最好，<-100 无信号
ip	String	设备内网 IP
ssid	String	WiFi 名称
version	String	固件版本
dhcpEnable	int	DHCP 开关：1（开启）、0（关闭）
t_compensate	Float	温度补偿（范围 -20 至 +20）
h_compensate	Float	湿度补偿（范围 -20 至 +20）
timerEnable	int	定时上报开关
timerInterval	int	上报间隔（秒）

---

三、GSPE1B 智能插座

设备信息

项目	值
型号	GSPE1B
厂商	GeekOpen / smart-bird.cn
通信协议	MQTT
设备类型	控制器（actuator）
设备标识	MAC 地址（如 e8f60a2f01e8）
上报指标	voltage、current、power、energy、key（通断状态）

注意：该设备的 MQTT 主题方向与常规配置相反——设备发布到 /down/cmd 主题，订阅 /up/telemetry 主题接收命令。后端已适配此情况。

1. 设备定时上报（遥测数据）

设备每 15 秒自动上报电量数据，source 字段为 "auto"：

{
  "mac": "e8f60a2f01e8",
  "source": "auto",
  "voltage": 226.234,
  "current": 0.327,
  "power": 66.795,
  "energy": 0.025,
  "key": 1
}

2. 命令响应（设备 -> 后端）

source 字段为 "command" 表示是对下行命令的回复。

info-all 响应（设备信息）：

{
  "commandName": "info-all",
  "mac": "e8f60a2f01e8",
  "source": "command",
  "success": true,
  "key": 1,
  "onState": 2,
  "wifiLock": 0,
  "keyLock": 0,
  "timerEnable": 1,
  "timerInterval": 15,
  "signal": "-75",
  "ip": "192.168.1.59",
  "version": "1.0.5"
}

info-statistic 响应（电量信息）：

{
  "commandName": "info-statistic",
  "mac": "e8f60a2f01e8",
  "source": "command",
  "success": true,
  "voltage": 226.234,
  "current": 0.327,
  "power": 66.795,
  "energy": 0.025,
  "key": 1
}

controller-event 响应（通断控制后回复）：

与 info-all 格式相同，包含设备状态信息。

3. 下行命令（后端 -> 设备）

功能	API 端点	命令 JSON
通电	POST /api/v1/devices/:id/plug/on	{"type":"event","key":1}
断电	POST /api/v1/devices/:id/plug/off	{"type":"event","key":0}
查询设备信息	POST /api/v1/devices/:id/plug/info	{"type":"info","messageId":"..."}
查询电量	POST /api/v1/devices/:id/plug/statistic	{"type":"statistic","messageId":"..."}
重启设备	POST /api/v1/devices/:id/gstmb1/restart	{"type":"setting","system":"restart"}
设置上报间隔	POST /api/v1/devices/:id/gstmb1/interval	{"type":"setting","timerEnable":1,"timerInterval":60}

API 端点中的 :id 是数据库中设备的 UUID，不是 MAC 地址。需 JWT 认证。

4. 指标字段说明

字段	类型	说明
voltage	Float	电压（V），如 226.234
current	Float	电流（A），如 0.327
power	Float	功率（W），如 66.795
energy	Float	累计电量（kWh），如 0.025
key	int	通断状态：1（通电）、0（断电）
onState	int	上电状态：0（保持断电）、1（保持通电）、2（记忆上次状态）
wifiLock	int	WiFi 锁：0（关闭）、1（开启）
keyLock	int	按键锁：0（关闭）、1（开启）

5. 命令响应字段说明

commandName	说明
info-all	设备信息查询响应，包含 key、onState、wifiLock、timerEnable 等
info-statistic	电量查询响应，包含 voltage、current、power、energy、key
controller-event	通断控制响应，格式同 info-all
error	错误响应，success: false，message 字段描述错误原因

---

四、GSCW1M-4G 4G 智能断路器

设备信息

项目	值
型号	GSCW1M-4G
厂商	GeekOpen / smart-bird.cn
通信协议	MQTT over 4G LTE（合宙780ex，4G全网通）
设备类型	控制器（actuator）
设备标识	IMEI 号（如 862323080741518），消息体中使用 imei 字段
上报指标	voltage、current、power、energy、key（通断状态）、signal（0-31）

与 GSPE1B 的区别：4G 通信（非 WiFi）；设备标识用 imei（非 mac）；信号强度为 0-31 整数（非 dBm）；timerInterval 单位为毫秒（非秒）；响应消息无 source 和 commandName 字段。

固件 Bug：部分设备在 info 响应中 imei 的第二位 6 误发为 G（如 8G2323080741518），statistic 响应中则为正确的 862323080741518。后端已做规范化处理（G -> 6）。

主题方向：与 GSPE1B 智能插座相同，设备响应消息出现在订阅主题（/down/cmd）上，而非发布主题（/up/telemetry）。后端已适配。

1. 设备响应（设备 -> 后端）

断路器的响应消息没有 source: "command" 字段，所有响应均作为遥测数据处理，后端自动提取 body 中的数值字段。

info 响应（设备信息）：

{
  "key": 0,
  "iccid": "898604E6192390306804",
  "imei": "862323080741518",
  "signal": 30,
  "version": "1.0.1",
  "timerEnable": 0,
  "keyLock": 0,
  "type": "Breaker-plus-1-4G",
  "timerInterval": 0,
  "resetLock": 0,
  "onState": 2
}

statistic 响应（电量信息）：

{
  "voltage": "230.547",
  "current": "0.035",
  "power": "4.547",
  "energy": "0.001",
  "key": 1,
  "imei": "862323080741518",
  "messageId": "auto"
}

注意：断路器的 voltage、current、power、energy 字段为字符串类型（如 "230.547"），后端 toFloat 函数自动转换为数值入库。messageId 为 "auto" 时表示定时上报数据。

event 响应（通断控制后回复）：

{
  "iccid": "898604E6192390306804",
  "timerEnable": 1,
  "onState": 2,
  "timerInterval": 60,
  "resetLock": 0,
  "imei": "862323080741518",
  "messageId": "0875c300-a0eb-475b-83ea-607eb27d19a0",
  "keyLock": 0,
  "type": "Breaker-plus-1-4G",
  "signal": 30,
  "version": "1.0.1",
  "key": 0
}

2. 下行命令（后端 -> 设备）

命令格式与 GSPE1B 智能插座完全相同，复用同一套 API：

功能	API 端点	命令 JSON
通电	POST /api/v1/devices/:id/plug/on	{"type":"event","key":1}
断电	POST /api/v1/devices/:id/plug/off	{"type":"event","key":0}
查询设备信息	POST /api/v1/devices/:id/plug/info	{"type":"info","messageId":"..."}
查询电量	POST /api/v1/devices/:id/plug/statistic	{"type":"statistic","messageId":"..."}
设置按键锁	POST /api/v1/devices/:id/gstmb1/command	{"type":"setting","keyLock":0}
设置定时上报	POST /api/v1/devices/:id/gstmb1/interval	{"type":"setting","timerEnable":1,"timerInterval":10000}
重启设备	POST /api/v1/devices/:id/gstmb1/restart	{"type":"setting","system":"restart"}
恢复出厂设置	POST /api/v1/devices/:id/gstmb1/command	{"type":"setting","system":"reset"}

timerInterval 单位为毫秒（如 10000 = 10 秒），取值范围 5000-86400000。

3. 指标字段说明

字段	类型	说明
voltage	Float	电压（V），如 226.024
current	Float	电流（A），如 15.027
power	Float	功率（W），如 2921.511
energy	Float	累计电量（kWh），如 25.047，断电不归零，重置后归零
key	int	通断状态：1（通电）、0（断电）
signal	int	4G 信号强度，0-31，值越大越好
imei	String	设备 IMEI（唯一标识，非数值指标）
iccid	String	物联网卡 ICCID（非数值指标）
onState	int	上电默认状态：0（记忆）、1（断电）、2（通电）
keyLock	int	按键锁：0（关闭）、1（开启）
resetLock	int	重置锁：0（关闭）、1（开启）
timerEnable	int	定时上报：0（关闭）、1（开启）
timerInterval	int	上报间隔（毫秒），如 10000 = 10 秒

---

五、GSCU1B-4G 智能红外控制器

设备信息

项目	值
型号	GSCU1B-4G
厂商	GeekOpen / smart-bird.cn
通信协议	MQTT over 4G LTE（合宙780ex，4G全网通）
设备类型	控制器（actuator）
设备标识	IMEI 号（如 864269069911747），消息体中使用 imei 字段
设备代号	Infrared-Controller-4G
功能	红外码学习、发射、擦除，遥控空调/电视/风扇等家电
红外码编号	1-248，可同时存储多个遥控器的红外码

与断路器共用 imei 标识和 IMEI 规范化逻辑。无电压/电流/功率等电量指标，仅有 signal（4G 信号强度 0-31）。

1. 设备响应（设备 -> 后端）

info 响应（设备信息）：

{
  "signal": 25,
  "code": "Infrared-Controller-4G",
  "version": "1.0.0",
  "iccid": "89860323442024493202",
  "type": "info",
  "imei": "864269069911747"
}

learn 响应（学习红外码结果）：

{
  "type": "infrared",
  "action": "learn",
  "imei": "864269069911747",
  "success": true
}

emit 响应（发射红外码结果）：

{
  "type": "infrared",
  "action": "emit",
  "imei": "864269069911747",
  "success": true
}

success: false 表示发射失败（红外编号对应的红外码为空）。学习成功蜂鸣器响 1 声，失败无声。

2. 下行命令（后端 -> 设备）

功能	API 端点	命令 JSON
查询设备信息	POST /api/v1/devices/:id/plug/info	{"type":"info","messageId":"..."}
学习红外码	POST /api/v1/devices/:id/ir/learn	{"type":"infrared","action":"learn","data":{"no":100}}
发射红外码	POST /api/v1/devices/:id/ir/emit	{"type":"infrared","action":"emit","data":{"no":100}}
取消学习	POST /api/v1/devices/:id/ir/cancel	{"type":"infrared","action":"learnCancel"}
擦除全部红外码	POST /api/v1/devices/:id/ir/erase	{"type":"infrared","action":"erase"}
重启设备	POST /api/v1/devices/:id/gstmb1/restart	{"type":"setting","system":"restart"}

学习和发射命令的 body 需包含 {"no": N}，N 为 1-248 的红外码编号。

3. 推荐红外码编号规划

编号	用途	学习方法
100	关机	遥控器对准控制器，按关机键
101	标准制冷	遥控器设为制冷 25°C 风量自动，按开机键
102	标准制热	遥控器设为制热 30°C 风量自动，按开机键
103+	自定义	按需扩展

4. 红外码学习流程

1. 后端发送 {"type":"infrared","action":"learn","data":{"no":100}}
2. 设备进入学习状态（不响应其他指令）
3. 遥控器对准设备，按一下对应按键
4. 设备"嘀"一声，返回 {"success":true}
5. 后续发送 {"type":"infrared","action":"emit","data":{"no":100}} 即可控制

---

六、通用 MQTT 数据格式（非 GSTMB1 设备）

后端同时兼容以下消息格式，按优先级依次匹配：

1. metrics 对象格式

{
  "msgId": "msg-test-001",
  "ts": 1751900000000,
  "metrics": {
    "temperature": 24.8,
    "humidity": 78.2,
    "lux": 360,
    "co2": 890
  }
}

2. data 数组格式

{
  "data": [
    {"metric": "temperature", "value": 24.8},
    {"metric": "humidity", "value": 78.2}
  ]
}

3. 单值格式

{
  "metric": "temperature",
  "value": 24.8
}

4. GSTMB1 顶层字段格式

{
  "type": "GSTMB1",
  "mac": "28562f8c35e8",
  "temperature": 28.24,
  "humidity": 57.83
}

设备标识优先级

1. body.deviceKey（显式指定）
2. body.mac（GSTMB1 传感器 / GSPE1B 智能插座）
3. body.imei（GSCW1M-4G 断路器，自动将 G 规范化为 6）
4. topic 路径第 4 段（如 sensor-001）

---

七、后端处理逻辑

消息处理流程

MQTT 消息到达
  │
  ├── JSON 解析失败 → 记录警告，丢弃
  │
  ├── 提取 deviceKey（mac > deviceKey > topic[3]）
  │
  ├── 记录 deviceKey → 上行主题映射（用于下行命令）
  │
  ├── 更新设备 online_status = "online", last_seen = now
  │
  ├── source == "command"?
  │   ├── success == false -> 记录警告，结束
  │   ├── commandName == "info-all" / "device-timer-interval" -> 提取温湿度入库
  │   ├── commandName == "info-statistic" / "controller-event" -> 提取电压/电流/功率/电量入库
  │   └── 其他 -> 记录日志，结束
  │
  └── 提取遥测指标（按优先级）
      ├── body.metrics（对象）
      ├── body.data（数组）
      ├── body.value（单值）
      └── body 顶层字段（温度/湿度/电压/电流/功率/电量/通断状态等）
          │
          ├── 持久化（IoTDB 优先，降级 PostgreSQL）
          ├── WebSocket 推送前端
          └── 阈值检测

离线检测

• 每 60 秒检查一次
• 超过 5 分钟未上报的设备标记为 offline
• 通过 WebSocket 广播状态变更