自助储物柜控制：怎么把24路智能线路控制器接入到软件项目中_解决方案

CATALOG

芯步的24路智能线路控制器采用HTTP接口对接，签名算法为 md5(md5(AppSecret) + ts)，任何能发起HTTP请求的编程语言都可接入。以下是完整的集成方案，涵盖接口协议、签名计算、核心代码示例及储物柜业务逻辑设计。

解决方案：自助储物柜控制系统——24路智能线路控制器集成方案

1. 总览

本项目旨在将芯步 UNI-KZQ-TY-24（智能通用控制器24路） 集成到现有的自助储物柜软件系统中。该设备支持 WiFi 2.4G 直连，无需网关，且开放标准的 HTTP API 接口。通过集成，软件系统可以实现对最多24个储物格口的独立开锁、状态查询及远程控制。

2. 硬件与接口概述

核心设备：智能通用控制器24路（UNI-KZQ-TY-24）。
核心能力：提供24路物理线路控制，对应24个独立的电磁锁或电控锁。
通信协议：HTTP/HTTPS。
通信模式
- 下行（控制）：软件系统通过调用芯步云端API或本地API（支持私有化部署）下发指令。
- 上行（状态）：设备状态实时上报到软件指定的服务器。
技术优势：接口极其简单，适用于任何支持HTTP请求的编程语言（Java, Python, PHP, Go, Node.js等）。

3. 软件集成设计

推荐采用请求响应+状态监听的架构模式：

业务层（APP/小程序/后台） ：用户发起“存物/取物”请求。
业务服务器（您的软件） ：处理用户鉴权、订单逻辑，并调用芯步API。
芯步云/私有化服务器：透传或执行控制指令。
24路控制器（硬件） ：执行开锁动作，并回传锁状态（如门磁信号）。

4. 核心接口对接流程

在开始编码前，需要在芯步开发者后台获取以下凭证：

AppID：应用唯一标识。
AppSecret：密钥，用于接口签名验证。
Device ID：设备的唯一ID（在控制台绑定获得）。

4.1 接口鉴权（签名算法）

芯步的API通过携带 sign和ts（时间戳）的方式保证安全性。依据其接口定义，签名生成算法逻辑如下

公式sign = md5（ md5（AppSecret） + ts ）

Step 1：对开发者后台的 AppSecret 进行 MD5 哈希，得到 secret_md5。
Step 2：将 secret_md5 与当前精确到秒的 Unix 时间戳 ts （如 1715328000）进行字符串拼接。
Step 3：对拼接后的字符串再次进行 MD5 哈希，得到最终的 sign。

4.2 控制单个柜门（下发命令）

业务场景：用户扫码支付成功或管理员点击“开门”，系统需要打开第3个柜门（对应物理线路 3）。

请求URLhttps://api.thingboot.com/{AppId}/device/control/？sign={sign}&ts={ts}
请求方式：POST
请求头：Content-Type： application/json
请求体（Body）：

注意power1代表第一路，power3代表第三路。如果需要关闭，发送 {“power3”： 0}。

4.3 批量控制/全开全关

业务场景：管理员下班清理储物柜或系统初始化，需要一次性打开所有柜门。

由于24路控制器支持多线路，order 对象中可包含多个线路指令：

4.4 接收设备实时状态（消息推送/回调）

业务场景：用户取完物品关门后，系统需要立即知道“柜门已关闭”状态，以便标记订单完成；或检测到门磁异常时触发报警。

软件系统需要提供一个公网可访问的 HTTP 回调接口（Webhook）。

配置：在芯步控制台中，将 “消息推送地址” 配置为： https://your-server.com/api/callback/device_status
接收的数据格式：当第3路开关状态发生变化或有门磁信号时，芯步会向该地址发送POST JSON数据包。
处理逻辑：解析包中的 device_id 和线路状态，更新数据库中的“柜门状态”。

5. 业务逻辑代码示例（伪代码/逻辑示意）

以下是以 Python （Flask）和 Java （Spring Boot）为例的核心逻辑，演示如何将 HTTP 指令转化为储物柜业务。

Python 示例

import hashlib
import time
import requests
import json

