项目版本: v2.1

一、前言

1. 设备标识规则

1. 使用 MAC 地址作为设备唯一标识(device_id)
2. 用于区分不同设备的通信

1. MQTT 与 TCP 通信机制

1. 基于发布/订阅模式 (MQTT) 和请求/响应模式 (TCP)
2. 设备与服务器双向通信
3. 支持命令下发与状态上报

1. 命令交互规范

1. JSON 格式数据交换
2. 完整的命令应答机制
3. 标准化的错误处理

1. 适用的产品型号
2. 标准术语定义
3. "硬件终端": 指代智能设备上运行的嵌入式系统，其用于与服务器进行通信以及执行各种控制和监控功能。
4. "服务器端": 指代中心服务器，负责接收智能设备上传的数据、下发控制命令并进行数据处理与存储。
5. "应用终端": 指用户操作界面，如手机应用或网页界面，通过它用户可以发送命令到服务器端并查看设备的状态。
6. 支持的协议
7. MQTT: "硬件终端"作为MQTT客户端
8. TCP Client: "硬件终端"作为TCP客户端
9. HTTP Server: "硬件终端"作为HTTP服务端

二、产品型号说明

三、设备标识 (device_id)

1. 用途：代表终端的唯一编号
2. 默认值：设备的主芯片的唯一id

四、通信协议

4.1. MQTT 协议

4.1.1. MQTT 协议概要

1. mqtt 通讯基于2个主题,device_id/device_pub_topic与device_id/device_sub_topic
2. "硬件终端"通过device_id/device_pub_topic主题发布数据,"应用终端"通过该主题接收"硬件终端"的数据
3. "硬件终端"通过device_id/device_sub_topic主题接收数据,"应用终端"通过该主题发送数据

4.1.2. MQTT 通讯框图

sequenceDiagram
    participant HW_MQTT_Client
    participant MQTT_Server
    participant APP_MQTT_Client

    HW_MQTT_Client->>MQTT_Server: 发布消息到 device_pub_topic
    Note right of HW_MQTT_Client: 事件上报

    MQTT_Server->>APP_MQTT_Client: 转发消息

    APP_MQTT_Client->>MQTT_Server: 发布控制指令到 device_sub_topic
    Note right of APP_MQTT_Client: 控制命令或参数请求

    MQTT_Server->>HW_MQTT_Client: 转发指令
    Note right of MQTT_Server: 设备执行指令

    HW_MQTT_Client-->>MQTT_Server: 回复确认或失败信息
    MQTT_Server-->>APP_MQTT_Client: 转发应答结果

1. HW_MQTT_Client: 硬件终端,MQTT客户端
2. MQTT_Server: MQTT 服务器端,一般指客户在阿里云,华为云等云平台构建的MQTT服务器终端
3. APP_MQTT_Client: 应用终端,也是MQTT客户端,一般由手机小程序充当

4.2. TCP Client 协议

4.2.1. TCP Client 协议概要

1. TCP Client 代表"硬件终端"作为TCP客户端与"服务器端"进行socket通讯
2. "硬件终端"上电联网完成后,会主动与"服务器端"建立socket

4.2.2. TCP Client 通讯框图

以下图表,展示了"硬件终端"的"事件上报"与"应用终端"的"控制命令请求"或"参数请求"对应的通讯流程图.

sequenceDiagram
    participant TCP_Client
    participant TCP_Server

    Note over TCP_Server: TCP Server启动并监听端口
    Note over TCP_Client: 硬件终端上电初始化
    
    TCP_Client->>TCP_Server: 发起TCP连接请求(SYN)
    TCP_Server-->>TCP_Client: 确认连接请求(SYN+ACK)
    TCP_Client->>TCP_Server: 完成连接建立(ACK)
    Note over TCP_Client,TCP_Server: TCP连接建立完成

    TCP_Client->>TCP_Server: 事件上报
    Note right of TCP_Client: 事件通知(如设备状态变化)

    TCP_Server->>TCP_Client: 发送控制指令
    Note right of TCP_Server: 控制命令或参数请求

    TCP_Client-->>TCP_Server: 回复执行结果
    Note right of TCP_Client: 执行指令并反馈状态

    Note over TCP_Client,TCP_Server: 连接保持,可继续通信
    Note over TCP_Client,TCP_Server: 任一方可主动断开连接

4.3. HTTP Server 协议

4.3.1. HTTP Server 协议概要

1. 由于 HTTP 协议的限制，"硬件终端"仅支持通过 HTTP POST 请求。
2. 仅支持控制命令（ctrl_cmd）和参数（set_param、get_param）和状态 (set_status、get_status)请求，不支持主动上报、事件上报等。
3. 推荐所有 HTTP 请求均使用 Content-Type: application/json，且数据体为标准 JSON 格式。
4. 由于默认情况下,设备使用 DHCP 获取 IP 地址,所以设备端默认的 IP 地址是动态的,请通过配网页面查询.
5. 在这个模式下,硬件终端采用 STA 模式,硬件终端与应用终端都需要事先先连接到同一个网络中,才可以实现通讯.

