怎样接入3路触摸墙壁开关以实现3 路独立照明控制_解决方案

CATALOG

1 背景与目标

在智能家居和商业智能照明场景中，实现多路照明电路的独立远程控制是基本需求。芯步推出的智能触摸墙壁开关3路（型号：UNI-KG-3 / UNI-KG-3-TS）采用标准86型底盒设计，可直接平行替换传统墙壁开关，支持通过HTTP API接口对三路线路进行独立控制。本方案的目标是指导开发者快速接入该产品的开放接口，实现三路照明电路的独立远程控制，适用于Web应用、移动端应用、小程序等多种软件形态。

独立控制：三路线路均可单独控制开关状态，互不干扰
灵活部署：支持云端API与局域网控制两种模式，满足不同网络环境需求
快速响应：从命令下发到设备执行仅需80-120ms
状态保持：支持状态保持（锁定）模式，适用于商业场景的定时控制

2 产品概述与接口能力

2.1 产品规格

芯步3路触摸墙壁开关的核心参数如下：

参数项	规格说明
产品型号	UNI-KG-3 / UNI-KG-3-TS
控制路数	3路独立控制
工作电压	100-240V AC
额定电流	10A/路
负载功率	300-1200W/路（LED/节能灯负载<300W/路）
无线连接	WiFi 2.4GHz（IEEE 802.11 b/g/n）
安装方式	标准86型底盒

2.2 接口支持的命令

该设备通过HTTP API接口开放了以下命令，用于控制三路线路的通断状态

命令字段	功能描述	参数说明
`power1`	线路1控制	1=开启，0=关闭
`power2`	线路2控制	1=开启，0=关闭
`power3`	线路3控制	1=开启，0=关闭
`point1/2/3`	先通后断（脉冲）	单位毫秒，如`{"point1":"2000"}`表示通电2秒后自动断电
`reset1/2/3`	先断后通（重启）	单位毫秒，如`{"reset1":"3000"}`表示断电3秒后自动通电
`power1/2/3`（对象）	状态保持/锁定	`{"keep":"1","revert":"3"}`表示锁定开启，用户手动关闭3秒后自动恢复

注point和reset命令常用于需要临时通电的场景，如门禁控制、设备重启等。

3 接入认证与接口调用

芯步的开放接口采用AppID + 动态签名的认证方式，每次请求都需要携带签名参数以防止重放攻击。

3.1 准备工作

在正式调用接口前，需要完成以下准备工作：

注册账号：访问芯步官网（）完成注册
创建工作台：登录后进入控制台，创建新的工作台
获取凭证：在“开发设置”中获取AppID和AppSecret（开发者密码）
添加设备：将3路触摸墙壁开关配网绑定至工作台，获取设备唯一ID（可在外壳或控制台查看）

3.2 签名算法说明

为防止接口被恶意调用，所有请求均需携带签名（sign）和时间戳（ts）。签名计算规则如下

第一步：将AppSecret进行MD5加密，得到secret_md5 = md5(AppSecret)
第二步：将secret_md5与当前时间戳ts拼接，得到temp = secret_md5 + ts
第三步：将temp再次进行MD5加密，得到最终签名：sign = md5(temp)

ts = 当前Unix时间戳（秒）
sign = md5(md5(AppSecret) + ts)

3.3 接口调用示例

3.3.1 请求地址与格式

POST https://api.thingboot.com/{AppId}/device/control/?sign={sign}&ts={ts}
Content-Type: application/json

{AppId}替换为您的应用ID
{sign}替换为计算得到的签名
{ts}替换为当前时间戳（秒）

请求体JSON格式

参数说明：device为设备唯一ID（字符串），order为命令对象

3.3.2 使用curl命令测试

4 三路独立照明控制实现

4.1 基础开关控制

通过向power1、power2、power3字段分别传递1（开）或0（关），可实现三路线路的独立控制。以下是在不同开发环境中的实现方式：

Python实现（Flask示例）

import requests
import hashlib
import time

class YoyoSwitch:
    def __init__(self, app_id, app_secret, device_id):
        self.app_id = app_id
        self.app_secret = app_secret
        self.device_id = device_id
        self.base_url = f"https://api.thingboot.com/{app_id}/device/control/"
    
    def _generate_sign(self):
        ts = int(time.time())
        secret_md5 = hashlib.md5(self.app_secret.encode()).hexdigest()
        sign_str = secret_md5 + str(ts)
        sign = hashlib.md5(sign_str.encode()).hexdigest()
        return ts, sign
    
    def control_channel(self, channel, state):
        """控制单路开关"""
        ts, sign = self._generate_sign()
        url = f"{self.base_url}?sign={sign}&ts={ts}"
        order = {f"power{channel}": 1 if state else 0}
        payload = {"device": self.device_id, "order": order}
        response = requests.post(url, json=payload)
        return response.json()
    
    def control_all(self, states):
        """同时控制三路"""
        ts, sign = self._generate_sign()
        url = f"{self.base_url}?sign={sign}&ts={ts}"
        order = {f"power{i+1}": 1 if states[i] else 0 for i in range(3)}
        payload = {"device": self.device_id, "order": order}
        response = requests.post(url, json=payload)
        return response.json()

