最近在做一个物联网项目，需要让STM32设备生成一个包含设备信息的二维码，方便手机App扫码快速绑定。本以为找个库就能搞定，结果发现网上资料要么是PC端的，要么依赖复杂图形库，在资源受限的MCU上根本跑不起来。经过一番折腾，终于实现了一个极简、高效的纯C语言文本二维码生成方案，代码量不到2KB，内存占用极低，非常适合STM32这类嵌入式平台。

本文将手把手带你从零实现一个“14-文本二维码生成器”。这个“14”指的是QR Code的版本1（21x21模块），支持数字、字母数字和8位字节（包括中文）编码，纠错等级可选。我们将深入解析QR Code的编码原理，并用纯C语言实现核心算法，最后移植到STM32上，通过串口或OLED显示生成的二维码。无论你是嵌入式新手想了解二维码生成原理，还是有经验的开发者需要在资源紧张的项目中集成二维码功能，这篇文章都能提供完整的代码和清晰的思路。

1. 二维码基础与核心概念

在动手写代码之前，我们必须先搞清楚二维码（这里特指QR Code）到底是怎么一回事。它不仅仅是一堆黑白方块，而是一套严谨的编码规则和容错机制。

1.1 QR Code 的结构解析

一个标准的QR Code图形由以下几个功能区域组成：

• 寻像图形：就是三个角落的大回字型图案，用于快速定位和识别二维码的方向。
• 分隔符：围绕在寻像图形周围的一圈白色边框，用于将寻像图形与数据区分开。
• 定位图形：由黑白相间的线条组成的“十字”，辅助确定模块的坐标。
• 校正图形：在较大版本的QR Code中会出现的小型寻像图形，用于校正因透视变形造成的图形扭曲。
• 格式信息：存放纠错等级和掩模图案编号，即使部分损坏也能被读取。
• 版本信息：在版本7及以上出现，用于标识QR Code的版本号。
• 数据和纠错码字：核心区域，存放着我们编码后的实际数据以及用于纠错的冗余信息。
• 空白区：二维码四周的留白区域，是成功扫描的必要条件。

1.2 关键的“版本”与“纠错等级”

这是我们项目名“14-文本二维码生成器”中“14”的含义所在。

• 版本：决定了二维码的大小和数据容量。版本从1到40，版本1是21x21个模块（最小单位方块），每增加一个版本，每边增加4个模块。版本1就是21x21。
• 纠错等级：决定了二维码的抗损毁能力，等级越高，能纠正的错误越多，但可用于存储实际数据的空间就越少。分为四个等级：
  • L (Low):可恢复约7%的数据码字。
  • M (Medium):可恢复约15%的数据码字。
  • Q (Quartile):可恢复约25%的数据码字。
  • H (High):可恢复约30%的数据码字。

我们的生成器将支持版本1（21x21）和全部四种纠错等级，这已经能够容纳数十个字符的文本，对于大多数嵌入式场景（如设备序列号、Wi-Fi配置信息、简单URL）完全足够。

1.3 编码流程总览

生成一个二维码，需要经过一系列标准化的步骤：

1. 数据分析：确定待编码文本的类型（数字、字母数字、8位字节等）。
2. 数据编码：根据数据类型，将其转换为特定的位流。
3. 纠错编码：使用里德-所罗门（Reed-Solomon）算法为数据位流生成纠错码。
4. 构造最终信息：按规则将数据码字和纠错码字交错排列。
5. 模块布置：在矩阵中放置功能图案（寻像图形、定位图形等）。
6. 掩模：为了避免出现大面积的空白或黑色区域影响识别，对数据区域应用8种预定义掩模之一，并选择最优的一个。
7. 格式与版本信息：生成并填入格式和版本信息。
8. 生成输出：将矩阵中的每个模块转换为黑（1）或白（0），最终生成图像。

我们的C语言实现将完整覆盖这8个步骤。

2. 开发环境与项目准备

由于核心是纯C算法，因此对开发环境要求非常灵活。你可以先在PC上验证算法，再移植到嵌入式平台。

2.1 环境与工具

• PC端验证环境：
  • 编译器：任何支持C99标准的编译器，如GCC (MinGW)、Clang。
  • 开发工具：Visual Studio Code、Code::Blocks 或简单的文本编辑器+命令行。
  • 目的：用于验证二维码算法的正确性，可以输出到控制台或PPM/PBM图像文件。
