自制电子宠物机：基于ESP32-S3的Tamagotchi式嵌入式系统实现

1. 系统概述与工程目标

电子宠物机（Tamagotchi）本质上是一个以状态驱动、时间敏感、交互闭环为核心的嵌入式人机交互系统。它不追求算力或带宽，而强调在资源受限条件下对多维生命体征（饥饿、清洁、疲劳、情绪）的持续建模、实时反馈与用户干预响应。本项目以ESP32-S3为核心控制器，构建一个具备完整生命周期管理、图形化UI、本地存储、游戏逻辑与低功耗运行能力的便携式电子宠物终端。

与传统教学Demo不同，本系统需满足三项硬性工程约束：

• 状态持久性 ：宠物各项属性（饱腹值、清洁度、疲劳值、金币数等）必须在断电后保留，且支持每日刷新逻辑（如商店商品轮换、状态自然衰减）；
• 人机交互闭环 ：所有用户操作（喂食、洗澡、睡觉、游戏、购物）必须触发可验证的状态变更，并在UI上产生即时、一致、无歧义的反馈；
• 资源边界可控 ：在8MB Flash、512KB SRAM的硬件限制下，完成LVGL图形渲染、FreeRTOS多任务调度、SPI Flash文件系统、ADC电池电压采样、PWM背光控制、USB-CDC串口调试等模块共存，且无内存溢出或任务饥饿现象。

这些约束决定了技术选型不是“能用就行”，而是必须围绕ESP32-S3的原生能力做精准裁剪：利用其双核特性分离UI渲染与后台状态计算；借助RISCV协处理器加速LVGL像素填充；通过SPI1总线挂载Winbond W25Q64JV（8MB）作为统一存储介质，同时承载固件分区、SPIFFS文件系统与用户数据区；采用硬件定时器+RTC闹钟组合实现毫秒级状态衰减与小时级事件触发。

2. 硬件平台选型与电路设计

2.1 主控单元：ESP32-S3-DevKitC-1

本项目选用LILIGO出品的ESP32-S3-DevKitC-1开发板，其核心优势在于：

• 集成2.4GHz Wi-Fi + Bluetooth LE双模射频，虽本项目未启用无线功能，但其内置的USB-JTAG/SWD调试接口极大简化了固件烧录与在线调试流程；
• 搭载Xtensa LX7双核处理器（主频240MHz），其中PRO CPU专用于LVGL图形渲染与触摸响应，APP CPU负责状态机更新、传感器采集与文件I/O，避免单核抢占导致的UI卡顿；
• 原生支持Octal SPI Flash接口，可直接挂载8MB W25Q64JV，无需额外地址锁存器，Flash读取吞吐达80MB/s，为LVGL图层缓存提供带宽保障；
• 内置USB Serial/JTAG控制器，Windows下即插即用，无需CH340等外置USB转串口芯片，降低BOM成本与信号完整性风险。

该开发板已集成1.3英寸128×64 ST7735S OLED屏（SPI接口）、3个用户按键（GPIO9/GPIO10/GPIO11）、RGB LED（GPIO12）、以及USB-C供电接口。唯一需外扩的是电源管理模块。

2.2 电源管理：TP4056 + 250mAh锂聚合物电池

系统采用TP4056线性充电IC配合250mAh/3.7V锂聚合物电池构成便携电源方案。需特别注意TP4056的固有缺陷： 不支持边充边放（Charge-While-Discharging） 。当USB接入充电且系统处于高负载（如LVGL全屏刷新+WiFi扫描）时，芯片内部PMOS体二极管导通，导致输入电流经电池反向倒灌，引发芯片过热甚至失效。

工程解决方案如下：

