怎么二次开发触摸式出门控制开关以实现门禁设备联动控制_解决方案

CATALOG

芯步的智能触摸墙壁出门开关（型号：UNI-KG-CM-C）是一款专为门禁联动场景设计的智能设备。它采用标准86型底盒安装，支持两路独立控制，可通过HTTP接口实现远程门锁控制，广泛应用于办公室、公寓、酒店等场景的门禁二次开发。

一、解决概述

传统出门开关只能实现本地按键开门，缺乏与门禁系统的联动能力——刷卡开门后无法记录，远程无法管控，异常开门也无法告警。

本方案利用芯步智能触摸墙壁出门开关的HTTP接口能力和消息推送机制，将出门开关与门禁管理系统无缝对接，实现：

本地按键+远程控制双模式：既保留传统出门按键功能，又支持远程开锁
开门事件实时上报：有人按下出门开关时，系统实时收到通知并记录
设备状态监控：实时掌握开关在线/离线状态
灵活扩展：可与门磁、人脸识别等设备联动，构建完整门禁系统

二、核心技术能力分析

2.1 产品规格

智能触摸墙壁出门开关的核心参数如下

类别	特性说明
产品型号	UNI-KG-CM-C（左灯右门版）/ UNI-KG-CM-KC（左门右灯版）
控制路数	2路独立输出
按钮配置	第1按钮：短按状态反转（默认，可配置）；第2按钮：短按先断开、5秒后接通（默认）
工作电压	100-250V AC（交流/市电）
单路负载	MAX 1000W（如接LED/节能灯等感性负载，需小于300W）
待机功耗	0.4W（全断）- 1.3W（全通/无负载）
产品尺寸	宽：86mm；长：86mm；厚：41mm
安装方式	标准86型底盒安装，直接平行替换原有出门开关
外壳材质	防火V0级PC，耐高温，符合安规标准
无线连接	WiFi 2.4GHz IEEE 802.11 b/g/n，无需网关
控制协议	开放标准HTTP接口，任何编程语言均可对接
配套门锁	支持所有类型的电磁锁、电插锁（可到三方购买）

2.2 支持命令表

根据芯步接口规范，出门开关支持以下核心命令

命令类型	JSON格式示例	功能说明
开锁/关锁	`{"power":"1"}` 或 `{"power":"0"}`	门锁控制（1=开锁，0=关锁）
先断后通（复位）	`{"reset":"3000"}`	断开后3秒自动接通（用于门禁延时）
先通后断（点动）	`{"point":"3000"}`	接通后3秒自动断开（电磁锁点动开锁）

⚠️ 重要说明：门锁控制需根据锁的类型选择命令。断电开锁型锁（如磁力锁）用{"power":"0"}开锁；断电上锁型锁用{"power":"1"}开锁。point和reset命令的数值单位为毫秒（ms）。

2.3 消息推送机制：实现开门事件上报

芯步设备支持将状态变化实时推送到开发者服务器。通过配置消息推送，当有人按下出门开关时，系统可立即获知开锁事件。

设备状态上报消息格式（设备状态变化时触发）：

设备上下线消息（设备网络状态变化时触发）

reason字段含义

normal：设备正常退出
timeout：设备断网或断电（延迟约10秒检测），可用于判断门禁开关供电异常
closed：设备主动关闭连接

2.4 API鉴权与请求格式

芯步API采用动态签名验证机制

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

签名算法:
md5_secret = md5(AppSecret)
sign = md5(md5_secret + ts)

参数说明:
- AppId:应用ID，在控制台获取
- AppSecret:应用密钥，在控制台获取
- ts:当前Unix时间戳（秒）

请求Body示例

三、门禁联动二次开发方案

3.1 整体架构

┌─────────────────────────────────────────────────────────────────┐
│                        门禁现场                                  │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │        智能触摸墙壁出门开关（86型壁挂/门边安装）          │   │
│  │  ┌─────────────┐    ┌─────────────┐                    │   │
│  │  │   按钮1     │    │   按钮2     │                    │   │
│  │  │  （开门）   │    │  （报警）   │                    │   │
│  │  └──────┬──────┘    └──────┬──────┘                    │   │
│  │         │                  │                            │   │
│  │         ▼                  ▼                            │   │
│  │     继电器1             继电器2                         │   │
│  │         │                  │                            │   │
│  └─────────┼──────────────────┼────────────────────────────┘   │
│            │                  │                                 │
│            ▼                  ▼                                 │
│        电磁锁              报警器                               │
│                                                                 │
│  网络:2.4G WiFi                                                │
└─────────────────────────────────────────────────────────────────┘
                                       │
                                       │ WiFi / HTTP API / MQTT
                                       ▼