• STM32嵌入式环境：
  • MCU：任意一款STM32系列单片机，如STM32F103C8T6（蓝桥杯常用）、STM32F407等。Flash和RAM资源越丰富越好，但我们的实现非常精简。
  • 编译器/IDE：Keil MDK-ARM (uVision)、STM32CubeIDE、IAR Embedded Workbench 或 PlatformIO + VSCode。
  • 显示/输出设备：可选OLED屏幕（SSD1306驱动）、LCD屏，或通过串口打印到PC端工具显示。
• 版本说明：
  • 核心算法库不依赖特定硬件或操作系统。
  • 本文示例代码基于C99标准编写。
  • STM32的HAL库或标准外设库版本不影响核心逻辑，仅驱动部分有差异。

2.2 项目文件结构

在开始编码前，建议创建清晰的项目目录结构：

qrcode_stm32/ ├── core/ # 二维码核心算法 │ ├── qrcode.c │ └── qrcode.h ├── drivers/ # 硬件驱动（针对STM32） │ ├── oled.c # OLED显示驱动 │ ├── oled.h │ ├── uart.c # 串口打印驱动（用于调试或PC显示） │ └── uart.h ├── examples/ # 示例程序 │ ├── pc_main.c # PC端测试程序 │ └── stm32_main.c # STM32主程序 ├── utils/ # 工具函数 │ └── bitmap_utils.c # 位图生成工具（如生成PBM文件） └── README.md

我们将主要精力集中在core/qrcode.c和core/qrcode.h上，实现独立的二维码生成库。

3. 二维码生成核心算法拆解

这是整个项目最核心的部分。我们将分模块实现QR Code生成标准。

3.1 数据结构定义

首先，我们需要定义几个关键的数据结构来存储二维码数据。

// qrcode.h #ifndef QRCODE_H #define QRCODE_H #include <stdint.h> #include <stdbool.h> // 纠错等级定义 typedef enum { QR_ECC_LOW = 0, QR_ECC_MEDIUM, QR_ECC_QUARTILE, QR_ECC_HIGH } qr_ecc_t; // 二维码对象结构体 typedef struct { uint8_t version; // 版本号 (本项目固定为1) qr_ecc_t ecc_level; // 纠错等级 uint8_t size; // 二维码矩阵大小 (version*4 + 17) uint8_t *data; // 指向存储最终模块数据的缓冲区 (0=白, 1=黑) } qrcode_t; // 核心API int qrcode_init(qrcode_t *qrcode, uint8_t version, qr_ecc_t ecc_level, uint8_t *buffer, uint16_t buffer_len); int qrcode_encode_text(qrcode_t *qrcode, const char *text); void qrcode_print_console(const qrcode_t *qrcode); void qrcode_deinit(qrcode_t *qrcode); // 内部函数（通常不直接调用） uint16_t qrcode_get_buffer_size(uint8_t version); #endif // QRCODE_H

qrcode_t结构体是核心，它管理着二维码的所有属性。data指针指向一个一维数组，按行优先顺序存储整个二维码矩阵（0表示白色模块，1表示黑色模块）。size是矩阵的边长。

3.2 数据编码模块

这是将文本转换为二进制位流的过程。QR Code支持多种编码模式，我们实现最常用的两种：数字模式（0-9）和字母数字模式（0-9, A-Z, 以及9个符号$%*+-./:和空格）。

// qrcode.c (部分代码) static uint16_t encode_numeric(const char *text, uint8_t *buffer, uint16_t offset) { uint16_t length = strlen(text); uint16_t index = 0; // 写入模式指示器 (0001) offset = write_bits(buffer, offset, 0x01, 4); // 写入字符计数指示器 (对于版本1-9，数字模式是10位) offset = write_bits(buffer, offset, length, 10); // 每3个数字编码为10位 while (index + 2 < length) { uint16_t num = 100 * (text[index] - '0') + 10 * (text[index+1] - '0') + 1 * (text[index+2] - '0'); offset = write_bits(buffer, offset, num, 10); index += 3; } // 处理剩余2个数字 if (index + 1 == length) { uint16_t num = text[index] - '0'; offset = write_bits(buffer, offset, num, 4); } // 处理剩余1个数字 else if (index == length - 1) { uint16_t num = 10 * (text[index] - '0') + (text[index+1] - '0'); offset = write_bits(buffer, offset, num, 7); } return offset; }

