SkyCompass Satellite (人造天体观测罗盘)
简体中文 | English
🔥 固件已发布至 M5Burner!您可以在 M5Burner 官方烧录工具中直接搜索 SkyCompass Satellite 并一键免编译烧录体验。
项目概述
SkyCompass Satellite 是 SkyCompass 项目的扩展演化版本,运行在 M5Stack Cardputer ADV (ESP32-S3) 上。与原项目关注自然天体(太阳、月亮等)不同,Satellite 版本专注于**人造飞行器(如国际空间站 ISS、中国空间站天宫、哈勃望远镜等)**的实时空间轨道追踪与过境可视性预测。
核心产品定位: 向用户回答:“今晚有哪些人造天体值得抬头观测?”。它不仅是一个三维空间轨迹展示器,更是一个融合天文力学与光学评价的“今晚值得看”人造天体推荐系统。
核心功能亮点
- 🌍 3D 极简天球地球仪:内置矢量大陆轮廓、太阳昼夜晨昏线阴影、极地视觉锚点与 12000 点 NASA 夜景光害点云。
- ⭐ 智能观测推荐引擎:综合地平仰角、太阳照明与地球本影遮挡,动态预测视星等,自动推荐最佳过境肉眼可见窗口。
- ⏳ 时光机时间穿梭 (Time Machine):支持随时快进/快退模拟任意未来时刻的过境轨迹,具备 120ms 计算冷却门限保证 60 FPS 流畅操作。
- 📻 全天候业余无线电 (HAM) 通联辅助:实时多普勒频移补偿计算、APRS/SSTV 双通道频移监听、空间遥测数据包抓取控制台。
- 🧭 独创太阳日影物理对齐法 (Solar Shadow Alignment):在无内置电子罗盘硬件环境下,利用地表标针投影与现实影子平行重合实现三维空间 100% 精准对齐。
- 🪐 三轴浑仪乐高云台物理联动 (Orbital Arch Gimbal):I2C 联动三轴机械拱门机构,物理复现卫星飞行航向、过境最大仰角与实时太空滑行轨迹。
- 🔋 全天候离线生存与智能低功耗待机:48 小时 TLE 本地闪存多级缓存,GNSS 搜星后自动休眠,支持侧键
BtnG0 一键 3 秒倒计时主动息屏(关背光、关副屏、停止 IMU 与 3D 渲染,整机电流降至 30~45mA;在 RF 控制台仍可后台持续抓包收信),任意按键安全唤醒。
- 💡 开机多语言航天冷知识 (Satellite Trivia):利用多卫星积分算轨与外设初始化的开机时间,在开机界面直接展示精选航天与无线电极客故事,初始化完成即刻无缝进入程序(每次开机随机抽取一条)。附带专属 Prompt 模板 方便社区使用 AI 共同扩充。
硬件支持与接线
- 主机平台:M5Stack Cardputer (兼容 ADV 版与 v1.1 标准版,自适应引脚重映射)
- 定位授时:内置/外置 GNSS 模块 (GPS/北斗/GLONASS,串口 115200bps@8N1)
- 姿态感应:板载六轴 IMU (MPU6886 / SH200Q,独立 I2C 通道,与 GPS 并发运行互不干扰)
- 机械联动:M5Stack Unit 8Servos / PCA9685 舵机驱动板 + 乐高三轴立体浑仪机构
- 无线电扩展:M5Stack Cap LoRa-1262 射频通信单元 (SX1262)
预设硬件方案速查表
用户可根据手头的硬件模块自由选择以下接线组合,各场景均已在系统固件中经过总线调度与引脚适配:
| 硬件组合方案 | 顶部 14-Pin 扩展槽 | Cap 顶部 HY2.0-4P 接口 | 机身侧面 Grove 接口 | 硬件特性与适用场景 |
| :--- | :--- | :--- | :--- | :--- |
| Cap + 浑仪云台 + 像素副屏 | Cap LoRa-1262 (GNSS+射频) | Unit 8Servos (I2C: G8/G9) | Chain Mono (UART: G1/G2) | 全功能组合:双频定位、遥测抓包、浑仪机械三轴指向与 8x8 副屏动态外显全部激活,多总线独立并发无冲突 |
| Cap + 浑仪机械云台 | Cap LoRa-1262 (GNSS+射频) | Unit 8Servos (I2C: G8/G9) | 闲置 / 备用 | 空间三轴物理追踪,天球拱门立体复现过境走向、最高仰角与卫星滑行轨迹 |
| Cap + 像素副屏 | Cap LoRa-1262 (GNSS+射频) | 闲置 / 备用 | Chain Mono (UART: G1/G2) | 便携高精度双频授时定位、LoRa 空间遥测监听与 8x8 像素动态过境动画外显 |
| 仅 Cap 顶置单独使用 | Cap LoRa-1262 (GNSS+射频) | 闲置 / 备用 | 闲置 / 备用 | 手持便携:无任何外挂线缆,整机极致紧凑,提供高精度双频 GNSS 与 433~438MHz 空间无线电抓包 |
| 外置 Unit GPS 徒步便携版 | 未插接 Cap | - | Unit GPS v1.1 (UART 独占) | 侧面外接高灵敏度陶瓷天线 GNSS 模块,适合户外野外无网络环境单兵观测 |
| 独立浑仪舵机云台 (无Cap) | 未插接 Cap | - | Unit 8Servos (I2C: G2/G1) | 侧面直连舵机驱动板,依靠 WiFi 网络授时或断网离线预存坐标驱动浑仪 |
| 独立像素副屏 (无Cap) | 未插接 Cap | - | Chain Mono (UART: G1/G2) | 侧面直连 8x8 点阵副屏,依靠 WiFi 网络授时或断网坐标渲染过境动画 |
| 纯单机模拟演示 (无外设) | 无外接硬件 | - | 闲置 | 零外设门槛脱机运行,通过 WiFi NTP 对时与内置离线坐标,或按 C 键手动设定观测点 |
💡 外设配置向导:开机后在任意主界面按下 M 键,可随时呼出图形化硬件向导(Hardware Wizard),自由勾选模块并由系统实时校验总线冲突与显示动态接线指引。
⚠️ 舵机供电规范:驱动三轴浑仪乐高舵机时,Unit 8Servos 绿色接线端子必须接入 5V DC 独立外接电源(峰值电流可达 1.5A),严禁仅依靠 Cardputer 主控带载 3 个舵机,以防电压跌落导致 ESP32 重启。
🔌 Chain Mono 接线:副屏模块具有 IN 与 OUT 两个接口,Grove 线缆必须插接至 IN 端口(插 OUT 端口将无法正常通信)。
实机交互与按键速查
| 按键 | 功能操作 | 说明 |
| :--- | :--- | :--- |
| Enter | 展开/收起推荐面板 | 在面板中按 Enter 查看过境详情或直跳 AOS 时刻;开机时切下一条冷知识 |
| S | 卫星选择与百科全书 | f 分类筛选,d 删除自选卫星,O 发射单星入轨 |
| W | WiFi 连接与数据更新 | 扫描热点配网,执行 NTP 对时与 TLE 轨道根数拉取 |
| H | 快捷键帮助菜单 | 屏幕中央悬浮呼出按键提示,支持多语言适配 |
| L | 切换多语言 (i18n) | 支持中文、English、日本語、Español 实时切换并持久化 |
| M | 硬件配置向导 (Wizard) | 自由检测并开关 WiFi、GNSS、地磁仪、浑仪云台外设 |
| V | 卫星跟随视角 (Sat View) | 进入目标跟踪视角;; / . 切换目标,投射 3D 激光视线与仰角 |
| Ctrl | 射频终端控制台 (RF Console) | 实时多普勒频移监控、背景动态瀑布图与空间遥测抓包;T 测试注入 |
| Aa (Shift) | 浑仪舵机测试模式 | 0/1/2 切换轴,,// 微调角度,内置 30°~180° 防卡死保护 |
| C | 十字准星手动定位 | ;/. 调纬度,,// 调经度,[/] 调海拔高度 |
| , / / | 时光机快退 / 快进 | 短按步进 60 秒,长按高速穿梭(时间偏移时 HUD 呈黄色) |
| R | 重置时光机与坐标 | 瞬间恢复到真实物理时间与默认观测点 |
| Tab | 全局切换视觉模式 | 循环切换普通/极光/红光夜视护眼模式(在 RF 控制台同样生效) |
| Space | IMU 姿态锁定 / 切冷知识 | 锁定/释放当前体感跟踪视角;开机时按空格切换下一条冷知识卡片 |
| Del | 切换 HUD 状态角标 | 隐藏/恢复四角遥测数据显示 |
| [ / ] | 调节屏幕背光亮度 | 硬件级调节 TFT 屏幕背光(16 ~ 255) |
| G0 (侧键) | 主动息屏与低功耗待机 | 倒计时 3 秒后关闭背光、副屏、IMU 与渲染,任意键唤醒;在 RF 控制台下保持后台自动收信 |
| Esc / ~ | 返回 / 退出当前浮层 | 退出当前对话框、推荐面板或跟随视角 |
工程目录与代码架构
本项目遵循分层解耦与高内聚的设计原则,核心代码划分清晰:
SkyCompass_Satellite/
├── src/
│ ├── app/ # 应用程序控制(时间机器、用户按键上下文)
│ ├── core/ # 核心数学推算、天文力学与工具库
│ │ ├── orbit_utils.* # SGP4 轨道采样推算、GEO 槽位、编队识别与视口焦点维护
│ │ ├── radio_tracking_pipeline.* # 离散多普勒频移微分、过境窗口探测与射频动态调谐
│ │ ├── coord_transform.* # TEME / ECEF / 地心 / 站心拓扑坐标系精密转换
│ │ ├── earth_renderer.* # 3D 地球仪矢量海岸线、卫星天球投影与昼夜晨昏线渲染
│ │ ├── observation_predictor.* # 7天过境事件预测、光学视星等与多属性评分仲裁引擎
│ │ ├── image_utils.* # 夜视红光滤镜与串口 Base64 截图像素流传输
│ │ ├── text_utils.* # UTF-8 字符宽度折行、受限高度文本绘制与平滑跑马灯
│ │ ├── encyclopedia.* # 卫星百科全书静态数据库与分类标签
│ │ └── i18n.* # 多语言国际化字典与字体字形支持
│ ├── gimbal/ # 机械浑仪立体拱门云台驱动与自主巡天
│ │ ├── gimbal_tracking_pipeline.* # 全天自主巡天仲裁 (Sky Patrol) 与单星特写追踪 (Sat View)
│ │ └── gimbal_controller.* # Unit 8Servos / PCA9685 底层 I2C 舵机角度驱动与限位保护
│ ├── hal/ # 统一硬件抽象层 (HAL)
│ │ ├── hal_gnss.* # GPS/北斗 串口驱动、NMEA 解包与低功耗待机
│ │ ├── hal_imu.* # 六轴姿态传感器驱动 (MPU6886 / SH200Q)
│ │ ├── hal_wifi.* # WiFi STA 扫描、连接管理与网络状态监听
│ │ └── hal_radio.* # SX1262 (Cap LoRa-1262) 射频硬件 SPI 通讯抽象
│ ├── hardware/ # 扩展硬件显示服务
│ │ └── chain_mono_view.* # M5Chain 单色副屏刷新调度、倒计时与图标展示
│ ├── ui/ # 独立页面与组件视图
│ │ ├── sat_select_view.* # 卫星选择与百科大视图、多分类筛选弹窗
│ │ ├── recommendation_view.* # 左侧过境推荐卡片、折叠树视图与底部硬件双行状态栏
│ │ ├── rf_console_view.* # 全屏射频控制台终端与原始报文 HEX 查看器
│ │ ├── wifi_setup_view.* # WiFi 扫描分页热点列表与虚拟键盘配网
│ │ ├── servo_test_view.* # 浑仪舵机三轴标定与微调调试视图
│ │ ├── hardware_wizard_view.*# 硬件外设配置向导 (按 M 键呼出)
│ │ ├── dialog_views.* # 快捷键帮助浮窗(智能黄色高亮)与多语言切换对话框
│ │ └── startup_view.* # 开机 3D 地球仪体感自转与初始化加载条
│ └── main.cpp # 系统初始化入口 setup()、主事件泵 loop() 与轨推后台任务
├── docs/ # 专题技术白皮书与硬件设计文档
├── scripts/ # PC 端配套工具与数据预处理工具链
│ ├── update_builtin_tles.py # 出厂 TLE 轨道自动同步与固件头文件烘焙脚本
│ ├── get_screenshot.py # 串口原始像素流高保真截图接收与无损重构
│ ├── gen_light_points.py # NASA Black Marble 夜景灯光点云离线重采样
│ └── optimize_earth_data.py # 全球陆地矢量轮廓离线三角函数预计算
└── platformio.ini # PlatformIO 编译与依赖库配置文件
固件打包与出厂轨道数据更新 (scripts/update_builtin_tles.py)
为确保首次烧录后设备在完全离线环境下即开即用(无需联网即可精确计算全部卫星过境),并彻底杜绝首次开机因本地无缓存而连续向 CelesTrak 发起密集请求触发 IP 封锁(HTTP 403),本项目开发了出厂 TLE 一键自动同步与固件烘焙脚本 scripts/update_builtin_tles.py:
# 步骤 1:一键拉取全部 59 颗预置卫星当天的最新 TLE 并自动烘焙至 src/core/builtin_tles.h
python scripts/update_builtin_tles.py
# 步骤 2:编译并烧录固件
pio run -t upload
- 全量目标自动解析:静态扫描并解析
src/core/encyclopedia.cpp,自动提取百科库中全部 59 颗预置卫星(天宫、空间站、哈勃、导航群、业余无线电卫星、深空望远镜等)的 NORAD ID 与元数据;
- 双通道容灾与动力学拟合:优先拉取 CelesTrak 官方 GP API,遇到网络限制时自动无缝回退至开源卫星轨道镜像源;针对 JWST、鹊桥等非地心深空飞行器自动应用专有轨道动力学伪 TLE 拟合,实现 100% 轨根覆盖率;
- 固件静态内嵌烘焙:自动生成只读头文件
src/core/builtin_tles.h,包含完整的 TLE 数据结构表与精确到秒的 UTC 烘焙时间戳;
- 首次开机自动建表 (Cache Seeding):新固件首次烧录启动时,系统自检发现 LittleFS 闪存为空,会秒级将出厂烘焙的最新 TLE 注入本地文件系统。后续设备开机或联网时,直接复用有效的本地缓存,无需重复高频向云端请求,从源头上保障网络健壮性。
详细技术专题与开发文档
深入研究底层原理、物理算法与拓展开发,请参阅 docs/ 目录下的专题文档:
| 专题技术文档 | 核心内容概述 |
| :--- | :--- |
| 📐 轨道推演与可见性预测技术细节 | SGP4 摄动模型、TEME/ECEF/ENU 坐标转换、大气折射/消光、视星等相函数、多普勒频移物理推导与太阳日影对齐原理 |
| 💾 数据层与多级缓存架构 | 兼容 6 位 NORAD Catalog ID 的 Pseudo TLE 桥接技术、GP JSON 格式解析、48h TLE/7d API 离线分级缓存策略 |
| 🛠️ 固件编译与烧录指南 | M5Burner 免编译体验、PlatformIO CLI 本地构建与烧录、环境依赖与常见故障排查 |
| 📸 高保真屏幕截图与辅助工具链 | 无 PSRAM 架构下零压缩 RGB565 分段串口截图机制、PC 监听脚本及离线点云地图预处理工具 |
| 🔭 浑仪卫星过境指向功能设计与使用指南 | 机械三轴立体拱门联动原理、舵机死区与活动角度标定、巡天仲裁机制 |
| 📡 卫星 LoRa+UHF 接收解析实现方案 | SX1262 射频前端、动态多普勒自动调谐与 AX.25 遥测报文解析架构 |
| 🛰️ 物理射频仿真测试与实测收包验证指南 | 利用 Meshtastic 开源硬件与时光机完成室内高保真闭环收发验证、多普勒容差数学原理推导与实测照片 |
软件界面与物理射频实机演示
1. 核心软件交互视图
| 3D 轨迹主视角与卫星环绕 | 卫星百科、特制图标与 HAM 频率 | 快捷键帮助悬浮框 |
| :---: | :---: | :---: |
| | | |
2. 真实物理射频链路空中收包实测 (Cap LoRa-1262)
配合系统的时光机 (Time Machine) 功能(模拟将卫星轨道时间推演至过境高点),使用常见开源 LoRa 模块(如 ESP32-C3 + SX1268)模拟星载信标发射,在室内无网络环境下成功实现物理空中连续无误码抓包与星务遥测解析:
| RF Console 瀑布流接收与多普勒跟踪 (5包 0误码) | 实时数据包 HEX 解码与遥测解析弹窗 |
| :---: | :---: |
| | |
- 多普勒理论验证:当推演仰角为 $EL: +13.4^\circ$ 时,系统精确计算出 $-10.2\text{ kHz}$ 多普勒频移并将中心频率下调至 $436.690\text{ MHz}$。由于 LoRa BW125kHz 拥有高达 $\pm 31.25\text{ kHz}$($\pm \text{BW}/4$)的载波频偏容限,即使地面以固定频率发射,亦能百分之百牢固捕获并解调出空中报文,实测信噪比高达 $+12\text{ dB}$;
- 全链路闭环:验证了从SGP4 轨道动力学 ➔ 仰角过境自动唤醒 ➔ 多普勒动态微调 ➔ 物理空中捕获 ➔ 频谱瀑布图 ➔ 遥测协议数据字典还原 ➔ Flash/SD 长期记录的全套自动化巡天流程。
数据来源与致谢
- TLE 轨道数据:感谢 CelesTrak 提供高精度、实时更新的轨道根数服务。
- 3D 陆地轮廓矢量数据:感谢 Natural Earth 提供的 50m 分辨率全球陆地边界矢量数据。
- 全球夜景灯光点云:感谢 NASA GIBS 提供的 VIIRS Black Marble 全球夜景图源。
- 航天器 3D 构型参考:感谢 NASA-3D-Resources 提供的官方航天器与空间站 3D 模型开源参考资源。
- 空间遥测与地面站灵感:感谢 TinyGS 开放硬件与全球分布式地面站网络在业余空间 LoRa 遥测接收与多普勒调谐方面的先驱探索与宝贵灵感。
- UI 动效与物理弹簧设计:特别鸣谢 lilt 在物理弹簧动力学模型与细腻交互动效方面的卓越探索与开源灵感,本项目借鉴其物理弹簧阻尼架构与连续微积分思想,在无 PSRAM 嵌入式设备上实现了流畅、自然的交互体验。
- 模型校准与仿真参考:感谢 天文通 与 Heavens-Above 提供的模拟比对支持。
许可证
本项目采用 GNU General Public License v3.0 (GPLv3) 开源许可证。