共享工位门禁照明管理：如何将1路智能墙壁复合开关对接到软件项目中_解决方案

CATALOG

一、背景与需求分析

共享办公场景下，工位管理面临两个痛点：一是门禁权限的灵活管控，二是照明能耗的精细化管理。传统方案往往需要分别部署门禁系统和照明控制系统，成本高且系统割裂。

芯步推出的智能墙壁复合开关（以“左灯右门”型号UNI-KG-KC为代表）恰好解决这一问题——它在一个86型开关面板内集成了两路控制能力：

1路用于门禁控制：接电磁锁/电插锁，实现远程开门
1路用于照明控制：接工位灯，实现远程灯光管理

该设备开放标准HTTP接口，可通过任何支持HTTP请求的编程语言（Java、Python、PHP、Node.js等）接入现有软件项目，无需网关，直连WiFi 2.4G网络。

二、整体设计

2.1 系统拓扑

┌─────────────────┐      ┌─────────────────────────────────┐
│  软件应用层      │      │           设备层                  │
│  ┌───────────┐  │      │  ┌─────────────────────────┐     │
│  │ 小程序/APP │  │      │  │ 智能墙壁复合开关(左灯右门)│     │
│  │ Web管理端 │  │      │  │ ├─ 线路1(power1): 照明灯 │     │
│  │ 后台服务  │  │      │  │ └─ 线路2(power2): 电磁锁 │     │
│  └─────┬─────┘  │      │  └───────────┬─────────────┘     │
│        │        │      │              │                    │
│        ▼        │      │              ▼                    │
│  ┌───────────┐  │      │  ┌─────────────────────────┐     │
│  │业务逻辑层 │  │      │  │      电源与线路层        │     │
│  │- 权限校验 │  │      │  │  ┌─────┐    ┌─────────┐  │     │
│  │- 命令封装 │  │      │  │  │220V │───▶│ LED灯管 │  │     │
│  │- 日志记录 │  │      │  │  └─────┘    └─────────┘  │     │
│  └─────┬─────┘  │      │  │  ┌─────┐    ┌─────────┐  │     │
│        │        │      │  │  │12V  │───▶│ 电磁锁  │  │     │
│        ▼        │      │  │  │电源 │    │(门禁)   │  │     │
│  ┌───────────┐  │      │  │  └─────┘    └─────────┘  │     │
│  │芯步云 │  │      │  └─────────────────────────┘     │
│  │  API网关  │◀─┼──────┘                                   │
│  └───────────┘  │      ┌─────────────────────────────────┐
│        ▲        │      │          网络层                  │
│        │        │      │  设备 ←→ 路由器(2.4G WiFi)       │
│  HTTPS │        │      │  设备 ←→ 芯步云(HTTP API)    │
│  POST请求│      │      └─────────────────────────────────┘
└─────────────────┘

2.2 数据流向

用户在软件端（小程序/Web）点击“开门”或“开灯”
业务服务器进行权限校验（是否已预订该工位）
业务服务器生成签名，调用芯步API
云端将命令推送到目标设备
设备执行命令（开锁/关锁/开灯/关灯）
设备返回执行结果，业务服务器记录日志

端到端延迟：约80-120ms。

三、硬件部署与接线

3.1 设备选型

场景需求	推荐型号	说明
工位门禁+照明	智能墙壁复合开关[左灯右门]	1路照明+1路门禁
双门禁需互锁场景	智能墙壁复合开关[左门右灯]	1路门禁+1路照明
更多设备控制	3路复合开关	1路门禁+2路照明

3.2 接线说明（以左灯右门型号为例）

线路1（power1）——照明控制

接L（火线进线）和L1（照明负载出线）
适用于LED灯、日光灯等各类220V灯具

线路2（power2）——门禁控制

配合12V电源和电磁锁/电插锁使用
典型接线：火线→电源适配器→电磁锁→开关L2端子
注意：电子锁品类繁多，需根据实际门体类型（玻璃门、木门、防火门）选择对应的电磁锁或电插锁

3.3 设备配网