write_bits是一个辅助函数，用于将指定位数的数据写入字节缓冲区的特定位位置，处理位跨越字节边界的复杂情况。字母数字模式的编码逻辑类似，只是将45个字符（0-9, A-Z, 及9个符号）映射为0-44的数字，然后每两个字符编码为11位。

3.3 纠错编码与信息构造

纠错码使用里德-所罗门（RS）算法生成。对于嵌入式环境，实现完整的RS编解码器较复杂。一个实用的策略是使用查表法。由于版本1、纠错等级确定后，所需的RS码字块数、数据码字数、纠错码字数都是固定的（标准定义），我们可以预先计算好生成多项式，或者直接使用现成的轻量级RS编码库（如libcorrect的裁剪版）。 核心步骤是：

1. 根据版本和纠错等级，查表得到数据码字总数和纠错码字总数。
2. 将编码后的数据位流按8位一组，分成多个数据码字块。
3. 对每个数据块，使用RS算法生成对应数量的纠错码字。
4. 按照QR Code规范，将不同块的数据码字和纠错码字交错排列，形成最终的数据序列。

为了简化，我们可以针对版本1的四种纠错等级，硬编码其RS参数。例如，版本1-L：数据码字19个，纠错码字7个，每个块26个码字。

3.4 模块布置与掩模

这是将数据“画”到二维码矩阵上的过程。

1. 初始化矩阵：创建一个size x size的矩阵，所有模块置为空白（例如，用0xFF表示未定义）。
2. 放置功能图案：
   • 寻像图形：在 (0,0), (0, size-7), (size-7, 0) 三个位置放置7x7的固定黑白图案。
   • 分隔符：在寻像图形周围画一圈宽度为1的白色边框。
   • 定位图形：在第6行和第6列（从0开始计数）放置黑白相间的线条。
   • 校正图形：版本1没有。
3. 预留格式/版本信息区域：将存储格式信息（围绕寻像图形）和版本信息的位置标记为“已占用”。
4. 填充数据位：按照QR Code标准的“之字形”路径，将最终数据序列的每一个比特，填充到矩阵中未被功能图案占用的模块上（1变黑，0变白）。
5. 应用掩模并评估：定义8种掩模图案（例如，(行+列)%2==0则翻转）。用每一种掩模对数据区域进行异或操作，然后根据“惩罚规则”（如连续黑块、类似寻像图形的图案等）计算分数，选择分数最低（最优）的掩模。
6. 写入格式信息：将选中的纠错等级和掩模编号，编码为15位格式信息（含10位纠错位），填入预留的格式信息区域。

4. 完整实战：从文本到二维码图像

现在，我们将上述模块组合起来，形成一个完整的、可运行的示例。我们先在PC环境下验证。

4.1 核心库的实现与集成

首先，完成qrcode.c的核心函数qrcode_encode_text。这个函数是外部调用的总入口。

// qrcode.c int qrcode_encode_text(qrcode_t *qrcode, const char *text) { // 1. 参数检查 if (!qrcode || !text || !qrcode->data) return -1; // 2. 计算文本长度，选择编码模式（简化：此处假设为字母数字） // 3. 数据编码 -> encode_alphanumeric(...) uint8_t data_bits[256] = {0}; uint16_t bit_len = encode_alphanumeric(text, data_bits, 0); // 4. 添加结束符和填充位，直到达到目标数据码字长度 bit_len = add_terminator_and_padding(data_bits, bit_len, target_data_codewords * 8); // 5. 分组并进行纠错编码 -> rs_encode_blocks(...) uint8_t final_codewords[128] = {0}; uint16_t final_len = construct_final_message(data_bits, final_codewords, ...); // 6. 初始化矩阵，放置功能图案 -> initialize_functional_patterns(...) uint8_t modules[QR_MODULE_SIZE][QR_MODULE_SIZE]; init_modules(modules, qrcode->size); place_finder_patterns(modules, qrcode->size); place_timing_patterns(modules, qrcode->size); // 7. 填充数据位 fill_data_modules(modules, qrcode->size, final_codewords, final_len); // 8. 掩模评估与应用 uint8_t best_mask = evaluate_and_apply_best_mask(modules, qrcode->size); // 9. 写入格式信息 write_format_info(modules, qrcode->size, qrcode->ecc_level, best_mask); // 10. 将矩阵数据复制到qrcode->data缓冲区（按行优先一维化） flatten_modules(modules, qrcode->size, qrcode->data); return 0; // 成功 }

