怎样对接8路包间设备控制模块以实现门禁电磁锁接口控制_解决方案

CATALOG

针对无人值守包间（如共享棋牌室、茶室、影音房）的门禁管理需求，利用 UNI-KZQ-BJ-MAX 包间控制器自带的第七路（GPIO 7）门禁专用接口，配合其标准化的 HTTP API，可以实现高效、稳定的远程电磁锁控制。

以下方案详细说明了对接过程中的硬件确认、接口签名逻辑、核心指令下发及完整的业务流程逻辑。

1. 对接准备与硬件确认

在开始开发前，请确认您的硬件设备满足以下条件：

设备选型：确认使用的是 芯步智能包间控制器 Max 或标准版。这两款设备均明确标识了第七路（GPIO 7）为门禁电磁锁接口。
锁具匹配
- 该接口为 10A 继电器输出。
- 理论上兼容 100% 的直流电磁锁和电插锁。您只需根据锁具的工作电压（DC 12V 或 24V）接入对应电源即可，控制器本身仅作为开关，不输出驱动电压。
环境配置
- 确保控制器已连接 WiFi（2.4GHz）并在线。
- 在芯步后台获取 AppID 和 AppSecret，并将设备 ID 添加到您的应用账户下。

2. 接口对接核心逻辑

芯步的开放接口采用标准的 HTTP POST 请求，数据格式为 JSON。所有对接的关键在于动态签名的生成。

2.1 签名算法（Python 示例）

为了防止接口被篡改，每次请求都需要携带签名 sign 和时间戳 ts。算法规则为：Sign = md5( md5(AppSecret) + ts )。

2.2 请求地址与 Headers

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

3. 电磁锁控制指令详解

针对“开门”这一动作，本质是控制继电器瞬间断开。电磁锁通常为“通电上锁，断电开锁”。因此，开门流程是：临时关闭第7路电源 -> 延时 -> 恢复供电（自动布防）。

你需要关注 order 字段中的以下三种指令模式：

3.1 模式一：即时开关

场景：手动强制解锁或紧急情况。
命令：直接设置第7路状态。
JSON结构
{ "device": "设备ID", "order": {"power7": 0} // 0:断电（开门）；1:通电（锁门） }
解析：发送 {"power7":0} 后，门会立即打开并不再自动锁闭，直到收到 {"power7":1}。不太适合无人值守全自动场景，容易忘关。

3.2 模式二：定时脉冲（推荐标准开门）

场景：用户扫码支付后，自动开门 5秒钟 然后自动吸合。
命令：使用 reset（先断后通）。
JSON结构
{ "device": "设备ID", "order": {"reset7": 5000} // 单位:毫秒 }
解析：该指令会让第7路线路先断开（门开），保持 5000 毫秒后自动重新接通（门锁吸合）。这是最符合“开门-过人-自动关”逻辑的命令。

3.3 模式三：联动语音播报（TTS版专用）

场景：开门时同时让包间内喇叭播报提醒（如：“欢迎光临，XX号房间，电源已接通”）。
命令：复合命令。
JSON结构
{ "device": "设备ID", "order": { "play:gbk:16": "欢迎光临，门锁已开启，请注意安全", "reset7": 8000 } }
解析：利用 order 支持多指令的特性，一次性发送播报和动作指令。

4. 对接流程图：从用户下单到开门

在实际的包间管理系统中（如共享棋牌室小程序），对接流程如下：

sequenceDiagram
    participant User as 手机用户
    participant SaaS as 您的业务系统/小程序
    participant Yoyo as 芯步云API
    participant Device as 包间控制器(第7路)
    participant Lock as 电磁锁

    User->>SaaS: 1. 下单/点击"开门"
    SaaS->>SaaS: 2. 校验订单状态(是否已支付/已到时间)
    SaaS->>Yoyo: 3. POST请求 /control/ (携带签名&ts) 
 {"device":"xxx", "order":{"reset7":6000}}
    Yoyo->>Device: 4. 推送指令(MQTT/HTTP)
    Device->>Lock: 5. 第7路继电器断开(电磁铁失电)
    Lock-->>Device: 6. 锁舌收回(开门)
    Note over Lock: 延时6秒
    Device->>Lock: 7. 第7路继电器闭合(电磁铁得电)
    Lock-->>Device: 8. 锁舌弹出(闭锁/可关门状态)
    Device->>Yoyo: 9. 返回执行结果
    Yoyo->>SaaS: 10. 返回 {code:0, msg:"success"}
    SaaS->>User: 11. 开门成功，请进入

5. 典型场景代码实现 (cURL / Python)

假设您需要实现一个“一键开门”接口，以下是基于 reset7 指令的核心实现逻辑。

Bash/cURL 示例

Python 示例

6. 常见问题与排障

电磁锁“嗡嗡”响或发烫控制器第7路输出的是开关信号。如果电磁锁是 DC 12V，请请一定要使用 DC 12V 电源 单独供电，将电源的正负极串联在控制器的 COM 和 NO 端子上。如果直接给 12V 锁接入 220V，会烧毁设备。
开门延迟过长芯步的云指令响应通常在 80ms-120ms 之间。如果发现点击开门后延迟超过 2 秒，检查本地网络上行带宽或考虑使用 局域网 IP 直连 模式（如果系统支持私有化部署）。
如何实现“室内出门按钮”？控制器下方提供了 8 路开关量输入接口。您可以将一个普通的复位开关接在 GND 和 IN7 上。并在控制台配置联动规则：检测到 IN7 输入信号，则触发执行 reset7 动作。这样即使断网，物理按钮也能开门。