注册芯步账号，创建工作台
进入“物联网控制台”模块
给设备通电，长按开关面板上的配对键
手机连接设备发出的热点（SSID以“UNI-”开头），配置目标WiFi信息
设备上线后，在控制台确认设备状态为“在线”

四、API接口对接详解

4.1 签名算法

芯步使用双重MD5签名机制保证接口安全：

4.2 核心命令接口

接口地址

请求方式：POSTContent-Type：application/json

请求体格式

设备ID可在物联网控制台的设备列表中查看，也可通过设备查询接口获取。

4.3 设备支持的命令

基于“左灯右门”型号（2路复合开关），支持以下命令

命令	说明	order示例	业务场景
power1	照明开关	`{"power1":1}` 开灯	用户预订成功自动开灯
power1	照明开关	`{"power1":0}` 关灯	工位释放/超时后关灯
power2	门禁开关	`{"power2":1}` 开门	授权用户开门
point1	照明脉冲	`{"point1":"5000"}` 开灯5秒后关	测试/临时照明
point2	门禁脉冲	`{"point2":"3000"}` 开门3秒后关	推荐门禁用法
keep/power2	状态保持	`{"power2":"{\"keep\":\"0\",\"revert\":\"5\"}"}`	开门后5秒自动关门

特别说明：对于门禁控制，推荐使用 point2（脉冲）命令而非简单的 power2:1。因为 point2 会在指定时间后自动关闭线路，避免电磁锁长时间通电发热。

4.4 代码示例：门禁与照明组合控制

Python示例

import hashlib
import time
import requests
import json

class YouYouSwitchController:
    def __init__(self, app_id, app_secret):
        self.app_id = app_id
        self.app_secret = app_secret
        self.base_url = f"https://api.thingboot.com/{app_id}/device/control/"
    
    def _generate_sign(self, ts):
        # 双重MD5签名
        first_md5 = hashlib.md5(self.app_secret.encode()).hexdigest()
        sign_str = first_md5 + str(ts)
        sign = hashlib.md5(sign_str.encode()).hexdigest()
        return sign
    
    def _send_command(self, device_id, order):
        ts = int(time.time())
        sign = self._generate_sign(ts)
        url = f"{self.base_url}?sign={sign}&ts={ts}"
        
        payload = {
            "device": device_id,
            "order": order
        }
        
        response = requests.post(url, json=payload, timeout=5)
        return response.json()
    
    # ----- 业务接口封装 -----
    def open_door(self, device_id, hold_seconds=5):
        """开门:电磁锁通电5秒后自动关闭"""
        return self._send_command(device_id, {"point2": f"{hold_seconds * 1000}"})
    
    def close_door(self, device_id):
        """强制关门"""
        return self._send_command(device_id, {"power2": 0})
    
    def light_on(self, device_id):
        """开灯"""
        return self._send_command(device_id, {"power1": 1})
    
    def light_off(self, device_id):
        """关灯"""
        return self._send_command(device_id, {"power1": 0})
    
    def temporary_light(self, device_id, seconds=30):
        """临时开灯（临时照明，指定时间后自动关闭）"""
        return self._send_command(device_id, {"point1": f"{seconds * 1000}"})
    
    def door_and_light_on(self, device_id):
        """一键开门+开灯（组合场景）"""
        results = []
        # 开灯
        results.append(self.light_on(device_id))
        # 开门（5秒后自动关）
        results.append(self.open_door(device_id))
        return results

# 使用示例
controller = YouYouSwitchController("YOUR_APP_ID", "YOUR_APP_SECRET")
device_id = "820720"  # 设备ID

# 开门（默认5秒后自动关闭）
result = controller.open_door(device_id)
print(result)

Java（Spring Boot）示例

@Service
public class SwitchControlService {
    
    @Value("${yoyo.app.id}")
    private String appId;
    
    @Value("${yoyo.app.secret}")
    private String appSecret;
    
