一、概述

1.1 应用场景

在共享棋牌室、茶室、包间式KTV、舞蹈练习室、共享琴房等场景中，经营者需要对多个独立包间的电源设备进行远程管理——顾客下单后自动通电、计时结束时自动断电，或由前台手动控制。芯步8路包间电源控制器专为此类场景设计，通过开放HTTP接口，可实现与现有预约/收银系统的无缝对接。

1.2 核心能力

1.3 方案架构图（文字描述）

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│   业务系统       │      │   芯步云平台  │      │   现场设备       │
│ (预约/收银/PMS)  │ ──► │  api.thingboot.com │ ──► │  8路电源控制器   │
│                 │      │                 │      │                 │
│ 下单→通电        │      │ • 签名验证       │      │ 包间1: 照明      │
│ 计时→断电        │      │ • 命令转发       │      │ 包间2: 麻将机    │
│ 手动控制         │      │ • 状态同步       │      │ 包间3: 空调      │
└─────────────────┘      └─────────────────┘      └─────────────────┘

如为局域网私有化部署，业务系统可直接与设备通信，无需经过云平台。

二、设备选型与规格

2.1 推荐设备：智能包间控制器|Max

针对8路包间独立控制场景，推荐使用智能包间控制器|Max，该设备为包间场景专用设计，各通道负载能力差异化配置，适配不同电器类型

2.2 备选设备：智能通用控制器|8路

如需更紧凑的安装尺寸或控制纯阻性负载（如单纯的照明场景），可选择通用8路控制器

2.3 设备配网准备

设备上电后需连接现场WiFi（仅支持2.4GHz频段）：

1. 登录芯步官网控制台，进入“物联网控制台”模块

2. 点击“网络配置”→“登记网络”，输入现场WiFi名称和密码

3. 通过手机热点方式为设备配网：将手机热点名称/密码设置为指定格式，设备自动连接并同步WiFi信息

4. 配网成功后，设备停止闪烁，在控制台“设备列表”中可看到设备唯一ID（device）

说明：设备ID是后续所有HTTP接口调用中的核心标识，请妥善保存。

三、HTTP接口对接详解

3.1 接口基础信息

请求地址（公网云平台）：

http(s)://api.thingboot.com/{AppID}/device/control/?sign={sign}&ts={ts}

请求方式：POST（推荐，参数较长时）或 GET

数据格式：JSON（推荐）或 Form-Data

私有化部署说明：如需局域网内使用，可将请求地址替换为设备局域网IP，接口格式保持一致，不依赖公网。

3.2 签名算法（sign计算）

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

sign = md5(AppID + AppSecret + ts)

其中 AppSecret 在创建应用时由平台生成，请妥善保管。

示例

• AppID = "12345"

• AppSecret = "abcde12345"

• ts = 1700000000

• 拼接字符串 = "12345abcde123451700000000"

• sign = md5(拼接字符串) = "xxxxxx"

3.3 核心接口：向设备下发命令

命令格式核心要点

• device：必填，设备唯一ID，可在控制台设备列表查看

• order：必填，命令内容，JSON字符串格式

• 单路控制使用 {"power1":"1"} 或 {"power1":"0"}，其中 1 表示接通，0 表示断开

• 8路控制器中，power1 至 power8 分别对应第1至第8路输出

3.3.1 单路独立控制

场景1：打开包间1的照明（第1路）

场景2：关闭包间3的空调（第8路）

3.3.2 批量控制（同时控制多个通道）

场景：顾客离开现场时，关闭包间所有设备（第1、2、3、4、5、6、8路断开）

参数说明

• relay：要控制的通道数组，如 [1,2,3]

• power：目标状态，"1" 为通，"0" 为断

3.3.3 延时控制

场景1：先通后断（点动模式）—— 打开包间排风扇，5秒后自动关闭

执行逻辑：先接通指定通道，间隔 interval 毫秒后断开。

场景2：先断后通（复位模式）—— 重启包间路由器

执行逻辑：先断开指定通道，间隔 interval 毫秒后重新接通。

3.3.4 携带业务标识（extra字段）

在需要追踪命令来源（如订单号）的场景，可在 order 中增加 extra 字段，后续异步消息推送时会原样返回

3.4 响应结果处理

接口返回 HTTP 200 仅表示云平台已接收命令并成功下发给设备，不代表设备已执行成功（设备可能离线或执行异常）。对可靠性要求高的场景，应使用异步消息推送获取执行结果。

同步响应示例

常见错误码

3.5 设备状态查询

如需查询设备当前各通道的通断状态，可通过设备信息接口获取（具体接口路径请参考芯步开放平台文档）。典型返回数据结构包含各通道 power1 ~ power8 的实时状态。

四、与业务系统集成示例

4.1 伪代码实现

以下伪代码展示了在订单系统中集成控制的典型逻辑：

