如何二次开发8路包间综合管理控制器以实现门禁电磁锁接口控制_解决方案

CATALOG

一、概述

1.1 背景与目标

在KTV、足浴店、酒店式包间等场景中，包间门的智能化管理是提升运营效率和安全性的关键环节。传统电磁锁门禁系统通常独立运行，无法与包厢预定、计时计费、服务呼叫等业务系统联动，导致管理碎片化。

本方案的目标是利用芯步8路包间综合管理控制器（智能通用控制器UNI-KZQ-TY-8）的开放HTTP接口，通过二次开发，将传统电磁锁门禁系统无缝接入现有业务管理平台，实现以下目标：

实现门锁的远程集中控制与实时状态监控
将门禁权限与包厢预定/计费系统深度绑定
支持多包间（最多8路）的独立并行控制
保留物理出门开关，确保紧急情况下的安全逃生

1.2 适用产品

产品名称	型号	核心特性
智能通用控制器	UNI-KZQ-TY-8	8路独立继电器输出，每路最大负载2200W（阻性），支持HTTP API控制
智能墙壁出门开关	-	86型面板，支持断电开锁/通电上锁模式切换
电磁锁/电插锁	第三方配套	根据门型选择，选用DC12V供电型号

二、系统设计

2.1 整体架构

┌─────────────────────────────────────────────────────────────────┐
│                        业务应用层                                │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐          │
│  │ 收银/POS │ │ 预定系统 │ │ 计时系统 │ │ 小程序   │          │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘          │
│       └────────────┴────────────┴────────────┘                  │
│                          │                                      │
│                    HTTP API 调用                                │
│                          ▼                                      │
├─────────────────────────────────────────────────────────────────┤
│                        二次开发层                                │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              门禁管理中间件 (自研)                        │   │
│  │  • 签名生成服务  • 设备状态缓存  • 命令队列  • 日志审计   │   │
│  └─────────────────────────────────────────────────────────┘   │
│                          │                                      │
│                    HTTP/HTTPS                                   │
│                          ▼                                      │
├─────────────────────────────────────────────────────────────────┤
│                        设备控制层                                │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │         芯步开放平台 API                              │   │
│  │   https://api.thingboot.com/{AppID}/device/control/        │   │
│  └─────────────────────────────────────────────────────────┘   │
│                          │                                      │
│                    WiFi 2.4GHz                                  │
│                          ▼                                      │
├─────────────────────────────────────────────────────────────────┤
│                        硬件设备层                                │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │           8路智能通用控制器 (UNI-KZQ-TY-8)               │   │
│  │  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │   │
│  │  │继电器1│ │继电器2│ │继电器3│ │ ...  │ │继电器7│ │继电器8│ │   │
│  │  └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ │   │
│  └─────┼────────┼────────┼────────┼────────┼────────┼───────┘   │
│        ▼        ▼        ▼        ▼        ▼        ▼           │
│    电磁锁1   电磁锁2   电磁锁3   ...     电磁锁7   电磁锁8        │
│        ▲        ▲        ▲                  ▲        ▲           │
│        └────────┴────────┴──────────────────┴────────┘           │
│                    出门开关 (常开型，并联接入)                      │
└─────────────────────────────────────────────────────────────────┘

2.2 控制逻辑说明

控制器继电器采用常开（NO）触点与电磁锁串联的接线方式：

开锁：继电器断开 → 电磁锁断电 → 磁力消失 → 门可开启
闭锁：继电器吸合 → 电磁锁通电 → 磁力吸合 → 门锁闭

出门开关并联在继电器输出端，按下时相当于短接继电器触点，为电磁锁临时断电，实现本地开门。

三、接口对接技术方案

3.1 接口认证机制

芯步开放平台采用双重MD5签名的认证方式，每个请求需携带sign和ts参数。

签名生成算法

完整Shell脚本示例

3.2 核心接口命令

根据芯步8路控制器产品手册，支持以下核心命令

命令格式	功能说明	应用场景
`{"power1":1}`	第1路继电器吸合	电磁锁通电闭门
`{"power1":0}`	第1路继电器断开	电磁锁断电开门
`{"power1":1,"power2":0}`	批量控制多路	同时控制多个包间
`{"reset1":5000}`	第1路先断后通，延时5秒	临时开门（客人外出）
`{"point1":3000}`	第1路先通后断，延时3秒	点动控制场景

各语言调用示例

Java (OkHttp)

PHP

3.3 私有化部署支持

芯步产品支持纯局域网环境运行，无需连接公网。部署方式：

设备配置固定IP，与业务服务器处于同一网段
自建消息服务器接收设备状态推送
API请求地址切换为设备局域网IP

四、电磁锁接入方案

4.1 接线原理图

