芯步的吸顶式人体传感器提供开放的HTTP API接口，支持私有化部署和局域网通信，可快速集成到各类软件项目中。以下是完整的接入方案。

1. 项目概述与选型分析

在智能化改造项目中，人体感应场景（如智能照明、安防监控、节能控制）是高频应用场景。为了实现精准的“人在灯亮，人走灯灭”或安防联动，我们需要一款高可靠性、低误报率且易于集成的硬件设备。

推荐设备芯步 智能人体存在红外传感器 [吸顶版]（型号：UNI-CGQ-RT-XD-H）。

核心选型理由

• WiFi直连，无需网关：该设备采用2.4G WiFi无线网络，支持直连路由器。这降低了项目成本，减少了网关故障点，且部署灵活。

• 双模检测（可选）：除了红外版，该品类还支持红外+雷达双模版。雷达可检测微动（如呼吸、办公中的微小动作），相比纯红外感应，能有效避免“人未离、灯已灭”的尴尬。

• 开放接口（HTTP API）：设备完全开放上行（数据上报）和下行（远程控制）接口，不绑定特定云平台，支持私有化部署和纯局域网通信。

• 供电与集成便利性：吸顶设计美观，且内置继电器线路（power），可直接控制照明等强电设备，也可以仅作为传感器通过API通知服务器。

2. 系统设计

为了将硬件接入软件项目，我们采用经典的“设备直连-云平台中转-业务系统处理”的架构。考虑到芯步支持私有化部署，我们可以将数据完全控制在自己的服务器内。

2.1 网络拓扑结构

1. 感知层：吸顶式传感器通过WiFi连接至现场路由器。

2. 传输层：设备连接至芯步云（公有云）或用户自建的私有化服务器。

3. 应用层：用户的Web/APP后端服务器订阅设备数据，或接收设备推送的HTTP请求。

2.2 数据流向图

sequenceDiagram
    participant Sensor as 吸顶人体传感器
    participant YoyoCloud as 芯步云/私有化Broker
    participant UserServer as 客户软件后端
    participant ClientApp as Web/APP前端
    
    Note over Sensor,UserServer: 1. 实时数据上报流程
    Sensor->>YoyoCloud: 上报状态变化（有人/无人）
    YoyoCloud->>UserServer: HTTP POST 回调 (携带设备ID与状态)
    UserServer->>UserServer: 业务逻辑处理（记录/联动）
    UserServer-->>ClientApp: WebSocket/轮询推送状态
    
    Note over UserServer,Sensor: 2. 远程控制/配置流程
    ClientApp->>UserServer: 管理员下发指令（关灯/重启）
    UserServer->>YoyoCloud: HTTP API 请求 (携带签名)
    YoyoCloud->>Sensor: 下发指令

3. 详细接入实施步骤

本阶段旨在打通设备与软件的数据通道，主要分为：设备注册、接口鉴权、数据接收处理三个核心环节。

3.1 设备部署与注册

在开始API对接前，需要完成设备的物理安装与联网：

1. 安装：按照产品手册完成吸顶式安装（注意避开出风口、大型金属物体以防干扰）。

2. 配网：使用芯步官方提供的“物联网控制台”或APP，为设备配置WiFi网络（仅支持2.4G）。

3. 获取凭证：在控制台获取关键参数：

   • AppId：应用ID，标识哪个项目。

   • AppSecret：开发者密码，用于计算签名。

   • Device ID：设备的唯一ID（如 820720）。

3.2 接口鉴权机制

软件调用接口前必须解决安全问题。芯步采用动态签名（Sign）验证，防止接口被恶意篡改。

• 签名算法Sign = md5( md5(AppSecret) + ts )。

• 参数说明

  • AppSecret：开发者密码。

  • ts：Unix时间戳（秒），用于防重放攻击。

• 实现逻辑

  1. 将AppSecret进行一次MD5加密得到字符串 S1。

  2. 将 S1 与当前时间戳 ts 拼接成字符串 S2。

  3. 将 S2 再次进行MD5加密，得到最终的 Sign。

3.3 核心 API 集成开发

接入工作主要围绕两个方向：接收设备上行数据 和 发送下行控制指令。

3.3.1 下行控制：软件如何反向控制设备

场景：用户在APP上点击“关闭传感器内部指示灯”或“重启设备”。

• 请求地址http(s)://api.thingboot.com/{AppId}/device/control/?sign={sign}&ts={ts}

• 请求方式：POST (JSON格式)

• 代码实现逻辑（通用伪代码）

常用指令集映射（根据物模型定义）

3.3.2 上行消息：如何接收有人/无人事件

场景：当有人进入房间时，传感器立即通知服务器，服务器记录日志并触发其他联动。

芯步采用 HTTP回调推送 机制。你需要部署一个公网可访问（或局域网内可访问）的API接口作为接收端。

• 配置回调地址：在芯步控制台中，将 http://yourdomain.com/api/sensor/callback 设置为接收地址。

• 推送时机：当检测到 infrared_target (红外感应) 属性由 0 变为 1，或由 1 变为 0 时 。

• 接收数据示例当传感器检测到状态变化，你的服务器将收到如下结构的POST数据：

服务器端处理逻辑

1. 验签：与下行类似，验证请求是否真的是芯步发出，防止伪造数据。

2. 异步处理：收到“有人”消息后，如果涉及开灯操作，应立即返回 200 OK 给物联平台，避免超时，然后异步执行开灯命令。

3. 防抖过滤：雷达/红外传感器可能在边界处产生抖动。如果你在控制台配置了“红外无人触发持续时间”为 30s，设备将会在确认无人30秒后才发送“无人”报文，软件端无需重复做延迟处理。

4. 关键场景配置与优化

为了让感应逻辑更符合业务需求，在软件端或控制台配置产品的“配置项”，这些配置保存在设备Flash中，无需在业务代码中反复做延迟处理。

4.1 感应延迟策略配置

在智能办公场景中，不希望员工稍微静止就关灯。可以通过infrared_change_1和infrared_change_0配置项调整。

4.2 私有化部署（数据安全场景）

对于政府、金融或注重隐私的企业，若数据不能出内网：

1. 自建Broker：芯步支持私有化部署，即把消息服务器部署在客户自己的机房。

2. 局域网中断网运行：设备WiFi连接后，即使外网断开，只要局域网内的服务器存活，HTTP API调用依然可以正常工作。

5. 总结

将芯步吸顶式智能人体感应器接入软件项目，核心优势在于其 HTTP接口的通用性 和 物模型的透明性。

• 对开发者：无需理解复杂的物联网底层协议（如MQTT、CoAP），使用任何主流编程语言（Java, Python, Go, PHP）通过处理JSON格式的HTTP请求即可完成全栈集成。

• 对项目：支持从单台设备的小型办公场景到成千上万台的大型商业楼宇改造，且具备私有化部署能力，保障了系统未来的扩展性和数据安全性。

通过上述方案，你可以在两天内完成从设备上电到软件界面显示“有人/无人”状态的原型开发，并实现远程联动控制。