怎样对接智能触摸墙壁开关3路以实现自定义联动逻辑控制_解决方案

CATALOG

芯步智能触摸墙壁开关3路支持完整的HTTP API接口，你可以通过简单的API调用实现单路控制、场景联动、定时任务等自定义逻辑。以下方案涵盖接口对接流程、核心命令说明以及典型联动场景的代码实现。

一、对接准备与接口鉴权

在开始编码前，你需要准备以下三个核心凭证，这些可以在芯步控制台的“开发设置”中找到：

AppID：应用的唯一标识。
AppSecret：接口调用的密钥，请勿泄露。
设备ID (Device ID)：开关外壳上或控制台显示的ID。

签名计算规则

芯步的开放接口通过 sign 和 ts（时间戳）参数进行防盗用验证。签名生成逻辑如下

二、核心接口：设备控制

所有的自定义联动逻辑，最终都是通过调用 设备控制接口 向开关下发指令来实现的。

请求地址： https://api.thingboot.com/{AppID}/device/control/?sign={sign}&ts={ts}
请求方式： POST
Content-Type： application/json

请求体参数说明

参数	类型	必填	描述
`device`	String	是	目标设备的ID，支持多设备（用逗号分隔）
`order`	JSON Object	是	具体的控制命令，根据你想要实现的功能填入不同的JSON结构

三、针对3路开关的核心命令详解

这款3路开关支持三种主要的控制模式，你可以根据联动需求灵活选用。

1. 基础通断控制

最常规的开关灯操作，直接将某一路设为开启或关闭。

命令对象： power1、power2、power3
取值： "1" (开)， "0" (关)

场景示例： 晚上11点，网关检测到无人移动，联动关闭客厅开关的第2路（射灯）。

2. 临时覆盖模式（脉冲/点动）

常用于排气扇、门禁或暂态照明。设备在开启（或关闭）后，自动延时恢复原状。

先通后断 (point)：立即接通电路，持续N秒后自动断开。适合楼道灯或排气扇。
先断后通 (reset)：立即断开电路，持续N秒后自动接通。适合设备重启场景。

场景示例： 按下门铃按钮或收到“离家模式”指令，联动卫生间第3路（排风扇）开启2分钟后自动关闭。

3. 状态保持（互斥/优先级锁定）

强制锁定开关的物理状态，用户手动操作后会在设定时间内自动恢复。这在酒店客控（插卡取电）或办公场景非常有用。

参数格式： {"keep": "1或0", "revert": "秒数"}

场景示例： 会议室系统检测到“空闲状态”，强制将第1路（投影幕布电源）关闭，并锁定。如果有人手贱按下开关试图打开，将在3秒后再次被系统自动关闭。

四、自定义联动逻辑的代码实现

结合上述接口，假设我们想要实现一个具体的联动场景：“回家模式”。当智能门锁检测到主人回家（或被SaaS平台触发），我们需要同时执行：

开启客厅开关的第1路（主灯）。
开启走廊开关的第3路（氛围灯带），并设置5分钟后自动关闭。

以下分别展示不同技术栈的调用代码，你可以直接复制到后端服务或云函数中运行。

1. Shell + cURL 实现（适合轻量级脚本和快速测试）

利用 curl 命令是最快捷的测试方式。

2. Python 实现（适合Django/FastAPI后端集成）

Python 在处理复杂的业务逻辑时更方便。

import hashlib
import time
import requests

class YoYoSwitch:
    def __init__(self, app_id, app_secret):
        self.app_id = app_id
        self.app_secret = app_secret

def _gen_sign(self, ts):
        # 签名生成逻辑
        md5_secret = hashlib.md5(self.app_secret.encode()).hexdigest()
        combined = md5_secret + str(ts)
        return hashlib.md5(combined.encode()).hexdigest()

def control_device(self, device_id, order_dict):
        ts = int(time.time())
        sign = self._gen_sign(ts)
        url = f"https://api.thingboot.com/{self.app_id}/device/control/?sign={sign}&ts={ts}"
        payload = {
            "device": device_id,
            "order": order_dict
        }
        response = requests.post(url, json=payload)
        return response.json()

# --- 业务逻辑封装:自定义联动场景 ---
def scenario_away_mode(api, device_id):
    """离家模式:关闭所有三路灯光"""
    print("执行离家模式，切断所有电路...")
    return api.control_device(device_id, {"power1": "0", "power2": "0", "power3": "0"})

def scenario_cooking_mode(api, device_id):
    """烹饪模式:抽油烟机（第2路）开启，30分钟后自动关"""
    print("进入烹饪模式，抽油烟机已启动...")
    # point2 支持设定延时关闭，30000毫秒 = 30秒
    return api.control_device(device_id, {"point2": "30000"})

# 使用示例
if __name__ == "__main__":
    switch_api = YoYoSwitch("YOUR_APP_ID", "YOUR_APP_SECRET")
    my_switch_id = "123456789"
    
    # 触发离家模式
    scenario_away_mode(switch_api, my_switch_id)

五、私有化部署与局域网控制

如果你的项目运行在纯内网环境（如工业厂房、学校或涉密单位），芯步的这款设备支持私有化部署。

在此模式下，你可以将消息服务器地址指向自己的服务器，所有的控制指令和状态同步都在局域网内完成，无需互联网连接。此时，你需要将上述代码中的 https://api.thingboot.com 替换为你自建服务器的IP地址。

六、注意事项与最佳实践

执行反馈机制：接口返回 200 仅代表指令下达成功，并不代表设备真的执行了动作。在关键业务场景中，配置消息推送来接收设备执行后的回调确认。
并发控制：如果你同时发送多条指令（如瞬间开关10次），设备侧会按队列处理。对于高频率的联动，在代码中增加 time.sleep 间隔或使用 service 模式。
硬件复位：在编写“全关”逻辑时，注意3路开关支持的总负载功率，避免同时启动大功率设备导致瞬间电流过大。