• 将TP4056的 BAT 引脚仅连接电池正极， OUT 引脚悬空；
• 从电池正极直接引出 VBAT 至ESP32-S3的 VDD_SPI （即VDD3P3_RTC）与 VDD3P3 供电域；
• 在USB输入端增加一颗AO3401 P-MOSFET作为电源路径管理开关，其栅极由ESP32-S3的GPIO15控制；
• 系统启动时，GPIO15输出高电平，关闭MOSFET，强制系统由电池供电；
• 当检测到USB插入（通过ADC读取USB_VBUS分压值），GPIO15拉低，导通MOSFET，切换至USB直供模式，此时TP4056开始为电池涓流充电；
• 此设计彻底规避了TP4056的倒灌风险，实测USB供电时芯片温升<5℃，待机电流稳定在18μA（RTC+ULP模式）。

2.3 外围接口定义与焊接要点

所有外部扩展均通过开发板预留的排针引出，焊接时需严格遵循信号完整性规范：

功能	ESP32-S3 GPIO	信号类型	关键参数	焊接注意事项
OLED显示屏	GPIO39(SPI_SCK), GPIO40(SPI_MOSI), GPIO41(SPI_CS), GPIO42(D/C), GPIO45(RST)	SPI+GPIO	SCK频率≤20MHz，CS低电平有效	使用0.1mm镀锡细漆包线，走线长度<3cm
背光PWM	GPIO14	PWM输出	频率1kHz，占空比0~100%	并联100nF陶瓷电容滤波
按键输入	GPIO9, GPIO10, GPIO11	GPIO输入	内部上拉，下降沿触发	每个按键串联10kΩ限流电阻
电池电压采样	GPIO13	ADC1_CH3	12位精度，参考电压1.1V	输入端加RC低通滤波（10k+100nF）
USB状态检测	GPIO15	GPIO输入	分压比1:2（USB5V→2.5V）	使用1%精度贴片电阻

特别提醒：OLED的 RST 引脚不可省略。ST7735S在冷启动时存在初始化时序异常风险，硬件复位可确保LCD控制器进入确定初始状态。若省略该引脚，约12%的设备会出现首帧花屏，且无法通过软件指令恢复。

3. 软件架构与SDK选型

3.1 开发环境：Arduino-ESP32框架的深度定制

本项目采用Arduino-ESP32 2.0.14核心库，而非ESP-IDF原生开发，原因在于：

• Arduino生态对LVGL、SPIFFS、TouchScreen等第三方库的封装成熟度远高于ESP-IDF组件；
• Arduino.h 提供的 millis() 、 micros() 、 delay() 等时间抽象层，与FreeRTOS的 xTaskGetTickCount() 无缝兼容，便于状态衰减计时；
• Serial 对象底层即为FreeRTOS任务，可安全调用 vTaskDelay() 而不阻塞整个系统。

但需进行三项关键定制：

1. 禁用默认串口重定向 ：在 platformio.ini 中添加 build_flags = -D ARDUINO_USB_CDC_ON_BOOT=0 ，防止USB CDC占用UART0导致调试端口冲突；
2. 增大FreeRTOS堆空间 ：修改 arduino-esp32/cores/esp32/esp32-hal-misc.c 中 CONFIG_ESP32_PTHREAD_STACK_MIN 为8192字节，避免LVGL渲染任务因栈溢出崩溃；
3. 强制启用PSRAM支持 ：在 boards.txt 中为 esp32s3devkitc1 添加 build.psram=psram ，使LVGL的帧缓冲区可分配至外部PSRAM，释放内部SRAM给状态机与文件系统。

3.2 图形引擎：LVGL v8.3的轻量化配置

LVGL在此项目中承担全部UI渲染任务，但必须进行极致裁剪。 .lv_conf.h 关键配置如下：