┌─────────────────────────────────────────────────────────────────┐
│                    门禁管理系统（开发者服务器）                   │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                    事件接收模块                          │   │
│  │  - 接收state消息 → 记录开门事件、更新门状态              │   │
│  │  - 接收disconnect消息 → 标记设备离线                    │   │
│  └─────────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                    远程控制模块                          │   │
│  │  - 远程开锁/关锁                                        │   │
│  │  - 定时开锁                                             │   │
│  │  - 批量门禁管理                                         │   │
│  └─────────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                    联动告警模块                          │   │
│  │  - 异常开门告警（非工作时间）                           │   │
│  │  - 设备离线告警                                         │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────┐
│                       前端展示                                   │
│  - 管理后台:门禁监控面板、开门记录查询                         │
│  - 小程序/APP:远程开门                                         │
└─────────────────────────────────────────────────────────────────┘

3.2 硬件安装与接线

步骤1：替换原有出门开关

断电操作，拆卸原有86型出门开关
安装智能触摸墙壁出门开关于86底盒
接入AC 220V电源线（火线L、零线N）

步骤2：门锁接线

将电磁锁/电插锁的控制线接入开关的继电器输出端
注意区分锁的类型：
- 断电开锁型（如磁力锁）：通电时门锁上，断电时门打开。需要开锁时，通过命令让继电器断开。
- 断电上锁型（如电插锁）：通电时门打开，断电时门上锁。需要开锁时，通过命令让继电器接通。
具体接线方式参考锁具说明书

步骤3：网络配置

确保开关安装位置WiFi信号覆盖（仅支持2.4G频段）
长按第1按钮6秒进入配网模式
通过芯步控制台为开关配网

步骤4：获取凭证

登录
获取 AppId 和 AppSecret
记录开关的设备ID

步骤5：配置消息推送

在控制台「消息推送」中设置回调URL
选择接收方式（HTTP或MQTT）
保存配置，设备状态变化将实时推送

3.3 代码集成示例

以下提供Python、Java、微信小程序后端三种语言的完整对接示例。

Python实现（推荐用于后端服务）

import hashlib
import time
import requests
import json
from typing import Dict, Optional, List
from flask import Flask, request, jsonify

app = Flask(__name__)

class ExitSwitchController:
    """出门开关控制器类"""
    
    def __init__(self, app_id: str, app_secret: str):
        self.app_id = app_id
        self.app_secret = app_secret
        self.api_base = "https://api.thingboot.com"
    
    def _generate_sign(self, ts: int) -> str:
        """生成API签名"""
        md5_secret = hashlib.md5(self.app_secret.encode()).hexdigest()
        sign_str = md5_secret + str(ts)
        return hashlib.md5(sign_str.encode()).hexdigest()
    
    def _send_command(self, device_id: str, order: Dict) -> Optional[Dict]:
        """发送控制命令"""
        ts = int(time.time())
        sign = self._generate_sign(ts)
        url = f"{self.api_base}/{self.app_id}/device/control/?sign={sign}&ts={ts}"
        
        payload = {"device": device_id, "order": order}
        try:
            response = requests.post(url, json=payload, timeout=5)
            return response.json()
        except Exception as e:
            print(f"命令发送失败: {e}")
            return None
    
    # ========== 远程开锁/关锁 ==========
    def unlock(self, device_id: str, lock_type: str = "断电开锁") -> Optional[Dict]:
        """
        远程开锁
        :param device_id: 设备ID
        :param lock_type: 锁类型（断电开锁/断电上锁）
        """
        if lock_type == "断电开锁":
            # 磁力锁类:断电即开锁
            return self._send_command(device_id, {"power": "0"})
        else:
            # 电插锁类:通电即开锁
            return self._send_command(device_id, {"power": "1"})
    
    def lock(self, device_id: str, lock_type: str = "断电开锁") -> Optional[Dict]:
        """远程上锁"""
        if lock_type == "断电开锁":
            # 磁力锁类:通电即上锁
            return self._send_command(device_id, {"power": "1"})
        else:
            # 电插锁类:断电即上锁
            return self._send_command(device_id, {"power": "0"})
    
    def point_unlock(self, device_id: str, hold_ms: int = 3000) -> Optional[Dict]:
        """
        点动开锁:开锁后延时自动上锁（电磁锁专用）
        :param device_id: 设备ID
        :param hold_ms: 开锁持续时间（毫秒），默认3秒
        """
        return self._send_command(device_id, {"point": str(hold_ms)})
    
    def reset_lock(self, device_id: str, delay_ms: int = 3000) -> Optional[Dict]:
        """
        复位开锁:先断后通（用于特殊门禁逻辑）
        :param device_id: 设备ID
        :param delay_ms: 断开持续时间（毫秒）
        """
        return self._send_command(device_id, {"reset": str(delay_ms)})
    
    def get_status(self, device_id: str) -> Optional[Dict]:
        """查询设备状态"""
        return self._send_command(device_id, {"status": "1"})

