【ESP32-S3】番茄钟

ESP32-S3-WROOM-1 模组简介

• 核心：搭载 双核 Xtensa® 32 位 LX7 处理器，主频最高 240 MHz。
• 存储：内置 384 KB ROM，512 KB SRAM，合封 8 MB Flash 和 8 MB PSRAM，为屏幕显示提供充足缓冲空间。
• 无线：集成 2.4 GHz Wi-Fi (802.11 b/g/n) 与 蓝牙 5.0 模块，内置 PCB 天线，简化射频设计。
• 外设：多达 45 个 GPIO，支持 SPI、I2S、I2C、UART、USB、PWM 等多种接口，满足多外设连接需求。

引脚功能列表

嗯哼哼，ESP32-S3 相对 ESP32-C3 来说，能使用的引脚数量多了不少哦！（不过价格也很贵就是了），因此本设计的引脚功能列表也会列得超长~

IP5306 电源管理 SOC 简介

• 充电：最大 2.1A 同步开关充电，充电效率高达 91%，支持 3.7V 锂电池充电。
• 放电：最大 2.4A 同步升压转换，升压效率高达 92%，支持边充边放。
• 保护：自带过充、过放、过流、短路与过温保护，ESD 耐压 4 kV。
• 电量显示：支持 1~4 颗 LED 电量指示灯（本设计中使用 2 灯电量指示模式）

外围电路设计

作为一个设计目标是能随时随地使用的番茄钟设备，可靠的电源管理必不可少~官方技术手册提供的 4LED 电量指示参考电路原理图 如下所示~

考虑到本设计已配备了一块 LCD 屏幕，IP5306 原本的 LED 电量指示功能就显得有些冗余了？因此本设计最终采用 IP5306 的 2 灯模式，仅对充电与放电状态进行基本指示，既保留了必要的状态反馈，又简化了电路设计~

基于上述参考设计，我们对电路进行了相应调整：修改 LED1、LED2、LED3 的连接方式，移除 R3 与 D5 元件，并省略了虚线框内的辅助电路。这样就得到了 本设计采用的 IP5306 锂电池充放电电路~

LCD 屏幕规格

本设计使用一块 上接 22pin 2.0 英寸 IPS 彩色 LCD 屏，分辨率为 240(H)×320(V) 像素，通过 8bit 8080 MCU 接口 进行通信，驱动芯片则采用 ST7789，工作电压为 3.3V。

外围电路设计

这部分实在是没什么好说的了......直接看图~值得一提的是，屏幕的供电与 ESP32-S3 模组的 3.3V 供电共用。

代码编译环境与框架

本项目基于 ESP-IDF v5.4.1 框架开发，使用 FreeRTOS 实时操作系统管理多任务。代码采用 C/C++ 进行编写，主要模块封装在独立的类中，便于维护和扩展~

FreeRTOS 多任务架构

• GUI 更新任务：app_gui_update_entry() 运行在 Core 1，负责处理 LVGL 界面更新和消息队列，任务优先级为 8。
• 按键输入任务：app_input_entry() 运行在 Core 0，处理5个物理按键的事件响应，任务优先级为 8。
• 系统节拍任务：app_tick_entry() 运行在 Core 0，处理定时事件（1s、1min 等），任务优先级为 6。
• 系统初始化任务：system_init_entry() 一次性任务，完成所有硬件初始化和 NVS 数据加载。

事件驱动通信机制

状态模式 (State Pattern) 的应用

GUI 控制器采用状态模式设计，定义了 cpp_gui_controller_state 抽象基类，派生出四种具体状态：

• cpp_gui_controller_state_normal：正常时钟显示状态
• cpp_gui_controller_state_pomodoro：番茄钟计时状态
• cpp_gui_controller_state_setting_pomodoro：番茄钟设置状态
• cpp_gui_controller_state_setting_audio_volume：音量设置状态

每个状态独立实现 enter()、exit()、time_update() 等方法，通过 GUI_Controller::change_state() 动态切换，确保UI行为与当前模式严格对应。

GUI 更新消息机制

通过 GUI::updater::send_xxx_update() 系列函数发送更新请求，由 app_gui_update_entry() 任务统一处理：

