共享台球室灯光控制：如何把1路照明触摸开关集成到软件项目中_解决方案

CATALOG

共享台球室的智能化改造中，照明控制是最基础也最关键的一环——用户开单后自动通电、时间到前提醒、超时自动断电，这些体验都依赖照明开关与软件系统的联动。以下方案围绕芯步智能照明控制器（8路）的HTTP接口，说明如何将1路物理触摸开关集成到软件项目中。

1. 解决概述

在共享台球室场景中，用户通过小程序开单后，对应的台球灯应自动亮起；用户点击“结束”或时长耗尽，灯光自动熄灭。同时，为了符合物理操作习惯，墙上的触摸开关需要保留，允许用户在打球过程中手动关灯（如暂时休息）或开灯。

痛点：物理开关直接切断电路会导致设备离线，软件无法同步状态，造成计费混乱（用户关灯但订单未结束）。

解决方案思路：采用“软件定义输入输出”的模式。物理开关不再直接控制强电负载，而是作为低压信号输入接入智能控制器；控制器负责执行通断，并通过 HTTP 主动上报状态变化，软件项目（小程序/后台）通过 API 同步状态并下发指令。

2. 硬件选型与接线方案

为了实现上述逻辑，需要选择具备多路控制、开关量输入检测及开放 API 的硬件。

推荐设备：芯步智能照明控制器（8路）

型号参考：UNI-KZQ-ZM-8（8路版本）。
为什么选它
- 8路独立控制：可覆盖台球室的多张球台，成本分摊低。单路负载能力强（10A/16A），适配大功率照明灯。
- 物理开关接入能力：设备自带开关量输入接口，正好用来接墙面的触摸开关（复位式/自复位式）。这解决了"物理按键损坏或线路复杂"的问题，将物理操作转化为低压数字信号。
- 开放性：支持 HTTP 接口，不依赖特定云平台，可私有化部署。

物理触摸开关集成方案

接线方式
1. 强电端：台球室照明灯的火线接入控制器的第1路输出端（Relay 1），零线共用。
2. 信号端：墙面的触摸开关（使用复位式自回弹开关）的两根线，接入控制器的开关量输入端（GPIO/DI 通道1） 和 GND。
3. 电源：控制器接 5V/2A 供电，保持设备常在线。

这种接法下，触摸开关的作用是向控制器发送一个通断信号，而不是直接切断 220V 电路。

3. 软件集成架构

软件端采用 云云对接 或 服务器直连 模式。由于芯步开放本地 API，将控制器与业务服务器放在同一局域网（如台球室本地服务器），公网则通过反向代理访问，保证响应速度。

控制流（App/小程序 -> 灯光）用户点击小程序 -> 业务服务器 -> 芯步 API -> 智能控制器 -> 继电器吸合 -> 灯亮。
状态流（物理开关 -> App/小程序）用户触摸墙面开关 -> 控制器检测到信号 -> 控制器切换继电器状态（本地执行） -> 控制器 HTTP 推送给业务服务器 -> 服务器更新订单状态或仅更新界面。

4. 接口对接实现与代码示例

基于 HTTP 接口，采用 POST 请求，数据格式为 JSON。假设控制器设备 ID 为 LAMP_01，需要控制第 1 路。

4.1 核心接口逻辑（设备控制）

根据设备接口规范，控制指令通过 order 字段传递。

功能：远程开启第1路照明

URLhttp(s)://api.thingboot.com/{AppId}/device/control/?sign={sign}&ts={ts}
Method：POST
Body (JSON)

注：如果是批量控制或更高级的继电逻辑，可使用 batch 或 point 命令。

4.2 触摸开关与软件的联动逻辑（状态同步）

这是关键步骤。当物理开关被按下时，控制器会切换状态。为了确保 App 端显示正确，服务器需要知道这个变化。

方案一：HTTP 消息推送（推荐）在芯步控制台中配置 HTTP 回调 URL（由你的后端提供）。

当物理开关触发第1路状态改变时，控制器会主动向你的服务器发送状态包。
后端接收逻辑（示例如 Node.js 接收路由）：

方案二：轮询接口如果无法配置公网回调，可以采用定时轮询：GET /device/query?device=LAMP_01。服务器每 2 秒请求一次该接口获取 power1 值，感知开关动作。

5. 业务场景流程设计

场景 1：用户下单（开台）

用户小程序下单并支付。
业务系统创建订单，根据球桌号（如 1号桌）拼接设备 ID（DEV_01）。
调用 API：向该设备下发 {"power1": "1"}。
1号桌球灯亮起，计时开始。
存在物理开关：如果此时用户误触墙面开关试图开灯（其实是关灯），控制器关闭继电器。
业务逻辑处理：服务器收到回调 power1=0。
- 策略 A（严苛计费）：视为用户暂停/作弊，服务器立即下发 {"power1":"1"} 强制开灯（需做防抖处理，如3秒内不重复下发），软件端不影响计费。
- 策略 B（人性化）：确认关灯，App 端弹窗提示“灯光已关闭，订单仍在计时，请点击开灯”。

场景 2：倒计时结束

订单剩余 0 分钟。
调用 API：向设备下发 {"power1": "0"}。
灯光熄灭。即使触摸开关再怎么按，由于订单结束，逻辑上业务服务器忽略或拒绝执行开灯请求。

场景 3：无订单操作（防逃单）

用户未下单，直接按触摸开关。
控制器推送状态给服务器。
服务器检测到“该设备无进行中的订单”。
执行保护逻辑：服务器向设备下发 {"power1":"0"}，强制断电（或者设置设备不响应此开关操作）。

6. 总结

通过将 1路照明触摸开关 接入 芯步 8路智能控制器 的 开关量输入端，并利用其 开放 HTTP API 和 状态主动推送 能力，能够完美实现“软件控制优先，物理开关辅助”的共享台球室智能照明方案。

对于开发者而言，由于控制器本身提供了完整且简洁的 HTTP 接口文档，集成工作主要集中在 业务逻辑层 的状态机维护（计费中、暂停中、空闲中），以及利用 HTTP 回调 解决物理操作与软件系统的状态同步问题。最终方案可实现远程控制、物理本地控制和无人化自动管理的高效闭环。