# ========== 消息推送接收接口（开门事件上报）==========
@app.route('/api/door/callback', methods=['POST'])
def door_callback():
    """
    接收出门开关状态推送
    当有人按下开门按钮时，会收到state消息
    """
    data = request.get_json()
    device_id = data.get('device')
    msg_type = data.get('type')
    
    if msg_type == 'state':
        # 开门事件:设备状态变化
        message = data.get('message', {})
        state_data = message.get('data', [])
        
        for item in state_data:
            if 'power' in item:
                power_status = item['power']  # "1"或"0"
                timestamp = message.get('ts')
                
                # 判断是开门还是关门事件（根据锁类型判断逻辑）
                # 记录开门事件到数据库
                record_door_event(device_id, power_status, timestamp)
                
                # 非工作时间开门告警（示例:22:00-06:00）
                if is_abnormal_time():
                    send_alert(f"门禁异常:设备{device_id}在非工作时段被打开")
        
        return jsonify({"code": 0})
    
    elif msg_type == 'connect':
        # 设备上线
        print(f"门禁设备 {device_id} 已上线")
        update_device_status(device_id, "online")
        return jsonify({"code": 0})
    
    elif msg_type == 'disconnect':
        # 设备下线
        message = data.get('message', {})
        reason = message.get('reason')
        print(f"门禁设备 {device_id} 已下线，原因: {reason}")
        
        if reason == 'timeout':
            # 断网或断电，触发告警
            send_alert(f"门禁设备 {device_id} 可能断电或断网")
        
        update_device_status(device_id, "offline", reason)
        return jsonify({"code": 0})
    
    return jsonify({"code": 0})

# ========== 辅助函数 ==========
def record_door_event(device_id: str, status: str, timestamp: str):
    """记录开门事件到数据库"""
    # TODO: 实现数据库记录逻辑
    print(f"[记录] 设备{device_id}状态变更为{status}，时间{timestamp}")

def is_abnormal_time() -> bool:
    """判断是否为非工作时间（示例）"""
    import datetime
    now = datetime.datetime.now()
    hour = now.hour
    return hour < 6 or hour > 22  # 22:00-06:00为异常时段

def send_alert(message: str):
    """发送告警通知"""
    # TODO: 集成钉钉/企业微信/邮件通知
    print(f"[告警] {message}")

def update_device_status(device_id: str, status: str, reason: str = None):
    """更新设备状态"""
    # TODO: 更新数据库中的设备状态
    pass

# ========== 远程开门API接口 ==========
@app.route('/api/door/unlock', methods=['POST'])
def remote_unlock():
    """远程开门接口（供小程序/APP调用）"""
    data = request.get_json()
    device_id = data.get('device_id')
    lock_type = data.get('lock_type', '断电开锁')
    hold_ms = data.get('hold_ms', 3000)  # 点动持续时间
    
    controller = ExitSwitchController("YOUR_APP_ID", "YOUR_APP_SECRET")
    
    if lock_type == "电磁锁":
        # 电磁锁使用点动模式（开锁后自动上锁）
        result = controller.point_unlock(device_id, hold_ms)
    else:
        # 其他锁类型
        result = controller.unlock(device_id, lock_type)
    
    # 记录远程开门日志
    record_remote_unlock(device_id, data.get('operator', 'unknown'))
    
    return jsonify({"code": 200 if result else 500, "message": "开锁指令已发送"})

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

Java实现

import okhttp3.*;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

public class ExitSwitchController {
    private final String appId;
    private final String appSecret;
    private final OkHttpClient client;
    private static final String API_BASE = "https://api.thingboot.com";
    
