怎样对接吸顶式人体存在红外传感器以实现HTTP接口远程控制_解决方案

CATALOG

一、概述

1.1 产品简介

芯步智能人体存在红外传感器（吸顶式，型号：UNI-CGQ-RT-XD-H）是一款基于被动红外技术的人体存在检测设备，采用吸顶式安装设计，适用于室内场景的人体移动侦测。该设备支持WiFi 2.4GHz直连接入，无需额外网关，核心优势在于提供开放的HTTP API接口，支持第三方系统通过HTTP协议远程获取设备状态及控制设备参数。

1.2 解决方案定位

本方案面向集成商、开发者及企业IT部门，解决以下核心需求：

将人体存在传感器数据对接到自有业务系统（如楼宇自控、智慧照明、安防联动等）
通过HTTP接口实现远程配置和控制传感器参数
接收设备主动上报的状态变化事件
支持局域网或公网环境下的私有化部署

1.3 技术架构概览

整体采用“设备-云平台-应用系统”的三层架构，开发者可通过芯步开放平台完成设备接入，使用HTTP协议进行指令下发和消息订阅。

二、接口对接准备

2.1 账号与凭证获取

在进行接口调用前，需完成以下准备：

步骤	操作	说明
1	注册芯步开放平台账号	访问平台官网完成注册
2	创建应用	在控制台创建应用，获取 AppId 和 AppSecret
3	添加设备	扫描设备二维码或手动输入设备ID完成设备添加
4	获取设备ID	设备外壳标签或控制台均可查看

2.2 设备联网配置

设备通电后进入配网模式，需将设备连接至2.4GHz WiFi网络。设备支持配置最多5组WiFi，会自动选择信号最优的网络连接。

2.3 签名说明

所有HTTP接口请求需携带签名参数进行身份验证，签名算法如下：

sign = md5(md5(AppSecret) + ts)

参数说明：

AppSecret：应用密钥，在控制台获取
ts：Unix时间戳（秒），请求时需传递当前时间戳
sign：最终签名值

签名计算示例（伪代码）：

考虑到时间戳的有效性，客户端与服务器时间保持同步，时间戳误差不应超过5分钟。

2.4 接口基础信息

项目	说明
请求地址	`http(s)://api.thingboot.com/{AppId}/device/control/?sign={sign}&ts={ts}`
请求方式	POST
数据格式	JSON
Content-Type	`application/json`

三、设备物模型详解

理解设备的物模型是对接开发的基础。该传感器主要包含以下属性、命令和事件。

3.1 状态属性（可读写）

属性	标识符	数据类型	值说明	功能描述
红外模块开关	`infrared_enable`	int	1=打开，0=关闭	启用/禁用红外感应功能
红外感应状态	`infrared_target`	int	1=有人，0=无人	当前人体存在检测结果（只读）
线路控制	`power`	int	1=通/开，0=断/关	控制设备内置继电器输出

3.2 系统命令

所有设备均支持以下系统级命令：

命令内容	功能说明
`{"system":"network"}`	查询设备网络信息（信号强度、IP地址等）
`{"system":"restart"}`	软重启设备，保持当前状态
`{"system":"reboot"}`	硬重启设备，放弃当前状态

3.3 设备触发事件

设备状态变化时会主动推送事件至配置的服务器：

事件标识	触发条件
`btn1`	设备上的按钮被按下
`infrared_detect`	红外检测状态发生变化（有人↔无人）
`relay1`	线路状态发生变化

3.4 可配置项

设备的运行行为可通过配置项进行调整，常用配置如下：

