⚡ ESP32 BMS GPS 🛰️

面向电摩、电动车与轻型车辆的 ESP32 智能仪表固件：在一块设备上整合 BMS、控制器、GPS、触摸屏、设备热点、Web 控制和手机投屏。

当前项目处于持续开发与实机联调阶段。核心固件和主要交互链路已经可用，OTA、轨迹存储及部分硬件兼容性仍未完成。

🖼️ 界面预览

设备设置首页	实时 BMS 数据
_{系统设置、亮度、音量、调节条位置与屏幕校准}	_{76% SOC、72.8 V、-12.6 A、剩余里程与单体电压}
BMW S1000RR 风格仪表	控制器数据
_{88 km/h、24 Wh/km、3 挡、控制器与电机温度}	_{86 km/h、3 挡、3.8 kW、4280 RPM 与温度}
本田火刃风格仪表
_{88 km/h、76% SOC、3 挡、功率、温度与续航信息}

🌐 在线控制网站

🌐 打开 Vercel 控制站

使用热点 API 控制设备：

在 TFT 设置中打开设备热点并查看二维码、SSID 和密码。
手机或电脑连接该热点。
打开上面的控制网站，允许浏览器访问本地网络，然后连接 http://192.168.4.1。

控制站默认中文，可切换英文。目前热点 HTTP API 是主要可用链路；页面也包含 Web Bluetooth 入口，但需要固件侧 BLE 控制服务配合。/cast 路径用于唤起 Android 投屏应用。

🎯 项目目标与开发进度

目标	开发进度	状态
🖥️ 用 TFT 提供适合骑行的速度、BMS、控制器和 GPS 仪表	配置档可选择 ST7789/XPT2046、ILI9488/FT6336U 或 ST7796U/GT1151；LVGL 仪表、旋转、亮度、触摸校准和快捷面板均已接入	🚧 持续优化
🔋 通过 BLE 接入各两轮平台的电池保护板，所有遥测均来自真实设备	ANT BMS 已完成扫描、绑定、连接、订阅、轮询和状态帧解析并通过实测，其他品牌与型号的保护板待适配验证	🚧 ANT 已实测，其他待测
🛞 通过 BLE 接入各控制器平台并准确换算车辆参数	已接入 BLE 协议、真实遥测、轮胎参数和传动比换算，继续完善设备兼容与数据校准	🚧 持续优化，目前接入了远驱控制器还未测试
🛰️ 提供 GPS 定位、速度、授时、轨迹记录和地图能力	已接入 336H UART NMEA、RMC 速度/定位/UTC 和按 profile 配置的 PPS 诊断，轨迹与地图尚未完成	🚧 基础链路可用
📡 通过 Setup AP、本地 Web UI 和公网 HTTPS 控制站完成配置、诊断与维护	随机热点凭据、二维码、`192.168.4.1`、配置 API 和 BMS 扫描/绑定入口已接入；Vercel 控制站已上线	✅ 已实现
🔊 为连接状态和设备操作提供清晰的音频反馈	经典 ESP32 可用 DAC，ESP32-S3 可用 I2S；功放与音频引脚由 profile 配置	✅ 已实现
📱 通过 Android 低延迟投屏扩展地图、导航与复杂信息展示	独立 Kotlin 应用和投屏协议已建立，正在优化延迟、稳定性与机型兼容	🚧 开发中
🌏 默认使用中文，并在设备设置中提供英文切换	中文默认界面与设置内语言切换策略已经确定，TFT 语言状态使用 ASCII `ZH` / `EN` 标记	🚧 持续完善
🔄 建立 OTA、TF 卡记录、历史轨迹和地图的完整闭环	OTA API 尚未形成完整升级闭环，TF 卡记录、历史轨迹和地图属于后续阶段	⏳ 待实现

“已实现”表示代码路径已经接入，不等同于所有目标硬件组合都已完成长期验证。

🛠️ 开发栈

