芯步的复合开关通过HTTP接口即可控制，核心是签名校验和指令封装。下面从设备选型、接口对接、业务集成三个层面展开。

1. 解决概述

在民宿智能化管理中，门口的公区照明与入户门禁是两个高频且关联紧密的控制节点。针对这一场景，芯步提供了 “智能墙壁触摸复合开关” 系列硬件（如型号：UNI-KG-CM-CK）。该硬件的核心优势在于单设备集成双路控制（一路控制门磁/电插锁，一路控制照明），且支持标准HTTP接口直接对接，无需额外网关。

本方案的目标是指导开发者如何利用芯步开放的API接口，将上述复合开关快速集成到现有的民宿PMS（Property Management System，物业管理系统）或自建APP/小程序中，实现 “入住自动通电、离电自动断电解锁、远程应急开门” 等自动化场景。

2. 硬件选型与接口特性

2.1 硬件：智能墙壁复合开关

在民宿场景下，推荐使用芯步的 “智能WiFi墙壁复合出门开关”。

• 物理结构：通常设计为“左门右灯”或“左灯右门”的双位面板，物理替换传统的墙壁开关。

• 负载能力

  • 门禁侧：专为电磁锁/电插锁设计，提供锁具所需的驱动电流。

  • 照明侧：标准的10A继电器输出，用于控制门口筒灯、玄关灯或走廊灯。

• 网络连接：支持2.4G WiFi直连，具备五组WiFi热备功能，可自动切换最强信号。

2.2 开放接口优势

该系列产品开放全量HTTP API接口，具有以下对接特性：

• 协议通用：任何支持HTTP请求的编程语言均可接入（Java, Python, PHP, Go, Node.js等）。

• 部署灵活：支持公有云调用，也支持私有化部署（局域网直连），满足民宿数据隐私需求。

• 免费：芯步开放平台永久免费，无设备接入数量的限制。

3. 软件对接技术方案

对接流程主要分为三个技术步骤：环境准备、核心指令下发、以及状态监听。

3.1 对接准备与鉴权

在调用API之前，需在芯步控制台获取密钥，这是保障设备安全的基础。

1. 获取凭证：登录芯步工作台，获取 AppID 和 AppSecret（开发者密码）。

2. 签名计算：所有HTTP请求需携带签名，计算公式为 sign = md5(md5(AppSecret) + ts)。校验通过后才被允许下发指令。

   开发提示：在开发测试阶段，可在控制台开启“调试模式”暂时绕过签名校验，提高调试效率。

3.2 核心指令下发（API调用）

以控制民宿某房间的“左门右灯”复合开关为例，对接时需重点关注 device（设备ID）和 order（命令）的构造。

接口信息

• URLhttp(s)://api.thingboot.com/{AppID}/device/control/

• Method：POST (支持 application/json 格式)

第一种场景：远程开启房门（退房清扫/应急）民宿保洁或管理员在退房时间未断电时，可通过后台远程开门。

• 业务逻辑：控制门禁线路（通常是线路1或线路7）断电，磁力锁失去吸力。

• 请求示例（JSON） ：

第二种场景：入住通电与灯光迎接客人办理入住后，PMS系统自动触发，开启门口灯光并给门锁上电（或维持上电）。

• 业务逻辑：同时控制两路输出。

• 请求示例（JSON） ：

第三种场景：智能联动（一键退房全关）客人一键退房或预约时段结束，系统自动断电并触发短暂开门（方便保洁进入）。

• 业务逻辑：利用 batch 批量命令或 reset 复位命令。

• 进阶命令示例：先断电，然后门禁短暂通电（点动模式）。

注：具体命令字段（如power1还是power7）需参考具体产品的《产品手册》，不同型号略有差异。

3.3 设备状态同步与事件监听

为了确保软件界面的状态与实际物理状态一致（例如客人手动按了出门开关），需要监听设备上报的消息。

• 消息推送机制：芯步支持配置HTTP/HTTPS的接收URL。当设备状态变化（如有人按下开关、灯被手动关闭），平台会主动推送消息到开发者服务器。

• 推荐拓扑

  1. 主动查询：APP打开控制页时，调用接口查询设备状态。

  2. 被动接收：配置消息服务器，接收设备实时回调，更新数据库中的“门锁/灯光”状态。

3.4 代码实现片段（逻辑示意）

以下伪代码演示了如何封装一个控制复合开关的函数：

4. 民宿业务场景

在实际部署“复合开关”时，结合软件逻辑，采用以下策略优化用户体验：

4.1 场景联动：无人值守模式

• 设备：复合开关 + 人体传感器（同样支持HTTP接口）。

• 逻辑

  • 客人离店关门后，人体传感器若在5分钟内未检测到移动。

  • 软件后台自动触发关闭灯光电源 + 门禁保持吸合。

  • 此时电费节省，门禁处于常闭安保状态。

4.2 定时任务：避免硬件依赖

由于部分民宿存在WiFi不稳定的极端情况，可在芯步云平台侧直接设置定时任务（云端执行，无需服务器保持运行）：

• 设置：每天中午12:00，执行“断开电路1（开门）”1秒，然后恢复，方便保洁定时进入。

4.3 故障冗余设计

• 本地按钮优先：复合开关保留了物理按键功能。即使网络断开或软件服务器宕机，客人依然可以通过触摸面板上的“出门”按键开启门锁（硬件底层逻辑），这符合民宿消防规范。

• 断网重连：硬件支持存储多组WiFi配置，当主WiFi信号差或密码变更时，可自动切换备用WiFi，减少“设备离线”的发生率。

5. 总结

芯步的复合开关通过标准化的HTTP API，将“门禁”与“照明”这两个民宿核心控制点抽象为简单的 power1 / power2 指令。

对软件开发者而言，无需关心底层硬件驱动，只需处理好签名生成、HTTP请求封装以及状态回调接收三个环节，即可在1-2天内完成从0到1的对接。该方案能有效帮助民宿主降低公区能耗，实现远程清房控制，提升运营效率。