qrcode_init函数用于初始化结构体和分配缓冲区。qrcode_get_buffer_size帮助用户计算需要多大的缓冲区。

4.2 PC端测试程序

创建一个pc_main.c来测试我们的库。

// examples/pc_main.c #include <stdio.h> #include <stdlib.h> #include "core/qrcode.h" #define QR_VERSION 1 #define QR_BUFFER_SIZE(qr_version) (qrcode_get_buffer_size(qr_version)) int main() { const char *text_to_encode = "HELLO CSDN"; qr_ecc_t ecc = QR_ECC_MEDIUM; // 计算所需缓冲区大小并分配 uint16_t buf_size = QR_BUFFER_SIZE(QR_VERSION); uint8_t *buffer = (uint8_t *)malloc(buf_size); if (!buffer) { printf("内存分配失败！\n"); return -1; } // 初始化二维码对象 qrcode_t qrcode; if (qrcode_init(&qrcode, QR_VERSION, ecc, buffer, buf_size) != 0) { printf("二维码初始化失败！\n"); free(buffer); return -1; } // 编码文本 if (qrcode_encode_text(&qrcode, text_to_encode) == 0) { printf("成功生成二维码！内容：%s\n", text_to_encode); // 打印到控制台 qrcode_print_console(&qrcode); // 可选：保存为PBM图像文件 // save_as_pbm(&qrcode, "output.pbm"); } else { printf("二维码编码失败！\n"); } // 清理 qrcode_deinit(&qrcode); free(buffer); return 0; }

qrcode_print_console函数简单地将data数组中的0/1打印为空格和字符（如██），以便在终端中查看二维码轮廓。

4.3 编译与运行（PC端）

使用GCC编译并运行：

gcc -o qr_test core/qrcode.c examples/pc_main.c -Icore ./qr_test

如果一切正常，你将在终端看到一个由字符组成的二维码。你可以用手机扫码软件（如微信“扫一扫”）尝试扫描这个终端输出的图案，验证其正确性。

4.4 移植到STM32并显示

在STM32上的主要工作是实现输出。我们以OLED（SSD1306 I2C）为例。

1. 硬件连接：将OLED的SDA、SCL分别连接到STM32的I2C引脚（如PB7, PB6），VCC接3.3V，GND接地。
2. 驱动集成：将成熟的OLED驱动代码（如oled.c/oled.h）加入工程。驱动通常包含OLED_Init,OLED_Clear,OLED_ShowChar,OLED_DrawPoint等函数。
3. 编写显示函数：在qrcode.c或单独的文件中，创建一个函数，将二维码的data数组绘制到OLED上。

// drivers/oled_qrcode.c #include "oled.h" #include "core/qrcode.h" void oled_draw_qrcode(const qrcode_t *qrcode, uint8_t x, uint8_t y, uint8_t pixel_size) { // pixel_size: 每个二维码模块用几个OLED像素点表示 if (!qrcode || !qrcode->data) return; for (uint8_t row = 0; row < qrcode->size; row++) { for (uint8_t col = 0; col < qrcode->size; col++) { uint8_t is_black = qrcode->data[row * qrcode->size + col]; if (is_black) { // 画实心矩形 OLED_DrawRectangle(x + col * pixel_size, y + row * pixel_size, x + (col+1) * pixel_size -1, y + (row+1) * pixel_size -1, OLED_COLOR_SOLID); } else { // 画空心矩形或留白 // OLED_DrawRectangle(... , OLED_COLOR_EMPTY); } } } OLED_Refresh(); // 更新显示 }

4. STM32主程序：

// examples/stm32_main.c #include "main.h" #include "oled.h" #include "core/qrcode.h" // 定义缓冲区（使用全局数组或静态内存，避免动态分配） #define QR_VERSION 1 #define BUFFER_LEN qrcode_get_buffer_size(QR_VERSION) static uint8_t qr_buffer[BUFFER_LEN]; int main(void) { HAL_Init(); SystemClock_Config(); OLED_Init(); OLED_Clear(); qrcode_t qrcode; const char *device_id = "DEV:12345;VER:1.0"; // 初始化二维码对象 if (qrcode_init(&qrcode, QR_VERSION, QR_ECC_MEDIUM, qr_buffer, BUFFER_LEN) != 0) { // 错误处理 while(1); } // 编码设备信息 if (qrcode_encode_text(&qrcode, device_id) == 0) { // 在OLED中央绘制二维码，每个模块用2x2像素显示 oled_draw_qrcode(&qrcode, (128 - qrcode.size*2)/2, (64 - qrcode.size*2)/2, 2); } while (1) { // 主循环 } }