配置项	标识符	可选值	说明
LED指示灯模式	`led`	rl_s（与线路同步）、rl_r（与线路相反）、ss_s（与感应同步）、ss_r（与感应相反）、1（长亮）、0（长灭）、blink（闪烁）	控制LED指示灯的显示逻辑
红外开机状态	`infrared`	1（打开）、0（关闭）	设备通电后红外模块的初始状态
有人触发持续时间	`infrared_change_1`	0（马上）、1、2、3、5（秒）	检测到有人后上报延迟
无人触发持续时间	`infrared_change_0`	0~600（秒/分钟）	检测到无人后上报延迟（最长10分钟）
线路开机状态	`relay1`	1（通）、0（断）	设备通电后线路的初始状态
发现有人时线路动作	`relay_change_1`	1（打开）、0（关闭）、no（无动作）	感应到有人时的自动联动
发现无人时线路动作	`relay_change_0`	1（打开）、0（关闭）、no（无动作）	感应到无人时的自动联动

四、核心接口调用

4.1 向设备下发指令

设备控制接口用于向指定设备发送命令，支持单设备或多设备批量控制。

请求示例：

请求参数：

参数	必填	类型	说明
device	是	string	设备ID，多设备用逗号或竖线分隔（最多100个）
order	是	object/string	命令内容，JSON对象格式
gateway	否	string	网关设备ID（本设备为WiFi直连，无需填写）

常用命令示例：

1. 控制继电器线路接通

2. 开启红外感应模块

3. 查询设备网络信息

4. 重启设备

5. 携带业务标识的命令

使用 extra 字段可在命令中携带业务订单号等标识信息，设备响应消息中将原样返回，便于异步回调时进行业务关联。

响应结果：

状态码说明：

code	说明
200	命令下发成功（仅表示平台已接收，不代表设备已执行）
501	未指定设备ID
502	设备不存在或无权限
503	设备数量超限（超过100个）
504	部分设备不可用

重要提示：返回200仅代表平台成功接收到指令并向设备下发，不代表设备已实际执行。如需确认设备执行结果，需通过消息推送机制接收异步反馈。

4.2 接收设备状态上报

传感器设备主要是上行消息，当环境状态变化（人体存在状态变化、温湿度变化等），设备会实时上报状态消息到您的服务器。

开发者需在控制台配置消息接收服务器地址（Webhook URL），平台会将设备上报的数据通过HTTP POST方式推送到该地址。

推送数据格式示例：

典型推送事件类型：

事件类型	触发场景	数据字段
`infrared_detect`	红外检测状态变化	infrared_target (1有人/0无人)
`relay1`	线路状态变化	power (1通/0断)
`boot`	设备开机上线	当前所有属性状态

4.3 修改设备配置项

配置项的修改通过在控制台进行操作，平台未开放批量修改配置的接口，主要原因在于配置项存储在设备Flash中，频繁擦写可能影响设备寿命。

如确需通过接口修改，可使用通用命令格式：

以上命令将LED指示灯设置为“与感应同步”模式（有人时长亮，无人时熄灭）。

五、典型应用场景与代码示例

5.1 第一种场景：智能照明联动

需求描述：会议室中，当传感器检测到有人时自动开灯，无人超过5分钟自动关灯。

实现方案：通过配置设备自身的联动规则即可实现，无需额外开发。

设备配置：

配置项	设置值	说明
`relay_change_1`	1	检测到有人时，线路自动接通（开灯）
`relay_change_0`	0	检测到无人时，线路自动断开（关灯）
`infrared_change_0`	300	无人状态持续5分钟后触发上报和联动

5.2 第二种场景：HTTP API远程控制线路

需求描述：第三方系统通过HTTP接口远程控制传感器的继电器输出（如控制排风扇、门锁等）。

Python代码示例：

import hashlib
import time
import requests
import json

