构建一个真实的 Minecraft 指南针 (MCompass)！本项目基于 ESP32-C3 和 GPS 模块，目前已完美复刻游戏中的 Lodestone 磁石指向功能。
1. 硬件准备与物料清单 (BOM)
MCompass 结构件 (3D 模型)
如果你有 3D 打印机（推荐拓竹 Bambu Lab 系列），可以直接前往 MakerWorld 下载已经配置好耗材参数的工程文件。
- 官方模型地址: MakerWorld - MCompass (The Lost Compass)
- 打印建议: 推荐使用 PLA 或 PETG 材质。黑色外壳配合适当的填充率可以获得更好的质感。
电子物料 (BOM)
| 类别 | 名称 | 规格 | 备注 |
|---|---|---|---|
| 主控 | ESP32-C3-MINI | ||
| 磁力计 | QMC5883L / P | LGA-16 3x3 | L 已停产多为翻新，推荐用 P 型号 |
| GPS | ATGM336H-5N71 | 13.1x15.7mm | 需包含配套陶瓷天线 |
| LED | WS2812B 0807 | 1.7x2.0x0.85mm | 需要 42 颗，推荐雾状灯珠 |
| 电池 | 213455 锂电池 | 500mAh | 尺寸需严格匹配外壳空间 |
关键辅助原件
- LDO电源: AP2112K-3.3 或 ME6211 (省钱型号)
- 充电管理: MCP73831
- USB接口: GT-USB-7010ASV (USB-C 16P)
- 结构五金:
- 滚花螺母: M2x3x3.2 (用于通过热熔嵌入外壳)
- 螺丝: M2x4 内六角
2. 烧录与编译指南
固件获取方式
如果你不打算修改源代码，可以直接下载编译好的二进制文件 (Firmware)。
2.1 从 GitHub Actions 自动构建下载 (推荐)
本项目已配置 GitHub Actions 自动编译。前往 GitHub 项目的 Actions 页面，找到最近一次构建成功的 “Build Firmware Workflow” 记录，在 Artifacts 区域下载对应版本的 .bin 文件。
2.2 手动编译 (PlatformIO)
- 固件: 基于 Arduino 框架，依赖库位于本地
lib文件夹。 - 网页资源: 进入
Server文件夹，执行npm i和npm run build，将out目录内容拷贝至固件的data文件夹下。
烧录指南
- 芯片选择: ESP32-C3, 下载模式: USB
- 文件选择: 将
.bin文件加载到地址 0x0。 - 参数: SPI SPEED: 40MHz, SPI MODE: DIO。
如果你想用手机烧录，可以使用作者开发的 ESPFlash (Android):
3. 交互使用说明
按钮操作
| 操作次数 | 功能描述 | 备注 |
|---|---|---|
| 单击 1 次 | 切换模式 | 在“出生点模式”与“指南针模式”间切换 |
| 连按 4 次 | 查询状态 | 网页模式下会显示当前设备的 IP 地址 |
| 连按 6 次 | 地磁校准 | 倒计时结束后，需拿稳罗盘在空中平稳画“8”字旋转 |
| 连按 8 次 | 出厂设置 | 清除所有配置并重启 |
| 长按 3 秒 | 特殊功能 | 出生点模式：重设坐标点；指南针模式：进入 Nether 模式（乱转） |
后台配置
- 蓝牙后台: 通过微信小程序 “罗盘控制台” 搜索连接。可自定义指针颜色及地图选点。
- 网页后台: 连接热点
The Lost Compass，访问192.168.4.1进行 WiFi 配置和传感器调试。
4. 重要声明 (Copyright & Safety)
- 素材声明：Minecraft 视觉素材版权归 Microsoft / Mojang 所有。本项目仅提供点阵开源设计，不分发游戏原始资源。
- 商业使用限制：严禁 用于商业盈利。PCB 背面的标准银河字母丝印如涉及商业化请自行删除。
- 制作建议：本装置涉及锂电池，请在具备电子制作常识的情况下进行。
更新日志 (Changelog)
- 2025.09.17: 引入指针过冲物理效果；优化启动容错；增加智能 GPS 电源策略。
- 2024.12.14: 初始版本发布，支持磁石定位。