STM32口罩识别门禁系统开发指南：从系统拆解到环境配置-育师

口罩识别门禁系统是嵌入式项目里比较完整的一种综合训练：摄像头每隔几百毫秒抓取画面，视觉模块判断进出的这个人是否佩戴口罩，再把结果交给 STM32；STM32 需要同时处理按键、OLED、蜂鸣器、舵机或电磁锁等外设。很多学习者在网上找到类似“STM32 口罩识别门禁系统，源码+原理图（0465A）”的免费开源资料后，第一个动作往往是打开 Keil 直接编译。结果不是编译报错，就是下载后没有任何现象。

这一类资料和普通串口点灯 Demo 不同。它里面包含原理图、PCB、多份源码文件、文档和可能的模型文件。只有在真正搞清楚“哪一颗芯片负责识别、哪一颗芯片负责门锁控制”的前提下，代码才能和电路对应起来。这篇文章以这类 STM32 口罩识别门禁系统为对象，整理从资料初检、原理图阅读、环境安装、模块联调、故障排查到生产化改造的完整路径。文中给出的代码、表格和排查步骤都可以直接移植到自己的工程里，而不只是把开源包再解压一遍。

1. 拿到资料先拆系统：口罩识别和门禁控制可能分别在不同芯片

1.1 先理解“识别计算量”和“控制可靠性”是两回事

口罩识别门禁系统本质上由三个能力组成：图像采集与识别、业务决策、门锁执行。很多人误以为所有功能都应该由同一颗 STM32 完成，这是第一个认知误区。

STM32F103C8T6 只有 64KB Flash、20KB RAM，主频 72MHz。如果还要让它同时处理摄像头原始图像和神经网络推理，内存和算力都不现实。而 STM32H743 这类高性能 MCU 在算力和内存上明显更强，可以把视觉识别和门控逻辑放在同一颗芯片上。因此拿到资料的第一步，不是找main.c，而是先打开原理图，找到图上到底有几颗处理器。

这里的核心问题是：口罩识别发生在哪里，门禁控制逻辑又发生在哪里。这决定了你后续要编译几个工程、需要烧录几颗芯片，也决定了排错时先看哪一侧的日志。

1.2 三种常见系统架构与选型对照

在常见的“STM32 + 口罩识别门禁”开源资料中，主要有三种架构，可以用一张表快速判断。

架构类型	典型芯片组合	口罩识别在哪里完成	主控芯片的任务	优点	难点	适用场景
STM32 主控 + 独立视觉模块	STM32F103 + OpenMV / K210 / ESP32-CAM	第二颗视觉芯片或模组	接收识别结果，控制门锁、显示、按键	软件分层清晰，视觉算法不占主控资源	双端通信协议、另配一路电源	多数低成本门禁 Demo，也是 0465A 这类资料最常见的设计
高性能 MCU 本地 AI	STM32H743 / STM32H747 + 摄像头	主控内部通过 Cube.AI 或 TensorFlow Lite Micro 运行模型	视觉推理与门控逻辑	单板少一颗处理器，BOM 更紧凑	模型量化、内存分配、IDE 配置复杂	偏 AI 一体板，需要研究模型部署
STM32 + WiFi / 网络后端	STM32 + ESP8266 / 4G 模组	服务器或云端	网络通信、门锁控制	后台可以在线管理、记录通行数据	必须依赖网络，存在隐私合规问题	需要远程后台和通行记录的项目

区分方法很简单：看原理图中除了 STM32 之外，是否还有 OpenMV、K210、摄像头模组、ESP32-CAM 等第二处理器。如果有，那 STM32 主要负责门禁业务逻辑；如果没有，那视觉识别大概率在同一颗芯片内完成。拿到 0465A 这类资料时，先不要管压缩包内的项目名，先把原理图缩放到全局，理解芯片位置和芯片型号，然后再进入源码阅读。

1.3 读源码前先整理一张“功能到引脚”映射表

嵌入式开发最常见的问题不是代码不会写，而是代码和原理图对不上。比如原理图中某个网络标号叫DOOR_LOCK，但在代码里可能叫LOCK_Pin。如果不做一次人工翻译，后面排查时会浪费大量时间。

建议打开原理图后，对每个外设整理一张映射表，格式如下。

功能	原理图网络标号	STM32 引脚	代码宏定义	GPIO 模式	初始电平	所在驱动文件
蜂鸣器	BUZZER	PB5	`BUZZER_Pin`/`GPIO_PIN_5`	推挽输出	低电平	`bsp_buzzer.c`
舵机信号	PWM_SERVO	PA0	TIM2_CH1	复用推挽	低电平	`bsp_servo.c`
OLED SCL	OLED_SCL	PB6	I2C1_SCL	开漏或复用	高电平	`bsp_oled.c`
电磁锁继电器	DRLOCK	PB1	`LOCK_Pin`	推挽输出	低电平释放	`bsp_lock.c`
视觉模块 RX	UART1_TX	PA9	USART1_TX	复用推挽	-	`bsp_uart.c`

这张表不需要一开始填满，但遇到每一个外设都要补。填写完成后，把它作为 README 放回源码目录，比任何现成说明都可靠。代码中的引脚配置、GPIO 模式、复用功能，都会在这张表里暴露矛盾。

2. 环境准备：Keil、芯片 Pack、串口驱动都要和源码对齐

2.1 判断源码用的是标准外设库还是 HAL 库

很多资料在网盘或压缩包内会出现两种风格完全不同的代码：一种是标准外设库，文件里常见GPIO_InitTypeDef、GPIO_ResetBits、GPIO_SetBits；另一种是 HAL 库，文件里常见HAL_GPIO_WritePin、HAL_UART_Transmit、__HAL_TIM_SET_COMPARE。

快速判断方法：在源码目录中搜索是否包含stm32f1xx_hal.h，如果存在，说明是 HAL 库工程；如果看不到*_hal_*文件，而是大量stm32f10x_gpio.c、stm32f10x_tim.c，说明是标准外设库。

这两种风格对应不同的编译环境和底层初始化思路。HAL 工程大多可以直接用 CubeMX 重新生成，标准外设库工程则依赖原作者的模板。使用 0465A 这类开源资料时，最忌讳在拿到资料后立刻用 CubeMX 重新生成自己的工程，再强行把源码里的main.c替换进去。因为不同库的时钟初始化、GPIO 初始化函数名称完全不一样，混在一起会出现几十个编译错误。

2.2 Keil MDK 的芯片包与 Arm 编译器版本要匹配

即使源码版本正确，编译时仍可能遇到启动文件报错、找不到芯片、语法不兼容等问题。建议在打开工程前做一个环境检查。

检查项	推荐做法	检查点
芯片型号	在 Keil 的 Options for Target → Device 中选择原理图对应的型号	常见的是 STM32F103C8 / STM32F103RCT6 / STM32F407ZGT6
芯片 Pack	使用 Pack Installer 安装对应厂商的 DFP 包	能识别芯片型号，编译时不报 algorithm 错误
Arm 编译器版本	旧工程默认 AC5，新 Keil 默认 AC6	编译出现大量 GNU 语法告警时，先切回 AC5 测试
C99 标准	在 C/C++ 选项卡中勾选 C99	代码中出现`for(int i=0;...)`时，没有 C99 会报错
MicroLib	在 Target 选项卡勾选 Use MicroLib	源码中重定向了`printf`到串口时，不勾选可能导致串口无输出