class YoyoiotController:
    def __init__(self, app_id, app_secret):
        self.app_id = app_id
        self.app_secret = app_secret
        self.base_url = f"https://api.thingboot.com/{app_id}/device/control/"
    
    def _generate_sign(self, ts):
        # 第一步:对AppSecret进行MD5加密
        md5_secret = hashlib.md5(self.app_secret.encode()).hexdigest()
        # 第二步:拼接加密后的密钥和时间戳
        sign_str = md5_secret + str(ts)
        # 第三步:再次MD5加密得到最终签名
        sign = hashlib.md5(sign_str.encode()).hexdigest()
        return sign
    
    def control_device(self, device_id, order):
        ts = int(time.time())
        sign = self._generate_sign(ts)
        
        url = f"{self.base_url}?sign={sign}&ts={ts}"
        payload = {
            "device": device_id,
            "order": order
        }
        
        response = requests.post(url, json=payload)
        return response.json()
    
    def turn_on_relay(self, device_id):
        """打开继电器（接通线路）"""
        return self.control_device(device_id, {"power": 1})
    
    def turn_off_relay(self, device_id):
        """关闭继电器（断开线路）"""
        return self.control_device(device_id, {"power": 0})
    
    def enable_infrared(self, device_id):
        """开启红外感应"""
        return self.control_device(device_id, {"infrared_enable": 1})
    
    def get_device_network(self, device_id):
        """查询设备网络状态"""
        return self.control_device(device_id, {"system": "network"})

# 使用示例
if __name__ == "__main__":
    # 初始化（替换为实际值）
    controller = YoyoiotController("your_app_id", "your_app_secret")
    
    # 控制设备
    device_id = "820720"
    
    # 开灯
    result = controller.turn_on_relay(device_id)
    print(f"开灯结果: {result}")
    
    # 关灯
    result = controller.turn_off_relay(device_id)
    print(f"关灯结果: {result}")

Node.js代码示例：

const crypto = require('crypto');
const axios = require('axios');

class YoyoiotController {
    constructor(appId, appSecret) {
        this.appId = appId;
        this.appSecret = appSecret;
        this.baseUrl = `https://api.thingboot.com/${appId}/device/control/`;
    }

generateSign(ts) {
        // 第一步:对AppSecret进行MD5加密
        const md5Secret = crypto.createHash('md5').update(this.appSecret).digest('hex');
        // 第二步:拼接加密后的密钥和时间戳
        const signStr = md5Secret + ts;
        // 第三步:再次MD5加密
        return crypto.createHash('md5').update(signStr).digest('hex');
    }

async controlDevice(deviceId, order) {
        const ts = Math.floor(Date.now() / 1000);
        const sign = this.generateSign(ts);
        
        const url = `${this.baseUrl}?sign=${sign}&ts=${ts}`;
        const payload = {
            device: deviceId,
            order: order
        };
        
        const response = await axios.post(url, payload);
        return response.data;
    }

async turnOnRelay(deviceId) {
        return this.controlDevice(deviceId, { power: 1 });
    }

async turnOffRelay(deviceId) {
        return this.controlDevice(deviceId, { power: 0 });
    }
}

// 使用示例
async function main() {
    const controller = new YoyoiotController('your_app_id', 'your_app_secret');
    const result = await controller.turnOnRelay('820720');
    console.log('控制结果:', result);
}

5.3 第三种场景：接收设备状态推送

需求描述：搭建HTTP服务接收设备上报的人体感应事件，用于安防记录或大屏展示。

Flask服务端示例（Python）：

from flask import Flask, request, jsonify
import json

app = Flask(__name__)

# 配置日志或数据库连接
INFRARED_EVENTS = []  # 简单存储，生产环境应使用数据库

@app.route('/webhook/infrared', methods=['POST'])
def handle_infrared_event():
    """接收红外传感器状态上报"""
    data = request.get_json()
    
    device_id = data.get('device')
    event_type = data.get('event')
    event_data = data.get('data', {})
    
    if event_type == 'infrared_detect':
        human_status = event_data.get('infrared_target')
        timestamp = event_data.get('timestamp')
        
        status_text = "有人" if human_status == 1 else "无人"
        
        # 记录事件
        event_record = {
            'device_id': device_id,
            'status': status_text,
            'timestamp': timestamp
        }
        INFRARED_EVENTS.append(event_record)
        
        print(f"[{timestamp}] 设备 {device_id} 检测到: {status_text}")
        
        # 可在此触发业务逻辑，如:
        # - 写入数据库
        # - 发送WebSocket通知前端
        # - 调用其他API进行联动
        
        return jsonify({"code": 200, "message": "received"})
    
    return jsonify({"code": 200, "message": "ignored"})

