怎样二次开发智能触摸墙壁开关 2 路来实现远程指令开关控制_解决方案

CATALOG

芯步智能触摸墙壁开关2路开放了标准HTTP API接口，通过签名认证即可实现远程控制。以下从接口机制、签名算法到代码实现，完整说明二次开发过程。

解决方案：基于芯步开放接口的智能开关远程指令二次开发

1. 背景与概述

芯步的智能触摸墙壁开关2路（型号：UNI-KG-CM-2）是一款支持WiFi直连的智能硬件产品。为了实现通过互联网远程控制开关的闭合与断开（例如集成到自有App、Web中台或自动化系统中），开发者可以利用其开放的HTTP API接口进行二次开发。

本方案的目标是指导开发者如何通过编程方式（如Python、Java、PHP等）生成合法的签名（Sign），并向指定的设备ID下发标准的JSON命令，从而实现对两路灯路的远程独立控制。

2. 核心技术原理

芯步的API接口采用签名机制来确保安全性，所有控制指令最终通过物联网平台下发给设备。

通信协议：HTTPS/HTTP
请求方式：POST / GET
认证机制：动态MD5签名（防止数据篡改）
控制模式：云端API下发（支持局域网与公有云）

3. 准备工作：获取关键凭证

在进行二次开发前，您需要先完成账号注册与设备配网，并获取以下三个核心参数：

参数名称	获取位置	用途说明
AppID	登录芯步官网 -> 控制台 -> 开发设置	唯一标识您的应用/账户
AppSecret	登录芯步官网 -> 控制台 -> 开发设置	通信密钥，用于生成签名，严禁泄露
Device ID	控制台 -> 设备列表或设备外壳标签	指定需要控制的目标设备

前置步骤

注册芯步账号。
在控制台创建“工作台”。
参考手册，使用小程序或控制台为开关配置现场2.4G WiFi网络，确保设备状态显示为“在线”。

4. 接口请求构建详解

二次开发的核心环节是动态生成API请求的URL和Body。API的核心请求地址结构如下：

https://api.thingboot.com/{AppID}/device/control/?sign={YourSign}&ts={Timestamp}

4.1 签名算法 (Sign)

为了防止请求被伪造，必须按照特定算法生成 sign 参数。算法规则如下：

将 AppSecret 进行一次MD5加密，得到 Secret_MD5。
将 Secret_MD5 与当前Unix时间戳（秒级，即 ts）拼接成字符串。
将拼接后的字符串再次进行MD5加密，得到最终的 sign。

公式化表达sign = MD5( MD5(AppSecret) + ts )

注意：ts 必须为发起请求时的实时时间戳，与服务器的时差过大将导致请求失败。

4.2 关键命令 (Order)

针对“智能触摸墙壁开关2路”，控制命令需以JSON格式放在请求体中。支持的命令如下

控制指令 (order参数)	功能描述	业务场景
`{"power1": 1}`	开启第1路	继电器吸合，灯亮
`{"power1": 0}`	关闭第1路	继电器断开，灯灭
`{"power2": 1}`	开启第2路	继电器吸合，灯亮
`{"power2": 0}`	关闭第2路	继电器断开，灯灭
`{"power1": 2}`	第1路状态反转	若开则关，若关则开
`{"point1": 1}`	第1路“点动”	先接通后立即断开
`{"reset1": 1}`	第1路“复位”	先断开后接通

4.3 完整请求示例 (以Python为例)

以下代码展示了如何动态生成签名并发起请求（该逻辑适用于任何支持HTTP编程的语言）

import requests
import hashlib
import time
import json

# 1. 配置参数 (请替换为实际值)
AppID = "10001"          # 您的应用ID
AppSecret = "your_app_secret_key" 
DeviceID = "1878"        # 开关的设备ID

# 2. 生成签名
ts = str(int(time.time()))  # 获取当前秒级时间戳
# 第一次MD5加密Secret
secret_md5 = hashlib.md5(AppSecret.encode()).hexdigest()
# 拼接并第二次MD5
sign_str = secret_md5 + ts
sign = hashlib.md5(sign_str.encode()).hexdigest()

# 3. 构建请求
url = f"https://api.thingboot.com/{AppID}/device/control/"
params = {
    "sign": sign,
    "ts": ts
}
# 控制命令:打开第一路
payload = {
    "device": DeviceID,
    "order": {"power1": 1}   # 根据需求修改命令
}

# 4. 发送POST请求
headers = {"Content-Type": "application/json"}
response = requests.post(url, params=params, data=json.dumps(payload), headers=headers)

# 5. 结果处理
if response.status_code == 200:
    res_json = response.json()
    if res_json.get("code") == 200:
        print("命令下发成功，设备已执行动作。")
    else:
        print(f"API返回错误码: {res_json.get('code')}")
else:
    print(f"HTTP请求失败: {response.status_code}")

针对不同场景的命令修改

只关第二路{"order": {"power2": 0}}
场景联动（全开）{"order": {"power1": 1, "power2": 1}}

5. 高级特性和需要注意的点

5.1 异步反馈机制

接口返回 code:200仅代表指令已送达物联网平台，并不代表开关已实际执行（例如设备当时离线）。对于需要确认结果的场景，需监听平台的消息推送服务，平台会在设备成功执行后推送执行结果。

5.2 局域网直连与私有化

如果您希望在没有外网的环境下使用，该系列产品支持局域网和私有化部署。在本地网络环境下，您可以绕过云端服务器，直接向局域网内设备的本地IP地址发送HTTP请求，延迟更低且更稳定。

5.3 多设备批量控制

您可以在一次请求中控制多个开关。device 参数支持用逗号分隔传入多个Device ID，order 参数会同时下发给所有指定的设备（前提是它们支持相同的命令格式）。

5.4 错误排查

code 502：请核对Device ID是否正确，或设备是否已被删除。
签名错误：请检查MD5加密后的字符串是否为小写32位，以及时间戳是否为秒级（10位数字）。
设备无响应：检查设备在控制台是否显示“在线”；确认配网时输入的WiFi密码是否正确（仅支持2.4G频段）。

6. 总结

通过芯步提供的开放接口，开发者无需深入了解复杂的嵌入式通信协议，仅需通过标准的HTTP请求即可完成对智能开关路的二次开发。掌握 “双MD5签名生成” 和 “JSON命令构造” 这两个核心点，即可轻松将其集成至企业微信、HomeAssistant、自建管理后台等各类系统中。