怎样二次开发AC3-10A 计量版能耗通断器来实现远程开关状态查询_解决方案

CATALOG

AC3-10A计量版的核心优势在于其全开放的HTTP接口——无需网关、支持局域网私有化部署，签名机制也相对简单。下面从环境准备、签名算法、状态查询指令到代码实现，梳理完整的二次开发方案。

一、解决概述

本方案的目标是指导开发者利用芯步开放的HTTP API，对 AC3-10A 计量版能耗通断器 进行二次开发。通过调用特定的接口指令，实现对设备当前开关状态的远程查询。

不同于传统的轮询方式，AC3-10A 作为一款“计量版”设备，不仅支持状态查询，还支持电压、电流、功率等能耗数据的实时读取，适合用于能源管理系统、智能家居网关集成或工业设备监控场景。

二、准备工作与环境配置

在代码开发之前，需要完成以下基础配置，以确保API调用能够通过鉴权：

获取关键凭证
- 登录芯步IoT控制台。
- 在“开发设置”中，获取 AppId（开发者ID）和 AppSecret（开发者密码）。这两个字段是生成签名的核心要素。
获取设备ID
- 在控制台的“设备列表”中找到已配网的 AC3-10A 计量版设备。
- 记录下 Device ID（设备唯一ID），请求时需要此字段来指定目标设备。
网络环境确认
- AC3-10A 支持 WiFi 2.4G 直连，无需网关，确保设备与二次开发的服务端网络互通即可。
- 支持私有化部署和局域网直连，若在内网环境可将 api.thingboot.com 替换为私有化服务器地址。

三、核心逻辑：签名机制

芯步的接口通过动态签名进行安全校验。二次开发时，必须按照以下规则生成 sign 参数，否则接口会拒绝访问。

签名算法步骤如下（以 Python 逻辑为例）

将 AppSecret 进行 MD5 加密，得到字符串 S1。
获取当前的 Unix 时间戳ts （单位：秒）。
将 S1 与 ts 进行拼接，形成新的字符串 S2。
将 S2 再次进行 MD5 加密，得到最终的 sign。

公式化表述sign = MD5( MD5(AppSecret) + ts )

注意：时间戳 ts 需要作为参数明文一同传递，服务端会用同样的算法进行比对。时间戳的有效期一般为几分钟，防止请求被重放攻击。

四、接口调用与状态查询实现

AC3-10A 系列产品的控制与状态查询使用统一的 HTTP 接口地址，通过 order 字段中的不同命令来区分操作类型。

请求地址： http(s)://api.thingboot.com/{AppId}/device/control/
请求方法： POST
请求参数（Query String）：
- sign：按上述规则生成的签名。
- ts：生成签名时使用的时间戳。
请求体（Body JSON）：
- device：目标设备的ID。
- order：具体的指令 JSON 对象。

1. 查询实时状态与能耗

要查询 AC3-10A 的当前通断状态及计量数据，需要发送 metering 命令。

功能：该命令用于读取设备的实时电量参数，其中包含开关状态、电压、电流、功率等。
指令代码： {"metering":""} 或 {"metering":"all"}

请求示例（JSON）

设备响应解析接口会返回一个包含多字段的 JSON 数据。开发者在解析时重点关注以下字段以判断开关状态

power / status：代表当前开关状态（通常 1=闭合/通电，0=断开/断电）。
voltage：当前电压。
current：当前电流。
apower：有功功率。

2. 辅助方案：控制指令的副作用

虽然 metering 是获取状态的标准做法，但开发者也可以利用“控制指令”的返回包来确认状态变更（原子操作）。

查询开关状态：通过 power 命令获取。部分版本的设备支持直接查询状态。
指令代码： {"power":""} （发送空值或不带数值的key，可能返回当前状态）。

在实际开发中，优先使用 metering 接口，因为它不仅反馈状态，还附带能耗数据，有助于构建更完善的监控看板。

五、代码开发示例

以下伪代码演示了如何封装一个查询 AC3-10A 设备状态的函数。该逻辑适用于任何支持 HTTP 请求的语言。

1. Python 实现示例

import hashlib
import time
import requests
import json

def query_device_status(app_id, app_secret, device_id):
    # 1. 准备时间戳和签名
    ts = str(int(time.time()))
    
    # 2. 生成签名: md5(md5(AppSecret) + ts)
    md5_secret = hashlib.md5(app_secret.encode()).hexdigest()
    sign_str = md5_secret + ts
    sign = hashlib.md5(sign_str.encode()).hexdigest()
    
    # 3. 拼接 URL
    url = f"https://api.thingboot.com/{app_id}/device/control/"
    params = {
        "sign": sign,
        "ts": ts
    }
    
    # 4. 构造请求体 - AC3计量版查询命令
    payload = {
        "device": device_id,
        "order": {
            "metering": "all"  # 获取全部计量信息及状态
        }
    }
    
    headers = {
        'Content-Type': 'application/json'
    }
    
    # 5. 发送请求
    response = requests.post(url, params=params, headers=headers, data=json.dumps(payload))
    
    if response.status_code == 200:
        res_data = response.json()
        # 解析开关状态（具体字段路径请参照实际返回文档，通常类似 data.status）
        # 假设返回 data 中包含 status 字段
        print("设备状态查询成功")
        print("实时状态:", res_data)
        # 提取开关状态 (示例，需根据实际返回结构调整)
        # status = res_data.get('status') 
        # return status
    else:
        print(f"查询失败，状态码: {response.status_code}")

2. 关键注意事项

计量数据的读取频率：虽然 AC3-10A 响应很快（80-120ms），但高频读取计量数据可能会增加设备 WiFi 模块的负载。在实际应用中，设定合理的轮询间隔（如 5-10 秒一次）。
局域网直连：如果希望减少公网延迟，可在控制台配置私有化方案。此时，API 地址需更换为自建服务器的 IP，签名机制不变，完全离线运行，适合对数据安全要求高的生产环境。
调试模式：在开发测试阶段，可以在控制台“开发设置”中开启“调试模式”。在该模式下，系统将 关闭签名(sign)和时间戳(ts)校验，方便开发者优先调试业务逻辑，上线前再关闭即可。

六、总结

通过对 AC3-10A 计量版能耗通断器的二次开发，开发者可以在 10-20 分钟内完成核心的对接工作。只需掌握“MD5 双重加密”的签名机制，并向标准接口发送结构化的 metering 或 power 指令，即可准确获取设备的开关状态与能耗参数。这种低成本、高效率的集成方式，使得 AC3-10A 能够快速融入各类智慧用电解决方案中。