ESP32-S3TFT/OLEDHZK16离线中文点阵字库

ESP32 离线中文显示(esp32-tft-hzk16-chinese)

在 ESP32 屏幕上显示简体中文,内嵌 HZK16 点阵字库——无需文件系统、无需网络字体、无需 gb_idx 索引。

一、这个 skill 是做什么的

你想在 ESP32 / ESP32-S3 驱动的屏幕(TFT 如 ST7735/ILI9341/ST7789,或 OLED 如 SSD1306/SSD1309/SH1106)上显示简体中文——命令回显、状态提示、菜单都行。常见的做法是挂 LittleFS/SD 卡放字体、或者联网下载字体,但很多小项目根本不想要这些依赖。

本技能的做法是:把标准的 HZK16 点阵字库(16×16 点阵,267616 字节)直接编进固件 flash,设备端用 GB2312 区位码定位每个字、逐点画出来。它零文件系统依赖(字库编进 flash .rodata,不占 RAM)、不需要 gb_idx 索引(用 Python 内置的 s.encode('gb2312') 直接得到字节串)。适合想让屏幕"开箱即显中文"的轻量项目。

二、什么时候用它

你可能会听到的"信号原话":

三、前置条件 / 准备

四、具体用法(步骤)

  1. 放字库:把 HZK16.bin 放到工程根(或已知路径)。
  2. 生成脚本 main/gen_fonts.py(用 IDF 自带 Python 跑):读 HZK16.bin → 写 main/hzk16_data.c(const uint8_t hzk16_font[...],约 267KB,编进 flash .rodata,不占 RAM);并把中文显示串 s.encode('gb2312') 写成 C 字符串字面量 → main/cn_names.h。
  3. CMake 自动生成:在 main/CMakeLists.txt 里用 execute_process 调脚本(注意:组件被 component_get_requirements.cmake include 时 CMAKE_CURRENT_SOURCE_DIR 指向 build 目录,必须用 CMAKE_CURRENT_LIST_DIR 指组件目录)。idf.py build 在 configure 阶段自动跑。FATAL_ERROR 信息用英文(UTF-8 中文会被 GBK 控制台读成乱码)。
  4. 绘制函数(在 tft_display.c):tft_draw_glyph(x,y,q,w,color) 按 offset 取 32 字节逐行发 16 像素;tft_cn_text(gb,x,y,color) 遍历 GB2312 字节串(每字 +16px);tft_show_text 对外接口。
  5. 刷新策略:只刷新各自区域、不要整屏清屏(否则擦掉中文回显);回显前先 tft_fill 清掉回显区矩形再画字。

取模原理:GB2312 区位码定位 offset = ((区码-0xA1)*94 + (位码-0xA1))*32;设备侧遇 字节≥0x80 即视为一个中文(取连续两字节为区/位码),字节<0x80 跳过(ASCII);MSB 先行,bit7 = 最左像素。

五、可直接照用的示例

你直接对 AI大模型或AI智能体 说:"我的 ST7735 128×160 小屏想显示中文命令回显,但不想挂文件系统,帮我把字库编进固件。"

AI大模型或AI智能体 会:让你把标准 HZK16.bin 放进工程根,写 gen_fonts.py 把字库转成 hzk16_data.c(编进 flash、不占 RAM),并把中文串用 s.encode('gb2312') 写成 cn_names.h;再帮你配好 CMakeLists 自动生成(用 CMAKE_CURRENT_LIST_DIR 避开 build 目录陷阱),最后给出 tft_draw_glyph / tft_cn_text 的绘制函数骨架。

你直接对 AI大模型或AI智能体 说:"屏上中文显示一半、还总残留亮点,怎么根治?"

AI大模型或AI智能体 会:指出两个根因——① 画图形时对"图形外像素填黑色"会互相擦除,正确做法是只画亮的部分、不碰背景,消残影靠"逐元素重绘成背景色"而非大矩形清;② 多任务写同一 SPI 屏没加互斥锁会刷屏卡死,要加递归互斥锁且等待超时别用 portMAX_DELAY,否则高优先级音频任务被阻塞。

进阶 / 可选——下面是"把中文串转成 GB2312 字节、写进 C 头文件"在做什么(用 Python 内置 gb2312 编解码,不需要 gb_idx.bin):

s = "打开灯光" gb = s.encode('gb2312') # 得到字节串,每两字节一个汉字 # 再写成 C 字符串字面量 "(const uint8_t*)\"\xB4\xF2...\""

(这只是"生成脚本"里处理中文串的一步;字库转 C 数组与 CMake 集成 AI大模型或AI智能体 会替你写好。)

六、常见注意 / 避坑

七、相关 skill / 延伸

← 返回 SKILL 库