如何在共享台球厅中对接智能硬件以实现8路照明设备电源状态监测_解决方案

CATALOG

一、背景与需求

共享台球厅的运营核心之一是照明管理——一方面需要在用户下单后自动开灯、订单结束后关灯，另一方面需要实时掌握每张球桌上方灯箱的“真实通断电状态”，避免因设备故障或异常导致“系统显示关灯但灯还亮着”的能源浪费，或者“系统显示开灯但灯不亮”的用户投诉。

实现这一目标的关键在于：选用具备“状态回读”能力的智能硬件，并通过开放接口将其与业务系统无缝集成。芯步的8路智能照明控制器恰好满足这一需求。

二、硬件选型：8路智能照明控制器

2.1 设备选型

推荐使用芯步 UNI-KZQ-ZM-8-10A/16A 智能照明控制器。

参数项	规格说明
控制路数	8路独立分控
负载类型	阻性负载（如LED灯）≤2200W/路，感性负载≤350W/路
通信方式	WiFi 2.4GHz，直连路由器
接口协议	HTTP API（支持公网/局域网调用）
输入接口	8路开关量信号输入（可接物理开关）
工作电压	DC 5V/2A

2.2 为何选择这款设备

该设备在共享场景中具备三个核心优势：

8路独立分控：恰好匹配一个台球厅8张球桌（或最多8个独立灯组）的照明控制需求，单台设备即可覆盖，无需多台堆叠。
开放HTTP接口：设备提供标准的HTTP API，任何能发HTTP请求的服务端语言（Java、Python、Node.js、Go等）或前端（小程序云函数）均可调用，无需私有SDK，集成成本极低。
状态主动上报：这是实现“状态监测”的关键。当设备收到控制指令或因本地开关操作导致状态变化时，可通过配置向业务服务器推送实时状态，业务系统由此获知“当前灯的真实开/关状态”。

三、技术设计

3.1 整体架构

┌─────────────────────────────────────────────────────────────┐
│                        用户端（小程序/APP）                   │
└─────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────┐
│                    业务服务端（SaaS/云服务器）                 │
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐     │
│  │  订单管理     │   │  设备管理     │   │  状态同步     │     │
│  └──────────────┘   └──────────────┘   └──────────────┘     │
└─────────────────────────────────────────────────────────────┘
                          ▲                       │
              HTTP API调用 │                       │ 状态推送
                          │                       ▼
┌─────────────────────────────────────────────────────────────┐
│                      芯步云平台                          │
│              （设备接入、消息路由、签名验证）                  │
└─────────────────────────────────────────────────────────────┘
                                    │
                                    ▼ WiFi
┌─────────────────────────────────────────────────────────────┐
│                 8路智能照明控制器（现场设备）                  │
│                        │            │                        │
│     ┌──────────────────┼────────────┼──────────────────┐     │
│     ▼                  ▼            ▼                  ▼     │
│   灯箱1             灯箱2        ...                 灯箱8    │
└─────────────────────────────────────────────────────────────┘

3.2 状态监测原理

“状态监测”并非业务系统主动轮询，而是由设备主动上报

指令下发后的自动回执：业务系统发送“闭合第1路”指令后，设备执行成功会返回结果，这只能证明“指令被设备接收并执行”，但不能100%确认灯亮（比如线路老化、灯泡损坏）。
持续状态监测的解决方案：设备的8路输出回路中内置了电流/电压检测模块，当某路处于通电状态但负载电流异常（如灯泡烧毁导致电流为0），设备可通过消息推送机制将异常状态上报业务系统。

注：具体是否支持“负载故障检测”功能，与芯步销售或技术确认硬件版本差异。

四、接口对接实现方案

4.1 准备工作

在芯步开放平台（ThingBoot Open）完成以下配置

注册开发者账号，创建应用，获取 AppId 和 AppSecret
在平台添加设备，获取设备的 device_id（每台8路控制器有唯一ID）
配置消息推送URL：设置业务服务器的接收地址（如 https://api.yourdomain.com/yoyo/callback），用于接收设备主动上报的状态消息
配置设备的WiFi网络，确保设备在线

4.2 核心接口：下发控制指令

当用户下单成功或点击“开灯”时，业务服务器调用此接口。

请求方式：POST

请求URL

https://api.thingboot.com/{AppId}/device/control/?sign={sign}&ts={ts}

请求体示例（开启第1路和第3路）

*字段说明：power1 ~ power8 分别对应控制器的1~8路，1=开启，0=关闭*。

签名生成规则（伪代码）：

4.3 状态接收：被动接收设备上报

这是实现“状态监测”的核心——无需主动查询，设备会在状态变化时主动推送。

接收方式：芯步平台向步骤4.1中配置的URL发起POST请求。

消息体示例（第1路状态变为“开启”）

业务系统处理流程

接收HTTP POST请求，验签（可选）
解析JSON，提取 device_id 和各路 powerX 状态
更新数据库中的设备状态表
异常判断：若某路指令下发时要求开启（本地记录为1），但连续多次上报为0 → 触发告警

4.4 接口调用安全说明

芯步开放平台支持私有化部署和局域网调用模式

公网模式：适用于加盟店分散、无需自建网关的场景，通过云端API调用
局域网模式：若门店有本地服务器且与控制器处于同一局域网，可直接调用设备本地IP，响应速度更快（80-120ms），且断外网仍可控

五、业务场景集成细节

5.1 用户订单流程中的状态联动

步骤	动作	涉及接口/逻辑
1	用户小程序下单，支付成功	业务系统生成订单，状态=“待使用”
2	系统自动下发开灯指令	调用控制接口，开启对应的1路或多路
3	设备执行成功，上报状态	推送消息至业务系统，确认灯已亮
4	用户入场打球	-
5	订单结束/超时	系统下发关灯指令
6	设备上报“灯已灭”	状态同步，完成闭环

5.2 异常监测与告警

通过持续接收状态上报，系统可识别以下异常并通知运维人员

异常类型	判断逻辑	处理
灯泡/线路故障	下发“开灯”指令后，1分钟内未收到“状态=开”的上报	推送告警：“XX球桌灯组故障，请检修”
设备离线	连续10分钟未收到任何状态上报	推送告警：“设备离线，请检查网络”
物理开关误操作	收到的状态与订单状态不一致（如订单未开始时灯却亮了）	可通过输入接口外接锁定开关，或由系统自动纠正