普通灯具系统交流控制：如何将AC3-10A 计量版电源开关对接到软件项目中_解决方案

CATALOG

芯步AC3-10A计量版支持通过HTTP接口直接控制，无需网关，可快速集成到现有软件系统中。以下是完整的对接方案。

一、产品特性与对接原理

1. 硬件核心参数

型号：UNI-TDQ-AC3-10A-P
负载能力：AC 220V / 10A（最大2200W），满足普通照明回路、LED灯带、大厅吊灯等常见场景。
计量功能：支持电压、电流、功率因数、累计电量实时采集。
网络：Wi-Fi 2.4GHz，设备直连路由器，无需网关，降低硬件成本。

2. 核心开放能力芯步设备的开放接口基于 HTTP/HTTPS 协议，数据格式为 JSON。这意味着无论你的后台是Java、Python、PHP还是Node.js，无论前端是Vue、React还是小程序，只要支持HTTP请求，即可完成对接。

3. 整体架构

flowchart LR
    subgraph A[用户层]
        A1[Web管理端] 
        A2[移动APP/小程序]
    end

    subgraph B[业务层]
        B1[你的应用服务器]
    end

    subgraph C[云端层]
        C1[芯步开放API]
    end

    subgraph D[设备层]
        D1[AC3-10A计量版]
        D2[普通灯具]
    end

    A1 --> B1
    A2 --> B1
    B1 -->|HTTP/JSON指令| C1
    C1 -->|Wi-Fi透传| D1
    D1 -->|物理通断| D2
    D1 -->|电量数据上报| C1
    C1 --> B1

二、对接准备

在开始编码前，需要在芯步开发者后台完成以下准备工作（参考开放平台文档）：

注册企业/开发者账号：登录芯步开放平台。
创建应用：获取 AppId 和 AppSecret。这是你调用API的身份凭证。
添加设备：将AC3-10A计量版设备添加到你的账号下，获取唯一标识 Device ID（如：820720）。同时需要在APP端为设备配置好Wi-Fi网络。

三、核心接口调用实现

1. 接口鉴权机制

所有API请求均需携带签名以确保安全。基本请求地址：http(s)://api.thingboot.com/{AppId}/device/control/?sign={sign}&ts={timestamp}

签名算法简述：通常将 AppSecret、Device ID、timestamp 按字典序排序后拼接，进行MD5或SHA256加密生成 sign。
请求头Content-Type: application/json

2. 远程开关控制（核心功能）

场景：用户点击软件上的“开灯”按钮，通过后台下发给设备。

请求方式：POST
请求Body示例

代码处理逻辑

后端接收前端请求（如 /api/light/switch）。
校验权限后，拼接上述JSON体，并生成签名Header。
向芯步API发起HTTP请求。
设备会在数百毫秒内响应，执行继电器动作。
无论设备当前是本地按键操作还是远程控制，设备状态都会反向推送给服务器。

3. 电量数据读取与监控（计量版特有）

场景：在软件后台实时展示当前灯具的功率或统计日/月耗电量。

通过API主动查询设备状态或接收设备主动推送。

查询Body示例

返回数据解析（预期）设备返回的数据通常包含瞬时功率、累计电量等（需根据具体API文档映射）。可以利用该数据实现 “异常告警” 。例如，灯具正常功率为50W，若检测到功率超过3500W（16A版本阈值），可调用关闭指令保护线路。

4. 消息推送接收（Webhook配置）

为了让软件项目“实时”感知设备状态（如有人通过物理按键关灯了，或者电量异常上报），不能让软件一直轮询。应采用消息推送机制。

设置推送URL：在芯步控制台设置你的服务器回调地址，例如：https://yourdomain.com/api/yoyo/callback。
接收逻辑当AC3-10A状态变化时，芯步服务器会POST JSON数据到你的URL。
你需要做：写一个接口接收这些数据，解析 Device ID 和 Status，更新你本地数据库中的“设备状态”和“最新电量读数”。

四、软件项目集成实战（分场景）

第一种场景：嵌入式Web后台（Vue/React + Java/Go）

后端实现：封装“芯步Service”，统一管理签名生成和设备指令下发。提供一个对内的RESTful接口供前端调用。
前端实现：制作一个开关按钮，点击时调用后端接口 /api/control/light/toggle。利用WebSocket接收后端通过消息推送转发的设备状态变更，实现界面实时反馈——即用户在另一个手机上关灯，当前页面的按钮状态也会自动变为“关闭”而不需刷新页面。

第二种场景：企业微信/钉钉小程序

免登对接：利用小程序的HTTP请求能力，直接或通过云函数调用芯步API。
典型界面：列表页展示所有“会议室灯具”。进入详情页显示“当前功率：45W，今日耗电：0.3kWh”。

五、高级应用与优化策略

定时任务与联动由于AC3-10A支持API控制，你的软件项目可以轻松实现定时策略。

实现路径：在你的服务器设置Cron Job -> 到点触发 -> 调用芯步API关闭灯具。
场景：园区路灯定时开启、写字楼下班后自动关灯。

异常熔断与计量预警通过分析计量数据，软件可以实现“软熔断”。

逻辑：监控API推送过来的功率值。
动作：如果电流超过10A（如检测到功率 > 2500W），软件自动调用关闭指令，并发送告警给物业人员，这比物理空开更灵敏且具备数据记录。

混合组网（私有化部署）针对对数据安全要求比较高的客户（如政府大楼、军工单位），芯步支持私有化部署。对接方式不变，只需将API地址从公网改为局域网的服务器IP即可，所有数据不出园区。

六、常见问题与排障

问题现象	可能原因与分析
调用API返回签名错误	时间戳无效或签名算法中参数未按字典序排序。检查服务器时间是否标准。
指令下发成功但灯未亮	检查AC3-10A设备是否在线（如Wi-Fi信号弱）。若指示灯异常，需重新配网。
无法接收电量数据	确认购买的是“计量版”型号。普通版仅支持控制，无计量芯片。
局域网延时高	如果设备与服务器在同一局域网，开启“局域网发现”模式直连，避免数据绕行外网再回来。