怎么二次开发智能2路交流开关控制器以实现两路回路状态查询_解决方案

CATALOG

芯步的2路交流开关控制器提供开放HTTP API接口，支持通过签名认证方式进行二次开发。本文档详细介绍如何通过API查询设备两路回路的通断状态，包含完整的接口说明、签名算法及代码示例。

1. 解决概述

芯步智能2路交流开关控制器（如智能触摸墙壁开关2路、智能控制器2路）提供开放HTTP API接口。虽然官网展示的接口示例主要聚焦于设备控制（即下发命令），但若需实现状态查询，核心的二次开发思路如下：

主动查询（最佳实践）：调用平台提供的通用“设备状态获取”接口（通常为 /device/status/ 或类似路由），直接获取设备的当前属性。
状态上报接收：通过芯步平台配置HTTP 推送（Webhook），将设备状态变化实时推送到开发者自己的服务器。

本方案主要介绍第一种主动查询模式，因为它是最直接的集成方式。

2. 接口鉴权与基础信息

无论是控制设备还是查询状态，所有API请求都需要进行签名认证。芯步采用双重MD5加密机制。

2.1 核心参数

在开始开发前，请准备以下信息（在芯步控制台获取）：

AppID：开发者应用ID。
AppSecret：开发者密钥（严禁暴露在客户端代码中）。
Device ID：目标设备的唯一标识（如 1878 或更长的字符串）。

2.2 签名算法 (Sign)

签名生成规则如下：

\text{YourSign} = \text{MD5}(\ \text{MD5}(\text{AppSecret})\ +\ \text{ts}\ )

具体步骤：

将 AppSecret 进行第一次 MD5 加密（得到字符串 S1）。
获取当前 Unix 时间戳（秒级，例如 1714550400），拼接到 S1 后面（得到 S1ts）。
将拼接后的字符串进行第二次 MD5 加密，得到最终的 sign。

*代码示例 (Python) *

3. 实现“回路状态查询”功能

要实现“两路回路状态查询”，即获取 power1（第一路）和 power2（第二路）的当前值（通常是 0 表示关闭，1 表示开启）。

3.1 接口定位分析

根据芯步的API架构习惯，请求地址通常为：https://api.thingboot.com/{AppID}/device/status/

注：如果 /status/ 接口不可用，通用方案是利用 /device/control/ 接口的特性，但不使用控制接口做查询（可能会触发继电器动作）。

3.2 请求示例

假设 AppID 为 abc123，Device ID 为 10086。

请求URL：https://api.thingboot.com/abc123/device/status/?sign={YourSign}&ts={ts}

请求方式：POST

请求头：Content-Type: application/json

请求体 (Body) :

3.3 返回数据结构分析

预期服务器返回的 JSON 数据。对于 2 路控制器，返回数据可能包含以下字段：

预期响应示例：

3.4 代码实现 (Python Flask 示例)

以下 API 路由实现了查询指定设备的两路状态，并返回结构化数据。

from flask import Flask, jsonify, request
import requests
import hashlib
import time

app = Flask(__name__)

# 配置你的密钥 (需从控制台获取)
CONFIG = {
    "app_id": "YOUR_APP_ID",
    "app_secret": "YOUR_APP_SECRET",
    "device_id": "YOUR_DEVICE_ID"
}

def call_yoyo_api(device_id):
    ts = int(time.time())
    # 生成签名
    md5_once = hashlib.md5(CONFIG["app_secret"].encode()).hexdigest()
    sign_raw = md5_once + str(ts)
    sign = hashlib.md5(sign_raw.encode()).hexdigest()
    
    url = f"https://api.thingboot.com/{CONFIG['app_id']}/device/status/"
    params = {
        "sign": sign,
        "ts": ts
    }
    payload = {
        "device": device_id
    }
    
    try:
        response = requests.post(url, params=params, json=payload, timeout=5)
        return response.json()
    except Exception as e:
        return {"error": str(e)}

@app.route('/device/status', methods=['GET'])
def get_device_status():
    result = call_yoyo_api(CONFIG["device_id"])
    
    if result.get("code") == 0:
        # 提取两路状态
        power1 = result.get("data", {}).get("status", {}).get("power1")
        power2 = result.get("data", {}).get("status", {}).get("power2")
        
        return jsonify({
            "success": True,
            "channels": {
                "channel_1": "ON" if power1 == 1 else "OFF",
                "channel_2": "ON" if power2 == 1 else "OFF"
            }
        })
    else:
        return jsonify({"success": False, "message": result.get("msg")})

if __name__ == '__main__':
    app.run(port=5000)

预期输出：

4. 高级调试：通过控制命令“间接”获取

在某些旧版固件中，如果没有专用的状态查询接口，可以通过“查询型”命令来获取状态。请参考芯步硬件手册中的命令字。

例如，虽然 {"power":1} 是控制，但如果手册支持 {"get_status":1} 或类似的只读命令，同样可以通过上述请求方式发送。该命令不会实际切换继电器，而是会返回类似 {"power1":1, "power2":0} 的响应数据。

5. 自动化方案：状态上报回调

如果不想频繁轮询设备状态，推荐使用芯步平台的消息推送功能：

登录控制台：进入“物联网控制台” -> “设备管理” -> “HTTP 推送”。
配置回调 URL：填入你自己的服务器地址（例如 http://yourdomain.com/api/report）。
处理回调：当设备状态发生变化（例如手动按下墙壁开关或通过 API 控制）时，平台会向该 URL 发送 POST 请求。

服务器接收示例：

通过这种方式，可以实现实时同步，无需二次开发额外的轮询逻辑。

6. 常见问题排查 (FAQ)

异常现象	可能原因	解决方案
签名错误	AppSecret 使用了 MD5 后的值，或时间戳 ts 与服务器时间相差超过 5 分钟	必须使用原始 AppSecret 进行 MD5，同步服务器时间（NTP）
返回“设备离线”	控制器断电或 4G/WiFi 信号不稳定	检查设备供电，观察设备指示灯状态
返回“命令无效”	发送 `status` 命令时路由错误或方法不对	确认 Base URL 使用的 `device/status` 接口是否正确
无法获取状态	尝试通过控制接口获取，但命令字 `power1` 触发了继电器	查阅最新产品手册，寻找“查询”类命令

总结

对芯步智能2路控制器进行二次开发以查询状态，核心在于掌握 MD5 双重加密的签名规则。最稳健的做法是调用 /device/status/ 接口并解析 power1 / power2 字段。若对实时性要求比较高，搭配使用 HTTP 推送回调 功能，以降低服务器轮询压力并实现毫秒级状态同步。