# 使用示例
switch = YoyoSwitch("your_app_id", "your_app_secret", "your_device_id")
switch.control_channel(1, True)   # 开启第1路
switch.control_all([True, False, True])  # 第1、3路开，第2路关

JavaScript（Node.js）实现

const crypto = require('crypto');

class YoyoSwitch {
    constructor(appId, appSecret, deviceId) {
        this.appId = appId;
        this.appSecret = appSecret;
        this.deviceId = deviceId;
        this.baseUrl = `https://api.thingboot.com/${appId}/device/control/`;
    }

_generateSign() {
        const ts = Math.floor(Date.now() / 1000);
        const secretMd5 = crypto.createHash('md5').update(this.appSecret).digest('hex');
        const signStr = secretMd5 + ts;
        const sign = crypto.createHash('md5').update(signStr).digest('hex');
        return { ts, sign };
    }

async controlChannel(channel, state) {
        const { ts, sign } = this._generateSign();
        const url = `${this.baseUrl}?sign=${sign}&ts=${ts}`;
        const order = { [`power${channel}`]: state ? 1 : 0 };
        
        const response = await fetch(url, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ device: this.deviceId, order })
        });
        return response.json();
    }
}

微信小程序实现

微信小程序中调用接口时需注意在request合法域名中添加api.thingboot.com

// pages/index/index.js
Page({
  data: {
    channel1: false,
    channel2: false,
    channel3: false
  },
  
  // 控制单路开关
  toggleChannel(e) {
    const channel = e.currentTarget.dataset.channel;
    const currentState = this.data[`channel${channel}`];
    const newState = !currentState;
    
    this.controlSwitch(channel, newState);
    this.setData({ [`channel${channel}`]: newState });
  },
  
  controlSwitch(channel, state) {
    const ts = Math.floor(Date.now()  / 1000);
    // 签名计算逻辑（需与服务端配合或在前端实现md5）
    const sign = this.calculateSign(ts);
    
    wx.request({
      url: `https://api.thingboot.com/${appId}/device/control/`,
      method: 'POST',
      data: {
        device: deviceId,
        order: { [`power${channel}`]: state ? 1 : 0 }
      },
      dataType: 'json',
      success: (res) => {
        console.log('控制成功', res);
      },
      fail: (err) => {
        console.error('控制失败', err);
        // 回滚UI状态
        this.setData({ [`channel${channel}`]: !state });
      }
    });
  }
})

4.2 高级控制模式

4.2.1 状态保持（锁定）模式

在共享空间场景中，可能需要保持照明在特定状态：即使顾客手动操作开关，若干秒后设备会自动恢复到预设状态。通过向power1/power2/power3传递对象参数实现

keep：1=锁定开启，0=锁定关闭
revert：自动恢复时间（秒）

此模式适用于自习室计时收费、棋牌室包间等场景：用户扫码后自动开灯并锁定，时间结束后自动恢复

4.2.2 脉冲模式

脉冲模式适用于需要临时通电的场景，如门禁控制或设备重启：

命令格式为{"point1":"2000"}，其中point表示先通后断，reset表示先断后通，数值为脉冲持续时间（毫秒）。

5 典型应用场景配置

5.1 智慧会议室

在会议室场景中，三路线路可分别接入主照明、投影区照明和氛围灯带，通过中控系统实现一键场景切换：

会议模式：主照明开（power1=1），投影区关（power2=0），氛围灯开（power3=1）
投影模式：主照关闭（power1=0），投影区关闭（power2=0），氛围灯调暗（power3=1）
清洁模式：三路全开（power1-3=1），便于保洁人员操作

5.2 共享自习室

在共享自习室中，三路线路分别控制不同区域或座位的照明，结合状态保持模式实现计时收费控制：

5.3 智能家居联动

通过定时任务或传感器联动实现自动化控制：

触发条件	执行动作	说明
日落（18:00）	power1=1	开启客厅主灯
夜间23:00后	power2=0	自动关闭阳台照明
离家模式	power1=0, power2=0, power3=0	全屋关灯
回家模式	power1=1	开启玄关照明

6 注意事项

6.1 网络环境要求

设备仅支持2.4GHz WiFi，不支持5GHz频段
若需纯局域网控制，可联系芯步技术支持获取私有化部署方案

6.2 签名时效性

签名中的时间戳ts为秒级Unix时间戳，在请求生成时实时计算
时间戳与服务器时间偏差过大会导致签名验证失败，请确保设备时间同步

6.3 LED负载特殊说明

当负载为LED灯或节能灯时，单路功率小于300W，因为LED灯启动时会产生较大浪涌电流，可能触发设备保护

6.4 并发控制

对同一设备连续下发命令时，间隔不少于200ms，确保设备有足够时间响应
如需批量控制多个设备，可在device参数中用逗号分隔多个设备ID

总结

芯步3路触摸墙壁开关通过开放HTTP API接口，为开发者提供了简洁、高效的三路独立照明控制能力。本方案介绍了从账号注册、设备配网到接口调用的完整流程，并提供了基础开关控制、状态保持和脉冲模式等多种控制方式的代码示例。开发者可参考本方案快速完成照明控制功能的集成，应用于智能会议室、共享自习室、智能家居等场景。接口响应迅速（80-120ms），支持多语言开发（Python/JavaScript/PHP/Shell等），且提供局域网私有化部署选项，能够满足不同规模项目的需求。