5. 编译与烧录：在Keil或STM32CubeIDE中配置好工程，包含所有源文件，编译并烧录到STM32。上电后，设备ID等信息将以二维码形式显示在OLED上。

5. 常见问题与排查思路

在实现和移植过程中，你可能会遇到以下问题：

6. 最佳实践与工程建议

将二维码生成器用于实际项目时，以下几点能帮你走得更稳更远。

6.1 资源优化策略

• 内存使用：核心算法中的缓冲区（如数据位数组、码字数组、模块矩阵）尽量使用全局或静态数组，避免在函数内定义大数组导致栈溢出。版本1的模块矩阵是21x21=441位，用字节数组存储只需56字节。
• CPU与速度：RS纠错编码是计算密集型操作。如果对生成速度有要求，可以：
  • 使用查表法代替实时计算RS码。
  • 针对固定的版本和纠错等级，预计算并存储生成多项式或直接存储RS编码表。
  • 仅在需要时生成二维码（如按键触发），而不是周期性刷新。
• 代码空间：如果Flash空间紧张，可以裁剪不用的编码模式（如只保留数字模式），或者使用-Os优化等级编译。

6.2 可维护性与扩展性

• 模块化设计：正如我们做的，将数据编码、纠错、矩阵处理、绘制显示分离成独立模块。这样便于测试、调试和替换（例如，换用更高效的RS库）。
• 配置化：通过宏定义或结构体参数来配置二维码的版本、纠错等级、编码模式，而不是硬编码在函数里。
• 错误处理：核心API函数（如qrcode_encode_text）应返回明确的错误码（如QR_ERR_OK,QR_ERR_BUFFER_TOO_SMALL,QR_ERR_DATA_TOO_LONG），便于上层应用处理。

6.3 生产环境注意事项

• 内容安全：避免在二维码中编码明文敏感信息（如密码、IP地址）。考虑使用简单的对称加密或哈希后再编码。
• 鲁棒性：确保生成函数能处理异常输入（空指针、超长字符串）。在STM32中，可以考虑加入看门狗（IWDG）防止在复杂计算中卡死。
• 显示优化：在低分辨率OLED上，pixel_size为1时可能难以扫描。可以尝试在绘制时进行简单的反走样（如对模块边缘进行灰度处理），或者确保二维码周围有足够的空白区（4个模块宽）。
• 多平台支持：核心算法库保持纯C标准，不依赖平台特定函数。通过#ifdef来区分PC的printf调试和嵌入式平台的日志输出。

6.4 进阶功能探索

当基本功能稳定后，可以考虑以下扩展：

• 支持更多版本：扩展数据结构，支持版本2（25x25）及以上。这需要动态计算定位图形、校正图形的位置，以及更复杂的容量计算。
• 支持8位字节模式：实现此模式以支持中文（需先转换为UTF-8或GBK）。注意，一个中文字符占3个字节，数据容量消耗很快。
• 生成位图文件：在PC端完善save_as_pbm或save_as_png函数，方便生成图片文件。
• 与通信结合：STM32生成的二维码可以包含蓝牙MAC地址、Wi-Fi SSID/密码、WebSocket连接字符串等，实现设备快速配网或绑定。

7. 总结

通过本文，我们完成了一个在STM32上从零实现的轻量级文本二维码生成器。我们从QR Code的基本原理入手，逐步实现了数据编码、纠错计算、矩阵构造和掩模评估等核心算法，并将这些算法封装成可移植的C语言库。最后，我们成功地将生成的二维码显示在OLED屏幕上。

整个过程的关键在于理解QR Code的国际标准（ISO/IEC 18004），并将复杂的规范分解为一个个可实现的函数。对于嵌入式开发而言，在资源受限的环境下，做出合理的裁剪和优化（如固定版本、使用查表法）是保证项目可行的关键。

你可以将本文的代码作为起点，根据实际项目需求进行修改和增强。例如，增加对更复杂内容的支持，优化生成速度，或者将其与你的物联网设备管理平台深度集成。希望这篇详细的实战笔记能帮助你解决项目中二维码生成的难题。