一、概述

本方案的目标是为开发者/系统集成商提供一份完整的技术指南，用于将芯步的吸顶式智能雷达感应开关（如型号 UNI-CGQ-RT-XD-L 等）通过其开放的 HTTP API 接口，快速集成到第三方服务器或物联网平台中，实现对办公空间、智能家居或商业场所的人体存在感知与联动控制。

与其他仅能识别移动热源的红外传感器（PIR）不同，芯步的吸顶雷达传感器采用毫米波雷达技术，可精准探测静止状态下的人体微动（如呼吸、心跳），解决了传统传感器在人体静坐、睡眠时误判为“无人”的痛点。

适用场景：智慧办公室节能照明、智能卫生间厕位检测、酒店客控系统、仓库安防警戒等。

二、对接前准备与环境要求

在开发对接之前，请确保具备以下条件并完成硬件部署：

1. 硬件清单与环境

• 传感器设备：购买至少一台吸顶式智能雷达存在传感器（如 UNI-CGQ-RT-XD-L或同系列雷达版）。该设备支持 AC 100-250V 市电直接输入，并带有一路继电器输出，可直接控制照明或报警器。

• 网络覆盖：设备仅支持 2.4GHz WiFi（802.11 b/g/n）。确保安装点位有稳定的 2.4G Wi-Fi 信号覆盖，若信号弱可能影响状态上报的实时性。

• 安装高度与范围：吸顶安装，高度 2.5-3 米，在此高度下探测半径约为 5 米（以安装点为圆心的圆锥形探测区域）。安装时需避免面对空调出风口、大幅摆动植物或大功率电器，以防雷达波受到气流/震动干扰。

2. 账号与开发凭证

在芯步开发者后台完成注册与准备：

• 注册账号：访问芯步官网（）注册企业/个人账号。

• 获取密钥：登录控制台，创建“工作台”并进入“物联网控制台”模块。在“开发设置”中获取系统分配的 AppID 和 AppSecret。这两项是后续所有 API 请求的鉴权凭证。

• 目标设备 ID：将传感器通电并配网成功后，在控制台设备列表中可以查看到唯一的 Device ID（如 820720 或 1878），这是 API 命令的目标地址。

三、核心对接流程与技术实现

芯步的接口采用标准的 HTTP/HTTPS 协议，交互模型由两种模式组成：

1. 上行（设备 -> 服务器）：传感器检测到“有人”或“无人”状态变化时，主动向您的服务器推送数据。

2. 下行（服务器 -> 设备）：您的服务器下发指令（如关闭继电器、设置灵敏度）给传感器。

3.1 配置数据接收服务器（上行）

为了实现人体存在监测，您的服务器需要接收设备主动上报的状态变化。

• 推送机制：当雷达探测到环境从“无人”变为“有人”，或从“有人”变为“无人”时，设备会立即向预设的服务器地址发送 POST 请求。

• 如何在设备端配置推送地址

  • 通过芯步官方控制台，在设备详情的“服务设置”中填入您的公网接收 URL。

  • 或通过 API 接口调用设置回调 URL（具体详见官方 API 文档）。

• 数据格式示例：设备上报的 JSON 数据大致示例如下：

  { "device_id": "820720", "type": "radar_induction", "status": "someone_exists", // 另一个状态为 "none" "timestamp": 1712645432, "light": 120 // 如该型号带光照度传感器，同时上报光照值 }

  注：具体字段名需根据产品手册确认，通常包含设备 ID、检测结果（存在/不存在）及时间戳。

3.2 接口鉴权与签名计算（关键）

向设备下发命令或查询状态时，需在 URL 中携带签名。所有请求均使用 MD5 双重加密机制。

签名算法步骤

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

2. 获取当前的 Unix 时间戳（秒级）Ts。

3. 将 S1 与 Ts 拼接成字符串 S1Ts。

4. 对 S1Ts 再次进行 MD5 加密，得到最终签名 Sign。

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

安全提示：时间戳 Ts 用于防止请求重放攻击，通常服务器会校验时间戳与当前时间差需小于合理范围（如 5 分钟内）。

3.3 下行命令控制（下发与控制）

场景：您希望强制关闭传感器所连接的照明线路，或重启雷达模块。

• 请求方法：POST

• HeaderContent-Type: application/json

• Body 结构

  { "device": "820720", // 设备ID "order": { "power": 0 // 0=断开线路，1=接通线路 } }

  *示例解析：该命令让 ID 为 820720 的设备的继电器断开，关闭所接灯具。从发出到设备执行约 80-120ms。*

• 雷达参数调节：若需调节雷达灵敏度（如避免隔墙误报），可修改 order 对象中的 radar_enable 及相关雷达参数（具体支持字段可查阅该产品的“产品手册”）。

3.4 实战代码片段（Python 示例）

以下是一个用 Python 实现的向传感器下发“开启继电器”命令的示例逻辑：

四、高级应用与联动策略

集成基础数据流后，您可以在业务层实现更智能的逻辑：

1. “人来灯亮、人走灯灭”的极速联动

由于芯步的传感器自带一路 power 输出线路（继电器），最稳妥的逻辑是本地联动 + 云端备份。

• 本地执行：可以将灯具直接接在传感器的 AC 输出后端。在传感器配置中设置“有人通电，无人延时断电”。

• 云端联动：您的服务器收到“有人”消息后，立即通过 HTTP 下发指令开启吸顶灯；收到“无人”消息后关灯。这适合需要结合光照度阈值（例如：照度 > 100Lux 时不自动开灯）的场景。

2. 区域人数统计（逻辑过滤）

雷达传感器若灵敏度调高，容易在边界处出现“临界抖动”。在服务器端解析时，加入防抖动逻辑

• 设置一个判定窗口期（如连续 2 秒内状态均为“无人”），才确认无人状态，避免人影闪过后瞬间断电导致用户投诉。

3. 私有化部署与局域网控制

芯步支持私有化部署方案。如果您的服务器与传感器处于同一局域网（LAN），且无需云端中转，可将 API 请求地址指向局域网内的服务器 IP。传感器固件支持配置多组网络，当公网不可达时，局域网控制依然生效。

五、常见问题排查

六、总结

通过对接芯步的吸顶式雷达传感器，开发者可以利用其高度标准化的 HTTP API 快速实现“人体存在感知”能力。关键在于处理好 签名鉴权 以及 数据上行接收服务的稳定性。相比传统红外方案，雷达方案在办公工位检测、智能卫生间等需要检测人体静止行为的场景中更具优势。

对接完成后，在 3 米左右高度的标准房间内进行静态（静坐看书）和动态（来回走动）的全量测试，以验证雷达算法对环境自适应校准的效果。