把 Wi-Fi CSI 感知接进 Home Assistant：ESPHome、MQTT 与路由器 REST

作者 Wu Jun · 更新于 2026-10-29 · 约 6 分钟

Home Assistant 需要的是实体，不是原始 CSI 字节流。关键不是“把 256 个子载波塞进 HA”， 而是先确定谁负责采集、谁负责判决、实体代表什么。

截至 2026-10-29，实际有两条成熟路线：

1. ESPectre + ESPHome：一块 ESP32 直接在设备端计算 motion/movement，HA 通过 ESPHome 发现实体；
2. ESPectre Native + MQTT Discovery：不经过 ESPHome，由设备把实体发布到 MQTT；

本项目已有的 MT6000 platform/ 是第三条路线：它提供 REST/WebSocket，但当前源码没有内置 MQTT。 如果要把路由器平台接入 HA，应先用 REST；需要 MQTT 时必须另外实现 bridge，不能假设已有 topic。

0. 先选接入层

ESPectre 官方说明它支持 ESP32-C6 / C5 / C3 / S3 / S2 和经典 ESP32，使用普通 2.4GHz Wi-Fi 4 网络；一块板覆盖一个区域，不能识别身份、人数，也不能证明房间绝对无人 ^[1]。底层的 CSI 采集能力来自 ESP-IDF ^[2]。

1. 先统一实体语义

CSI 感知的能力边界可参考领域综述 ^[3]。在自动关灯、安防等动作前， 应加保持时间、人工确认或其他传感器，而不是把单条 CSI 当安全认证。

2. 路线 A：ESPectre + ESPHome（推荐先跑通）

官方 ESPHome 组件不是旧式 platform: espectre。当前仓库要求使用 external_components 指向组件目录，然后用顶层 espectre: 声明， 组件会生成 motion、movement、threshold 等实体。

在官方对应芯片的完整示例基础上，合并这个组件块；不要只复制片段而丢掉板级配置：

external_components:
  - source:
      type: git
      url: https://github.com/francescopace/espectre
      path: src/cpp/frontend/esphome/components
    components: [espectre]

espectre:
  detection_algorithm: lightweight
  csi_capture_profile: lltf
  csi_target_pps: 100
  traffic_generator_mode: ping
  motion_sensor:
    name: "Living Room Motion"
  movement_sensor:
    name: "Living Room Movement"
    internal: true

说明：

• csi_capture_profile 可选 auto、lltf、ht-vht，修改后需要重新构建；
• csi_target_pps 和流量模式可先用默认值，确认 HA 实体出现后再优化；
• internal: true 可减少高频 movement score 写入 HA recorder；只保留 binary_sensor 给自动化使用；
• 真实 SSID、密码和 BSSID 不要写进公开 YAML，使用官方 Improv Serial 或 captive portal 配置 Wi-Fi。

ESPHome 上线顺序

1. 按官方支持的芯片示例选择完整 YAML，不要混用其他芯片的配置；
2. 用 USB 首次烧录，配置 Wi-Fi；
3. 在 HA 的 ESPHome 集成中确认设备被发现；
4. 检查 binary_sensor.*_motion、threshold 和 diagnostics；
5. 先观察 24 小时，再接关灯或空调自动化；
6. 更换位置、BSSID 或家具后重新标定。

3. 路线 B：ESPectre Native + MQTT Discovery

Native 前端可以通过 MQTT Discovery 自动创建实体。推荐在 HA 中使用官方 Mosquitto broker；HA 文档要求 broker 支持 MQTT 5，并默认启用 discovery ^[4]。

设备侧只需要在 Device settings 填写：

scheme: mqtt
host:   homeassistant.local
port:   1883

然后确认设备能力接口返回 configured: true。TLS broker 使用 mqtts 和通常的 8883 端口；主机字段不要填写 mqtt://、账号、端口或路径。Native 的实体会自动出现， 不要为同一台设备再手工创建一套同名实体。

当 discovery 被关闭时，才需要手动配置。下面使用 ESPectre Native 的 motion topic：