    public ExitSwitchController(String appId, String appSecret) {
        this.appId = appId;
        this.appSecret = appSecret;
        this.client = new OkHttpClient();
    }
    
    private String md5(String input) {
        try {
            MessageDigest md = MessageDigest.getInstance("MD5");
            byte[] digest = md.digest(input.getBytes());
            StringBuilder sb = new StringBuilder();
            for (byte b : digest) {
                sb.append(String.format("x", b));
            }
            return sb.toString();
        } catch (NoSuchAlgorithmException e) {
            throw new RuntimeException(e);
        }
    }
    
    private String sendCommand(String deviceId, String orderJson) throws IOException {
        long ts = System.currentTimeMillis() / 1000;
        String md5Secret = md5(appSecret);
        String sign = md5(md5Secret + ts);
        String url = API_BASE + "/" + appId + "/device/control/?sign=" + sign + "&ts=" + ts;
        
        String bodyJson = "{\"device\":\"" + deviceId + "\",\"order\":" + orderJson + "}";
        RequestBody body = RequestBody.create(bodyJson, MediaType.parse("application/json"));
        
        Request request = new Request.Builder()
                .url(url)
                .post(body)
                .build();
        
        try (Response response = client.newCall(request).execute()) {
            return response.body() != null ? response.body().string() : null;
        }
    }
    
    // 点动开锁（电磁锁专用）
    public void pointUnlock(String deviceId, int holdMs) throws IOException {
        sendCommand(deviceId, "{\"point\":\"" + holdMs + "\"}");
    }
    
    // 远程开锁（根据锁类型）
    public void unlock(String deviceId, String lockType) throws IOException {
        if ("断电开锁".equals(lockType)) {
            sendCommand(deviceId, "{\"power\":\"0\"}");
        } else {
            sendCommand(deviceId, "{\"power\":\"1\"}");
        }
    }
}

微信小程序调用示例

四、典型应用场景

4.1 办公室门禁联动

场景：员工刷卡/人脸识别通过门禁后，系统自动记录开门日志，同时远程打开办公室大门。

4.2 异常开门告警联动

场景：非工作时间有人按下出门开关时，系统自动触发告警并记录。

4.3 设备离线监控

场景：收到disconnect消息且reason为timeout时，说明门禁开关可能断电或断网，立即通知运维人员。

4.4 远程批量管理（多门禁）

芯步API支持同时向多个设备下发命令，设备ID用逗号分隔：

五、集成步骤

步骤一：硬件采购与安装

采购芯步智能触摸墙壁出门开关（根据场景选择左灯右门或左门右灯版本）
由电工在门口安装，替换原有出门开关
接入门锁、门磁等外设

步骤二：平台配置

登录
获取 AppId 和 AppSecret（在开发设置中获取）
为开关配网，记录设备ID
配置消息推送地址（接收开门事件）

步骤三：后端集成

将上述ExitSwitchController类集成到门禁管理系统中
实现开门事件接收与记录
配置异常告警规则

步骤四：前端接入

在管理后台接入门禁控制面板
可选：为员工App/小程序提供远程开门功能

六、总结

优势	说明
本地+远程双控	既保留传统出门按键功能，又支持远程开锁，双重保障
开门事件实时上报	通过消息推送机制，有人按下出门开关时系统实时获知并记录
设备状态监控	上/下线消息实时反映网络状态，`timeout`原因快速定位断网/断电
HTTP开放接口	任何编程语言均可对接，10分钟完成基础集成
点动开锁命令	`point`命令精确控制开锁时长（最长5秒），避免电磁锁长时间通电
标准86型安装	直接替换原有出门开关，无需改造墙体
私有化部署	支持纯局域网运行，满足内网安全要求

七、注意事项

锁类型匹配 ⚠️：接线前必须确认锁的类型（断电开锁/断电上锁），否则命令会相反
电磁锁点动：电磁锁使用point命令控制开锁时长，设置3000ms（3秒）
WiFi信号：确保开关安装位置WiFi信号良好（仅支持2.4G频段）
API响应说明：返回code:200仅表示平台接收指令，不代表设备执行成功
专业安装：涉及强电操作，必须由持证电工按照安全规范安装
消息推送配置：如需接收开门事件，必须在控制台配置消息推送地址

通过以上方案，你可以快速将芯步智能触摸墙壁出门开关集成到门禁管理系统中，实现远程开锁、开门事件记录、异常告警等核心功能。如有疑问，可访问获取详细产品手册和技术支持。