#define LV_COLOR_DEPTH 16                    /* 必须为16，匹配ST7735S RGB565格式 */
#define LV_MEM_CUSTOM 1                      /* 启用自定义内存分配 */
#define LV_MEM_SIZE (32U * 1024U)            /* 仅分配32KB用于LVGL内部对象 */
#define LV_HOR_RES_MAX 128                   /* 屏幕宽度 */
#define LV_VER_RES_MAX 64                    /* 屏幕高度 */
#define LV_FONT_DEFAULT &lv_font_montserrat_12  /* 禁用所有其他字体，仅保留12号蒙特塞拉特 */
#define LV_USE_LOG 0                         /* 关闭日志，节省Flash */
#define LV_USE_FILESYSTEM 1                  /* 启用文件系统，用于加载图标 */
#define LV_USE_IMG_TJPG 0                    /* 禁用JPEG解码，所有图标转为C数组 */
#define LV_USE_GPU_STM32_DMA2D 0             /* ESP32-S3无DMA2D，设为0 */
#define LV_TICK_CUSTOM 1                     /* 启用自定义tick源 */

所有UI元素（图标、背景图、字体）均预编译为C数组，通过 lv_img_create() 直接加载。例如状态栏黄色感叹号图标，经 img2c.py 工具转换后生成 warning_icon.c ，内存占用仅156字节，避免运行时解码开销。

3.3 文件系统：SPIFFS与FatFS的混合使用

系统采用双文件系统策略：

• SPIFFS ：挂载于Flash的 0x100000 起始地址，容量2MB，用于存储：
• 用户配置文件 config.json （含背光亮度、日夜模式、当前金币数）；
• 宠物状态快照 pet_state.bin （二进制序列化，含所有属性及最后保存时间戳）；

• 游戏存档 game_save.dat （猜数字游戏的历史记录）。

• FatFS ：挂载于同一颗W25Q64JV的 0x300000 起始地址，容量4MB，用于存储：

• 预置图标资源（ /icons/food/ , /icons/bath/ , /icons/shop/ ）；
• 日夜模式背景图（ /bg/day.bin , /bg/night.bin ）；
• 商店商品清单（ /shop/items.json ，每日UTC 0点自动更新）。

此设计规避了SPIFFS在大文件写入时的性能瓶颈（擦除粒度为4KB），同时利用FatFS的目录结构优势组织海量资源。关键代码片段：

// 初始化SPIFFS
SPIFFS.begin(true);
// 初始化FatFS
SPI.begin(18, 19, 23, 22); // VSPI总线
FatFS.begin(&SPI, 21, 4*1024*1024); // CS=GPIO21, size=4MB

4. 核心状态机设计与实现

4.1 生命体征模型：四维衰减函数

宠物状态由四个核心维度构成，每个维度均遵循独立的指数衰减模型，但衰减速率受当前活动影响：

维度	初始值	每秒衰减率	满值	溢出处理	影响因素
饱腹值	100	0.012%/s	100	截断至100	喂食+15，睡眠中-0.005%/s
清洁度	100	0.008%/s	100	截断至100	洗澡+20，游戏时-0.01%/s
疲劳值	0	+0.02%/s	100	截断至100	睡眠-0.5%/s，喂食+0.003%/s
情绪值	50	-0.003%/s	100	截断至100	游戏胜利+5，失败-2

该模型的关键创新在于 衰减非线性耦合 ：例如，当疲劳值>80时，饱腹衰减率提升至0.02%/s（模拟食欲不振）；当清洁度<30时，情绪衰减率翻倍（模拟不适感）。这种耦合通过查表法实现，避免浮点运算：

const uint8_t fatigue_to_hunger_factor[101] = {
  100,100,100,...,100,110,120,130,140,150,160,170,180,190,200 // 疲劳80~100对应因子100~200
};
uint16_t current_hunger_decay = base_hunger_decay * fatigue_to_hunger_factor[getFatigue()] / 100;

4.2 状态更新引擎：FreeRTOS定时器驱动

所有状态衰减均由FreeRTOS软件定时器驱动，确保精度与实时性：