mqtt:
  binary_sensor:
    - name: "Living Room CSI Motion"
      unique_id: living_room_csi_motion
      state_topic: "espectre/v1/devices/<device_id>/motion"
      value_template: "{{ value_json.state }}"
      payload_on: "motion"
      payload_off: "idle"
      availability_topic: "espectre/v1/devices/<device_id>/health"
      availability_template: "{{ 'online' if value_json.online else 'offline' }}"
      payload_available: "online"
      payload_not_available: "offline"

motion 是边沿事件 topic，不保留；HA 重启后若没有新事件，实体可能暂时不可用。 真正长期运行时应优先让 MQTT Discovery 管理实体，并检查 health/availability。

4. 路线 C：本项目路由器平台 + REST

本项目的 platform/ 实际提供：

• GET /api/health；
• GET /api/stations；
• GET /api/stats；
• WebSocket /ws；
• 录制与会话 REST API。

它没有 /api/csi/status，也没有内置 MQTT。旧示例里的这两个接口不能照抄。

先在运行平台的机器上验证：

curl -fsS http://csi-platform.local:8080/api/health
curl -fsS http://csi-platform.local:8080/api/stations

/api/stations 返回 stations 数组；每项包含 alias、online、present、 motion_db、last_seen_ago 等字段。一个按 alias 提取客厅设备的 Home Assistant REST 配置如下：

rest:
  - resource: "http://csi-platform.local:8080/api/stations"
    scan_interval: 2
    timeout: 5
    binary_sensor:
      - name: "Living Room CSI Presence"
        unique_id: living_room_csi_presence
        value_template: >-
          {% set s = value_json.stations
             | selectattr("alias", "equalto", "living-room")
             | list | first %}
          {{ (s.online and s.present) if s else false }}
    sensor:
      - name: "Living Room CSI Motion dB"
        unique_id: living_room_csi_motion_db
        unit_of_measurement: "dB"
        state_class: measurement
        value_template: >-
          {% set s = value_json.stations
             | selectattr("alias", "equalto", "living-room")
             | list | first %}
          {{ s.motion_db if s else none }}

实际字段以平台当前响应为准；如果平台在 nginx 反向代理后，资源路径仍应是 /api/stations。REST 的 resource、scan_interval 和 binary_sensor 结构以 Home Assistant 官方文档为准 ^[5]。

REST 路线的标定和自动化

1. 安静房间采集至少 10 分钟，记录 motion_db 分布；
2. 正常走动 10 分钟，比较活动期分布；
3. 取安静期高分位数作为进入参考，活动期低分位数作为释放参考；
4. 使用滞回和保持时间，不要每条曲线抖动都触发；
5. 连续观察 24 小时，统计误报、漏报和不可用时间；
6. 换房间、路由器位置、BSSID 或家具后重新标定。

automation:
  - alias: "Turn off living-room light after ten quiet minutes"
    mode: single
    trigger:
      - platform: state
        entity_id: binary_sensor.living_room_csi_presence
        to: "off"
        for: "00:10:00"
    condition:
      - condition: state
        entity_id: binary_sensor.living_room_csi_presence
        state: "off"
    action:
      - service: light.turn_off
        target:
          area_id: living_room

先不要直接控制门锁、安防或医疗报警。CSI 是低带宽、受环境和标定影响的传感器， 自动关门锁需要独立安全认证与失效策略。

5. MQTT 与 REST 怎么选

选择原则：先跑通 ESPHome 单房间；需要不依赖 ESPHome 构建时选 Native MQTT； 已经有路由器采集服务时才选 REST。不要同时开三套重复实体。

6. 常见问题

7. 隐私与部署边界

• 只在自有或获授权的空间部署；
• 让同住者知情，不要把 CSI 变成隐蔽监控；
• MQTT 使用独立账号、局域网 broker，不把 1883 端口暴露到公网；
• REST/ESPHome API 不直接暴露到互联网，必要时用 VPN 或反向代理鉴权；
• 原始 CSI、motion score 和 HA 历史都按敏感数据管理，设置保留期限；
• 变更后重新标定，并记录模型、固件、阈值和位置。

继续阅读：ESP32 CSI 入门 · ESP32 人体检测 · 树莓派部署 · MT6000 复现