如何二次开发智能密码门禁|按键版以实现远程定时任务_解决方案

CATALOG

针对芯步智能密码门禁（按键版）的开放接口，以下是实现远程定时任务的二次开发解决方案。

1. 背景与目标

芯步智能密码门禁（按键版）不仅支持本地键盘密码验证，还全面开放了HTTP API接口。这意味着开发者可以通过编程方式远程控制门禁。本方案的目标是指导开发者如何利用该接口进行二次开发，实现定时任务功能（例如：公司工作日9:00-18:00自动解锁、深夜时段自动锁定、快递员特定时段临时密码下发等）。

2. 核心原理

由于门禁设备本身不具备复杂的定时逻辑存储能力，二次开发的核心架构采用 “服务器/云主机轮询或定时触发” 模式：

设备层：芯步物安门禁设备连接WiFi，长连接云端API。
开发层：开发者拥有一台服务器（或支持定时任务的SaaS平台/Python脚本环境）。
逻辑层：在服务器上编写脚本，设定Cron Job（定时任务）。到达指定时间，服务器向芯步API发起HTTP请求。
执行层：API验证签名后，向指定设备ID下发order指令（如开门、关门、复位）。

3. 准备工作

在开始二次开发前，请确保完成以下配置：

硬件就绪：已将“智能密码门禁[按键]”连接至2.4G WiFi网络（无需网关）。
获取凭证
- AppID：应用ID，在芯步控制台获取。
- AppSecret：开发者密码，用于计算签名。
- Device ID：设备的唯一ID 。
开发环境：任何支持HTTP请求的语言（Python、Node.js、Java、Shell等）或带有Webhook的低代码平台。

4. 接口鉴权详解

芯步的API采用双重MD5签名机制，这是开发中唯一的技术难点，具体签名逻辑如下

签名算法sign = md5( md5(AppSecret) + ts )
1. 将 AppSecret 进行MD5加密，得到字符串 S1。
2. 将 S1 与当前Unix时间戳（秒，即 ts）拼接，得到新字符串 S2 = S1 + ts。
3. 将 S2 再次进行MD5加密，得到最终的 sign。
请求地址https://api.thingboot.com/{AppID}/device/control/?sign={sign}&ts={ts}

5. 指令集与参数说明

针对“按键版”门禁，常用的order指令格式如下（根据产品手册整理）

功能描述	Order JSON 格式	适用场景
远程开门	`{"power":1}` 或 `{"power":0}`	控制锁继电器吸合，实现常开或点动开门。
设置密码	`{"pwd":"123456"}`	远程修改或添加管理密码。
删除密码	`{"delete":"123456"}`	删除特定密码。
清空所有密码	`{"clear":"clear"}`	恢复出厂设置（清空所有用户凭证）。
定时复位	`{"reset":5000}`	实现“点动开门”：接通（开门），保持5秒（5000ms）后自动断开（锁门）。
定时点动	`{"point":3000}`	实现“短暂解锁”：断开（上锁），3秒后自动接通（通常用于门磁复位）。

6. 实现“远程定时任务”的三种方案

以下是针对不同技术栈的二次开发实施方案：

方案一：轻量级Shell脚本 + Crontab（适合Linux服务器/树莓派）

适用场景：办公室固定时间开关门、低成本服务器运维。

步骤

编写 control_door.sh 脚本，封装API调用逻辑。
在脚本中定义开门函数，调用 https://api.thingboot.com/... 并携带签名。
使用Linux的 crontab -e 设置定时任务。

核心代码逻辑 (Bash + Curl参考) ：

Crontab设置示例

方案二：Python + 调度库（APScheduler / 云函数）

适用场景：需要更复杂的业务逻辑（如记录日志、异常重试、节假日排除）。

核心逻辑利用Python的 requests 库进行HTTP调用，利用 schedule 或 APScheduler 管理时间。

开发步骤

安装依赖pip install requests schedule
实现签名算法
import hashlib, time, requests, json def generate_sign(secret, ts): # MD5(MD5(Secret) + ts) s1 = hashlib.md5(secret.encode()).hexdigest() s2 = s1 + str(ts) return hashlib.md5(s2.encode()).hexdigest() def remote_control(order_json): ts = int(time.time()) sign = generate_sign(APP_SECRET, ts) url = f"https://api.thingboot.com/{APP_ID}/device/control/" params = {'sign': sign, 'ts': ts} payload = {"device": DEVICE_ID, "order": order_json} response = requests.post(url, params=params, json=payload) print(f"指令下发结果: {response.text}") # 定义具体任务 def morning_unlock(): # 早上9点执行点动开门，持续5秒 remote_control({"reset": 5000})
部署定时
- 传统服务器：运行脚本并保持后台运行。
- Serverless（推荐）：将代码打包为阿里云/腾讯云函数，配置触发器的Cron表达式，无需维护服务器。

方案三：可视化低代码 / IoT规则引擎（适合非专业开发者）

适用场景：不想写代码、希望快速搭建原型。

原理：使用支持HTTP节点的SaaS工具（如智汀、Node-RED、或芯步自带的SaaS后台）。

实现

在芯步控制台找到“设备联动”或“场景自动化”。
添加条件：“定时”（例如：每天14:00）。
添加动作：“控制设备” -> 选择“智能密码门禁” -> 动作选“点动开门”。注：如果官方SaaS界面未提供该选项，可使用Node-RED等第三方工具，拖拽一个“Inject”(定时)节点连接“HTTP Request”节点完成POST请求。

7. 进阶应用：动态临时密码与审计

利用API接口，可以将定时任务与业务系统深度结合

定时生成临时密码
- 场景：家政服务时段为14:00-16:00。
- 实现：服务器在13:55 调用 {"pwd":"1234"} 设置一个时效密码；并在 16:05 调用 {"delete":"1234"} 删除该密码，确保安全。
审计日志
- 虽然门禁设备本身有日志，但二次开发时，服务器在每次执行开门指令后，落库记录（时间、操作人、指令结果），方便事后追溯。

8. 注意事项与最佳实践

网络稳定性：该设备仅支持2.4G WiFi，确保门禁安装位置信号强度良好。
接口超时与重试：若网络波动导致API返回失败，业务系统需设计随机间隔（或逐次增大间隔）重试机制（最多重试3次），避免重复发单导致多次开门。
Token缓存：虽然目前是签名机制，但如果高频调用，注意服务器时间同步（NTP），避免因服务器时间误差导致签名过期。
复位指令的使用：在“远程开门”场景下，请一定要使用 reset 参数（如 {"reset":5000}），这样门锁会在几秒后自动锁闭，防止因程序逻辑错误导致门一直开着。