┌─────────────────────────────────────────────────────┐
│                 8路智能控制器                        │
│  ┌─────────┐                                       │
│  │  DC12V  │──┐                                    │
│  │  电源   │  │                                    │
│  └─────────┘  │                                    │
│               │                                    │
│  ┌─────────┐  │     ┌──────────────┐              │
│  │ 继电器1 │  │     │   电磁锁     │              │
│  │   COM   │──┼─────┤    (红)      │              │
│  │   NO    │──┼─────┤    (黑)      │              │
│  └─────────┘  │     └──────────────┘              │
│               │                                    │
│         ┌─────┴─────┐                              │
│         │ 出门开关   │  (并联在电磁锁两端)           │
│         └───────────┘                              │
└─────────────────────────────────────────────────────┘

4.2 工作模式选择

控制器继电器可配置两种工作模式

模式	控制器状态	电磁锁状态	适用场景
通电上锁	继电器吸合 → 通电	锁闭	常闭场景（包间无人时锁门）
通电开锁	继电器吸合 → 通电	开启	常开场景（如消防通道）

包间门禁推荐使用「通电上锁」模式：正常情况下继电器吸合保持锁闭；断电时自动开锁，符合消防安规。

4.3 出门开关配置

智能墙壁出门开关同样支持HTTP API控制

将出门开关设置为点动模式，配合reset命令实现：按下 → 开锁5秒 → 自动闭锁。客人按一次开关即可开门，5秒后门自动锁闭，无需再次刷卡。

五、二次开发核心功能实现

5.1 开锁/关锁功能

# Python伪代码示例
class DoorController:
    def __init__(self, app_id, app_secret, device_id):
        self.app_id = app_id
        self.app_secret = app_secret
        self.device_id = device_id
    
    def _generate_sign(self):
        ts = int(time.time())
        step1 = hashlib.md5(self.app_secret.encode()).hexdigest()
        sign = hashlib.md5(f"{step1}{ts}".encode()).hexdigest()
        return sign, ts
    
    def unlock(self, channel=1, duration=5000):
        """开门（断电开锁），duration毫秒后自动闭锁"""
        sign, ts = self._generate_sign()
        url = f"https://api.thingboot.com/{self.app_id}/device/control/"
        data = {
            "device": self.device_id,
            "order": {f"reset{channel}": duration}
        }
        response = requests.post(url, params={"sign": sign, "ts": ts}, json=data)
        return response.status_code == 200
    
    def lock(self, channel=1):
        """立即闭锁"""
        sign, ts = self._generate_sign()
        data = {"device": self.device_id, "order": {f"power{channel}": 1}}
        # ... 发送请求

5.2 业务系统集成示例

场景：包厢预订系统自动授权

5.3 安全机制设计

安全层级	实现的方式是	说明
接口签名	双向MD5加密	防止请求被篡改和重放攻击
设备隔离	每个设备独立device_id	权限细分到单个控制器
操作审计	记录所有API调用日志	追溯门禁操作记录
应急通道	物理出门开关直连	断电自动开锁，符合消防规范
心跳监控	定时查询设备状态	及时发现设备离线异常

六、实施步骤清单

硬件准备
- 购买8路智能通用控制器（UNI-KZQ-TY-8）
- 根据门型选购电磁锁/电插锁（DC12V）
- 购买智能墙壁出门开关（86型）
平台对接
- 注册芯步开放平台账号
- 在控制台获取AppID和AppSecret
- 添加设备，获取device_id
接线安装
- 控制器安装至弱电箱/机柜
- 参照接线图连接电磁锁和出门开关
- 通电测试本地控制功能
二次开发
- 实现签名生成中间件
- 封装门禁控制API
- 集成到现有业务系统
测试验证
- 单路控制功能测试
- 多路并发压测
- 断网/断电故障模拟
- 消防联动测试

七、注意事项

电磁锁选型：芯步不生产电磁锁，需自行采购。选购时确认工作电压与控制器输出匹配（DC12V），并注意电磁锁的吸力规格（通常包间门选用280kg或350kg级）
继电器触点容量：控制器每路最大负载2200W（阻性）/350W（感性），电磁锁功耗通常为3-5W，完全满足需求。如需控制大功率设备，应通过接触器扩展
消防规范：请一定要采用「通电上锁」模式，确保断电时自动开锁。出门开关保留物理直连通道，不依赖网络控制
网络要求：控制器仅支持2.4GHz WiFi，部署时需确保信号覆盖
并发控制：8路控制器支持各通道独立控制，多包间同时操作无相互影响

通过以上方案，开发者可在一周内完成从硬件接线到软件集成的全流程开发，实现包间门禁的智能化管理。如需进一步的技术支持，可联系芯步工程师获取全程指导。