怎么二次开发3路2灯1控复合开关来实现触摸按键控制照明门禁_解决方案

CATALOG

芯步的复合开关（型号UNI-KG-KKC）将照明控制与门禁驱动集成在单一86面板中，通过HTTP接口可同时管理两路照明和一路门禁。以下方案涵盖硬件选型、API对接、触摸事件回调到业务逻辑实现的完整链路。

一、解决概述

在许多办公空间或智能化宿舍的改造中，往往需要实现“一键离开”或“门禁联动照明”的场景。利用芯步的 智能墙壁复合开关，可以通过二次开发，将物理触摸按键的逻辑重写或增强。

本方案的目标是：通过调用芯步开放平台 HTTP API，监听并控制该复合开关，实现“触摸/点击门禁按键时，先自动关闭照明，再触发门禁电磁锁”的联动逻辑。

二、硬件选型与解析

本方案推荐使用 芯步智能墙壁复合开关 [左2灯右门] （型号：UNI-KG-KKC）。该设备的端口逻辑划分如下

左侧按键 (线路1/2)：控制照明或常规电器（常见的3路中的2路）。
右侧按键 (线路3/门禁)：专门设计用于控制门禁（如电插锁、电磁锁）。
核心优势：设备支持 WiFi 2.4G 直连，无需额外网关；开放 HTTP API 接口，支持远程控制和状态获取。

注意：如果是通用3路开关，需确认第三路是否支持门禁所需的“点动”（即通电几秒后自动断电）功能，否则外接电磁锁可能会烧毁线圈，优先使用门禁专用版。

三、二次开发环境准备

在进行代码开发前，需要完成以下基础配置：

注册开发者账号：登录芯步官网，进入控制台获取 AppID 和 AppSecret。
设备配网：将复合开关接通电源，按照产品手册将其配置连接到互联网（WiFi）。
获取设备ID：在控制台获取该开关的唯一标识 Device ID。
接口鉴权规则芯步的API签名规则较为独特，具体如下
- 步骤1：计算 md5_secret = md5(AppSecret)
- 步骤2：拼接字符串 tmp = md5_secret + ts（ts为Unix时间戳秒）
- 步骤3：计算最终签名 sign = md5(tmp)
*注：即最终的Sign = md5( md5(密钥) + 时间戳)*

四、接口调用与业务逻辑实现

为了实现“触摸门禁按键时联动关灯”，我们不能仅仅依靠简单的云端规则引擎，因为涉及到“触发源”的判断。架构如下：

物理层：用户按下开关。
感知层：设备上报事件到平台（Webhook/回调）。
控制层：您的服务器接收事件，执行逻辑判断，下发控制指令。

1. 接收物理按键事件

芯步支持通过 消息订阅 或 自建消息服务器 接收设备上行消息。当用户触摸开关的物理按键时，设备会向您的服务器推送事件。

上行数据示例（推测/参考结构）：

2. 联动控制代码实现

业务逻辑：当接收到的 channel 为 3（门禁键）时，程序自动向设备下发“关闭线路1”、“关闭线路2”、“启动门禁（点动）”的命令。

以下是利用Python实现的业务逻辑代码，包含完整的签名生成与命令下发：

import requests
import hashlib
import time
import json

# --- 配置信息 ---
APP_ID = "你的AppID"
APP_SECRET = "你的AppSecret"
DEVICE_ID = "目标开关的设备ID"

# API 地址模板
API_URL = f"https://api.thingboot.com/{APP_ID}/device/control/"

# --- 辅助函数:生成签名 ---
def generate_sign_and_ts():
    ts = str(int(time.time()))
    # md5(密钥)
    md5_secret = hashlib.md5(APP_SECRET.encode()).hexdigest()
    # md5( md5(密钥) + 时间戳 )
    sign_str = md5_secret + ts
    sign = hashlib.md5(sign_str.encode()).hexdigest()
    return ts, sign

# --- 核心功能:控制设备 ---
def control_device(order_json):
    ts, sign = generate_sign_and_ts()
    params = {
        "sign": sign,
        "ts": ts
    }
    payload = {
        "device": DEVICE_ID,
        "order": order_json
    }
    response = requests.post(API_URL, params=params, json=payload)
    return response.json()

# --- 业务逻辑:门禁联动关灯 ---
def handle_doorbell_touch():
    print("检测到门禁按键被触摸，执行联动逻辑...")
    
    # 1. 关闭两路灯 (命令:power1=0, power2=0)
    # 注意:根据芯步文档，3路开关的命令键值名为 power1, power2, power3[citation:2][citation:3]
    turn_off_lights = {
        "power1": "0",  # 关灯1
        "power2": "0"   # 关灯2
    }
    res1 = control_device(turn_off_lights)
    print(f"关灯指令执行结果: {res1}")
    
    # 2. 触发门禁 (开门)
    # 门禁通常需要"点动":即通电1-2秒后自动断开，防止锁体发热。
    # 使用 point3 命令实现线路3先接通后断开 (interval单位:毫秒)
    open_door = { "point3": "1000" }  # 通电1秒钟开门
    res2 = control_device(open_door)
    print(f"开门指令执行结果: {res2}")
    
    return True

# --- 模拟回调入口 (Webhook 接收)---
# 在实际生产环境中，这部分应由 Web 框架（如 Flask）接收来自云平台的回调。
# 假设接收到的回调数据如下:
received_callback_data = {
    "device": DEVICE_ID,
    "event": "button_click",
    "channel": 3  # 假设 3 代表门禁按键
}

# 执行逻辑
if received_callback_data.get("channel") == 3:
    handle_doorbell_touch()

五、高级功能与拓展应用

除了基本的一键关灯开门，基于该API您可以实现以下更复杂的功能：

防尾随与延时关门如果用户觉得开灯状态下出门不需要关灯，可以使用 reset 命令。
{ "reset3": "5000" } // 门禁线路先断开5秒，再自动接通（常用于反锁逻辑）
状态保持与互锁针对3路复合开关，可以利用 power1 的状态保持功能（配合 keep 参数）。例如，设置门禁开启时，如果灯是亮的，保持灯亮（或者使用 batch 指令进行更复杂的组合控制）。
集成到APP或小程序由于接口是标准的HTTP协议，您可以非常方便的将这段Python代码逻辑移植到微信小程序、Flutter或Vue项目中。用户不仅可以通过物理按键联动，还可以通过手机App界面上的“离家模式”按钮，一键调用同样的API接口关闭所有灯光并锁门。

六、注意事项

门禁负载匹配：请确认购买的开关型号是否支持门禁功能。普通3路开关通常用于照明（阻性负载），直接接电锁（感性负载）可能导致触点粘连。请一定要确认开关支持点动功能或明确标注支持门禁。
网络延时：由于代码逻辑基于“云端回调”，如果互联网断开，物理按键与关灯之间会有短暂延时（约0.5-2秒）。如果需要毫秒级响应，可咨询芯步是否支持 局域网API（LAN模式），在局域网内直连设备IP进行控制。
签名时效：API签名中的 ts 参数通常与服务器时间误差不能太大（一般为5分钟内），否则请求会被拒绝。请确保服务器时间已同步（NTP）。