// 配置常量
AppID = "你的应用ID"
AppSecret = "你的应用密钥"
DeviceID = "你的设备ID"

// 签名生成函数
function generateSign(appId, secret, ts):
    raw = appId + secret + ts
    return md5(raw)

// 向指定通道发送命令
function controlChannel(channel, state):
    ts = currentTimestamp()
    sign = generateSign(AppID, AppSecret, ts)
    url = "http://api.thingboot.com/" + AppID + "/device/control/?sign=" + sign + "&ts=" + ts
    
    body = {
        "device": DeviceID,
        "order": {"power" + channel: state ? "1" : "0"}
    }
    
    response = httpPost(url, body)
    return response.code == 200

// 场景1:顾客下单成功后，打开对应包间电源
function onOrderPaid(order):
    roomNumber = order.roomNumber
    result = controlChannel(roomNumber, true)
    if result:
        log("包间" + roomNumber + "通电成功")
        startTimer(order.orderId, order.duration)  // 启动计时器
    else:
        alert("设备控制失败，请人工检查")

// 场景2:包间使用时间结束，自动断电
function onOrderTimeout(orderId):
    order = getOrder(orderId)
    controlChannel(order.roomNumber, false)
    log("包间" + order.roomNumber + "使用时长已到，已自动断电")

// 场景3:前台手动操作
function onManualControl(roomNumber, action):
    // action: "on" 或 "off"
    state = (action == "on")
    controlChannel(roomNumber, state)

4.2 代码示例要点

在实际开发中，需注意：

• 签名生成的时效性：时间戳 ts 通常要求与服务器时间误差在合理范围内（如5分钟）

• 异步执行反馈：对于关键业务（如顾客开单通电），订阅消息推送确认设备实际执行成功，避免因设备离线导致客户投诉

• 通道与包间的映射关系：在业务系统配置表中维护，便于后续调整

五、高级功能与扩展

5.1 定时任务

在芯步控制台可直接为设备配置定时任务（如：每天23:00自动关闭所有包间照明），无需额外开发。支持：

• 循环定时（每日/每周特定时间执行）

• 单次定时（一次性任务）

• 联动定时（传感器触发后执行）

5.2 异步消息推送（获取执行结果）

如需可靠获取设备执行结果，可在业务系统搭建回调接口，接收平台的异步消息推送。消息中包含命令执行状态（成功/失败）及 extra 字段（若下发时携带）。这样可实现：

• 通电失败时自动重试

• 向管理员推送设备异常告警

• 记录完整的操作审计日志

5.3 传感器联动

芯步平台支持设备间联动规则配置。例如：

• 人体传感器检测到包间无人超过30分钟 → 自动断开所有电源

• 烟雾报警器触发 → 立即断开包间电源并推送告警

无需编写代码，在控制台配置联动规则即可。

六、注意事项与最佳实践

6.1 设备安装与负载安全

1. 总功率限制：全接通时总负载不得超过额定值（包间控制器Max总功率约6600W阻性负载）

2. 感性负载注意：电机、LED灯、节能灯为感性负载，实际承载能力约为阻性负载的1/6~1/5

3. 空调接入：第8路为30A专用接口，2匹以内空调可直接接入

4. 安装位置：设备应安装在干燥通风处，避免高温高湿环境

6.2 接口调用优化

1. 局域网优先：如业务系统与设备在同一局域网内，使用私有化部署方式，降低延迟并提高稳定性

2. 重试机制：命令下发超时或返回错误码时，采用随机间隔（或逐次增大间隔）策略重试（如间隔1s、2s、4s，最多3次）

3. 批量控制：同时控制多个通道时使用 batch 指令，减少网络请求次数

4. 连接保活：设备通过WiFi连接，路由器设置DHCP静态分配，避免设备IP变化（公网模式无需关注）

6.3 系统集成

1. 状态同步机制：在业务系统维护每个包间的期望状态与实际状态缓存，避免因网络波动导致状态不一致

2. 日志记录：所有控制指令应记录数据库（包括通道、目标状态、操作人/订单号、时间、执行结果），便于追溯

3. 异常告警：设备离线或命令执行失败时，应通过短信/钉钉/企微等方式通知运维人员

4. 安全加固：签名密钥 AppSecret 应存储在服务端配置文件中，切勿硬编码或暴露在前端代码

6.4 常见问题排查

七、总结

芯步8路包间电源控制器通过标准HTTP接口，为包间式营业场所提供了便捷、可靠的远程电源管理能力。通过本文介绍的接口对接方案，开发者可在1-2天内完成从设备配网到业务系统集成的全流程开发，实现：

• 自动化：订单驱动电源通断，降低人力成本

• 精细化：每路独立控制，按需供电

• 智能化：定时任务、传感器联动，提升管理效率

• 可扩展：支持私有化部署，适配各类业务系统

如在对接过程中遇到技术问题，芯步提供全程免费技术指导，涵盖选型、对接、走线、安装、调试等各环节。