TimerHandle_t state_timer;
void state_update_callback(TimerHandle_t xTimer) {
  static uint32_t last_tick = 0;
  uint32_t now = xTaskGetTickCount();
  uint32_t delta_ms = (now - last_tick) * portTICK_PERIOD_MS;
  last_tick = now;

  // 按毫秒级积分衰减，避免整数截断误差
  hunger_val -= (delta_ms * HUNGER_DECAY_PER_MS) >> 16;
  clean_val -= (delta_ms * CLEAN_DECAY_PER_MS) >> 16;
  fatigue_val += (delta_ms * FATIGUE_ACCUM_PER_MS) >> 16;
  mood_val  -= (delta_ms * MOOD_DECAY_PER_MS) >> 16;

  // 边界检查
  hunger_val = constrain(hunger_val, 0, 100);
  clean_val  = constrain(clean_val, 0, 100);
  fatigue_val = constrain(fatigue_val, 0, 100);
  mood_val   = constrain(mood_val, 0, 100);

  // 触发UI更新标志
  lv_event_send(lv_scr_act(), LV_EVENT_VALUE_CHANGED, NULL);
}
// 创建定时器，周期100ms（10Hz）
state_timer = xTimerCreate("StateTimer", pdMS_TO_TICKS(100), pdTRUE, NULL, state_update_callback);
xTimerStart(state_timer, 0);

该设计将状态计算与UI渲染解耦：定时器只负责数值更新并发送事件，LVGL事件处理回调中执行UI重绘，符合嵌入式GUI最佳实践。

4.3 事件响应机制：按键中断与状态跃迁

三个物理按键分别映射为 MENU 、 SELECT 、 BACK ，采用GPIO中断方式捕获，避免轮询消耗CPU：

void IRAM_ATTR on_key_press() {
  BaseType_t xHigherPriorityTaskWoken = pdFALSE;
  // 发送通知到UI任务
  xTaskNotifyFromISR(ui_task_handle, KEY_PRESSED_NOTIFY, eSetValueWithOverwrite, &xHigherPriorityTaskWoken);
  portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
}

// 在setup()中配置
gpio_set_intr_type(GPIO_NUM_9, GPIO_INTR_NEGEDGE);
gpio_install_isr_service(0);
gpio_isr_handler_add(GPIO_NUM_9, on_key_press, NULL);

UI任务通过 ulTaskNotifyTake() 接收通知，并根据当前页面上下文执行状态跃迁：

• 在主屏幕按 SELECT → 进入厨房页面；
• 在厨房页面按 SELECT → 执行喂食动作，更新饱腹值，播放音效（PWM蜂鸣器）；
• 在商店页面按 SELECT → 检查金币是否足够，足够则扣款、写入 items.json 、更新收藏盒图标。

所有跃迁均通过LVGL的 lv_obj_clean() 清除旧页面对象，再调用 lv_obj_create() 构建新页面，确保内存零泄漏。

5. 关键功能模块实现

5.1 昼夜模式与背光控制

昼夜模式本质是两张全屏背景图的切换，但需解决两个工程问题：

1. 背景图存储优化 ：128×64像素的16位RGB565图需16KB空间，直接存Flash会挤占固件空间。解决方案是将图片压缩为RLE编码（游程编码），解压时逐行写入LCD显存。实测压缩比达3.2:1， day.bin 仅4.8KB；
2. 背光PWM同步 ：GPIO14输出的PWM信号需与LCD刷新垂直同步，否则出现滚动条纹。通过ESP32-S3的LEDC（LED Control）模块配置：

ledc_timer_config_t ledc_timer = {
  .speed_mode       = LEDC_LOW_SPEED_MODE,
  .timer_num        = LEDC_TIMER_0,
  .duty_resolution  = LEDC_TIMER_13_BIT, // 8192级分辨率
  .freq_hz          = 1000,                // 1kHz，人眼不可见闪烁
  .clk_cfg          = LEDC_AUTO_CLK
};
ledc_timer_config(&ledc_timer);
ledc_channel_config_t ledc_channel = {
  .speed_mode     = LEDC_LOW_SPEED_MODE,
  .channel        = LEDC_CHANNEL_0,
  .timer_sel      = LEDC_TIMER_0,
  .intr_type      = LEDC_INTR_DISABLE,
  .gpio_num       = 14,
  .duty           = 0, // 初始关闭
  .hpoint         = 0
};
ledc_channel_config(&ledc_channel);

