zyn950929/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 模拟效果，非实机截图。 手机负责定位、路线与数据处理，圆屏展示导航、天气和音乐控制信息。

融合 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 将“前方终点”当成真正到达、导致圆屏提前播放到达动画的问题；同时限制重复结束、手动退出和迟到回调。维护者认为这是一个比较重大的 bug，建议旧版用户更新。详见 iOS 0.13.8 更新说明。新版 IPA 由 GitHub 的 macOS 构建流程生成，构建成功后出现在 Releases；仍需用自己的 Apple 账号签名安装。

维护者说明：我认为这是一个比较重大的 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 音乐响应及锁屏行为尚待实机验证，详见 配对与使用说明。

天气改用和风天气：实况、未来五小时预报、短时降水、空气质量和官方预警。圆屏天气页轻点循环显示主页、降水/空气、预警摘要；手机可查看完整详情及来源。仍按查看天气触发查询，并使用缓存，不在导航后台持续轮询天气。

从 GitHub Releases 下载 MotoNav-0.13.8-unsigned.ipa，使用自己的 Apple 账号通过 Sideloadly 签名安装。详见 安装与续签教程。

1. 下载仓库 ZIP 并完整解压到较短的本地路径。
2. 双击根目录“一键打包.bat”。不需要 Android Studio。
3. 首次需要联网下载 JDK、Android SDK、Gradle 和依赖；SDK 许可由官方工具提示，阅读后自行决定是否接受。
4. 成功后 output/MotoNav-personal.apk 是安装包，output/Application-info.txt 包含生成的包名和签名 SHA1。

首次打包自动生成专属应用包名与签名。源码命名空间 com.example.motonav 与实际安装包 applicationId 可以不同。

更新前必须备份 android/personal.properties 和整个 android/keystore 文件夹。新版解压后先复制回这两项，再打包，才能沿用包名、证书和地图绑定信息。不要把生成后的个人工程或证书公开上传。

本仓库不包含编译工具、依赖缓存、APK、个人签名或地图天气凭据。国内网络访问部分官方下载站点可能需要额外的网络配置。

已有环境可执行：

.\Build-Personal.ps1 -JavaPath 'D:\Tools\jdk-17' -SdkPath 'D:\Tools\android-sdk' -GradlePath 'D:\Tools\gradle\bin\gradle.bat'

已缓存所需依赖时可追加 -Offline。

安装后在手机首页“地图 Key”配置：

• 高德：Android 平台 SDK Key，绑定实际安装包的包名和发布证书 SHA1。地图、搜索、算路和导航仍依赖高德。
• 天地图：按所用 HTTP 地图服务申请对应 Key。仅选择天地图底图或卫星风格时需要。
• 和风：在“和风天气 → 配置”填入自己账号的 API Host 与 API Key，启用天气预报、分钟降水、空气质量和天气预警。凭据不内置。

服务权限、使用范围、请求额度、署名及计费以各服务商现行规则为准。不同用户重新签名并不自动获得服务授权。天气与预警可能延迟，不替代官方最新发布。

本机已安装 Arduino CLI / ESP32 Core 3.3.10 和 esptool 5.3.0。连接微雪 1.75 英寸圆屏的 USB 数据线，在 Finder 中双击根目录 一键烧录固件.command。脚本校验生成镜像的 SHA-256 和应用偏移，只有一个 USB 串口时自动选择，多个串口时要求选择。

默认写入 0x10000 的应用升级镜像，不执行整片擦除，适用于已有相同 16 MB / app3M_fat9M_16MB 分区的 MotoNav。首次完整安装可运行 ./一键烧录固件.command --full，需输入 INSTALL 确认。脚本只支持本仓库的 1.75 英寸板型。

./一键烧录固件.command --check 仅检查工具、固件和串口，不写入设备。固件镜像与清单位于 firmware/dist/175/panel0/；源码仓库不提交这些生成文件，缺少时需先构建并生成清单。HID 配对步骤见 说明。

iOS 与 Android 共用一份圆屏固件，源码位于 firmware/boards/175/MotoNav，第三方库位于 firmware/libraries。手机端 APK 与 IPA 分开发布，详见 通用固件说明。

使用 Arduino CLI，安装 Espressif ESP32 Arduino Core 3.3.10，然后执行：

.\firmware\build.ps1 -Board 175

可用 -CliPath、-ConfigFile 指定自己的 Arduino CLI 和配置。输出在 firmware/dist 中。已有相同板型及分区的 MotoNav 使用 app_0x10000 升级镜像；首次安装使用 full_0x0 完整镜像。完整刷写可能覆盖原程序和设置，请先备份。

android/tests/run.ps1 可运行到达判定、地图加载与轨迹采样、巡航计时、地图风格和区县格式检查。轨迹与常用目的地的持久化检查见 android/tests/README.md。天气解析测试见 android/tests/QWeatherClientTest.java，需要完成 App 编译、Kotlin 运行库及 org.json 测试运行库。

天气实现原版已完成 App、1.75 英寸板型固件的编译，以及接口示例数据解析检查；公开命名空间导出已构建验证。上方实拍来自用户提供的设备记录，软件检查与展示素材不代表独立路测或全场景验证通过。

licenses 和各第三方库目录保留原许可及版权声明。高德 SDK 通过构建依赖获取，地图/天气数据按服务商规则使用。品牌标识属于各自权利人。

项目自有代码及原创素材按 非商业使用条款 提供，不采用 MIT/Apache 等允许商业使用的许可。禁止未经许可倒卖源码、固件、安装包，或以付费代刷、打包销售、硬件捆绑销售等方式获利。第三方组件、地图和天气服务仍适用各自的许可及规则。

圆屏 v7.10.0 与 iOS v0.11.0 增加 iPhone AMS 歌曲信息：歌名、歌手、专辑、状态及进度，保留已实测可用的网易云 HID 媒体按键。详见 媒体控制与歌曲信息。

圆屏 v7.10.1 修复 iOS 无级旋转：正确解析 #R,最近四档,精确角度 的第二项，支持 0–359°，兼容旧四档 #R,0~3 和安卓版 #D角度。已安装的 iOS App 无需重装，停止拖动 1.5 秒后固件保存角度，触摸坐标继续按画面角度换算。

圆屏 v7.11.0 合并上述无级旋转修复并增加可选逐句歌词支持。配套 iOS v0.12.0 的媒体控制中“显示逐句歌词”默认关闭，默认布局是上方歌名、下方歌手；开启后使用 LRCLIB 匹配同步歌词，匹配不到时保留默认布局。仅升级固件不会给旧版手机 App 增加歌词开关。

圆屏 v7.12.0 增加歌词 OFF 清理及歌手栏刷新请求，并在 HID 未就绪时使用 iPhone AMS 媒体命令作为备用控制。iOS v0.12.1 增加独立歌词开关回执与重试；详见上述媒体协议说明。

iOS v0.13.7 默认使用高德建筑提取；修复 Retina 截图、相机更新时序与地图覆盖问题，并修复 App 重连错过认证通知、始终不查询圆屏建筑能力的问题。更新已安装到新手机，正常模拟导航已确认建筑地图生成和圆屏 K 回执，并通过固件解码器验证实际发送包。2026-10-17 的 120 km/h 前台模拟收到 42 次完整地图回执，用户确认此轮未再出现底图空白；地图传输延迟仍存在，详见 ios/README.md。