最近在折腾乐鑫的板子时，顺手做了一个叫ESP-Mosaico的小项目。它的作用很简单：让 ESP32 系列芯片把一张普通照片，实时转换成带强烈街头艺术感的马赛克拼贴画，并直接送上一块小屏幕显示，整个过程不依赖上位机、不依赖云服务，板子自己就能跑完。这个项目的价值在于，它把“图像处理”和“低功耗嵌入式开发”这两个看似有距离的方向拉到一起，很适合玩 ESP32 的创客、硬件爱好者，以及想试试 ESP-IDF 图形栈却不知道从何下手的朋友。
我最初的目标很朴素：手机里随便一张照片，经过 ESP32 处理后，能在屏幕上呈现出又酷又清晰的大色块效果。真正做完才发现，这里面藏了不少值得展开讲的细节——从内存预算、图像缩放策略，到屏幕刷新的时序配合。这篇文章就把整个项目的设计思路、核心代码、实操步骤和踩坑记录一次写透，照着走你也能复现一个属于自己的马赛克显示终端。
1. 项目整体拆解：为什么选择“马赛克”这条路
1.1 低算力硬件上的“以退为进”
ESP32 系列芯片的运算能力很强，但和桌面电脑、手机 SoC 相比，内存资源很紧张。以最常见的 ESP32 为例，SRAM 只有 520KB 左右，即使开 PSRAM，也需要在片外总线上付出额外的读写延迟。如果直接用高分辨率 RGB 图像做显示，光是一个 320x240 的 RGB565 帧缓冲就要 150KB 以上，再加上 JPEG 解码缓冲、显示驱动缓冲，内存很容易爆掉。
马赛克风格是低硬件配置下“以退为进”的最优解。马赛克化本质上是把一个高采样密度的图像变成低采样密度的网格，每个格子只保留一个代表性颜色，再放大成肉眼可见的方块。这样我们就不需要保存原图的全部信息，而是先把图缩小到很小的逻辑分辨率，再放大显示。比如把 800x600 的原始图片，先马赛克成 40x30 个色块，再显示到屏幕上，实际需要的像素处理压力就非常低了。
这个设计思路救了整个项目。它不需要复杂的卷积神经网络超分辨率，不需要外挂大容量显存，只需要最基础的降采样算法加颜色映射，ESP32 完全能扛得住。而且从视觉效果看，硬朗的方形色块本身就很有设计感，甚至比直接显示低分辨率图片还要耐看。
1.2 整体架构与模块分工
ESP-Mosaico 的整体架构被我划分成了三个相对独立的模块：
- 图像输入模块：负责把 JPEG 或 BMP 图片从 SD 卡、Flash 或摄像头缓冲中读出来，并做基础解码。
- 马赛克转换模块：这是核心，负责把解码后的图像按网格尺寸降采样成“马赛克小图”，再做颜色量化，得到适合屏幕显示的颜色值。
- 屏幕输出模块：把转换好的色块按放大倍数绘制到 LCD 屏幕对应的位置上，配合 DMA 或双缓冲刷新，实现流畅的显示效果。
选这个架构是考虑到调试的便利性：图像输入可以被替换，比如一开始用 SD 卡里的图片，后面换成摄像头实时拍照，马赛克模块和显示模块不需要做大的改动。模块间只通过标准的内存 buffer 和分辨率参数交互，这也方便后续做 Web 端图片上传或串口传输数据。
硬件方面我选择的是ESP32-S3-WROOM-1 模组 + 2.4 英寸 SPI 接口 TFT 屏（ST7789 驱动），另外加了一张普通 MicroSD 卡模块用来存测试图片。ESP32-S3 的优势在于自带 PSRAM、原生支持 RGB565 大缓冲，而且乐鑫的 ESP-IDF 对显示设备和图像解码组件的支持比经典 ESP32 更成熟。如果你手头只有经典 ESP32，也不要急着放弃，只要把图片分辨率限制小一点、优化内存分配，这个项目照样能跑，后面我会给出具体参数建议。
1.3 方案选型背后的取舍
我特意没有用 Arduino IDE 而是直接上了 ESP-IDF。为什么？因为这个项目需要精细控制内存和任务调度：JPEG 解码、图像转换、DMA 刷屏三个环节要在 FreeRTOS 任务里协同工作，用 Arduino 封装好的库虽然上手快，但一旦出现内存碎片或者任务优先级问题，排查起来会很痛苦。ESP-IDF 下可以清晰看到每个任务的最大栈用量、堆剩余量，这对一个主打图像处理的项目来说太重要了。
屏幕驱动也没有选择 LVGL，而是直接操作底层 spi_device API。LVGL 适合做 UI 控件，但 ESP-Mosaico 这种全屏绘制像素块的应用，直接用底层绘制可以省掉中间层开销，把有限的内存全部留给图像缓冲。当然，如果你后续想给项目加上菜单、滑块参数调节，再引入 LVGL 也不迟。
2. 图像处理核心：马赛克到底是怎么算出来的
2.1 马赛克化的本质是“降采样+放大”
很多人以为马赛克就是简单地打上方块格子，其实里面有两个关键步骤。第一步是降采样：把原图按照网格大小切成很多个小区域，每个区域只保留一个“代表色”。第二步是放大：把刚才得到的低分辨率小图，用最近邻算法放大到屏幕的实际分辨率。最近邻放大的特性就是像素边缘锐利、颜色过渡生硬，恰好能制造出我们要的方块感。
具体计算一个格子的代表色时，可以用取平均的方式，也可以直接取格子中心点的像素。平均值让色块颜色更“柔和”，中心采样则更具有决定性。实测中，中心采样偶尔会因为正好取到噪点而产生突兀的颜色，所以我最终采用了一个折中方案：每个格子先做 2x2 子采样，把四个点的颜色做均值，再作为整个格子的颜色。这个开销很小，但明显抑制了图像噪点带来的闪烁感。
伪代码大概长这样：
for (int gy = 0; gy < mosaic_h; gy++) { for (int gx = 0; gx < mosaic_w; gx++) { int sum_r = 0, sum_g = 0, sum_b = 0, count = 0; int start_x = gx * cell_w; int start_y = gy * cell_h; // 对格子里 2x2 子采样区域求平均 for (int dy = 0; dy < cell_h; dy += (cell_h / 2)) { for (int dx = 0; dx < cell_w; dx += (cell_w / 2)) { uint16_t rgb = getPixel(start_x + dx, start_y + dy); sum_r += RGB565_R(rgb); sum_g += RGB565_G(rgb); sum_b += RGB565_B(rgb); count++; } } uint16_t avg_color = RGB565_RGB(sum_r / count, sum_g / count, sum_b / count); // 将颜色存入 mosaic buffer buffer[gy * mosaic_w + gx] = avg_color; } }注意这里cell_h / 2在奇数格子时会有取整误差，但视觉上影响不大。如果格子尺寸是 1，那整个过程退化成普通缩放，也就没有马赛克效果了。
2.2 色彩量化：让色块更“纯粹”
屏幕上的颜色是 RGB565，最多只能区分 65536 种颜色。马赛克风格的视觉效果，很大程度上依赖颜色是否“干净”。如果每个格子颜色映射后都保持原始细微差异，整幅画看起来就会很碎，失去了色块拼接的秩序感。
这时候色彩量化就派上用场了。我在项目中专门做了一个调色板模块，预置了 32 种常用颜色（如黑色、白色、正红、橙色、肤色、草绿、天蓝等）。每个格子计算完平均色之后，不是直接把结果交给屏幕，而是先到这个调色板里找最近的颜色。实际显示效果比不量化好了非常多，色块之间形成鲜明的对比关系，特别像像素艺术的质感。
颜色匹配的计算方法很简单，就是遍历调色板，找欧几里得距离最小的那个：
int best_index = 0; int min_dist = INT_MAX; for (int i = 0; i < palette_size; i++) { int d_r = (r >> 3) - palette_r[i]; int d_g = (g >> 2) - palette_g[i]; int d_b = (b >> 3) - palette_b[i]; int dist = d_r * d_r + d_g * d_g + d_b * d_b; if (dist < min_dist) { min_dist = dist; best_index = i; } }然后把调色板中的颜色值写入缓冲即可。这里有个小优化点：把 RGB565 的 5 位、6 位、5 位分量提取出来和调色板比较时，需要对齐到相同的位宽再做差，否则误差计算会偏差很大。调色板数据我用 const 数组存放在 Flash，避免占用宝贵的 RAM。
2.3 内存布局：PSRAM 与大缓冲的配合
如果把一张包含原始 RGB 信息的图片完整解析到内存，一张 800x600 的 RGB565 位图需要 960KB，远超 ESP32 的 SRAM 容量。为此我用 PSRAM 作为大块图像数据的栖息地。
整体内存使用是这样的：
| 用途 | 大小估算 | 存放位置 |
|---|---|---|
| 输入 JPEG 文件缓冲 | 按文件大小，一般 50~200KB | PSRAM |
| 解压后的位图缓冲（RGB565） | 320x240 约 150KB | PSRAM |
| 马赛克中间缓冲（40x30x2） | 约 2.4KB | SRAM |
| LCD DMA 发送缓冲 | 320x240 约 150KB（双缓冲则 300KB） | PSRAM 或 SRAM |
| 各任务栈、协议栈 | 约 20~50KB | SRAM |
可以看到，真正常驻内存的数据是统一的低位宽图像缓冲。我在 DSP 渲染路径上做了一个省内存优化：JPEG 解码时只解码到马赛克所需的小尺寸，而不是先解码全尺寸再去缩小。
比如目标显示 320x240 屏幕，马赛克格子为 8 像素，逻辑分辨率就是 40x30。我直接在 JPEG 解码器配置里把输出缩放设置为 1/20，这样即使输入图片是 800x600，解码后得到的缓冲也只有 40x30。整个项目最耗内存的环节瞬间消失，解码速度反而快了很多。如果你用 ESP_JPEG 库，可以直接配置缩放比例；用 libjpeg 的话则需要自己实现层抽样。
注意：JPEG 解码的小尺寸化虽然节省内存，但会把“马赛克化所需的子采样细节”提前抹掉。所以我把马赛克格子尺寸设得比 JPEG 输出分辨率稍大，保证每个格子覆盖至少一个解码像素，否则平均色就失去意义了。
3. 实操过程：从接线到跑通完整流程
3.1 硬件清单与接线要点
这个项目用到的硬件不多，核心就是一块带 PSRAM 的 ESP32-S3 开发板、一块 SPI 接口 LCD、一张 MicroSD 卡模块，以及杜邦线和排母。板子型号没有限制，只要是 8MB 以上 Flash、2MB 以上 PSRAM 的 S3 模组都可以。
以我用的 2.4 英寸 ST7789 屏幕为例，它一般引出 8 个引脚：VCC、GND、CS、RESET、DC/RS、SDI（MOSI）、SCK、LED（背光）。接线对应关系如下：
| 屏幕引脚 | 接ESP32-S3引脚 | 说明 |
|---|---|---|
| VCC | 3V3 | 部分屏幕需要 5V 供电，看背光电路 |
| GND | GND | 共地 |
| CS | GPIO5 | 片选，可改任意 GPIO |
| RESET | GPIO3 | 复位，可改任意 GPIO |
| DC | GPIO4 | 数据/命令选择 |
| SDI | GPIO11 | SPI MOSI，S3 默认可配 |
| SCK | GPIO12 | SPI 时钟 |
| LED | GPIO2 | 背光控制，可接 3V3 直接点亮 |
需要注意的是，ESP32-S3 的 GPIO11、GPIO12 是默认的 SPI2 引脚，但不同开发板丝印可能标为 FSPI MOSI、FSPI SCK，不要和板载 Flash 的 SPI 搞混。上电后如果屏幕没反应，优先检查是不是把信号接到了 Flash 专用引脚上。
MicroSD 卡模块建议用 SPI 模式，接线同样挂在 SPI2 总线上，但用独立的 CS 引脚。我把它接在 GPIO6 上，和屏幕共享 MOSI、SCK，但片选不同。共享总线没问题，只要保证同一时刻只访问一个设备就行。需要特别提醒的是市面上的 SD 卡模块很多自带电平转换，但有些廉价模块直接上拉，如果发现读取时系统重启，大概率是电源纹波问题，给 SD 卡供电脚并联一个 10uF 电容能缓解。
3.2 创建 ESP-IDF 工程与环境配置
工程创建我直接用了官方支持：
idf.py create-project esp-mosaico cd esp-mosaico idf.py menuconfig在 menuconfig 里需要重点确认几个配置项：
- Component config → ESP32-S3-Specific → Support for external, SPI-connected RAM：必须开启并选择
SPI RAM模式。这一步直接决定代码能不能在编译期使用 PSRAM 相关 API。 - Component config → ESP32-S3-Specific → PSRAM clock and CS IO：根据开发板实际引脚配置，一般开发板默认 26MHz 或 40MHz 可选，频率过高可能出现随机数据错乱。
- Component config → FreeRTOS → HPI：如果后续要用
ps_malloc分配 PSRAM，推荐开启堆外内存分配支持。 - Flash size：如果模组是 8MB，设置为 8MB，否则分区表和 OTA 可能出现偏移错误。
我额外添加了esp_jpeg作为 JPEG 解码组件，用idf.py add-dependency esp_jpeg安装。这个库针对 ESP 平台做了优化，输出缓冲可以直接放到 PSRAM，和普通桌面 libjpeg 相比大大降低了 RAM 占用。屏幕驱动则没引入第三方库，直接基于 ESP-IDF 的spi_master驱动写了一个简化版 ST7789 初始化代码，驱动整个项目足够了。
工程目录大致结构：
esp-mosaico/ ├── main/ │ ├── CMakeLists.txt │ ├── app_main.c │ ├── image_source.c/h │ ├── mosaic_engine.c/h │ ├── palette.c/h │ └── lcd_st7789.c/h ├── managed_components/ │ └── esp_jpeg/ └── sdkconfig3.3 核心实现：图片读取、转换与刷屏
主流程可以拆成四步：从 SD 卡读取 JPEG 文件、JPEG 解码到小尺寸缓冲、马赛克化并量化颜色、把色块绘制到屏幕。下面给出几个关键代码片段。
第一步：读取图片文件到内存
FILE *f = fopen("/sdcard/test.jpg", "rb"); fseek(f, 0, SEEK_END); size_t file_size = ftell(f); fseek(f, 0, SEEK_SET); uint8_t *jpeg_buf = heap_caps_malloc(file_size, MALLOC_CAP_SPIRAM); fread(jpeg_buf, 1, file_size, f); fclose(f);这里刻意用了heap_caps_malloc配合MALLOC_CAP_SPIRAM，确保大文件缓冲不占用有限的内部 SRAM。如果你不指定，默认malloc也可能返回 PSRAM 内存，但行为不确定，还是显式标明更稳妥。
第二步：JPEG 解码到马赛克级别的小图
esp_jpeg_image_cfg_t jpeg_cfg = { .input = jpeg_buf, .input_size = file_size, .out_buffer = arena_buf, .out_buffer_size = arena_size, .scale = 8, // 输出缩小到原宽高的 1/8 }; esp_jpeg_image_output_t out_img; esp_jpeg_decode(&jpeg_cfg, &out_img);这里scale等于 8 的含义是输出宽高都除以 8。比如 640x480 的原图，解码后得到 80x60 的 RGB565 缓冲。然后再对它做网格化，每个网格 2x2 像素取均值，最后得到 40x30 的逻辑马赛克小图。如果原图更大，可以适当调大scale，但我发现缩得太狠会丢失局部颜色层次，实际操作中把解码输出控制在 80x60 到 160x120 之间视觉最舒服。
第三步：马赛克化与调色板映射
mosaic_width = out_img.width / CELL_SUB; mosaic_height = out_img.height / CELL_SUB; uint16_t *mosaic_buf = heap_caps_malloc(mosaic_width * mosaic_height * 2, MALLOC_CAP_SPIRAM); for (int y = 0; y < mosaic_height; y++) { for (int x = 0; x < mosaic_width; x++) { uint16_t acc[3] = {0, 0, 0}; for (int sy = 0; sy < CELL_SUB; sy++) { for (int sx = 0; sx < CELL_SUB; sx++) { uint16_t px = out_img.buf[(y * CELL_SUB + sy) * out_img.width + (x * CELL_SUB + sx)]; acc[0] += RGB565_R(px); acc[1] += RGB565_G(px); acc[2] += RGB565_B(px); } } int n = CELL_SUB * CELL_SUB; uint16_t avg = RGB565_RGB(acc[0] / n, acc[1] / n, acc[2] / n); mosaic_buf[y * mosaic_width + x] = nearest_palette(avg); } }因为out_img.buf已经是缩小后的图像缓冲，所以这里的双重循环计算量不大，整个转换在 10ms 内就能完成。如果你想实时调节格子的大小，只需把原本写死的CELL_SUB改成实时读取的变量，每次按键触发重新转换即可。
第四步：把马赛克图放大到屏幕并刷新
屏幕显示一个 40x30 的马赛克小图，每个格子映射到 8x8 的屏幕像素区域。最直接的办法是逐格绘制，但对 320x240 屏幕来说，要画 9600 个像素点，纯循环写 SPI 一次全屏刷会比较慢。我用了一个快速填充方案：因为马赛克格子颜色一致，先用 DMA 把一个 8x8 的色块填充模板写到 LCD 显存，然后通过多次disp_wait和地址设定连续块刷写。
for (int y = 0; y < mosaic_height; y++) { for (int x = 0; x < mosaic_width; x++) { uint16_t color = mosaic_buf[y * mosaic_width + x]; lcd_set_window(x * CELL_PX, y * CELL_PX, CELL_PX, CELL_PX); lcd_write_color_fill(&color, CELL_PX * CELL_PX); } }实测在 40MHz SPI 时钟下，一次全屏刷大概 60ms，加上图片解码、马赛克转换，整体从选图到显示大概 200ms 内完成，肉眼看着是“秒出图”。如果换更高时钟或者开双缓冲，还能更快。
4. 常见问题与排查技巧
4.1 问题速查表
我把折腾过程遇到的高频问题整理成一张表，方便你对着排查。
| 问题现象 | 常见原因 | 解决方法 |
|---|---|---|
| 屏幕花屏、色块错乱 | SPI 时钟过快或接线太长 | 降低 SPI 频率到 20MHz，缩短杜邦线长度 |
| 读取 SD 卡时系统反复重启 | 供电不足或 SD 卡兼容问题 | 接 5V 和 3V3 双路供电，给模块加 10uF 电容 |
| JPEG 解码后图像方向不对 | 摄像头或源图方向未处理 | 在转换前做 90° 旋转，或者在显示时做行列映射 |
| 马赛克色块全是黑色或白色 | 调色板匹配位宽未对齐 | 检查 RGB565 分量提取是否与调色板存储格式一致 |
| 刷新屏幕有明显撕裂感 | 单缓冲写入中途被读取 | 改双缓冲，或者刷屏前加disp_sleep同步 |
| 显示只有半屏或底部花掉 | 屏幕驱动窗口设置起始地址错误 | 核对 ST7789 的列偏移和行偏移寄存器 |
| 蓝牙或 Wi-Fi 同时开启后图像卡顿 | 射频任务抢占 DPI 任务 | 把显示刷屏任务优先级提到tskIDLE_PRIORITY + 3 |
这里最常踩的是调色板位宽问题。我最初把调色板颜色存成 8bit R、8bit G、8bit B，然后直接和 RGB565 分离出来的 5bit、6bit、5bit 比较，结果距离误差错得离谱，导致大量色块被映射成黑色。后来统一把调色板存成 RGB565 格式，再在比较前先移位，问题立刻消失。
4.2 调试工具与经验心得
一个很有用的调试手段是在关键路径打印剩余内存：
printf("heap free: %d, psram free: %d\n", heap_caps_get_free_size(MALLOC_CAP_INTERNAL), heap_caps_get_free_size(MALLOC_CAP_SPIRAM));我建议在 JPEG 解码前、解码后、马赛克转换后各打一次。如果看到 PSRAM free 数值在逐阶段下降但不回升，说明有内存泄漏。结合esp_heap_debug_dump可以快速定位是哪个环节的 buffer 没释放。
另外在切换不同分辨率的图片时，要确保所有动态分配的 buffer 都通过相应地释放函数返回，否则连续切换几十张图后系统就要崩溃。我踩过一个坑：esp_jpeg_decode函数内部的输出缓冲虽然由传入 buffer 承担，但内部临时结构还是会有内存残留，解决方案是在循环里对每个任务栈做vTaskDelay(1)并定期esp_heap_caps_check_integrity_all(true)检查堆完整性。
还有一个小技巧：先别急着上屏幕，先用串口打印马赛克小图的颜色矩阵。比如把 40x30 个颜色值用十六进制打印出来，确认转换结果符合预期后再搞屏幕刷新。这样能把“图像算法问题”和“显示驱动问题”分开排查，省掉不少时间。我给自己定了规矩：任何图形类嵌入式项目，底层打印验证永远比看屏幕快。
5. 扩展方向与个人体会
5.1 从静态图片到动态马赛克
项目跑通静态图片后，很容易想到扩展成动态效果。我给 ESP-Mosaico 加了一个可调参数：通过 BOOT 按钮切换马赛克格子大小，从 4x4 一直切到 16x16。按下按钮时，屏幕重新执行降采样、调色、刷屏三步操作。因为每次转换的开销很小，视觉上几乎实时响应，玩起来像是一个“马赛克密度调节器”。
如果再接一个 OV2640 摄像头模块，就能实现实时视频马赛克化。做法是把摄像头输出的帧直接喂给马赛克引擎，再上屏显示。但要注意摄像头帧率一般在 15fps 左右，马赛克转换和刷屏时间必须控制在 50ms 内才不掉帧。我实验下来，使用较少的格子数和单缓冲模式能勉强稳在 12fps，再想提高就需要开启摄像头 JPEG 输出模式并降低帧率。
5.2 联网挂到 Web 端，才是完全体
另一个我非常推荐的扩展方向是让 ESP-Mosaico 变成一个 Web 端图像处理器。ESP32-S3 开启 SoftAP 或接入局域网后，手机浏览器直接上传照片，设备接收 JPEG 数据、转换马赛克、再通过 HTTP 响应返回成品图。整条链路不依赖云服务器，完全是局域网内的小工具。
实现时，可以把现有的事件驱动逻辑拆成两个 task：一个 task 跑 HTTP 服务，负责接收图片；另一个 task 负责马赛克处理和显示。两个任务之间通过一个 ring buffer 或队列传递图片路径和缓冲指针。因为 ESP-IDF 的网络栈和事件循环已经很成熟，代码量没有想象中那么大，但对“嵌入式+IoT+数字图像”三个方向的理解会有明显提升。
5.3 心得体会
从我个人的实操感受来说，ESP-Mosaico 最有趣的时刻不是看到“它跑起来了”，而是搞清楚“为什么它用这么少的内存也能做图像处理”。很多人一提起嵌入式图像处理就觉得必须上高算力芯片，但马赛克风格化的思路提醒我：很多时候不是硬件不够，而是图像数据量过大导致系统不堪重负。主动降采样、量化到调色板，再用小缓冲去驱动大屏，这套思维方式可以迁移到很多资源受限的场景，比如低功耗传感器节点上的图形显示、LED 点阵屏的图案生成、甚至是小型手持游戏机的像素风渲染。
技术上唯一需要再打磨的地方是显示刷新机制。我现在用单缓冲加关键区锁，偶尔大图切换时还是能看到撕裂感。后续我计划把刷屏任务改成双缓冲：一块 PSRAM 缓冲负责后台计算马赛克小图，另一块缓冲直接交给 SPI 发送，利用spi_device_polling_transmit的块传输特性做到真正的无撕裂切换。如果你也在做相似的项目，建议从一开始就预留双缓冲的内存配置，避免像我这样中期改动工程结构。
如果你手头刚好有吃灰的 ESP32-S3 开发板和一块小 LCD，不妨照着这篇文章搭一套自己的 ESP-Mosaico。先从 SD 卡里放一张喜欢的照片开始，再慢慢调节格子大小，很快你就会发现，那块屏幕上的每个色块，其实都是你在“反向设计”一张高分辨率图片的过程。别怕踩坑，内存告急的时候多想想：低分辨率不一定是妥协，它本身也可以是一种风格。