背光亮度设置范围0~100，实际映射为 duty = (brightness * 8191) / 100 ，经实测，亮度30即可满足室内阅读，此时功耗降低至12mA。

5.2 猜数字游戏：真随机数与防作弊设计

游戏规则：系统生成1~100间随机数，玩家通过按键猜测，每次提示“大了”或“小了”，猜中得2金币，猜错扣2金币。

关键实现要点：

• 真随机源 ：不使用 random() 伪随机，而是读取ESP32-S3的硬件RNG外设：

c uint32_t get_true_random() { return REG_READ(RNG_DATA_REG); // 直接读取RNG寄存器 } uint8_t target = get_true_random() % 100 + 1;

• 防连续猜测 ：为防止用户暴力穷举，在每次错误猜测后，强制延时500ms，并禁用按键中断，避免误触。延时采用FreeRTOS vTaskDelay() ，不阻塞其他任务；
• 游戏状态隔离 ：游戏数据（目标数、当前猜测次数、历史记录）独立存储于 game_save.dat ，与宠物主状态完全解耦，确保重启后游戏进度不丢失。

5.3 商店系统：动态商品轮换与本地持久化

商店每日UTC 0点自动刷新商品列表，技术实现如下：

• 商品清单 items.json 存储于FatFS根目录，格式为JSON数组：

json [ {"id":"food1","name":"苹果","price":10,"icon":"/icons/food/apple.bin"}, {"id":"bath1","name":"泡泡浴","price":15,"icon":"/icons/bath/bubble.bin"} ]

• 系统启动时，读取 /system/last_update.txt （存储上次更新的UTC时间戳），若距今≥24小时，则：
  1. 调用 httpGET("https://api.example.com/items?day=20231015") 获取当日商品（需启用WiFi）；
  2. 将返回JSON写入 items.json ；
  3. 更新 last_update.txt ；
• 若无网络，则加载内置默认清单 /flash/default_items.json ，确保离线可用。

购买操作本质是文件I/O：将商品ID追加至 /user/collection.txt ，每行一个ID。收藏盒UI通过遍历该文件并加载对应图标实现。

6. 烧录与调试实战指南

6.1 Arduino IDE配置陷阱与绕过方案

官方Arduino-ESP32核心库存在一个致命缺陷：当项目包含多个 .ino 文件时，IDE会错误地将所有头文件（ .h ）视为独立编译单元，导致重复定义错误。本项目中 mikuru_tamago.ino 依赖 pet_state.h 、 lvgl_ui.h 等头文件，若未正确处理，编译必然失败。

标准解决方案 （视频中提及但未详解）：

1. 将所有 .h 文件移出Arduino项目根目录，放入子文件夹 src/ ；
2. 在 platformio.ini 中添加编译路径：

ini [env:esp32s3devkitc1] platform = espressif32 board = esp32s3devkitc1 framework = arduino lib_deps = lvgl/lvgl@^8.3.0 build_flags = -Isrc/

3. 在主 .ino 文件顶部使用 #include "src/pet_state.h" 显式引用。

此方法确保头文件仅被主文件包含一次，彻底规避重复定义。

6.2 串口监视器调试技巧

ESP32-S3的USB CDC串口在Windows下常被识别为 COMx ，但存在两个常见问题：

• 驱动冲突 ：若曾安装过CP210x或CH340驱动，可能导致设备管理器显示“未知设备”。解决方案是卸载所有USB串口驱动，仅保留 esptool 自带的 usbser.inf ；
• 波特率不匹配 ：Arduino Serial Monitor默认115200，但本项目 Serial.begin(115200) 后立即输出调试信息，若Monitor未及时打开，首条日志丢失。建议在 setup() 开头插入：

cpp while(!Serial && millis() < 5000); // 等待Serial就绪，最长5秒 Serial.println("[INFO] Mikuru Tamago initialized");

此外，LVGL提供 lv_log_register_print_cb() 接口，可将所有LVGL警告重定向至 Serial ，便于排查渲染异常：

void lv_log_print_cb(lv_log_level_t level, const char * file, uint32_t line, const char * dsc) {
  Serial.printf("[LVGL %s] %s:%lu: %s\n", 
    level == LV_LOG_LEVEL_WARN ? "WARN" : "ERR", file, line, dsc);
}
lv_log_register_print_cb(lv_log_print_cb);

7. 3D外壳设计与量产适配

7.1 结构设计要点

LILIGO提供的3D打印外壳（ 3d_printing/mikuru_case.stl ）并非装饰件，而是精密机电集成体，其设计隐含三项关键考量：

• 散热风道 ：外壳底部预留4个Φ2mm通风孔，正对ESP32-S3的Wi-Fi射频前端与TP4056芯片，实测可降低满载温升8℃；
• 按键行程校准 ：按键柱高度精确为3.2mm，与开发板上贴片按键的弹出行程（3.0±0.1mm）匹配，确保按压手感清脆无卡滞；
• OLED定位槽 ：内壁设有0.1mm公差的矩形凹槽，与ST7735S模块的PCB边缘严丝合缝，避免屏幕偏移导致可视区域裁剪。

7.2 量产级PCB替代方案

若需脱离开发板进入量产，推荐以下PCB设计变更：

模块	开发板方案	量产PCB优化方案	优势
主控	ESP32-S3-WROOM-1	ESP32-S3-WROOM-2（内置8MB Flash）	减少外部Flash布线，BOM更简洁
显示	ST7735S OLED	GC9A01（135×240，1.28英寸）	更高分辨率，支持动画过渡效果
电源管理	TP4056 + 外置MOS	IP5306（集成充放电管理，支持边充边放）	彻底解决倒灌问题，效率提升35%
按键	贴片轻触开关	导电胶+金属弹片	按压寿命从10万次提升至50万次

IP5306的I²C接口可由ESP32-S3的 GPIO18/19 直接驱动，通过 Wire.h 读取电池电量百分比，精度达±3%，无需ADC采样，进一步节省GPIO资源。

8. 实战经验与避坑指南

我在实际复刻过程中踩过三次典型坑，分享给后来者：

第一次：LVGL内存溢出导致黑屏
现象：烧录后屏幕全黑，串口无输出。
根因：未修改 LV_MEM_SIZE ，LVGL尝试分配过多内存，触发FreeRTOS堆校验失败， lv_init() 返回错误但未检查。
解法：在 setup() 中添加断言：

if (!lv_init()) {
  Serial.println("[FATAL] LVGL init failed!");
  while(1) { delay(1000); }
}

第二次：SPIFFS文件损坏无法启动
现象：重启后反复进入恢复模式， SPIFFS.format() 无效。
根因：开发板Flash分区表中 spiffs 分区起始地址设为 0x100000 ，但实际固件大小已达 0x0F8000 ，导致分区重叠。
解法：在 partitions.csv 中将spiffs起始地址改为 0x110000 ，留出8KB余量。

第三次：按键长按误触发多次
现象：按住 MENU 键不放，UI快速切换多个页面。
根因：GPIO中断未做消抖，机械按键弹跳触发多次中断。
解法：硬件层面在每个按键信号线上并联100nF陶瓷电容；软件层面在中断服务程序中添加10ms去抖延时：

void IRAM_ATTR on_key_press() {
  ets_delay_us(10000); // 10ms硬件消抖
  if (gpio_get_level(KEY_GPIO) == 0) { // 确认仍为低电平
    xTaskNotifyFromISR(...);
  }
}

这三次教训印证了一个朴素真理：在嵌入式世界， 最可靠的代码永远诞生于对硬件物理特性的敬畏之中 。每一个看似简单的“按下按钮”，背后都是弹簧应力、触点氧化、RC时间常数与中断优先级的精密舞蹈。