层	技术
固件	C、ESP-IDF 6.0.2、FreeRTOS、CMake / `idf.py`
显示	LVGL 9.5、`esp_lvgl_adapter`、`esp_lcd`、ST7789/XPT2046、ILI9488/FT6336U、ST7796U/GT1151
设备能力	NimBLE、Wi-Fi SoftAP、`esp_http_server`、NVS、UART NMEA、ADC、LEDC、DAC、I2S
嵌入式 Web	单页 HTML / CSS / Vanilla JavaScript，编译进固件镜像
Vercel 控制站	React 19、TypeScript、Vite 6、Vercel
Android 投屏	Kotlin、Android SDK 35、Java 17、Gradle 8.14.2
质量与协作	GitNexus、Trellis、主机协议自测、ESP-IDF 构建与实机日志

依赖版本、分区、诊断构建和各平台构建命令以项目构建规范为准。

🚀 配置、构建与烧录

start.sh（Linux/macOS）和 start.cmd（Windows）是统一固件配置器。先用 doctor 检查环境；无参数运行进入交互式配置。--dashboards 可选 s1000rr、controller、fireblade，--modules 只编入所需模块。

Linux/macOS：

# 检查公共 ESP-IDF 环境；首次安装 ESP-IDF 6.0.2 时使用 install-idf
./start.sh doctor
./start.sh install-idf --dir /vol1/1000/toolchains/esp-idf-v6.0.2

# 交互式配置，或校验/保存火刃+BMS+控制器配置档
./start.sh
./start.sh validate --profile fireblade --modules bms,controller --dashboards fireblade
./start.sh configure --profile fireblade --modules bms,controller --dashboards fireblade

# 写入配置并在隔离目录中本地构建；云构建只触发工作流，不会推送
./start.sh build-local --profile fireblade --modules bms,controller --dashboards fireblade
./start.sh build-cloud --profile fireblade --modules bms,controller --dashboards fireblade

Windows 使用相同参数，将命令替换为 .\start.cmd，例如 .\start.cmd doctor、.\start.cmd 或 .\start.cmd build-local --profile fireblade --modules bms,controller --dashboards fireblade。Windows 首次安装可运行 .\start.cmd install-idf --dir C:\esp\esp-idf-v6.0.2；当前 Linux 主机的公共 ESP-IDF 位于 /vol1/1000/toolchains/esp-idf-v6.0.2，工具缓存位于 /vol1/1000/toolchains/.espressif-v6.0.2。

Linux 本地串口：

./scripts/esp-idf-env.sh -p /dev/ttyUSB0 flash monitor

Windows 本地串口：

.\scripts\flash.ps1 -Port COM3 -Monitor

编译后的交互烧录默认选择本地串口；远程 RFC2217 仅在明确选择后才输入地址。

本地编译会在 output/<配置名>/ 生成完整烧录包。在线烧录请选择 <配置名>-flash.bin 并写入 0x0；单独的 <配置名>.bin 是 OTA/应用镜像，只能按同目录 flash-manifest.json 的应用地址烧录（旧 ESP32 为 0x10000），不能写入 0x1000。

如果设备此前使用其他分区表，首次切换时需要先擦除 Flash。详细的构建、擦除、诊断镜像、分区布局和故障排查见固件硬件、构建与烧录规范。

🖥️ 桌面模拟器

Debian 安装 cmake、pkg-config、编译器和 libsdl2-dev 后运行：

./scripts/run-lvgl-simulator.sh --headless
./scripts/run-lvgl-simulator.sh --headless --portrait
./scripts/run-lvgl-simulator.sh

Windows 原生环境不需要 WSL。下载并解压 SDL2 开发包后，通过 PowerShell 指定目录：

.\scripts\run-lvgl-simulator.ps1 -SDL2Root C:\SDK\SDL2 --headless
.\scripts\run-lvgl-simulator.ps1 -SDL2Root C:\SDK\SDL2 --headless --portrait
.\scripts\run-lvgl-simulator.ps1 -SDL2Root C:\SDK\SDL2