class LockerController:
    def __init__（self, app_id, app_secret, device_id）:
        self.app_id = app_id
        self.app_secret = app_secret
        self.device_id = device_id
        self.api_url = f"https://api.thingboot.com/{app_id}/device/control/"

def _generate_sign（self, ts）:
        # 签名算法: md5（ md5（secret） + ts ）
        step1 = hashlib.md5（self.app_secret.encode（））.hexdigest（）
        sign_str = step1 + str（ts）
        return hashlib.md5（sign_str.encode（））.hexdigest（）

def open_box（self, slot_number）:
        """开启指定格子 （1-24）"""
        if slot_number < 1 or slot_number > 24:
            return False
        
        ts = int（time.time（））
        sign = self._generate_sign（ts）
        
        # 构建命令:例如 open slot 3 -> "power3": 1
        order_key = f"power{slot_number}"
        payload = {
            "device": self.device_id,
            "order": {order_key: 1}  # 1 for on/activate
        }
        
        response = requests.post（
            url=self.api_url,
            params={"sign": sign, "ts": ts},
            json=payload,
            timeout=5
        ）
        
        if response.status_code == 200:
            result = response.json（）
            # 根据芯步返回码判断成功与否 （假设 status: success）
            return result.get（"status"） == "success"
        return False

# 调用示例
if __name__ == "__main__":
    locker = LockerController（"your_AppId", "your_AppSecret", "device_123456"）
    # 用户点击存物，分配了 08号柜
    locker.open_box（8）

Java 示例

@Component
public class YoyoLockerService {
    @Value（"${yoyo.appId}"） private String appId；
    @Value（"${yoyo.secret}"） private String secret；
    
    private String generateSign（long ts） {
        String step1 = DigestUtils.md5DigestAsHex（secret.getBytes（））；
        String step2 = step1 + ts；
        return DigestUtils.md5DigestAsHex（step2.getBytes（））；
    }
    
    public void openDoor（int channel） {
        long ts = System.currentTimeMillis（） / 1000；
        String sign = this.generateSign（ts）；
        
        RestTemplate rest = new RestTemplate（）；
        String url = "https://api.thingboot.com/" + appId + "/device/control/？sign=" + sign + "&ts=" + ts；
        
        Map<String, Object> body = new HashMap<>（）；
        body.put（"device"， "your_device_id"）；
        
        Map<String, Integer> order = new HashMap<>（）；
        order.put（"power" + channel, 1）；
        body.put（"order"， order）；
        
        HttpEntity<Map> entity = new HttpEntity<>（body）；
        ResponseEntity<String> response = rest.exchange（url, HttpMethod.POST, entity, String.class）；
        
        // 处理响应
        System.out.println（response.getBody（））；
    }
}

6. 私有化部署与局域网方案

针对安全性要求比较高的场景（如保密单位、校园、没有外网的地下停车场），该设备支持纯局域网工作。

方案：部署一个本地服务，将上述API地址切换为局域网内服务器的地址。
优势：数据完全不经过外网，响应速度可低至 80-120ms。

7. 高级功能与用户体验优化

结合芯步生态和其他硬件，可进一步优化自助储物柜的体验：

语音联动
- 设备：智能语音喇叭。
- 场景：当用户扫码成功，24路控制器打开门时，同步调用语音API播报：“B区的08号柜门已打开，请存放物品，记得关好门哦。”
- 实现：您的后端在处理完开门逻辑后，紧接着调用一次语音设备接口即可。
传感联动（安全监控）
- 设备：智能人体存在传感器。
- 场景：实时监控柜体内部或维修口是否有人员活动，结合继电器实现“有人自动照明”或“非法入侵立即报警并上报服务器”。

8. 总结

通过集成芯步 UNI-KZQ-TY-24 控制器，您的软件开发团队只需关注 HTTP 接口的 sign 签名计算 和 业务逻辑（如分配的格子序号 powerX） ，无需深入底层无线通讯开发。

实施检查表：

获取 AppID/Secret 和设备 ID。
后端实现 签名工具类（重点：md5嵌套） 。
实现 open（slot） 核心函数.
（可选）配置回调地址，接收开关门状态。
在 UI/UX 上设计 24 个直观的格子图标。