4.3.2. HTTP Server 通讯流程

sequenceDiagram
    participant App_Client
    participant HW_HTTP_Server

    App_Client->>HW_HTTP_Server: 发送 HTTP POST 控制指令
    Note right of App_Client: 仅支持控制命令/参数设置

    HW_HTTP_Server-->>App_Client: 返回执行结果
    Note right of HW_HTTP_Server: 处理请求并反馈状态

1. App_Client：应用终端（如手机App、Web前端等）
2. HW_HTTP_Server：硬件终端（设备本身）

4.3.3. HTTP 报文与调用示例

HTTP 请求报文

POST /device_sub_topic HTTP/1.1
Host: 192.168.43.87
Content-Type: application/json
Content-Length: 85

{
    "ctrl_cmd": {
        "open_relay_cmd": {}
    }
}

curl 调用示例

curl -X POST http://192.168.43.87/device_sub_topic \
  -H "Content-Type: application/json" \
  -d '{"ctrl_cmd":{"open_relay_cmd":{}}}'

1. 仅支持 POST 方法，路径为 /device_sub_topic（device_id 为设备唯一标识）。
2. 数据体必须为 JSON 格式，支持的命令类型详见 5.1 控制命令表。
3. 典型响应为：

HTTP 响应报文

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 17

{
    "ask": true
}

1. 成功时返回 { "ask": true }，失败时返回 { "ask": false }。
2. 不支持主动上报,事件上报等请求，收到此类请求将返回 { "unknown_cmd": 0 }。

> 注意：

> 1. HTTP Server 仅用于本地局域网内调试或配置，不建议用于公网环境。

> 2. 仅支持控制命令和参数设置，所有查询类和事件上报类请求均不支持。

> 3. 详细命令格式请参考"5.1 控制命令"章节。

五、通讯报文

5.1. 控制命令

5.2. 参数设置&参数获取

1. 参数表中的所有配置项都支持掉电保存
2. 当设备收到参数设置命令后,会返回一个"确认帧"或"否认帧"来表示设置是否成功
3. 当设备收到参数查询命令后,会返回包含查询参数值的应答帧,具体格式请参考: #5.6. 消息应答

5.3. 状态设置&状态获取

1. 状态是运行时的实时数据, 如当前电压、电流等测量值, 这些数据断电后不会保存
2. 当设备收到状态获取命令后, 会返回对应的状态值, 具体格式请参考: #5.6. 消息应答

5.4. 事件上报

注意：

1. 按键事件上报中的数值表示按键索引，从0开始
2. 对于多按键产品（如D2_SW），每个按键都有独立的索引
3. 按键事件的触发时间：

1. 短按：立即触发
2. 双击：两次按键间隔小于300ms
3. 三击：三次按键间隔小于500ms
4. 长按：按住时间超过3秒
5. 超长按：按住时间超过10秒

5.5. 主动上报

5.6. 消息应答

六、电量统计功能说明

6.1. 功能概述

1. 通过控制指令开始和结束统计
2. 在统计期间，实时累加用电量
3. 结束统计时，自动清零，为下次统计做准备

6.2. 通信流程

sequenceDiagram
    participant App as 应用终端
    participant Device as 硬件终端

    App->>Device: 发送开始统计指令 {"ctrl_cmd":{"start_power_stat_cmd":{}}}
    Device-->>App: 返回确认帧 {"ask":true}
    Note over Device: 清零统计值并开始累加

    App->>Device: 查询当前用电量 {"get_status":{"power_consumption_w":{}}}
    Device-->>App: 返回当前累计值 {"ask_status":{"power_consumption_w":数值}}
    
    App->>Device: 发送结束统计指令 {"ctrl_cmd":{"stop_power_stat_cmd":{}}}
    Device-->>App: 返回确认帧 {"ask":true}
    Note over Device: 停止累加并自动清零

6.3. 相关指令说明

6.4. 工作原理

1. 开始统计：

1. 收到开始指令后，清零统计值并开始累加用电量

1. 结束统计：

1. 收到结束指令后，停止统计
2. 自动清零统计值，为下次统计做准备

1. 查询结果：

1. 通过状态查询指令可随时获取当前累计用电量
2. 单位为瓦时(Wh)

6.5. 注意事项

1. 统计过程中如果设备断电，统计将被中断并清零
2. 统计结果为实时累计用电量，单位为瓦时(Wh)
3. 可以随时查询当前累计值，不需要等待统计结束
4. 结束统计时会自动清零，下次开始统计时会重新开始计数

测试引用其他文档的功能