ESP32-Plane-Radar雷达范围预设与miles/km切换全解析:读懂声纳网格的完整指南
ESP32-Plane-Radar雷达范围预设与miles/km切换全解析:读懂声纳网格的完整指南
ESP32-Plane-Radar 是一款开源 ESP32 固件:在 1.28″ 圆形屏幕上以声纳网格实时显示你周边的 ADS-B 航班。读懂它的范围预设(5/10/15/25 km)与 miles/km 单位切换,是玩转这款雷达的第一步。
一分钟看懂声纳网格 📡
雷达画面的构成很克制:深蓝背景、绿色同心圆环与十字准线、白色中心点,屏幕外圈标注 N/S/E/W 方位,而第三环东侧会显示当前距离标签(如 10km 或 6mi)。颜色与布局常量集中在 radar_theme.h。
| 要素 | 说明 |
|---|---|
| 同心圆环 | 共 4 个环,外环半径 107 px(radar_theme.h) |
| 距离标签 | 打在第 3 环(外半径的 3/4 处),而非最外圈 |
| 中心点 | 即你在设置门户中配置的经纬度位置 |
| 飞机符号 | 圈内为红色机头三角 + 品红速度矢量 + 呼号/机型/高度标签 |
注:仓库内没有截图类图片文件,上面的占位说明可按实际运行效果替换。
4 个范围预设详解:5/10/15/25 km 怎么选
预设定义在 radar_range.h 的 kRangePresets 数组中,单位统一以公里存储:
| 第三环标签 | 外半径(飞机实际缩放) | 推荐场景 |
|---|---|---|
| 5 km / 3 mi | ≈ 6.7 km | 本场飞行、机场周边(pattern) |
| 10 km / 6 mi(默认) | ≈ 13.3 km | 邻里观机,日常最均衡 |
| 15 km / 9 mi | ≈ 20 km | 更宽的区域视角 |
| 25 km / 16 mi | ≈ 33.3 km | 都市圈/区域全景 |
为什么标签画在第 3 环,而不是最外圈?
这是整个网格最巧妙的数学细节。radar_range.h 中定义了换算常数 kRing3ToOuterKm = 4.0f / 3.0f:
- 屏幕上第 3 环半径 = 外半径 × 3/4,标签直接标注在这条环上;
- 飞机位置计算用的"外半径"则是第三环距离 ÷ 0.75,即 × 4/3。
好处是:标签离屏幕边缘留出余量,不会被方位字母或圆环压住,同时最外圈之外的飞机仍有数据支撑(见下文 fetch 半径)。
如何切换范围:BOOT 键一键循环
设备只需一个物理按键(BOOT,GPIO 9,低电平有效)。操作非常简单:
- 短按 BOOT:在 4 个预设间循环 5 → 10 → 15 → 25 km,自动写回闪存(flash);
- 长按 3 秒:清空 Wi-Fi、位置和 units 设置,重启进入设置门户(相当于恢复出厂)。
短按触发链路可以完整追到源码:main.cpp 中 handleBootButton() 消费到一次"tap"事件后调用 onRangeTap(),它执行 ui::radar::rangeNext(),并通过串口打印当前范围(如 Range: 15km (outer ~20 km)),随后立即重绘画面。
rangeNext() 的实现(radar_range.cpp)只有一行核心逻辑:索引 +1 后对 4 取模,实现无缝循环,并调用 saveRangeIndex() 持久化。
miles/km 单位切换:设置门户复选框
英制/公制切换不靠按键,而是在 Wi-Fi 设置门户中完成:
- 连接设备 AP
PlaneRadar-Setup(或已联网后打开http://plane-radar.local/ 设备 IP); - 找到 "Display distances in miles" 复选框并勾选/取消;
- 保存后设备自动重启应用,第三环标签即时变为
mi或km形式。
标签如何从 km 换算成 mi?
换算在 radar_range.cpp 的 formatRing3Label() 中完成,固定换算率 kKmPerMile = 1.609344f,并四舍五入到整数再拼接单位:
| 预设(km 存储值) | km 模式显示 | miles 模式显示 |
|---|---|---|
| 5 km | 5km |
3mi |
| 10 km | 10km |
6mi |
| 15 km | 15km |
9mi |
| 25 km | 25km |
16mi |
注意:内部永远以公里存储,miles 只是显示层换算——所以你切换到 miles 后再短按 BOOT,范围行为完全一致,只是标签数字变了。
门户中该复选框的参数定义见 wifi_setup.cpp(参数名 use_miles,默认值 "T" 表示勾选)。
进阶:fetch 半径让"圈外红点"有数据
你可能会问:飞机明明超出了最外圈,为什么边缘还能出现指示红点?答案是 fetchRadiusKm()(radar_range.cpp):
它把当前预设的 outer_km 按像素比例放大到屏幕边缘(kCenterX - kBeyondRingScreenMarginPx 对应 107 px 外环)。于是 ADS-B 查询半径略大于显示外圈:
- 圈内飞机:完整红色三角符号 + 速度矢量 + 信息标签;
- 圈外飞机:屏幕边缘的正确方位上显示小红点(方向提示,距离不精确);
- 范围调小或飞机进场后,圈外红点"长"成完整符号。
这意味着:范围预设同时决定了数据抓取范围,切换预设后下一次轮询(约 5 s 一次)就会按新半径请求数据。
设置项如何持久化:NVS 闪存机制
所有偏好都存在 ESP32 的 NVS(Non-Volatile Storage)中,命名空间为 planeradar(radar_range.cpp):
| NVS Key | 含义 | 默认值 |
|---|---|---|
rangeIdx |
当前范围预设索引 | 1(即 10 km) |
useMiles |
距离单位 miles/km | false(km) |
showRwys |
机场跑道叠加层 | true |
开机时 rangeInit() 一次性读回这些值(radar_range.cpp),并做了越界保护:若保存值超出预设数量则回落到默认 10 km。因此范围和单位选择断电不丢失,重启即恢复上次设置。
想整体重置 units 时,长按 BOOT 3 秒即可——unitsReset()(radar_range.cpp)会把单位复位为 km、跑道叠加复位为开启,并删除对应 NVS 条目。
常见问题 FAQ
Q:切到 miles 后范围会变吗?
不会。miles 只影响标签显示(如 10km ↔ 6mi),底层仍以公里存储和计算。
Q:为什么标签不是 10 mi 而是 6 mi? 因为换算率是 1 km = 0.621 mi,10 km 四舍五入后恰为 6 mi,属于正常换算而非 bug。
Q:想自定义范围预设(比如加一个 30 km)?
修改 radar_range.h 中 kRangePresets 数组即可,数组长度会自动反映到循环切换与 NVS 校验逻辑中;全局参数(轮询间隔、默认经纬度)在 config.h 调整。
Q:网格为什么不闪烁?
渲染采用双缓冲:先离屏合成网格 + 飞机到帧缓冲区,再一次 pushSprite 整屏推送到面板(radar_display.cpp),标签不会出现擦除/重绘的空档。
核心文件速查表
| 想了解 | 看这里 |
|---|---|
| 预设数值与 3/4 环数学 | include/ui/radar_range.h |
| 单位换算、NVS 持久化 | src/ui/radar_range.cpp |
| 网格/标签/双缓冲渲染 | src/ui/radar_display.cpp |
| 颜色、半径等视觉常量 | include/ui/radar_theme.h |
| BOOT 按键与主循环 | src/main.cpp |
| 门户 miles 复选框 | src/services/wifi_setup.cpp |
| 全局行为配置 | include/config.h |
| 构建入口 | platformio.ini |
总结
ESP32-Plane-Radar 的范围系统其实只有三个关键认知:
- 4 个预设(5/10/15/25 km)短按 BOOT 循环切换,自动写入闪存;
- 标签画在第 3 环,外半径 = 第三环 × 4/3,圈外飞机以边缘红点提示方向;
- miles/km 仅是显示层换算,内部恒以公里存储,门户一个复选框即可切换。
理解这三点后,你就能在任何机场旁边,随心调出最合适的声纳视角 🛩️。