zyn950929 / MotoNav

# MotoNav
Android / iOS 手机配合 ESP32-S3 圆屏的导航项目。当前 Android App 8.3.21，iOS App 0.13.8，微雪圆屏固件 7.12.1。
iOS 工程已整合到 ios/，包含 Xcode 工程、分享扩展、构建说明和功能对照。iOS 已移植高德截图底图、建筑处理和沿线离线地图；播放器支持和后台取图能力与 Android 存在差异，详见该说明。
**本项目借助 AI 辅助开发，由个人进行需求设计、设备验证和迭代。仅供个人非商业使用与学习交流，禁止未经许可的商业使用及转售。**
**上图为 AI 模拟效果，非实机截图。** 手机负责定位、路线与数据处理，圆屏展示导航、天气和音乐控制信息。
## 圆屏固件 7.12.1（2026-10-18）
融合 GitHub 7.12.0 的 iOS HID/AMS、歌词和旋转支持，以及 7.8.13 的五分钟无导航关机与防重启修复。修复了旧 7.8.12 在关机时释放蓝牙对象、被迟到断连事件访问后崩溃重启的问题；建议使用该版本的 1.75 用户升级。
固件 7.12.1 下载与更新说明 · 详细更新说明
Windows 下载独立的一键烧录 ZIP，完整解压后双击“一键烧录.bat”；默认升级保留设置，首次完整刷写会整片擦除。仅适用于微雪 1.75，不适用于 1.85B 或 M5Stack StopWatch。
已对照 Android 8.3.21 公开源码/分享打包版与 iOS 0.13.8 核对协议，504 项音乐/旋转检查、关机计时和烧录工具检查通过。7.12.1 在实物上完成启动与接 USB 五分钟关机观察；7.8.13 的纯电池五分钟关机已由用户确认。融合版的纯电池、两端手机交替连接和道路测试仍待验证。旧个人直装 Android 8.3.21 缺少切换 iPhone 后复位音乐模式的处理，公开源码/分享包已包含该处理。
## iOS 0.13.8 到达动画修复（2026-10-18）
修复 iOS 将“前方终点”当成真正到达、导致圆屏提前播放到达动画的问题；同时限制重复结束、手动退出和迟到回调。维护者认为这是一个比较重大的 bug，建议旧版用户更新。详见 iOS 0.13.8 更新说明。新版 IPA 由 GitHub 的 macOS 构建流程生成，构建成功后出现在 Releases；仍需用自己的 Apple 账号签名安装。
## Android 8.3.21 重要更新（2026-10-18）
**维护者说明：我认为这是一个比较重大的 bug。** 旧版在距离终点约七八百米、仍处于导航时，小屏可能提前显示“已到达”的结算画面，随后又回到导航，容易误导使用者。8.3.21 修复了这个问题：前方终点提示继续作为正常导航，只有本次导航真正结束时才发送一次到达结算。已使用旧版的 Android 用户建议更新。
这次也同步公开 8.3.19 之后新增的**地图加载状态提示、骑行轨迹记录与 GPX 导出、常用目的地**。入口、使用方法、验证范围及限制见 Android 8.3.21 更新说明。本次更新 Android 源码与说明，iOS 和圆屏固件版本沿用仓库现有版本。
## 交通安全与使用风险
**使用本套程序时，请遵守交通法规。使用本套程序，默认使用者已知悉并自愿承担使用过程中可能带来的交通事故及其他风险。** 行驶中请勿操作手机或圆屏，设置与查看记录请先安全停车；始终以实际道路、交通信号、标志和现场情况为准，不得仅凭本程序作驾驶判断。
本项目仍可能存在定位、路线、地图、通信或显示错误，不保证导航信息准确、及时、完整。上述风险提示不排除适用法律规定的责任，也不意味着能免除依法不能免除的责任。
## 装到车上是什么样
用户提供的停车安装实拍。小圆屏可固定在车把附近，具体支架、供电和安装方式由使用者按车辆情况安排。
## 实机画面
| 导航与路线 | 音乐控制 | 降水与空气 |
| :---: | :---: | :---: |
| | | |
| 地图、转向距离、车速及行程环；桌面演示 | 查看曲目，控制上一首、播放/暂停、下一首 | 查看短时降水趋势及空气质量 |
| 天气主页 | 天气预警 | 启动就绪 |
| :---: | :---: | :---: |
| | | |
| 实况与未来五小时预报；**照片经 AI 隐私处理，地名已替换** | 拍摄时显示暂无有效预警 | **照片经 AI 隐私处理，设备后缀已替换** |
天气照片中的数据仅代表拍摄时的显示内容。经过隐私处理的两张图片不是原始照片，界面细节可能有变化。
## 动态演示
点击预览可打开对应 MP4。以下均为实机拍摄的桌面演示，视频已静音。
| 导航画面 | 路线与行程环 | 龙珠雷达风格 |
| :---: | :---: | :---: |
| | | |
## 模拟效果展示
两种导航视觉的概念展示，**AI 模拟效果，非实机截图**。
天气页面概念展示，**AI 模拟效果；数据虚构，非实时预报**。实际界面、数据可用性和硬件外观以当前软件及设备为准。
查看完整素材说明 · 打开离线展示页
## 支持的硬件
- Waveshare ESP32-S3-Touch-AMOLED-1.75，466×466。
本说明仅介绍上述 1.75 英寸板型，其余板型不列入当前支持范围。M5Stack StopWatch 不包含在本仓库。
## 功能
地图、路线、转向提醒、车速、行程环、巡航、音乐控制和品牌开机动画；保留摩托车、驾车、自行车的路线分享处理。高德网页无法还原原路线时，按界面提示处理，不保证所有分享链接都能还原。
iPhone 新增圆屏 BLE HID 媒体按键，可向当前播放器发送播放/暂停和上一首/下一首，面向 QQ 音乐等播放器使用。导航与媒体按键共用同一 BLE 设备；HID 不读取歌名或确认播放状态。需要系统 HID 配对，QQ 音乐响应及锁屏行为尚待实机验证，详见 配对与使用说明。
天气改用和风天气：实况、未来五小时预报、短时降水、空气质量和官方预警。圆屏天气页轻点循环显示主页、降水/空气、预警摘要；手机可查看完整详情及来源。仍按查看天气触发查询，并使用缓存，不在导航后台持续轮询天气。
## iPhone 安装
从 GitHub Releases 下载 `MotoNav-0.13.8-unsigned.ipa`，使用自己的 Apple 账号通过 Sideloadly 签名安装。详见 安装与续签教程。
## Windows 一键打包
1. 下载仓库 ZIP 并完整解压到较短的本地路径。
2. 双击根目录“一键打包.bat”。不需要 Android Studio。
3. 首次需要联网下载 JDK、Android SDK、Gradle 和依赖；SDK 许可由官方工具提示，阅读后自行决定是否接受。
4. 成功后 output/MotoNav-personal.apk 是安装包，output/Application-info.txt 包含生成的包名和签名 SHA1。
首次打包自动生成专属应用包名与签名。源码命名空间 com.exampl