芯步2路智能复合开关是一款支持双路独立控制的WiFi设备，其开放API可对接照明和门禁系统。以下方案分别说明两路控制的调用方式与典型场景。

一、 硬件选型与预备知识

在开始二次开发之前，首先需要确认硬件细节。芯步针对混合控制场景提供了特定型号，通常被称为“智能墙壁复合开关[左灯右门]”（型号如 UNI-KG-KC）。

• 核心特性：该设备拥有两路继电器输出，支持 WiFi 直连（无需网关），支持 100-250V AC 或 DC 供电，且具备标准的 86 型底盒 安装规格。

• 开放接口：设备通过 HTTP API 接受控制命令，这意味着任何能发起 HTTP 请求的编程语言（如 Python, Java, Go, PHP, JS/Node.js）或工具（如 Postman, curl）都可以对其进行开发。

• 关于门锁的特别说明：请特别注意，该开关输出的是干触点信号或通断信号。若用于门禁，严禁将门锁的电流直接接到开关上。必须通过配套的12V 电源，将开关串接在电插锁或电磁锁的供电回路中。

二、 API 鉴权与基础请求结构

无论控制第一路还是第二路，都需要遵循统一的 API 鉴权规则。所有二次开发的第一步都是生成动态签名。

• 请求地址https://api.thingboot.com/{AppID}/device/control/

• 请求方法：POST

• 核心参数

  1. device：设备 ID（在芯步控制台获取）。

  2. order：命令对象（JSON 格式）。

签名生成规则（以 Shell/PHP 为例）为了安全，接口要求携带签名 sign 和时间戳 ts。生成的逻辑如下

1. 获取当前时间戳 ts。

2. 将你的 AppSecret 进行一次 MD5 加密。

3. 将上述结果拼接上 ts，再进行一次 MD5 加密，得到 sign。

   • 公式：sign = md5( md5(AppSecret) + ts )

请求头设置Content-Type: application/json

三、 场景 A：二次开发实现双路照明控制

如果“2路复合开关”的两路都接的是灯，实现标准的双开双控非常直接。

1. 命令协议

针对照明场景，通常只需切换通断状态。参考芯步 2 路开关的通用指令集

• 控制第一路（左灯）

  • 开灯：{"power1": 1}

  • 关灯：{"power1": 0}

• 控制第二路（右灯）

  • 开灯：{"power2": 1}

  • 关灯：{"power2": 0}

2. 开发示例（逻辑实现）

你可以通过以下伪代码逻辑实现一个“一键全开/全关”或“独立控制”的功能：

在代码逻辑中，你只需要修改 order 对象内的 power1 和 power2 的值，并将包含 device 和 order 的 JSON 字符串 POST 到上述 API 地址即可。

四、 场景 B：二次开发实现门禁控制（单路）

这是复合开关最实用的场景，即 “左灯右门” 模式。假设第二路接门锁，第一路接照明。

门禁控制的逻辑不仅仅是“开/关”，通常涉及“通电开锁”或“断电开锁”的时长控制。芯步的接口提供了专门的脉冲命令来处理这种场景。

1. 门禁接线逻辑（关键）

• 模式设定：首先确定你的锁是“断电开锁”（如电插锁，断电门弹开）还是“通电开锁”（如磁力锁，通电吸住）。

• 指令配合：如果你的锁是“通电开锁”，你需要发送一个 {"power2": 1} 给门吸电，但为了安全，通常按一下按钮，门吸电几秒后自动断开。这就需要用到 先通后断 (Point) 命令。

2. 核心 API 命令

针对控制门锁的线路（假设是第二路），推荐不使用简单的 power2，而使用带时长的点动/脉冲控制

• “先通后断” (Point)：线路接通，维持设定的毫秒数后自动断开。

  • 适用场景：通电开锁（如磁力锁，瞬间通电开门）。

  • 指令示例：{"point2": "3000"} （第二路接通 3 秒后自动关断）。

• “先断后通” (Reset)：线路断开，维持设定的毫秒数后自动接通。

  • 适用场景：断电开锁（如电插锁，断电后门弹开，然后恢复供电让锁体复位）。

  • 指令示例：{"reset2": "1000"} （第二路断开 1 秒后自动恢复接通）。

3. 开发实施步骤

在二次开发管理系统中，实现“远程开门”按钮的代码逻辑如下：

第一步：获取设备ID确定你要控制的设备 ID（例如 820720）。

第二步：构造开门指令由于门锁不需要常开，只需触发一下，强烈使用 point 或 reset 命令，避免因程序 Bug 导致门锁长时间通电烧毁。

第三步：组合照明控制如果需要同时实现“开门亮灯”的场景，可以组合命令：

五、 多语言快速集成参考

由于芯步的接口是标准的 HTTP RESTful 风格，你可以用任何语言调用。以下是几种常见的集成方式摘要：

• Java (OkHttp)：构建 RequestBody 包含 JSON 参数，通过 POST 提交至 URL，需处理签名 sign 的 MD5 计算。

• PHP：使用 file_get_contents 或 cURL 扩展，设置 http_build_query 或 JSON 字符串作为 POST 字段。

• Python / cURL：最直接的方式，在命令行或脚本中通过 -d 参数传递 JSON 数据。

六、 高级功能与扩展

除了单一设备控制，如果你的业务场景涉及多个门禁或大量照明同时控制，可以利用 标签控制 功能：

• 场景：下班时间，关闭整个楼层的灯，同时将所有门禁上锁。

• 接口/tag/control/

• 命令：向特定的“标签 ID”发送 {"power1": 0, "power2": 0}，即可批量控制该标签下所有开关的状态。

此外，若对数据安全有极致要求，芯步支持 私有化部署。你可以将 API 切换到局域网 IP 或私有云域名，让设备完全不经过外网。

七、 总结

通过芯步的开放接口对“2路智能复合墙壁开关”进行二次开发，核心在于理解 order 参数的灵活运用：

1. 对照明路：使用 power1 / power2 进行状态保持控制。

2. 对门禁路：使用 point（先通后断）或 reset（先断后通）配合时间戳（如 3000 毫秒）实现安全的“点动”开门。

3. 通信保障：利用统一的 AppID + AppSecret + ts 生成的签名进行鉴权，通过标准的 HTTPS POST 请求即可集成到现有的楼宇自动化、酒店 PMS 系统或智能家居中枢中。