• GUI_TIME_UPDATE_INFO：时间显示更新
• GUI_MENU_UPDATE_INFO：菜单选项更新
• GUI_WIFI_UPDATE_INFO：Wi-Fi状态更新
• GUI_BATTERY_UPDATE_INFO：电池电量更新
• GUI_SDCARD_UPDATE_INFO：SD卡状态更新
• GUI_MODE_UPDATE_INFO：工作模式切换
• GUI_STARTPRESS_DATA_UPDATE_INFO：长按进度条显示

设置界面的闪烁提示效果

在番茄钟设置状态中，通过回调函数指针 __filp_handler 实现当前编辑项的闪烁提示：

• GUI::clock::toggle_flag_opacity()：切换工作/休息标志透明度
• GUI::clock::toggle_hour_opacity()：切换小时数字透明度
• GUI::clock::toggle_min_opacity()：切换分钟数字透明度
• GUI::clock::toggle_sec_opacity()：切换秒钟数字透明度

每次时间更新时调用当前编辑项对应的闪烁函数，通过改变LVGL对象的 LV_OPA_COVER/LV_OPA_TRANSP 透明度实现视觉反馈。

状态机工作模式切换

番茄钟定义了 8 种工作模式，通过 iceclock_mode_t 枚举管理：

• ICECLOCK_MODE_CLOCK：普通时钟模式
• ICECLOCK_MODE_SET_WORK_REST：设置工作/休息目标
• ICECLOCK_MODE_SET_HOUR_TIME：设置小时值
• ICECLOCK_MODE_SET_MIN_TIME：设置分钟值
• ICECLOCK_MODE_SET_SEC_TIME：设置秒钟值
• ICECLOCK_MODE_WORK：番茄工作计时
• ICECLOCK_MODE_REST：休息计时
• ICECLOCK_MODE_AUDIO_SET_VOLUME：音频音量设置

通过 IceClock::set_mode() 切换模式，进入工作/休息模式时会自动计算结束时间并播放提示音。

时间管理与自动切换

番茄钟计时核心逻辑：

• 计时开始：进入 ICECLOCK_MODE_WORK 或 ICECLOCK_MODE_REST 时，记录当前时间到 __run_time，计算 __end_time。
• 每秒更新：IceClock::update_run_time() 在 1 秒节拍中递增运行时间。
• 超时检测：IceClock::check_timeout() 比较当前运行时间与结束时间，返回剩余秒数。
• 自动切换：当剩余时间为 0 时，自动从工作模式切换到休息模式（或反之），形成循环。

时间设置与编辑缓冲区

采用编辑缓冲区设计，避免直接修改实际时间值：

• 目标选择：__edit_target_ptr 指向当前编辑的时间结构（工作或休息时间）。
• 缓冲区：__edit_target_buf 作为编辑暂存区，所有修改先作用于缓冲区。
• 确认保存：通过 IceClock::save_edit_time(true) 将缓冲区内容复制回目标，并写入 NVS。
• 防误触：分钟和秒钟值以 5 为单位增减（±5），小时值以 1 为单位增减。

五按键功能分配

五个物理按键通过中断触发事件，在 app_input_entry() 任务中统一处理：

• KEY0（菜单键）：循环切换菜单选项（时钟→番茄钟设置→音频设置）
• KEY1（模式键）：在不同设置页面间切换，或进入/退出设置模式
• KEY2（开始键）：长按 1.5 秒开始/结束番茄钟，短按在音频模式切换播放/暂停
• KEY3（增加键）：增加时间值/音量/切换上一首音频
• KEY4（减少键）：减少时间值/音量/切换下一首音频

音频播放器状态机机制

音频播放器通过 audio_player_callback() 回调函数响应状态变化：

• AUDIO_PLAYER_CALLBACK_EVENT_IDLE：播放器空闲时，自动播放下一首（非番茄钟模式）
• AUDIO_PLAYER_CALLBACK_EVENT_PLAYING：开始播放音频
• AUDIO_PLAYER_CALLBACK_EVENT_PAUSE：暂停播放

在番茄钟工作/休息模式下，关闭音乐播放功能，仅在模式切换时播放系统提示音 S:/system/ding.mp3。

SD 卡插拔检测与播放列表