也可以设置当前终端的 SDL2_ROOT，之后省略 -SDL2Root。脚本只配置、构建并启动模拟器，不安装全局依赖或修改系统环境变量。

Windows 模拟器默认启用本机蓝牙桥，以便扫描并连接真实 BMS 或远驱控制器。首次使用前安装宿主蓝牙桥依赖：

py -3 -m pip install -r .\simulator\requirements-ble.txt
.\scripts\run-lvgl-simulator.ps1 -SDL2Root C:\SDK\SDL2

模拟器使用 Windows 本机 BLE 适配器作为 Central。BMS 页面中先选择正确的保护板类型，再进入“蓝牙连接”扫描绑定；控制器页面使用相同的扫描绑定流程。需要只运行纯 UI 模拟数据时，显式传入 -NoHostBle。保留 -HostBle 参数以兼容已有启动命令，但本机蓝牙现在无需额外开关即可启用。

📁 目录结构

main/                         启动入口与嵌入式 Web UI
components/                   运行时、显示桥接、LVGL UI、协议与音频组件
config/                       ESP-IDF sdkconfig 模板与构建配置
firmware/                     固件配置档与分区表
android-cast/                 Android 低延迟投屏应用
vercel/                       独立的 Vercel 控制站前端
simulator/                    可在主机运行的 LVGL 模拟器
scripts/                      构建、烧录、串口桥接与诊断脚本
tests/                        可在主机运行的协议/逻辑自测
preview/                      本地 UI 预览脚本与未纳入版本控制的预览素材
img/                          README 图片资源
.github/                      GitHub Actions 云构建工作流
.trellis/spec/                项目工程规范与可执行约定

main/idf_main.c 只负责启动编排；硬件、协议、状态和 UI 逻辑应放在对应 ESP-IDF 组件中。 build/、firmware-builds/、output/ 等目录是本地构建或生成产物，不纳入源码目录结构。

📄 许可

本项目采用 PolyForm Noncommercial License 1.0.0。仅允许用于非商业目的；任何商业使用均需事先获得版权持有人的单独书面授权。

Name		Name	Last commit message	Last commit date
.agents/skills		.agents/skills
.claude		.claude
.codex		.codex
.github/workflows		.github/workflows
.reasonix		.reasonix
.serena		.serena
.tools/gradle-8.14.2/gradle-8.14.2		.tools/gradle-8.14.2/gradle-8.14.2
.trellis		.trellis
android-cast		android-cast
components		components
config/sdkconfig		config/sdkconfig
firmware		firmware
img		img
main		main
preview		preview
scripts		scripts
simulator		simulator
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
.monitor.log		.monitor.log
.rebuild.log		.rebuild.log
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CMakeLists.txt		CMakeLists.txt
LICENSE		LICENSE
README.en.md		README.en.md
README.md		README.md
androguard.db		androguard.db
codex_ble_probe.obj		codex_ble_probe.obj
dependencies.lock		dependencies.lock
esp_bms_module_registry.c		esp_bms_module_registry.c
reasonix.toml		reasonix.toml
sdkconfig-s3-local		sdkconfig-s3-local
start.cmd		start.cmd
start.ps1		start.ps1
start.sh		start.sh
vercel.json		vercel.json

Navigation Menu

Repository files navigation

⚡ ESP32 BMS GPS 🛰️

🖼️ 界面预览

🌐 在线控制网站

🎯 项目目标与开发进度

🛠️ 开发栈

🚀 配置、构建与烧录

🖥️ 桌面模拟器

📁 目录结构

📄 许可

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

⚡ ESP32 BMS GPS 🛰️

🖼️ 界面预览

🌐 在线控制网站

🎯 项目目标与开发进度

🛠️ 开发栈

🚀 配置、构建与烧录

🖥️ 桌面模拟器

📁 目录结构

📄 许可

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages