quirc QR 码识别示例

📁 源码位置: samples/media/quirc 查看源码

功能说明

演示如何使用 quirc 库进行 QR 码识别和解码，包括创建 quirc 对象、设置图像尺寸、获取图像缓冲区以及 QR 码解码等基本操作。

硬件连接

无需外部连接，quirc 为纯软件 QR 码识别库。

示例内容

  1. 创建和初始化 quirc 对象

  2. 设置图像尺寸并获取图像缓冲区

  3. 将灰度图像数据写入缓冲区

  4. 执行 QR 码识别和解码

  5. 打印解码结果和错误处理信息

编译

重要提示：编译前需要先确认当前示例支持的目标板型，然后将板型标识传给 -DBOARD。请按以下方式选择：

  1. 确认示例限制：查看当前示例 README 中的硬件连接和注意事项，确认是否限定板型。

  2. 参考示例配置：查看相关示例目录下的 sample.yaml，确认支持的板型。

  3. 填写板型标识：SDK 内置板型的标识为 boards/ 下的目录名。例如实际使用的板型目录为 boards/<板型名称>/，则编译参数填写为 -DBOARD=<板型名称>。

在 SDK 根目录执行编译，并将命令中的 <示例路径> 和 <板型名称> 替换为实际值。

Linux 使用 build.sh：

# 通用命令
./build.sh -C -S samples/<示例路径> -DBOARD=<板型名称>

# 示例：使用 arcs_evb 开发板
./build.sh -C -S samples/<示例路径> -DBOARD=arcs_evb

Windows PowerShell 使用 build.ps1：

# 通用命令
.\build.ps1 -C -S samples/<示例路径> -DBOARD=<板型名称>

# 示例：使用 arcs_evb 开发板
.\build.ps1 -C -S samples/<示例路径> -DBOARD=arcs_evb

Note

确保已安装对应平台的工具链和 ListenAI 开发工具包。Windows 环境请先执行 .\env.ps1 或直接使用 .\build.ps1 自动加载环境。

注意事项：-DBOARD 填写的是板型标识，不是芯片系列名称。如果示例有板型专用配置或额外编译参数，以示例 README 中的说明为准。

烧录

编译完成后，使用 SDK tools/burn 目录下的 cskburn 工具烧录固件。请先根据目标板型和当前示例确定芯片系列、串口设备、烧录地址和固件路径。

Linux：

# 通用命令
./tools/burn/cskburn -C <芯片系列> -s <串口设备> -b 3000000 <烧录地址> <固件路径>

# 示例：使用 arcs_evb 开发板
./tools/burn/cskburn -s /dev/ttyUSB0 -b 3000000 0x0 build/arcs.bin -C arcs

Windows PowerShell：

# 通用命令
.\tools\burn\cskburn.exe -C <芯片系列> -s <串口号> -b 3000000 <烧录地址> <固件路径>

# 示例：使用 arcs_evb 开发板
.\tools\burn\cskburn.exe -C arcs -s COM7 -b 3000000 0x0 .\build\arcs.bin

Note

烧录参数说明：

  • -s /dev/ttyUSB0 / -s COM7：串口设备路径，需要根据实际情况修改 - Linux 系统：通常是 /dev/ttyUSB0 或 /dev/ttyACM0 - 可通过 ls /dev/tty* 命令查看可用串口设备 - Windows 系统：通常是 COM7、COM8 等，可在“设备管理器”的“端口”中查看 - 不同开发板或 USB 转串口芯片可能使用不同的设备名

  • -b 3000000：烧录波特率（3Mbps）

  • 0x0：烧录起始地址

  • build/arcs.bin / .\build\arcs.bin：编译生成的固件路径

  • -C arcs：芯片类型

注意事项：

  • 确保开发板已正确连接到电脑

  • 如果无法识别串口设备，请检查 USB 连接线是否正常，或尝试其他 USB 端口

预期输出

[I][sample] quirc initialized
[I][sample] Image buffer: 640x480
[I][sample] QR codes identified: 0
[I][sample] quirc sample completed

核心 API

API

说明

quirc_new()

创建新的 quirc 对象

quirc_resize()

设置图像尺寸

quirc_begin()

获取图像缓冲区指针

quirc_end()

完成图像写入并执行识别

quirc_count()

获取识别到的 QR 码数量

quirc_extract()

提取指定 QR 码的数据

quirc_decode()

解码 QR 码数据

quirc_destroy()

销毁 quirc 对象

关键代码

/* 创建 quirc 对象 */
struct quirc *qr = quirc_new();

/* 设置图像尺寸 */
quirc_resize(qr, width, height);

