芯步的吸顶式人体感应器开放HTTP接口，支持数据上报和设备控制，可以在局域网或公网环境下快速集成。以下方案涵盖消息接收和设备控制两个核心方向，可根据实际场景灵活采用。
1. 概述
本方案的目标是指导开发者如何利用芯步开放的HTTP API接口，将吸顶式智能人体传感器（以型号 UNI-CGQ-RT-XD-H 为例）无缝集成到第三方软件平台（如智慧办公系统、智能家居平台或能源管理系统）。
核心目标：实时获取“有人/无人”的状态数据，或通过下发指令查询即时状态。
技术优势
全开放接口：支持任何能发起HTTP请求的编程语言（Java, Python, PHP, Node.js等）。
私有化部署：支持局域网直连和私有化消息服务器，数据不外泄。
实时性：状态变化实时上报，无需频繁轮询。
2. 接入前准备
在开始开发前，请确认完成以下准备工作：
设备安装：确保吸顶式人体感应器已上电，并成功连接至2.4G WiFi网络（无需网关）。
获取凭证：登录芯步开发者后台，获取以下三个关键参数：
AppId：您的应用唯一标识。AppKey：用于生成接口签名（Sign）的密钥。Device ID：设备序列号，用于在接口中定位具体设备。
3. 接入方案：人员活动状态反馈
人员活动状态的获取主要有两种模式：被动接收（推荐） 和 主动查询。
3.1 方案A：被动接收（实时消息推送）
这是最高效的方式。当传感器探测到有人移动或变为无人时，设备会主动向您的服务器发送HTTP请求。
适用场景：实时监控、考勤打卡、人来灯亮/灯灭。
通信方向：设备 → 芯步云 → 您的服务器。
配置步骤：
设置回调URL：在芯步控制台中，配置您的服务器接收地址（例如：
http(s)://yourdomain.com/api/sensor/callback）。接收数据：当状态变化时，芯步云会POST JSON数据到该地址。
数据格式解析：传感器上报的数据结构通常如下（参考物模型设计）
服务器处理逻辑（伪代码示例）：
3.2 方案B：主动查询（接口下发命令）
如果您的系统需要即时获取当前状态（例如每隔5分钟轮询一次），可以通过调用芯步的开放API进行查询。
适用场景：设备重启后的状态同步、定时巡检、控制台面板实时刷新。
通信方向：您的服务器 → 芯步云API → 设备。
接口信息
请求地址
http(s)://api.thingboot.com/{AppId}/device/control/?sign={sign}&ts={ts}请求方法
POSTContent-Type
application/json
签名说明为了防止接口被滥用，需要在URL中携带签名（Sign）。通常情况下，签名生成规则为 md5(AppId + AppKey + Timestamp) 后取特定长度或直接传递，具体需严格按照官方SDK生成。
请求示例（查询设备状态）：虽然红外状态通常自动上报，但您可以通过查询infrared_enable（红外模块开关状态）来间接判断设备在线性，或通过系统命令获取设备信息。如果需要强制获取当前环境状态，通常利用系统命令或设备的特定属性读取。
查询红外模块开关状态命令：
注：order中的字段需参考该设备的[物模型定义]。
响应解析：接口会同步返回当前设备的状态，一般包含infrared_target字段，指示是否有人。
4. 关键参数与物模型详解
在进行开发时，请请一定要参考该产品的物模型。对于“吸顶式智能人体感应器”，以下属性是核心
| 功能模块 | 参数标识符 | 数据类型 | 值说明 | 用途 |
|---|---|---|---|---|
| 红外感应状态 | infrared_target | 整型(Integer) | 1=有人，0=无人 | 核心上报字段，判断人员活动最直接的证据 |
| 红外模块开关 | infrared_enable | 布尔/整型 | 1=打开，0=关闭 | 控制传感器是否工作，关闭后将无法感知人员 |
| 线路控制 | power | 布尔/整型 | 1=通，0=断 | 设备内部线路输出控制，可联动外部负载 |
| 按钮事件 | btn1 | 事件 | 触发时上报 | 识别物理按键操作 |
5. 高级联动场景：自动化控制
利用接收到的“人员活动状态”，您可以结合HTTP接口对传感器本身或其关联设备进行控制。
场景案例：有人自动接通线路（开灯）
触发：服务器收到回调，
infrared_target值为1。逻辑判断：代码判断当前时间是否为工作时间或光照传感器是否较暗。
执行动作：向芯步云API下发控制命令。
下发开灯命令示例
URL:
http(s)://api.thingboot.com/{AppId}/device/control/?sign=xxx&ts=xxxBody:
场景案例：无人自动断电（关灯/关空调）当持续收到infrared_target 为 0 的状态消息持续一段时间（如5分钟），系统自动下发：
6. 最佳实践和需要注意的点
去抖动处理：人体传感器在“有人”变“无人”的临界点可能会有短暂抖动。在您的业务层增加延时处理逻辑（例如连续5秒收到无人信号才判定为离开），而不是立即响应单次“无人”消息。
数据验签：为了安全起见，在您的回调接口中，对芯步推送过来的消息进行签名验证，确认消息确实来自芯步平台，而非伪造攻击。
配置参数调整：利用红外模块的配置项（如
infrared_change_0无人触发持续时间）可以调整传感器的灵敏度。您可以在控制台修改这些配置，以适应不同的办公环境。网络稳定性：该设备支持WiFi直连且具备“闪存”配置功能，支持设定5组WiFi，信号不好时会自动切换，开发时无需过多担心网络重连问题。
7. 总结
通过集成芯步的开放接口，接入吸顶式人体感应器的核心在于两步：
接收：搭建一个公网可访问的Webhook来接收设备主动上报的
infrared_target状态。控制：通过携带签名的HTTP POST请求下发
power或查询命令。
这种基于HTTP的轻量级集成方案，使得传统IoT设备能够快速融入现代的微服务架构中，实现即插即用的智能化改造。