在 app_tick_callback()中，每 10 秒触发一次 APP_SDCARD_MOUNT_STATUS 事件。在 app_tick_entry() 任务中检查该事件位，检测到该事件后读取 SD_CD 引脚电平判断 SD 卡的插拔状态，若检测到 SD 卡则尝试挂载 SD 卡。挂载成功后，将会初始化音频播放器并检查位于 SD 卡根目录 S:/ 下的 MP3 / WAV 音频文件并更新播放列表。

音量分级控制

音量控制以 5% 为步进单位，范围 0-80%：

• 增加音量：Audio::voice_volume(volume + 5)，上限为 80%。
• 减少音量：Audio::voice_volume(volume - 5)，下限为 0%。

音量值保存到 NVS，重启后自动恢复上次设置。

Wi-Fi STA 模式状态管理

通过事件回调 wifi_sta_event_callback() 管理连接状态：

• 连接失败重试：最多重试 EXAMPLE_ESP_MAXIMUM_RETRY 次，失败后停止 Wi-Fi
• 连接成功：获取 IP 地址后设置 APP_WIFI_GET_IP_STATUS 事件位
• 断线重连：每 30 秒检测一次，若未连接则触发 APP_WIFI_CONNECT_STATUS 重新初始化 Wi-Fi

在 app_input_entry() 任务中，如果检测到 APP_WIFI_CONNECT_STATUS 事件且 Wi-Fi 功能未使能，则重新初始化 Wi-Fi 并启动，实现自动重连机制。

SNTP 网络时间同步

获取 IP 地址后自动启动 SNTP 时间同步：

1. 初始化 SNTP：SNTP::init(sntp_networktime_callback) 设置回调函数
2. 启动同步：SNTP::start() 开始获取网络时间
3. 回调处理：sntp_networktime_callback() 收到时间后保存到 NVS
4. 系统时区：设置 setenv("TZ", "CST-8", 1) 为北京时间

每 1 分钟将当前系统时间备份到 NVS，确保断电后仍有相对准确的时间。

NVS 配置数据加载

系统启动时从 NVS 加载所有配置：

• 时间数据：从 "sntp" 命名空间加载最后保存的时间戳。
• 番茄钟设置：从 "iceclock" 加载工作和休息时间。
• Wi-Fi配置：从 "wifi" 加载 SSID 与密码。
• 用户偏好：从 "audio" 和 "gui" 加载音量和亮度设置。

只有配置存在时才覆盖默认值，确保首次启动正常运行。

自适应亮度调节

屏幕亮度目前仅能根据 USB 串口进行配置或由系统自动调整：

• 正常亮度：用户操作后，屏幕渐变为 GUI::get_default_light()（该默认值为初始化值或 NVS 保存值）
• 休眠亮度：30 秒无操作后，通过 GUI::fade(5, 1000) 实现屏幕渐暗
• 渐变效果：所有亮度变化使用 1 秒渐变动画（GUI::fade(value, 1000)）
• 亮度保存：用户调整的默认亮度保存到 NVS，重启后自动恢复

内存使用监控

可通过 log_get_free_heap_size() 函数监控内存使用：

• DRAM 内存：ESP32-S3内部 RAM，用于任务堆栈与数据存储。
• PSRAM 内存：外部 8MB PSRAM，主要用于 LVGL 帧缓冲和 Audio 缓冲区。
• 内存分配策略：音频播放列表使用 MALLOC_CAP_8BIT | MALLOC_CAP_SPIRAM 标志，确保分配到 PSRAM。

开屏动画播放

通过 预先解码 + 二进制缓存 + 双缓冲渲染 策略，在首次启动时对 user_op.h 下的 USER_OP_DIR 地址中指定的 OP_PLAYER_IMAGE_DECODER_NUM 张 JPEG 图片进行重编码（图片命名格式为 P%04lu.jpg），生成 cache.bin 与 cache.info 缓存文件。后续启动直接播放缓存文件与 USER_OP_DIR 路径下的 USER_OP_VIDEO_NAME mp3/wav 格式的音频文件实现一个简单的开屏动画播放功能。帧率大概能稳定在 20 FPS 左右？播放完毕通过回调进入 LVGL 界面。

这个功能基本上可以说是灵机一动搓出来的，本来是想实现 mp4 视频 的播放功能，但似乎这样的库大部分都不是开源库？只能自己简单手搓一个了，目前看起来还是蛮简陋的......