共享自习室照明门禁控制：怎样把1路智能墙壁复合开关对接到自己的项目中_解决方案

CATALOG

芯步的智能墙壁复合开关（型号UNI-KG-KC）是一款“1路照明+1路门锁”二合一设备，通过HTTP接口即可实现远程控制。以下方案涵盖接口对接、业务逻辑到异常处理的完整实现路径。

1. 硬件选型与场景定义

在共享自习室的场景中，每个独立的小房间或格子间通常需要管理两个核心设备：顶灯（照明） 和 电磁门锁（门禁）。

传统方案需要安装两个独立的设备（一个开关+一个门禁控制器），布线复杂且成本高。采用 芯步智能墙壁复合开关 [左灯右门] 型号：UNI-KG-KC 能够完美解决这个问题。

物理特性：标准86型墙壁开关，可直接替换原有开关，无需重新布线开孔。
电路分配
- 第1路（左/灯）：控制220V交流电照明灯。
- 第2路（右/门）：控制12V或24V直流电磁锁（通过继电器控制门锁电源的通断）。

2. 接口对接核心流程

该设备的最大优势是开放了标准的HTTP API接口，这意味着你可以使用任何后端语言（Python、Java、Go、PHP）或前端（小程序、App）直接发起请求，无需复杂的物联网协议解析。

2.1 前期准备

在芯步官方平台完成设备注册：

注册开发者账号，获取 AppId 和 AppSecret。
将UNI-KG-KC设备通过2.4G Wi-Fi配网，使其在线。
在控制台获取设备的唯一标识 Device ID。

2.2 签名机制（安全验证）

为了防止接口被恶意调用，你需要生成签名（Sign）。签名算法如下 $Sign = MD5( MD5(AppSecret) + ts )$

参数说明：

AppSecret：开发者密码。
ts：当前Unix时间戳（秒）。
+：表示字符串拼接。

生成步骤示例（逻辑伪代码）：

1. 原Secret = "abc123"
2. MD5一次 = md5("abc123") = "e99a18c428cb38d5f22e03"
3. 拼接时间戳 = "e99a18c428cb38d5f22e03" + "1678923456" = "e99a18c428cb38d5f22e031678923456"
4. MD5二次 = md5(拼接结果) = 最终Signature

2.3 接口调用地址

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

3. 业务逻辑实现（照明与门禁分离）

在共享自习室系统中，照明和门禁的触发逻辑完全不同。你需要通过向 order 字段下发不同的JSON指令来区分。

3.1 第一种场景：用户预约成功/扫码开门（开灯 + 开门）

用户通过小程序扫描座位码或点击“开始学习”，系统需要同时打开灯和释放门锁。

下发命令示例：

power1：控制照明。一旦开启，保持常亮，直到用户主动结束订单。
point2：控制门锁。point 命令意为“脉冲模式”（先通后断）。电磁锁不需要长期通电（容易烧毁线圈），只需通电3-5秒推开锁舌即可。这里 3000 代表3000毫秒（即3秒后自动断电）。

3.2 第二种场景：用户暂离/结束（关灯 + 锁定）

用户在小程序点击“结束使用”，系统需要关闭照明，并确保门锁处于锁定状态。

下发命令示例：

注意：对于门锁控制，如果你在上一步使用了 point2，设备会自动断电，这一步只是做状态同步，确保门锁回路断开。

4. 高级功能应用：防占座与节能

利用接口的高级参数，可以在不修改业务代码的情况下，实现更聪明的逻辑。

4.1 超时自动断电（防占座）

痛点：用户离开座位忘记在App端关灯，导致能源浪费。解决方案：使用 状态保持 功能。当用户开灯时，下发一个带有 revert 参数的指令。

下发命令：

这样即使App端没有收到结束指令，1小时后照明也会自动熄灭。若用户续费，只需在App后端查询订单剩余时间，重新发送一次“保持开”指令续时即可。

4.2 复位与清理

如果自习室采用固定座位制，管理员需要在每天凌晨统一关闭所有灯和门。

下发命令：

系统后端可以设置一个定时任务（Cron Job），在每晚23:59向所有设备发送关灯指令，确保无人使用的座位处于断电状态。

5. 系统架构流程图

为了让你更清晰地理解数据流向，以下是对接的逻辑序列：

sequenceDiagram
    participant User as 用户小程序
    participant Server as 自习室后端系统
    participant YoyoAPI as 芯步云API
    participant Device as 墙壁复合开关
    participant Lamp as 照明灯
    participant Lock as 电磁门锁

    Note over User,Lock: 场景:用户扫码开门
    User->>Server: 请求开座(携带设备ID)
    Server->>Server: 生成签名(Sign) & 时间戳(ts)
    Server->>YoyoAPI: POST /control/ (power1=1, point2=3000)
    YoyoAPI->>Device: 下发指令(通过WiFi)
    Device->>Lamp: 继电器1闭合(220V通路)
    Device->>Lock: 继电器2闭合(12V通路)
    Lamp-->>User: 灯光亮起
    Lock-->>User: 门锁弹开(3秒后自动锁定继电器)

6. 异常处理与

在实际开发中，需要注意以下几点：

网络延迟HTTP接口虽然是即时响应（通常80-120ms），但依赖WiFi信号。在自习室座位密集区部署企业级AP，避免2.4G信道干扰导致指令丢包。
门锁状态的调用机制不要在用户每次点击“开门”时都发送 point2 指令。如果后端连续调用两次API，门锁会通电两次（第一次通电3秒后断电，第二次又重新上电）。后端逻辑中增加状态缓存：只有当检测到当前状态为“已关”时，才发送开门指令。
本地局域网控制（可选）如果公网断网，为了保障自习室仍能运营，芯步设备支持私有化部署和局域网控制。如果你的服务器与设备在同一局域网内，可以不经过公网云API，直接向设备本地IP发送HTTP命令，提高稳定性。