怎样二次开发4 路智能远程照明控制器以实现远程定时任务_解决方案

CATALOG

芯步的4路智能照明控制器（型号UNI-KZQ-ZM-4）通过开放HTTP接口，可以灵活地实现二次开发。这篇方案会从接口准备、设备控制，到定时任务的完整实现（轮询和Cron两种方式）逐步说明，最后还会覆盖一些批量控制和延时操作的进阶用法。

一、前期准备与接口认知

在开始写代码之前，我们先得把手里的“家伙事儿”搞清楚。芯步的这套4路控制器（型号通常为 UNI-KZQ-ZM-4）说白了就是一个能联网的智能开关盒，只不过它里面有4个独立的继电器，可以分别控制4路灯光或电器。

要让它听话，核心就是调用他们的 HTTP 开放接口。哪怕你用 C 语言、Node.js、Python，甚至是 Postman，只要能发 HTTP POST 请求，就能控制它。

你需要提前拿到三个关键凭证：

AppID：你的应用唯一标识。
AppSecret：你的应用密钥（千万别泄露，虽然我们口语化交流，但这个规矩不能破）。
Device ID：就是那个4路控制器的设备编号（在芯步控制台后台能看到，比如截图里的 1878）。

这里有一个小小的“拦路虎”——签名计算。不过别怕，芯步的签名算法其实很直白：

公式sign = md5( md5(AppSecret) + ts )解释：先把你的 AppSecret 做一次 MD5 加密，然后把结果字符串加上当前的时间戳（ts），把拼接起来的新字符串再做一次 MD5。

举个栗子（伪代码）：假设 AppSecret = "abc123"，当前时间戳 ts = 1712345678。第一步：hidden_secret = md5("abc123") -> 得到 "xxxxxx"第二步：sign = md5("xxxxxx" + "1712345678") -> 得到最终签名。（注：ts 是秒级时间戳，请求的时候也要带上这个 ts）

二、最基础的操作：直接控制开关

这是我们二次开发的“地基”。我们要向这个地址发送 POST 请求：https://api.thingboot.com/{你的AppId}/device/control/?sign={计算好的签名}&ts={当前时间戳}

请求体（Body） 是一个 JSON，里面包含设备 ID 和命令。

场景1：上班打卡，全楼灯亮我想把第1路和第3路的灯打开（让“power1”和“power3”的值为 1）。

场景2：下班跑路，全关把控制器的 4 路全部关掉（值为 0）。

只要看到 HTTP 返回状态码 200 或者接口返回的 code 为 200，就说明指令已经下发，设备会在毫秒级（大约 80-120ms）内响应。

三、核心功能实现：远程定时任务

实现“定时任务”有两条路：死磕派（自建轮询） 和 偷懒派（云平台定时）。

鉴于题目要求的是“二次开发”，说明你可能想把定时逻辑集成到你自己的系统里（比如家里的 Home Assistant 或者公司的 ERP 系统）。这里介绍方案一：自建定时脚本。

假设你有一台服务器（或者树莓派），我们写一个简单的 Python 脚本，利用 schedule 库或者系统的 cron 作业来实现。

需求场景

每天 08:00 打开第 1 路（上班开灯）。
每天 18:00 关闭第 1 路（下班关灯）。

解决逻辑我们需要将上述“基础操作”中的 JSON 请求，塞进一个定时执行的函数里。

下面这段代码逻辑比较通俗（伪代码/Python 风格），主要看逻辑思路：

import requests
import hashlib
import time
import schedule

# 配置参数
APP_ID = "你的AppID"
APP_SECRET = "你的AppSecret"
DEVICE_ID = "1878"
API_URL = f"https://api.thingboot.com/{APP_ID}/device/control/"

def control_light(route, action):
    # 1. 准备时间戳和签名（重复利用上面的规则）
    ts = int(time.time())
    sign_step1 = hashlib.md5(APP_SECRET.encode()).hexdigest()
    sign = hashlib.md5((sign_step1 + str(ts)).encode()).hexdigest()
    
    # 2. 构造命令
    # 注意:order 里的 key 是动态的，比如 power1, power2
    command_key = f"power{route}"
    payload = {
        "device": DEVICE_ID,
        "order": {command_key: action} # action 是 1 或 0
    }
    
    # 3. 发送请求
    params = {"sign": sign, "ts": ts}
    response = requests.post(API_URL, json=payload, params=params)
    print(f"执行操作:{command_key} -> {action}，结果:{response.text}")

# 设定定时任务
schedule.every().day.at("08:00").do(control_light, route=1, action=1)
schedule.every().day.at("18:00").do(control_light, route=1, action=0)

print("定时任务已启动，正在监控...")
while True:
    schedule.run_pending()
    time.sleep(1)

进阶玩法（延时/闪烁）有时候我们不仅想定时开，还想让它亮一下就关。比如走廊灯，感应到人之后打开，5分钟后自动关闭。这时候不需要你自己去写“睡5分钟再发关灯指令”，芯步的接口支持设备端自带延时。你只需要在 order 里这么发

这就实现了“点动”或“定时关闭”，哪怕你的服务器断电了，设备自己也会在 2 分钟后关上灯，非常可靠。

四、场景拓展：批量控制与状态读取

既然都二次开发了，肯定不会只控制一台设备。

1. 批量控制多台设备

如果你的“device”参数想控制多台，直接传 ID 用英文逗号隔开就行"device": "1878, 1880, 1881"

2. 批量同时控制多线路

刚才我们用了 power1 和 power3 分别控制。如果想更简洁，或者控制复杂的组合，可以用 batch 命令

3. 获取当前状态（同步）

这是为了让你知道灯到底亮没亮。芯步平台提供了获取任务列表或设备状态的接口。你可以调用 task/list 接口来确认你之前设置的定时任务是否生效，或者通过设备的事件推送来感知状态变化（比如有人按了设备的物理按键，平台会推送给你的服务器）。

五、总结与避坑指南

总结一下这套二次开发方案的流程：

拿钥匙：计算 sign 签名，带上 AppId。
写命令：构建 JSON，指定 device 和 order（power1/power2...）。
发请求：POST 到 api.thingboot.com。
做定时：在你的服务器上写个 Cron 脚本或者用 Python 的 schedule 库，到点触发步骤 1-3。

几个容易踩的小坑，帮你提前避开：

WiFi频段：这个设备只支持 2.4GHz WiFi。如果你用 5GHz 是配不上网的，二次开发前记得确认网络环境。
签名时间戳：客户端和服务器的时间要同步。如果你的服务器时间比标准时间快了几分钟，签名校验很容易失败（Invalid signature）。
负载功率：虽然是二次开发，但硬件规格要心里有数。单路最大通常 10A/2200W（阻性负载），别把几万瓦的工厂机器直接接上去，会烧继电器的。
局域网控制：如果你不想走云端，其实芯步也支持局域网或私有化部署。如果你想在内网环境下低延迟控制，可以查阅他们的局域网 API 文档，原理类似，IP 换成设备的内网 IP 就行。

希望这份方案能帮你顺利搞定 4 路控制器的二次开发！如果遇到具体的代码报错，记得检查一下 JSON 格式和 sign 的 MD5 大小写（一般是小写十六进制）。