ESPHome 2026.10 这个版本最让我兴奋的其实是那个从实验性组件转正的 Wi-Fi 人体检测功能。简单说你手头那块吃灰很久的 ESP32 老开发板不用外接毫米波雷达不用焊 PIR 红外模块刷个新固件就能把“房间里有没有人”这个问题直接交给 Wi-Fi 信号来判断。我这一周把书房、卫生间、客厅各放了一块旧板子实测从配置到调参踩了不少坑也摸索出一套相对稳定的参数组合。这篇文章就聊聊我对这个新版本的理解、配置细节以及一些常规文档里不会写的排查经验给正打算把手头老设备利用起来的人一个参考。1. 为什么一个大版本更新把“用 Wi-Fi 检测人体”做成了主角1.1 人体存在检测的老方案有多贵/多麻烦先说一个很现实的问题在这之前想在智能家居系统里实现“人体存在检测”主流方案就两条路。一条是 PIR 红外模块确实便宜几块钱就能买到但它只能检测“动”。人只要坐在沙发上看手机超过十几秒PIR 就认为房间没人了灯光自动关闭体验非常割裂。另一条是毫米波雷达能检测微动、呼吸甚至能区分静止的人效果确实好但模块加运费动辄三四十块起步还得考虑供电、接线、安装角度、天线遮挡一系列问题。我家里已经部署了七八块 ESP32 做温湿度采集、门窗磁、灯带控制线路和位置都定死了。为一个人体检测再单独加一块毫米波雷达模块成本倒不是花不起关键是改造麻烦。所以当听说 ESPHome 新版把 Wi-Fi 人体检测做成官方组件时我第一反应是这方向对了。用现有设备、现有供电、现有 Wi-Fi 环境省掉一切硬件开销这才是老设备用户真正需要的功能。1.2 从 RSSI 到 CSIWi-Fi 信号里藏着人的“指纹”这里得稍微解释一下原理不然调参的时候你会很懵。Wi-Fi 信号在室内传播时并不是直直地从路由器打到设备上它会经过墙壁反射、家具散射、人体吸收最后到达接收端的是无数条路径叠加后的结果。传统 RSSI 只能告诉你“总信号强度”这个数值人在房间里走动引起的强度变化非常微弱容易被距离、天线朝向、蓝牙干扰这些因素淹没所以靠 RSSI 检测人体误差大到没法用。而 CSI也就是信道状态信息记录的是每个子载波在频域上的幅值和相位。你可以把它理解成对房间拍了一张“多径快照”人站在哪个位置呼吸时胸腔起伏抬手时手臂移动都会让特定子载波的相位和幅值发生变化。ESP32 系列本身具备采集 CSI 的能力之前只是没有框架把这些数据包装成好用的传感器接口。这次 ESPHome 把 CSI 转正为核心组件数据采集、特征提取、阈值判断全在固件里完成用户只需要在 YAML 里写几行配置就能得到一个标准的人体存在 binary_sensor。1.3 为什么说“老设备原地起飞”我手头这块 ESP32 是几年前买的经典款双核 240MHz没有蓝牙 5.0也没有任何 AI 加速模块按说实时跑 CSI 分析是有点吃力的。但实际体验下来ESPHome 把 CSI 处理流水线做得相当克制CPU 占用在合理范围内人体状态上报延迟在几秒级完全够用于存在检测这种场景。更关键的是这套功能对硬件零要求不需要额外传感器不需要改接线甚至不需要换天线。原本被各种“新功能只支持新芯片”规则劝退的老开发板升级固件后一夜之间多了一项过去必须掏钱买模块才能实现的能力。这就是“原地起飞”的意思——硬件没变能力边界变了。2. 动手前先搞懂CSI 人体检测组件在 ESPHome 里怎么工作2.1 配置入口和组件架构升级到 2026.10 后新组件并不是单独一个sensor:就完事它分成两个部分协同工作。第一部分是esp32_csi:负责初始化 Wi-Fi 信道状态信息采集相当于传感器的“硬件驱动层”第二部分是binary_sensor:里的platform: esp32_csi负责把采集到的 CSI 统计特征换算成有人/无人状态相当于“应用层”。我实测用的最小配置块长这样esp32: board: esp32dev framework: type: arduino esp32_csi: channel: 6 ht: true binary_sensor: - platform: esp32_csi name: 书房人体存在 device_class: occupancy这块配置跑起来之后ESPHome 日志里会周期性打印 CSI 数据包数量。如果这个数值在持续增长说明采集链路已经通了。然后binary_sensor会在检测到 CSI 特征变化时切换状态默认的判定逻辑是“特征变化幅度超过阈值就认为有人”。2.2 关键参数解读信道、HT 模式、阈值、窗口新组件给了不少可调参数但真正影响效果的其实就那么几个。第一个是信道。CSI 分析需要一个稳定的参考信号建议把channel固定下来和你的无线路由器保持一致更好。为什么如果信道跳来跳去CSI 的统计基线会不断重建人即使站着不动也可能被误判为“动态”。我一开始没设固定信道结果一个晚上触发了二十多次误报后来锁在路由器的信道上问题立刻缓解。第二个是 HT 模式。简单理解就是 Wi-Fi 带宽ht: false对应 20MHzht: true对应 40MHz。带宽越宽可分析的子载波越多灵敏度越高但受同频干扰的影响也越大。我的测试结论是家庭环境首选ht: true但如果你家附近 Wi-Fi 热点密集降回false能减少随机误报。第三个是最关键的“动作阈值”。它决定 CSI 特征变化要多大才会触发“有人”状态。数值越小越灵敏细微动作就能触发但误报率直线上升数值越大越保守只有明显移动才触发但漏报风险增加。我后面会给几组实测组合这里先记住一个原则阈值不是调出来的是配合你所在房间的活动特点试出来的。第四个是扫描间隔和滑动窗口。scan_interval控制多久采集一次 CSI 快照window_size控制用多少个快照做统计平滑。这两个参数直接影响延迟窗口越大越平滑但有人进屋后状态翻转会更慢窗口太小则容易出现瞬间抖动造成误判。2.3 部署位置与传感器布局对效果的影响这是所有参数里最容易被忽略、但影响最大的一项。Wi-Fi 人体检测的本质是通过环境电磁变化反推人的位置所以设备放哪里决定了它能“看见”多少空间。我总结了几条实测规律。设备最好放在房间对角线的一侧天线朝向房间主体空间离地面 80cm 到 1m 左右相当于家具的中间高度人体躯干活动最容易被捕捉到。放在桌面边缘且周围没有遮挡时覆盖一个 10 平米的卧室没问题。但如果塞到桌子下面、被金属收纳箱挡住信号路径被固定住人从旁边走过去 CSI 变化很小基本等于白装。还有一种情况设备离路由器不到 1 米人从它们之间走过时多径变化极小检测几乎无反应这时候需要把设备挪到离路由器至少两三米的位置。3. 老 ESP32 刷上 ESPHome 2026.10接入人体存在传感器全流程3.1 升级固件前的备份与兼容检查动手之前先把备份做好这是我不止一次吃过亏后的习惯。ESPHome 升级一般不会丢配置但大版本更新偶尔会改默认行为比如某些传感器的参数名变了或者新固件对老芯片存储器布局有调整。我的做法是先把当前设备的 YAML 和secrets.yaml复制一份到本地然后到 ESPHome Dashboard 里点升级。升级后第一次编译可能会提示旧组件与新组件冲突比如你之前手动配置过某些实验性 CSI 相关的自定义组件新版本转正后会跟它抢资源。遇到这种情况不用慌在 YAML 里把自定义组件的相关段落删掉保留官方组件即可。我这次就清理了一段两年前从社区抄来的 CSI 实验配置删掉后编译时间反而缩短了。3.2 最小可用配置5 分钟跑通 Wi-Fi 人体检测如果你只是想先跑通别急着调参用下面这份配置直接刷大概率能出效果。esp32: board: esp32dev framework: type: arduino logger: level: DEBUG wifi: ssid: !secret wifi_ssid password: !secret wifi_password channel: 6 esp32_csi: channel: 6 ht: true scan_interval: 2s window_size: 10 threshold: 75 binary_sensor: - platform: esp32_csi name: 书房人体存在 device_class: occupancy filters: - delayed_on: 5s - delayed_off: 60s逐个说明我为什么这样写。wifi里强制指定channel: 6是为了和esp32_csi的信道保持一致避免设备与路由器反复协商信道导致 CSI 基线不稳。scan_interval: 2s是扫描间隔window_size: 10表示用最近 10 次快照做统计相当于 20 秒的滑动窗口。threshold: 75是动作阈值先给个中庸值后面再调。filters里的两个延迟很关键delayed_on: 5s表示 CSI 特征变化持续 5 秒后才把状态翻转为“有人”防止瞬间干扰造成闪变delayed_off: 60s表示状态进入“无人”前必须保持 60 秒的无人特征避免人静止不动时被误判为离开。刷完固件后观察日志正常会看到类似CSI: packets123, threshold75的输出。然后走进房间手机打开 HA 的传感器页面等 5 秒左右状态应变“有人”。再走出门等 60 秒左右状态变回“无人”。3.3 调参进阶减少误报与漏报的实测组合跑通之后就是调优阶段。这一周我分别在书房、卫生间、客厅做了三组测试环境和活动特点不同最优参数完全不同。我整理成一张表你可以直接用。场景活动特点thresholdwindow_sizedelayed_off效果卫生间走动频繁、范围小60630s人来即亮人走快灭书房久坐、偶尔翻书751060s坐着不动也能保持“有人”客厅多人走动、有宠物9015120s误报最少状态稳定为什么会这样卫生间需要高灵敏度和快速响应所以阈值调低、窗口调小书房需要抑制“人静止但被判定为无人”的漏报所以把延迟关闭拉到 60 秒让状态翻转更保守客厅活动复杂随便一个动作变化都很明显阈值调高反而能过滤掉微动干扰。这里有个容易被忽略的联动细节delayed_off设得越长灯光自动化熄灭就越晚但也越不容易误关。如果你习惯人走灯灭又不介意多亮一分钟把delayed_off设成 90 秒甚至 120 秒体验会好很多。4. 常见问题与排查技巧实录4.1 日志里看不到任何 CSI 变化怎么排查如果你刷完固件日志里一直没有任何 CSI 相关的输出先别急着怀疑组件坏了。我遇到过三次原因各不相同。第一次是因为 ESP32 固件里开了省电模式Wi-Fi 接收窗口不稳定导致 CSI 采集失败。在 YAML 的wifi:段里加一行power_save_mode: none重启后问题解决。第二次是设备跑在 AP 模式下CSI 组件依赖 STA 模式的数据链路改成连接路由器后就正常了。第三次最隐蔽我手头那块老板子的天线虚焊信号太弱换了一块板子后 CSI 包数量立刻上来了。排查顺序建议是先看日志里有没有ESP32-CSI字样没有就检查供电和天线有数据但不触发状态翻转再检查信道一致性和阈值设置。4.2 有人但一直报“无人”是怎么回事这种情况最常见的诱因是“基线校准”问题。CSI 组件上电后会默认把当前环境当成无人基线。如果你在刷机后的前几分钟就有人待在房间里组件可能把“有人”的状态也纳入了基线统计之后人不动了它反而认为环境没变化输出无人。解决办法很简单刷完固件后让房间保持完全无人状态至少两分钟让组件建立干净的空环境基线。我每次调整参数后也会刻意等两分钟再进房间测试效果稳定很多。还有人静止坐在设备正下方 30cm 内的位置人体几乎贴住天线多径变化反而消失。这种物理遮挡问题只能通过调整部署位置解决。4.3 误报频繁、设备重启如何解决误报的来源通常不是人体而是房间里其他周期性工作的电器。空调风机启动、加湿器雾气喷出、鱼缸水泵运转都会让室内多径环境发生规律性变化CSI 统计特征就会被带偏。我书房的空调一开误报次数明显增加。后来把threshold从 75 提到 90配合delayed_on延长到 10 秒基本压住了。如果还不行可以考虑在 HA 自动化里增加“传感器在设备运行期间不触发灯光”的条件比如通过功率插座判断空调是否在工作在自动化里做一层逻辑过滤。另一个可能导致误报甚至重启的原因在供电。ESP32 用劣质 USB 电源时电流不足Wi-Fi 发射功率一上去电压就掉CSI 数据会剧烈抖动。这个不好直接看出来建议换一个标称 2A 以上的电源再观察。我实测换电源后误报率至少降了一半。4.4 和其他传感器联动时的两个坑如果你家里原来就有 PIR 传感器新加 CSI 人体检测后别急着让它们同时控制同一个自动化。PIR 的缺点是“人静即灭”CSI 的优点是“静默也能检测存在”两者冲突时应该以 CSI 为准PIR 只在 CSI 不可达的角落做辅助。我一开始直接让两个传感器“或”逻辑触发开灯结果人在书房刷手机超过半分钟PIR 关灯CSI 又立刻开灯灯光反复横跳体验非常糟糕。后来改成“CSI 优先PIR 仅在 CSI 状态为无人且检测到移动时提示”才算干净。还有一个坑是多个 ESP32 同时跑 CSI 检测同一个房间。如果两台设备信道相同且扫描时序不同步它们的 Wi-Fi 发射可能互相干扰导致 CSI 数据异常。我的建议是同一区域只保留一台主检测设备或者把两台设备设到不同信道中间用 HA 做结果汇总别让它们直接抢信号。最后说点个人体会。这套 Wi-Fi 人体检测不会取代毫米波雷达它测不到呼吸级别微动也无法和雷达那样输出距离信息。但对“人在不在房间”这个高频需求来说它的性价比无敌不用加硬件不用改布线把吃灰的老 ESP32 刷个固件就能用。如果你家里正好有旧板子强烈建议先拿一台试试固定信道、调好阈值、放对位置效果会比你预期的更接近毫米波方案。