/* 获取图像缓冲区并写入数据 */
uint8_t *image = quirc_begin(qr, NULL, NULL);
memcpy(image, gray_data, width * height);
quirc_end(qr);

/* 提取和解码 QR 码 */
int count = quirc_count(qr);
for (int i = 0; i < count; i++) {
    struct quirc_code code;
    struct quirc_data data;
    quirc_extract(qr, i, &code);
    quirc_decode(&code, &data);
}

/* 销毁对象 */
quirc_destroy(qr);

使用预生成测试数据

在 prj.conf 或代码中启用：

#define USE_QR_TEST_DATA

烧录到开发板后运行，程序将自动测试所有预生成的 QR 码。

测试的 QR 码规格

生成的测试数据包含以下类型的 QR 码：

#

名称

QR 版本

尺寸

纠错级别

数据内容

数据类型

1

small_low

1

21x21

L (Low)

“Hello World”

字节

2

small_medium

1

21x21

M (Medium)

“QUIRC”

字节

3

medium_high

3

29x29

H (High)

URL

字节

4

large_quartile

5

37x37

Q (Quartile)

“QR Code Test Data 12345”

字节

5

numeric_only

1

21x21

L (Low)

“1234567890”

数字

6

alphanumeric

2

25x25

M (Medium)

“ABC-123”

字母数字

7

chinese_text

4

33x33

M (Medium)

“聆思科技”

字节(UTF-8)

测试覆盖：

  • QR 码版本：Version 1-5（尺寸从 21x21 到 37x37）

  • 错误纠正级别：L/M/Q/H 四个级别

  • 数据类型：数字、字母数字、字节、UTF-8 编码文本

项目结构

samples/media/quirc/
├── CMakeLists.txt          # CMake 配置
├── Kconfig                 # 配置选项
├── prj.conf                # 项目配置
├── sample.yaml             # 示例描述
├── README.md               # 本文件
├── board_configs/           # 按板型自动合并的配置
│   ├── arcs_evb.conf
│   └── venusa_rd_evb.conf
├── src/
│   ├── main.c              # 主程序
│   └── qr_test_data.h      # QR 码测试数据（生成后）
└── tools/
    ├── qr_generator.py     # QR 码生成器
    ├── requirements.txt    # Python 依赖
    ├── generate_qr.sh      # 生成脚本
    └── output/             # 生成的文件输出目录
        ├── qr_*.png        # QR 码图片
        └── *.h             # 头文件

配置说明

prj.conf 保存示例的公共配置。构建时传入 -DBOARD=<board> 后，构建系统会自动合并 board_configs/<board>.conf，不需要手动切换配置文件。

板型

板级配置

用途

arcs_evb

CONFIG_MEM_SRAM_SIZE=0x00038000
CONFIG_MAIN_TASK_STACK_SIZE=20480
CONFIG_HEAP_SIZE=0x30000
CONFIG_PSRAM_HEAP_SIZE=0x100000

保留原有 SRAM、主任务栈和堆大小

venusa_rd_evb

CONFIG_MAIN_TASK_STACK_SIZE=16384
CONFIG_HEAP_SIZE=0x2000
CONFIG_PSRAM_HEAP_SIZE=0x100000

使用默认 SRAM 布局，为识别/解码路径保留足够主任务栈，并将 QR 图像缓冲等大块内存放入 PSRAM

这些配置主要用于平衡不同内存布局下的主任务栈、内部堆和 QR 图像缓冲占用。

QR 码生成器选项

qr_generator.py 支持以下参数：

  • -o, --output DIR - 指定输出目录（默认：output）

  • -c, --combined - 仅生成合并的头文件

  • -s, --separate - 仅生成单独的头文件

  • -a, --all - 生成所有格式（默认）

自定义 QR 码测试数据

编辑 tools/qr_generator.py 中的 QR_CONFIGS 数组来添加自定义的 QR 码配置：

{
    "name": "custom_qr",
    "version": 2,  # QR 码版本 (1-40)
    "error_correction": qrcode.constants.ERROR_CORRECT_M,  # L/M/Q/H
    "data": "Your custom data",
    "box_size": 10,
    "border": 4,
}

注意事项

  1. 图像格式: quirc 仅接受灰度图像，彩色图像需先转换为灰度格式

  2. 内存使用: quirc 每个像素占用一个字节，加上解码器对象的几 KB 内存

  3. 图像质量: 确保输入图像清晰，QR 码占据图像的合理比例，避免过度模糊或倾斜

  4. 测试数据: 默认模式仅演示 API 使用，启用 USE_QR_TEST_DATA 可使用预生成的 QR 码进行实际解码测试

  5. 错误处理: quirc_decode() 返回错误码时，使用 quirc_strerror() 获取错误描述