📚 课程目录第4章设备端二维码生成

4、设备端二维码生成：嵌入式环境下的二维码生成、内存与性能优化、使用C语言生成二维码的轻量级方案

好，咱们进入实战环节。前面几章讲了二维码的结构、编码规则，还有云端怎么生成二维码。但到了设备端，情况就完全不一样了。

设备端资源有限——RAM 可能只有几十 KB，Flash 也就几百 KB，CPU 主频还低。你想想看，在这种环境下要生成二维码，能直接把 PC 上的库搬过来用吗？肯定不行。

我个人习惯是，先搞清楚两个问题：二维码到底在设备端哪个环节生成？生成后怎么用？弄明白这个，选方案才有方向。

4.1 设备端二维码生成的典型场景

先看一张图，帮你快速建立整体认知。

这张图把设备端生成二维码的流程拆成了五步。每一步都有它的坑，咱们一个一个说。

4.2 嵌入式环境下的二维码生成方案选型

市面上能用的 C 语言二维码库，我列个表给你对比一下。

库名	语言	RAM 占用	Flash 占用	特点
libqrencode	C	~8-12 KB	~30-50 KB	功能完整，支持多版本
QR-Code-generator	C/C++	~4-8 KB	~15-25 KB	轻量，无动态内存
自家手写	C	~2-4 KB	~5-10 KB	极致精简，但开发周期长

我在项目中用过 libqrencode，功能确实强，但它的内存分配策略对裸机不太友好。后来换成了 QR-Code-generator，嗯，这个库的设计思路就很对胃口——所有内存都是静态分配的，没有 malloc。

核心原则：嵌入式环境选二维码库，第一看内存分配方式，第二看代码体积，第三才看功能完整性。动态内存分配在裸机环境下是灾难。

4.3 内存与性能优化实战

好，咱们深入聊聊优化。我总结了几条实战经验。

4.3.1 内存优化：静态分配 + 复用缓冲区

QR-Code-generator 这个库的设计思路值得学习。它把所有中间数据都放在一个结构体里，你只需要提供一个足够大的缓冲区。

// QR-Code-generator 的典型用法
uint8_t qrcode[qrcodegen_BUFFER_LEN_MAX];
uint8_t tempBuffer[qrcodegen_BUFFER_LEN_MAX];

bool ok = qrcodegen_encodeText(
    "https://iot.example.com/device/SN123456",
    tempBuffer, qrcode,
    qrcodegen_Ecc_MEDIUM,
    qrcodegen_VERSION_MIN, qrcodegen_VERSION_MAX,
    qrcodegen_Mask_AUTO, true
);

你看，两个缓冲区都是栈上分配的，没有 malloc。qrcodegen_BUFFER_LEN_MAX 这个宏会根据你设定的最大版本号自动计算大小。

我的建议：如果你确定设备只生成 Version 2-4 的二维码，可以手动把 BUFFER_LEN_MAX 改小。比如 Version 4 只需要 108 字节，比默认的 391 字节省了 70% 以上。

4.3.2 性能优化：减少纠错等级 + 固定版本

性能优化说白了就是做减法。我遇到过一个问题：设备上电后要快速显示二维码，但生成过程卡了 200 毫秒，用户体验很差。

怎么优化？两个方向：

降低纠错等级：从 H（30%）降到 M（15%），生成时间减少约 40%。设备端的二维码是近距离扫描，环境干扰小，M 级完全够用。
固定二维码版本：不要用自动版本选择，直接指定 Version 3 或 4。这样编码器不用做版本试探，省掉一次循环。

// 优化后的调用方式
// 固定 Version 3，纠错等级 M
bool ok = qrcodegen_encodeText(
    input, tempBuffer, qrcode,
    qrcodegen_Ecc_MEDIUM,  // 用 M 级，别用 H
    3, 3,                  // 固定 Version 3
    qrcodegen_Mask_AUTO, true
);

4.3.3 位图渲染优化：直接操作显存

二维码编码完成后，得到的是一个二维 bit 数组。接下来要把它渲染到屏幕上。

我曾经见过有人先把二维码转成 BMP 位图，再刷到屏幕——这太浪费了。正确的做法是直接操作显存。

// 直接渲染到单色屏的显存
// qrcode 是编码后的 bit 数组
// screen_buffer 是屏幕的显存区域
for (int y = 0; y < size; y++) {
    for (int x = 0; x < size; x++) {
        int module = qrcodegen_getModule(qrcode, x, y);
        // 直接设置显存对应像素
        if (module) {
            screen_buffer[y * screen_width + x] = 0x00; // 黑色
        } else {
            screen_buffer[y * screen_width + x] = 0xFF; // 白色
        }
    }
}

注意：别忘了加白边（quiet zone）。二维码规范要求四周至少留 4 个模块宽的白边。我见过有人忘了加，结果扫码死活扫不出来。

4.4 使用 C 语言生成二维码的轻量级方案

如果你对代码体积有极致要求，比如 Flash 只剩 10KB 了，那可以考虑自己手写一个精简版。

但说实话，我不建议从零开始写。QR-Code-generator 这个库已经足够轻量了，而且它把编码核心和渲染分离了。你只需要实现一个渲染回调就行。

4.4.1 裁剪库的步骤

去掉不需要的版本：只保留 Version 1-6，对应的表数据能省掉 60% 以上。
去掉高纠错等级：只保留 L 和 M 级，H 和 Q 级的 Reed-Solomon 生成多项式可以砍掉。
去掉掩码模式：固定用 Mask 0 或 Mask 2，省掉掩码评估的算力。
去掉 Kanji/Hanzi 编码：只保留数字、字母数字、字节模式。

我做过一次裁剪，最终库的体积从 22KB 降到了 6.8KB，RAM 占用从 5KB 降到了 2.4KB。效果很明显。

4.4.2 数据编码的注意事项

设备端生成的二维码，内容通常是设备标识符 + 签名。比如：

// 典型的数据格式
"https://iot.example.com/bind?sn=SN20241001&sig=a1b2c3d4"

这里有个坑：URL 长度。Version 3 的二维码最多只能存 53 个字节（M 纠错等级）。如果你的 URL 太长，就得升级版本，但版本越高，生成时间越长，占用的内存也越大。

我的经验：用短域名 + 短参数名。比如把 "serial_number" 缩成 "sn"，"signature" 缩成 "sig"。再配合 URL 缩短服务，能把 80 个字符的 URL 压到 40 个字符以内。

4.5 避坑指南

最后，分享几个我踩过的坑。

字节序问题：二维码编码时，数据是按大端序处理的。如果你在小端序的 MCU 上直接 memcpy，会出问题。我当初在这个问题上折腾了两天。
屏幕旋转：二维码是正方形，但屏幕不一定是。如果屏幕是竖屏，二维码显示出来会被拉伸。记得保持宽高比 1:1。
刷新率：有些屏幕刷新一次要 100ms。如果频繁生成二维码，屏幕会闪烁。我建议加一个防抖逻辑：内容没变就不刷新。
电源管理：生成二维码时 CPU 全速跑，电流会增大。如果设备是电池供电，生成完后记得让 CPU 进入低功耗模式。