ESP32-Plane-Radar雷达范围预设与miles/km切换全解析:读懂声纳网格的完整指南

原创2026-10-16 09:28:581,391 阅读

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 个同心圆环、十字准线与 N/S/E/W 方位,第三环东侧显示当前范围标签

注:仓库内没有截图类图片文件,上面的占位说明可按实际运行效果替换。

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,低电平有效)。操作非常简单:

  1. 短按 BOOT:在 4 个预设间循环 5 → 10 → 15 → 25 km,自动写回闪存(flash);
  2. 长按 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 设置门户中完成:

  1. 连接设备 AP PlaneRadar-Setup(或已联网后打开 http://plane-radar.local / 设备 IP);
  2. 找到 "Display distances in miles" 复选框并勾选/取消;
  3. 保存后设备自动重启应用,第三环标签即时变为 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 的范围系统其实只有三个关键认知:

  1. 4 个预设(5/10/15/25 km)短按 BOOT 循环切换,自动写入闪存;
  2. 标签画在第 3 环,外半径 = 第三环 × 4/3,圈外飞机以边缘红点提示方向;
  3. miles/km 仅是显示层换算,内部恒以公里存储,门户一个复选框即可切换。

理解这三点后,你就能在任何机场旁边,随心调出最合适的声纳视角 🛩️。

登录后查看全文
ESP32-Plane-Radar