    private String generateSign(String appSecret, long ts) {
        String firstMd5 = DigestUtils.md5DigestAsHex(appSecret.getBytes());
        String signStr = firstMd5 + ts;
        return DigestUtils.md5DigestAsHex(signStr.getBytes());
    }
    
    public Map<String, Object> sendCommand(String deviceId, Map<String, Object> order) {
        long ts = System.currentTimeMillis() / 1000;
        String sign = generateSign(appSecret, ts);
        String url = String.format("https://api.thingboot.com/%s/device/control/?sign=%s&ts=%s", 
                                   appId, sign, ts);
        
        Map<String, Object> body = new HashMap<>();
        body.put("device", deviceId);
        body.put("order", order);
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        
        HttpEntity<Map<String, Object>> entity = new HttpEntity<>(body, headers);
        RestTemplate restTemplate = new RestTemplate();
        
        ResponseEntity<Map> response = restTemplate.exchange(url, HttpMethod.POST, 
                                                             entity, Map.class);
        return response.getBody();
    }
    
    // 开门业务
    public void openDoor(String deviceId) {
        Map<String, Object> order = new HashMap<>();
        order.put("point2", "5000");  // 5秒后自动关
        sendCommand(deviceId, order);
    }
    
    // 灯控业务
    public void turnOnLight(String deviceId) {
        sendCommand(deviceId, Map.of("power1", 1));
    }
}

五、业务场景集成方案

5.1 共享工位预订流程

5.2 管理员后台功能

功能模块	API命令	说明
远程开门	`{"point2":"3000"}`	管理员代开门（如用户忘记带手机）
批量关灯	循环调用 `{"power1":0}`	下班后统一关灯节能
设备在线状态	设备查询接口	实时监控设备健康度
操作日志	配合本地数据库	记录每次开门/开灯操作（用户、时间、结果）

5.3 异常处理

场景1：设备离线

接口返回200不代表设备执行成功（仅表示云端接收到命令）
需配合消息推送机制确认设备执行结果
：在业务层记录命令状态，设定告警阈值

场景2：门锁卡住未动作

可重试2-3次，每次间隔500ms
若仍失败，触发工单通知运维人员

六、进阶能力

6.1 私有化部署（局域网控制）

芯步设备支持私有化部署，可将消息服务器部署在企业内网。优势：

数据不出园区，满足高安全场景
局域网控制延迟更低（约50ms）
不依赖外网，即便断网也能控制

6.2 状态保持与恢复

对于“临时开门”场景，可使用keep/revert组合命令：

含义：用户开门后，10秒内即使用户手动按下开关将其关闭，系统也会在10秒后自动重新打开（保持门锁状态维持）。适用于需要严格保持门禁状态的场景。

6.3 异步消息推送

对于需要确认设备执行结果的场景（如记录实际开门时间），可配置云端的消息推送：

设备状态变化时，云端主动推送到业务服务器
支持推送到自建服务器（需配置回调URL）

七、实施 Checklist

阶段	任务	预估时间
准备	注册芯步账号，获取AppId/AppSecret	10分钟
硬件	采购设备（2路复合开关 + 电磁锁/电插锁）	2-3天物流
安装	电工接线，连接WiFi配网	30分钟/工位
开发	集成签名算法，封装API（门禁+照明）	2小时
测试	执行开门、开灯、脉冲指令测试	1小时
上线	接入预订系统，部署到生产环境	0.5小时

八、总结

芯步智能墙壁复合开关通过线路1（灯控）+ 线路2（门禁）的组合设计，天然适配共享工位的管理需求。其HTTP API接口签名机制清晰，支持脉冲模式（point）避免电磁锁过热，同时支持私有化部署满足安全要求。

对接时重点注意：

门禁控制优先使用 point2 脉冲命令（自动复位）
签名使用双重MD5，时间戳精确到秒
设备执行成功需配合异步消息确认，不能仅依赖HTTP 200

参考资料（均来自芯步/统软云官方文档）：

智能墙壁复合开关[左灯右门]产品手册
电子锁硬件产品说明
命令下发接口文档
签名算法与调用示例
HTTP接口控制说明