Mon3tr 电子吊坠

Mon3tr 电子吊坠项目致力于复刻手游明日方舟干员Mon3tr所佩戴的随心情变换的表情挂件，也可作为一般电子吊坠使用。本项目基于 ESP32-C3-MINI-1U（ESP32-2424S012）（触摸屏版/无触摸版） 开发板开发，通过 BLE + Android APP 实现上传、管理等功能，主分支触摸版固件原生支持滑动手势切换，目前支持上传显示JPEG/GIF格式。

---

项目结构

• Mon3tr_ESP32_Pendant/ —— ESP32-C3 固件源码（C/C++）
• M3/ —— Android 应用源码（Java）
• Images/ —— 项目图库

---

功能简介

• ESP32-C3 通过 BLE 与 Android APP 通信，接收命令动态显示图片，触摸版固件支持滑动切换
• Android APP 支持自定义上传、管理、切换、排序图片

---

快速上手

0基础请看这里

1. 硬件准备

• ESP32-2424S012 开发板
• 数据线、电源

2. 固件编译与烧录

1. 安装 Arduino IDE 2.3.6

2. 克隆本仓库，并用 Arduino IDE 打开 Mon3tr_ESP32_Pendant/Mon3tr_ESP32_Pendant.ino

   git clone https://github.com/RoyZ-iwnl/Mon3tr-Emoji.git
   cd Mon3tr_ESP32_Pendant/

3. Arduino IDE 设置

   • 【首选项】-【附加开发板管理器网址】：
     https://espressif.github.io/arduino-esp32/package_esp32_index.json
   • 【开发板管理器】安装 esp32 by Espressif Systems 2.0.13

     ⚠️ 对于本开发板，使用最新版开发板支持套件可能会导致各种问题，本项目仅推荐使用2.0.13

   • 【库管理器】安装以下依赖

     TFT_eSPI by Bodmer 2.5.43
     TJpg_Decoder by Bodmer 1.1.0
     

4. 编辑 libraries/TFT_eSPI/User_Setup.h
   备份原文件，用以下内容覆盖（仅适配 ESP32-2424S012 + GC9A01 屏）：

   #define TFT_RGB_ORDER TFT_BGR
   #define TFT_WIDTH  240
   #define TFT_HEIGHT 240
   #define TFT_BACKLIGHT_ON HIGH
   #define LOAD_GLCD
   #define LOAD_FONT2
   #define SMOOTH_FONT
   #define USER_SETUP_INFO "User_Setup"
   #define GC9A01_DRIVER
   #define COLOR_DEPTH 16
   #define TFT_MISO -1
   #define TFT_MOSI 7
   #define TFT_SCLK 6
   #define TFT_CS   10
   #define TFT_DC   2
   #define TFT_RST  -1
   #define TFT_BL   3
   #define SPI_FREQUENCY  40000000
   #define SPI_READ_FREQUENCY  20000000
   #define SPI_TOUCH_FREQUENCY  2500000

   ⚠️ 如使用其他 GC9A01 屏/板，请根据实际引脚调整

5. 连接开发板，IDE 内选择对应端口，点击上传即可。

   ⚠️ 注意：Arduino IDE 2.3.6 的 SD 库与 esp32 by Espressif Systems 2.0.13 自带 SD 库冲突。请在编译前移走 %LOCALAPPDATA%\Arduino15\libraries\SD 文件夹，需要时再放回。

3. Android APP 编译与安装

1. 安装 Android Studio
2. 以项目方式导入 M3/
3. 连接手机，开启【开发者选项】与【USB调试】
4. 编译运行或打包 APK 安装

4. 使用方法

1. 上电启动 ESP32-C3，确认 BLE 正常广播
2. 打开 APP，连接设备
3. APP 内上传、管理和切换图片

---

蓝牙协议规范

• 服务 UUID：4fafc201-1fb5-459e-8fcc-c5c9c331914b
• 命令特征 UUID：beb5483e-36e1-4688-b7f5-ea07361b26a8
• 数据特征 UUID：beb5483e-36e1-4688-b7f5-ea07361b26a9

1. 命令格式

[命令ID(1字节), 负载长度(1字节), 负载数据(变长)]

2. 响应格式

[命令ID(1字节), 状态码(1字节), 负载长度(1字节), 负载数据(变长)]

3. 命令列表

命令ID	名称	描述	负载格式
0x01	开始传输	开始图片传输	[图片索引(1字节)]
0x02	图片数据	图片数据分片	[图片数据(变长)]
0x03	结束传输	结束图片传输	无
0x04	删除图片	删除指定图片	[图片索引(1字节)]
0x05	重排图片	重新排序图片	[新顺序索引数组]
0x06	获取列表	获取图片列表	无
0x07	设置显示	设置当前显示图片	[图片索引(1字节)]
0x08	获取状态	获取设备状态	无

• 图片索引高4位为格式ID，低4位为文件索引

4. 响应状态码

状态码	名称	描述
0x00	成功	命令执行成功
0x01	一般错误	通用错误
0x02	文件系统	文件操作失败
0x03	传输错误	数据传输出错
0x04	参数错误	命令参数无效

5. 图片格式标识

• 0x00：原始二进制（已弃用）
• 0x10：JPEG
• 0x20：PNG（已弃用）
• 0x30：GFP（GFP格式规范）

6. 主要通信流程

• 图片上传流程

  1. 发送开始传输（0x01），负载为 [图片索引]
  2. 分包发送图片数据（0x02），每包 ≤512字节
  3. 发送结束传输（0x03），无负载

• 获取图片列表

  1. 发送获取列表（0x06）
  2. 接收响应，负载：[图片数量, {位置索引, 文件索引, 大小(4字节)}*n]

• 获取设备状态

  1. 发送获取状态（0x08）
  2. 响应负载：[开机时长(4字节), 存储用量(4字节), 当前显示索引]

     开机时长单位：秒，小端序

• 设置显示图片 发送设置显示（0x07），负载 [图片索引]

• 删除图片 发送删除图片（0x04），负载 [图片索引]

• 重排图片 发送重排图片（0x05），负载 [索引1, 索引2, ...]

7. 数据传输建议

• 建议 MTU 设为 512 字节
• 每包发送间隔 ≥30ms，防止处理延迟
• 所有多字节数据均为小端序

---

二次开发提示

• 修改 BLE UUID：参考 ble_handler.h
• 修改 BLE 广播名：参考 ble_handler.cpp 的 setupBLE 函数
• 触摸屏开发：参考 CST816D.h和CST816D.cpp的双击手势可能不良，其他开发板I2C引脚请根据实际编辑

---

TODO

• 代码规整
• 下调安卓最低SDK支持版本
• 优化安卓端的UI，添加关于页面

---

已知问题

• 上传图片因为同名而被覆盖（问题已定位在安卓端）

---

鸣谢

• 感谢 囧囧怪的WIFI版本开源项目 提供灵感
  外壳 3D 打印建模和开发板购买可参考该视频
• 感谢 LYao2514维护非触摸屏分支
• 没有Claude 就没有这个项目~

---

LICENSE

GPL-3.0

如有建议欢迎 issue 或 PR！