@app.route('/events', methods=['GET'])
def get_events():
    """获取最近的事件记录"""
    return jsonify(INFRARED_EVENTS[-100:])  # 返回最近100条

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8080)

配置Webhook地址：在芯步控制台将消息推送服务器地址设置为 http://您的服务器IP:8080/webhook/infrared。

5.4 场景四：批量设备管理

需求描述：管理多个区域的传感器，统一控制或查询状态。

批量控制示例：

注意：批量操作时，所有设备需属于同一类产品，且指令必须兼容。

六、私有化部署方案

6.1 方案说明

芯步设备支持私有化部署，所有通信可在纯局域网环境中完成，无需访问公网。这对于数据安全要求高、网络隔离严格的场景尤为重要。

6.2 部署架构

私有化部署模式下，您需要自行部署MQTT Broker或HTTP消息服务器，设备配置为连接至私有服务器地址。

关键配置项：

配置项	说明
服务器地址	私有化部署的服务端IP/域名
通信协议	MQTT 或 HTTP（取决于部署方式）
认证信息	自签名证书或自定义Token

6.3 接口兼容性

私有化部署环境下的API调用方式与公网版本完全一致，仅请求的基础URL发生变化，设备ID和命令格式保持不变，代码无需修改。

七、最佳实践和需要注意的点

7.1 网络与部署

WiFi信号要求：设备使用2.4GHz频段，部署时需确保安装位置WiFi信号强度良好（RSSI ≥ -65dBm）
局域网优先：对于低延迟要求的场景，采用局域网私有化部署方案
心跳机制：设备上线/下线状态可通过接收 boot 事件获知

7.2 接口调用优化

签名缓存：同一时间戳可用于多个请求，避免频繁计算
超时设置：HTTP请求设置3-5秒超时，设备响应约80-120ms
异步处理：对于不要求即时反馈的场景，采用异步消息机制确认设备执行结果

7.3 设备配置注意事项

Flash擦写限制：配置项存储在Flash中，有擦写次数限制，避免频繁下发配置修改指令
无人触发延迟设置：根据实际场景合理设置 infrared_change_0 值，避免过于灵敏或过于迟钝
初始状态确认：设备上电后的默认行为可通过 infrared 和 relay1 配置项预设

7.4 常见问题排查

问题现象	可能原因	解决方案
命令下发返回200但设备无反应	设备离线或命令参数错误	检查设备在线状态，确认order格式正确；通过消息推送接收执行反馈
红外检测不灵敏	安装高度或角度不当	参考产品手册调整安装位置；避免遮挡传感器窗口
设备频繁上报无人/有人	触发延迟设置过短	适当增加 `infrared_change_0` 和 `infrared_change_1` 的值
签名验证失败	时间戳偏差过大	同步服务器时间，确保误差在5分钟内

八、总结

芯步吸顶式人体存在红外传感器提供了完整、标准的HTTP API接口，使得第三方系统能够便捷地集成人体感应能力。通过本方案，开发者可以：

快速对接：利用HTTP接口在30分钟内完成设备控制功能开发
灵活控制：支持单设备/批量设备控制，支持继电器联动
实时感知：通过Webhook接收设备状态变化推送
安全部署：支持私有化部署，满足数据安全要求

开发者在实际集成前，先在芯步开放平台完成应用创建和设备添加，通过本文档提供的代码示例进行联调测试。如有复杂业务场景需求，可参考官方文档进一步了解MQTT接入方式及更详细的物模型定义。