¶ Arcs-mini 开发板接入墨水屏
¶ 前言
我们将以 Arcs-mini 开发板为核心，展示如何使用触发 SPI 通信，驱动外接墨水屏。
- 目标：
墨水屏文本显示：聆思科技 ListenAI
¶ 开始之前请先检查
¶ SDK版本
实操之前，请确保已根据文档《Arcs-Mini 开发环境搭建指南》 搭建开发环境。
本篇示例源码基于 3.0.2-m3 版本的 SDK。
可通过命令git log查看版本，如果版本不一致，请使用命令git checkout mini-v3.0.2-m3切到指定 SDK 版本。
¶ 关闭云端OTA更新
参考文档《烧录工具安装教程》安装ADB工具
执行命令adb shell kv set int user.disable_app_update 1关闭云端OTA更新，防止云端更新把刚烧录的固件刷掉了。
¶ 一、准备硬件
使用的墨水屏模组是 微雪 4.2-inch-e-Paper-V2 ，参考手册下载链接：c359944_墨水屏_4.2inch+e-paper+module_规格书_wj69236.pdf
| 硬件型号 | 图片 | 购买链接 |
|---|---|---|
微雪 4.2-inch-e-Paper-V2 |
 |
购买链接 |
¶ 二、硬件连接
微雪 4.2-inch-e-Paper-V2 连接 Arcs_mini2 的扩展 GPIO 接口
当前代码使用 PA04 ~ PA09 接墨水屏，连接关系如下：
| 引脚 | 连接信号 | 当前用途 | 说明 |
|---|---|---|---|
PA04 |
BUSY |
GPIO 输入 | 当前代码按“低电平表示空闲”处理 |
PA05 |
CLK |
SPI1 时钟 | CSK_IOMUX_FUNC_ALTER6 |
PA06 |
RST |
GPIO 输出 | 低电平硬复位 |
PA07 |
CS |
SPI1 片选 | 使用硬件片选 |
PA08 |
DC |
GPIO 输出 | 低电平命令，高电平数据 |
PA09 |
DIN |
SPI1 数据输出 | CSK_IOMUX_FUNC_ALTER6 |
¶ 三、代码和固件下载
如果您不想重新编译代码而希望直接体验本固件，可点击下载。
-
代码仓库：https://cloud.listenai.com/CSKG532016/arcs_mini_sample/-/tree/sample/spi_epaper
-
固件下载：
Arcs-mini2 固件下载：arcs-mini-v3.0.2-m3-SPI-epaper.lpk
可参考文档《Arcs-Mini 固件烧录教程(ADB工具)》进行烧录。
烧录后，即可看到墨水屏显示指定文本
¶ 四、代码解读
本示例在 mini-v3.0.2-m3 基础上接入墨水屏，使用已有的 LISA GPIO/SPI 设备接口。驱动、字模和启动入口位于应用目录，SDK 无需替换。
¶ 1. 文件分工与编译开关
新增文件均位于 apps/arcs-mini/：
| 文件 | 职责 |
|---|---|
epaper_demo.c |
GPIO/SPI 配置、面板初始化、清屏、文字绘制、刷新和休眠 |
epaper_demo.h |
对外提供启动接口 epaper_demo_init() |
font24CN.c |
保存演示字符的点阵数据，实现字模查找 |
font24CN.h |
定义字模结构 epaper_font24_glyph_t 和查找接口 |
应用 Kconfig 增加 CONFIG_EPAPER_DEMO，启用时自动选择 GPIOA 和 SPI1 所需的 LISA 驱动。CMakeLists.txt 根据该开关决定是否编译墨水屏代码：
if(CONFIG_EPAPER_DEMO)
target_sources(${PROJECT_NAME} PRIVATE epaper_demo.c font24CN.c)
endif()
¶ 2. 处理与 TF 卡的引脚冲突
PA04 ~ PA09 同时也是 SDIO 引脚，墨水屏与 TF 卡不能在这组引脚上同时工作。连接墨水屏时须拔下 TF 卡，本分支的 prj.conf 使用以下配置：
CONFIG_EPAPER_DEMO=y
CONFIG_DISK_DRIVER_SDMMC=n
CONFIG_MIDDLEWARE_SD_MUSIC=n
CONFIG_CHERRYUSB_DEVICE_MSC=n
其中，Kconfig 通过 depends on !DISK_DRIVER_SDMMC 限制墨水屏示例与 SDMMC 磁盘驱动互斥。TF 卡音乐和 USB TF 卡盘功能随之关闭。
为使关闭 TF 卡后的工程可以完整编译，还补齐了以下配置条件：
src/system/platform.c：仅启用 SDMMC 磁盘驱动时包含 SD 驱动头文件、探测 TF 卡并挂载/SD:/；其他文件系统初始化仍保留。src/shell/cmd/CMakeLists.txt：仅启用 SDMMC 磁盘驱动时编译sd命令。apps/arcs-mini/services/：仅启用 SD 音乐中间件时编译 SD 音乐服务；关闭时，查询接口返回未同步、卡不可用，初始化接口不创建任务。src/middleware/usb/：仅启用 CherryUSB MSC 时编译卡盘回调、注册 MSC 接口；关闭时忽略旧的 MSC 模式 KV，继续进入正常应用。
¶ 3. 开机启动独立任务
main.c 在应用初始化后调用 epaper_demo_init()。该函数用 s_epaper_ready 防止重复启动，通过 xTaskCreate() 创建 epaper_demo 任务，优先级为 5，栈深度为 3072 个 FreeRTOS 栈元素。
任务的执行顺序如下：
配置 GPIO/SPI → 初始化面板 → 申请帧缓冲区
→ 清屏并刷新 → 绘制两行文字 → 写入图像并刷新
→ 面板休眠 → 释放帧缓冲区 → 删除任务
刷新等待在独立任务中进行，启动接口只负责创建任务。如果启用了 CONFIG_LISA_PM，任务在操作面板前获取系统睡眠锁，退出时释放，避免操作期间外设因系统睡眠而掉电。
¶ 4. 配置 GPIO 与 SPI1
epaper_hal_init() 获取 gpioa 和 spi1 设备，并用 lisa_device_ready() 检查设备是否就绪，然后配置 RST/DC 为输出、BUSY 为输入。
应用覆盖板级弱函数 lisa_spi1_pinmux()，将 PA05、PA07、PA09 配置为 SPI1 的时钟、硬件片选和数据输出，复用功能均为 CSK_IOMUX_FUNC_ALTER6。GPIO 控制脚在任务内配置：PA04/PA06 使用默认功能，PA08 使用 CSK_IOMUX_FUNC_ALTER1。板级原有的 lisa_gpioa_pinmux() 保留，避免影响摄像头、音频等其他 GPIO。
SPI1 的主要配置如下：
| 参数 | 设置 |
|---|---|
| 时钟 | 10 MHz |
| 模式 | Mode 0，CPOL=0、CPHA=0 |
| 数据格式 | 8 bit，MSB first |
| 主从模式 | 主机 |
| 片选 | 硬件片选 |
| 发送模式 | 中断发送 |
¶ 5. 等待异步 SPI 发送完成
lisa_spi_write() 发起异步发送后，不能立即切换 DC 或释放发送数据。epaper_spi_send() 将数据分块复制到静态 256 字节缓冲区 s_epaper_tx，清空完成信号量后发起发送，再等待完成通知。SPI 回调 epaper_spi_done() 释放信号量，任务收到通知后才发送下一块。
每块发送等待超时为 1000 ms，失败后停止本次演示。静态发送缓冲区和信号量保留，即使完成回调延迟到达，也不会访问已经退出的任务栈或已释放的帧缓冲区。
epaper_send_command() 将 DC 拉低后发送命令，epaper_send_data() 将 DC 拉高后发送数据；两者均检查 GPIO 操作和 SPI 发送结果。
¶ 6. 面板初始化、清屏与刷新
epaper_panel_init() 先执行 RST 高 200 ms、低 2 ms、高 200 ms 的硬复位时序，再发送软复位命令 0x12，配置边框、温度传感器和数据写入方向，最后设置整屏窗口及写入光标。
本示例按 BUSY 高电平忙、低电平空闲 处理。epaper_wait_idle() 先等待 20 ms，让复位或刷新后的 BUSY 信号有时间置忙，再按 10 ms 间隔检查。硬复位后等待上限为 3000 ms，软复位为 5000 ms，刷新为 10000 ms；读取失败或超时均记录日志并停止演示。
epaper_clear() 用小块缓冲区循环填充面板 RAM；epaper_display_black() 写入文字图像。两者通过 epaper_refresh() 发送 0x22、更新参数 0xF7 和刷新命令 0x20，随后等待 BUSY 回到空闲。文字刷新完成后，任务等待 3 秒，再发送 0x10 和参数 0x03 让面板休眠。
¶ 7. 帧缓冲区与文字绘制
屏幕分辨率为 400 × 300，每像素使用 1 bit，因此每行占 50 字节，整帧需要 400 × 300 / 8 = 15000 字节。任务通过 psram_malloc() 分配帧缓冲区，退出时用 psram_free() 释放。
epaper_fill_text_demo() 先将缓冲区填为 0xFF（白底），再分别在 Y=72 和 Y=156 处绘制“聆思科技”和“ListenAI”。epaper_draw_text_centered() 计算字模推进宽度，实现水平居中；epaper_draw_pixel() 按行定位字节，并通过位掩码把目标像素置为黑色。
font24CN.c 只包含这两行演示文本所需的 12 个字符，不是完整中文字库。epaper_font24_find_glyph() 根据 UTF-8 字符查找字模，未找到的字符会跳过。修改显示文案时，需要同时补充对应字符的点阵数据和字模表。
¶ 8. 构建与验证
在仓库根目录执行默认板型构建：
.\build.ps1 -S .\apps\arcs-mini -B build-epaper -DBOARD=arcs_mini
Mini 3 使用独立板型和资源：
.\build.ps1 -S .\apps\arcs-mini -B build-epaper-mini3 -DBOARD=arcs_mini3
Linux 对应使用 ./build.sh，其余参数相同。构建后可查看输出目录的 .config，确认 CONFIG_EPAPER_DEMO=y、CONFIG_LISA_SPI1=y，且 SDMMC 磁盘驱动和 CherryUSB MSC 均关闭。
¶ 五、字模生成教程
¶ 1 字模生成参考教程
https://www.waveshare.net/wiki/E-Paper_Font_Tutorial