STM32打地鼠掌机拆解：从原理图到驱动的完整复刻指南

简介基于STM32设计的打地鼠掌机项目包整合了完整的软硬件开发资料面向单片机初学者、毕业设计学生以及嵌入式竞赛参与者。项目实现了打地鼠游戏逻辑配合OLED屏幕实时显示与蜂鸣器背景音乐涉及STM32F10x系列的外设驱动、定时器中断、ADC采集、I2C通信等多个核心知识点既可整体复刻也可作为二次开发的功能底板。包内共103个文件以42个.h头文件与36个.c源程序文件为核心辅以工程配置文件、hex烧录文件、原理图与PCB设计文档及元器件库文件压缩包整体仅4.61MB目录结构清晰方便按模块查阅与移植。目前已有227人学习/下载适用于课程设计、工程实训、期末大作业等场景参考。拿到资料后可快速复现同款掌机源码工程可直接编译下载硬件部分若不会绘制PCB可用面包板加杜邦线连接外设模块替代按引脚定义连线烧录即可运行便于理解完整的嵌入式开发流程并支持在此基础上扩展更多功能。1. 基于STM32的打地鼠掌机资料包里到底有什么值不值得自己复刻做STM32课程设计或毕业设计的人应该都对“题目越简单跑起来越玄学”这句话有体会。打地鼠掌机听起来就是个普通小游戏实际拆开要处理OLED屏显、无源蜂鸣器背景音乐、按键消抖和游戏状态切换任何一个环节接错都会导致整机“半死不活”。这套资料比较难得的一点是把硬件原理图、驱动源码和游戏逻辑打包成了一个完整可运行的STM32工程不是只给你一段孤零零的main函数。它能解决的落地问题很明确你不用自己从头画板、查手册、调I2C时序拿到压缩包后先看原理图再编译固件用ST-Link烧进去就能看到OLED出画面、听到蜂鸣器响适合用来做毕设演示或者当入门复刻项目。适合的读者是正在做STM32方面毕设的学生以及想练I2C、PWM、定时器中断这套基本功的嵌入式新人。2. 把资料拆开看STM32F103C8T6选型与工程结构这类型资源包拿到手我一般先干两件事打开原理图PDF看主控型号和外设引脚再打开工程目录看启动文件和驱动文件是否齐全。主控不出意外是STM32F103C8T6这颗芯片在打地鼠掌机场景里非常典型它兼顾了价格、引脚数量和调试难度适合初学者也适合答辩讲解。2.1 主控为什么是STM32F103C8T6外设资源刚好够用STM32F103C8T6是F1系列里最常见的64脚芯片64KB Flash20KB RAM有3个通用定时器、2个I2C、多个PWM通道。一个打地鼠掌机需要什么需要I2C驱动OLED需要TIM输出PWM驱动蜂鸣器需要若干GPIO读按键还需要一个自由运行定时器做游戏时基。C8T6刚好全部覆盖不用为了省成本去换更小容量的C6也不用花更多钱上F407。对比51单片机最头疼的是没有硬件I2C用GPIO模拟I2C时一旦被定时器中断打断OLED就会花屏。Arduino当然也能做但库封装得太深寄存器看不到答辩时老师问一句“时钟树是怎么从8MHz倍频到72MHz的”答不上来就尴尬了。STM32F103用标准库时这个时钟关系是明摆着的。这套资源如果按标准库组织main函数开头一般长这样int main(void) { SystemInit(); /* 内部把外部8MHz晶振倍频到72MHz必调 */ /* 把用到的外设GPIO时钟一次性打开 */ RCC_APB2PeriphClockCmd(RCC_APB2Periph_GPIOA | RCC_APB2Periph_GPIOB | RCC_APB2Periph_GPIOC, ENABLE); OLED_Init(); BEEP_Init(); KEY_Init(); TIM2_Init(); /* 自由计数器兼作游戏随机源 */ while(1) { Game_Loop(); } }这里有几个参数要注意。SystemInit()是标准库启动代码里的函数它负责设置Flash等待周期、PLL和72MHz主频。如果换到HAL库对应的是HAL_Init()和SystemClock_Config()但底层逻辑一样。RCC_APB2PeriphClockCmd使能的是挂在APB2总线上的GPIO时钟GPIOA、GPIOB、GPIOC都开着方便后面调试时临时挪引脚。为什么把外设时钟尽量都先打开因为STM32外设的坑很大一部分来自“忘了开某个片内外设时钟”。GPIO开了但I2C1的RCC_APB1PeriphClockCmd没调I2C总线就会一直挂TIM3开了但PWM输出引脚没重映射配置蜂鸣器也没有波形。开局把所有时钟一次配置好后面查问题时能少走弯路。2.2 原理图里五块关键电路最小系统、OLED、蜂鸣器、按键、电源硬件资料里最重要的就是原理图。打地鼠掌机的硬件可以拆成五个模块对应关系如下。模块主要器件关键参数在掌机里的作用最小系统STM32F103C8T68MHz晶振20pF电容BOOT0下拉主控运行OLED显示0.96寸OLEDSSD1306I2C地址0x78PB6SCLPB7SDA显示分数、地鼠、游戏状态蜂鸣器无源蜂鸣器S8050三极管TIM3_CH2默认PB5背景音乐和命中音效按键阵列3x3轻触按键内部上拉按下读低电平选择地鼠洞电源AMS1117-3.35V输入并联10uF和0.1uF整个系统供电最小系统这部分最容易看错的是启动配置。STM32F103C8T6的BOOT0要接10k下拉到GNDBOOT1可以任意否则上电会进ISP而不是Flash运行。晶振旁边两个20pF负载电容是标配省略的话系统时钟可能不稳定时好时坏。OLED用的是I2C接口很多0.96寸屏模块地址是固定的7位地址0x3C写地址字节0x78。引脚上PB6走SCLPB7走SDA这是STM32F103的I2C1默认引脚。I2C需要上拉电阻大多数OLED模块上已经自带了底板布线时可以不用外加。蜂鸣器这里一定要看仔细。资料里的蜂鸣器大概率是无源的内部没有振荡源需要外部给一个PWM方波才能发声。驱动电路用的是S8050 NPN三极管基极串1k电阻接到STM32的PB5集电极接蜂鸣器负极蜂鸣器正极接3.3V蜂鸣器两端反向并联1N4148二极管。这个二极管很关键蜂鸣器线圈在PWM关断瞬间会产生反向电动势没有续流二极管的话轻则声音破音重则三极管击穿。按键阵列直接用3x3的独立按键接GPIO不搞矩阵扫描。原理上按键一端接GND另一端接STM32引脚引脚配内部上拉输入平时读到高电平按下变低电平。这样可以省去外部上拉电阻也省掉复杂的行列扫描代码。9个按键对应9个洞游戏里用一个编号表示地鼠在哪个洞。电源部分量不大但我要提醒一句OLED和蜂鸣器同时工作时电流峰值会超过50mA如果整机用PCB上的LDO供电AMS1117-3.3的输入输出各加10uF钽电容否则OLED刷新时屏幕亮度会抖动。2.3 解压后的工程目录标准库、硬件驱动、游戏逻辑分层资源包里的代码怎么组织直接决定你复刻时的心情。我个人的习惯是把这类固件按下面这种结构整理。WhackMole/ ├─ User/ │ ├─ main.c │ └─ stm32f10x_it.c ├─ Hardware/ │ ├─ oled.c / oled.h │ ├─ beep.c / beep.h │ ├─ key.c / key.h │ └─ game.c / game.h ├─ Library/ │ ├─ stm32f10x_gpio.c │ ├─ stm32f10x_i2c.c │ └─ stm32f10x_tim.c ├─ Core/ │ ├─ startup_stm32f10x_md.s │ └─ delay.c └─ Doc/ ├─ 原理图.pdf └─ 硬件设计说明.pdfHardware目录放的是芯片外围驱动oled.c只管显存和显示命令beep.c只管PWM频率key.c管扫键和消抖game.c管游戏状态。这是我最推荐的分层方式驱动不依赖游戏逻辑游戏逻辑不直接操作寄存器。Core目录里有startup_stm32f10x_md.s这个启动文件是编译时最容易踩坑的。STM32F103C8T6属于中容量产品启动文件必须选md后缀的。如果你把其他工程的hd后缀启动文件拷进来编译不一定报错但下载后进不了main函数因为堆栈地址和中断向量表对不上。这个坑我在好几个STM32资源包里都碰到过。Doc目录里的原理图和说明文档用于焊接和排查。拿到资源后先把工程用Keil5打开在Project - Options for Target - Device里确认芯片型号是STM32F103C8T6然后安装F1系列芯片包。这一步不做后面下载时会直接报“Flash Download failed”。3. 三个直接能抄的驱动模块OLED驱动、游戏状态机、蜂鸣器音乐资源包的核心价值在驱动源码。我按复刻顺序整理了三个模块OLED屏显、打地鼠逻辑、蜂鸣器音乐。它们互相独立又都集中在游戏主循环里交汇是最值得抄作业的部分。3.1 OLED屏显SSD1306的I2C配置命令序列与坐标计算OLED显示模块用的是SSD1306控制器I2C接口。STM32的I2C1默认引脚是PB6/PB7配置成复用开漏因为开漏配合上拉电阻才能正确输出高电平。void I2C_GPIO_Config(void) { GPIO_InitTypeDef GPIO_InitStructure; /* 开GPIOB和I2C1时钟 */ RCC_APB2PeriphClockCmd(RCC_APB2Periph_GPIOB, ENABLE); RCC_APB1PeriphClockCmd(RCC_APB1Periph_I2C1, ENABLE); /* PB6SCL, PB7SDA */ GPIO_InitStructure.GPIO_Pin GPIO_Pin_6 | GPIO_Pin_7; GPIO_InitStructure.GPIO_Mode GPIO_Mode_AF_OD; GPIO_InitStructure.GPIO_Speed GPIO_Speed_50MHz; GPIO_Init(GPIOB, GPIO_InitStructure); I2C_InitTypeDef I2C_InitStructure; I2C_InitStructure.I2C_Mode I2C_Mode_I2C; I2C_InitStructure.I2C_ClockSpeed 400000; I2C_InitStructure.I2C_Ack I2C_Ack_Enable; I2C_Init(I2C1, I2C_InitStructure); I2C_Cmd(I2C1, ENABLE); }注意这里的时钟速度是400kHz也就是I2C快速模式。如果OLED模块走线长或者花屏先把它降成100000这是最直接的调试手段。SSD1306初始化不能只发几个命令就完事它有一整套时序尤其是Charge Pump升压泵必须打开否则OLED屏幕根本没电压驱动像素。常见的初始化序列放在下面static void OLED_WriteCmd(uint8_t cmd) { /* I2C控制字节0x00表示后续字节是命令 */ I2C_Start(); I2C_SendByte(0x78); /* OLED写地址 */ I2C_SendByte(0x00); I2C_SendByte(cmd); I2C_Stop(); } void OLED_Init(void) { OLED_WriteCmd(0xAE); /* 关闭显示 */ OLED_WriteCmd(0x20); OLED_WriteCmd(0x02); /* Page Addressing Mode */ OLED_WriteCmd(0xC8); /* COM扫描方向上下颠倒校正 */ OLED_WriteCmd(0x40); /* 起始行0 */ OLED_WriteCmd(0x8D); OLED_WriteCmd(0x14); /* Charge Pump开启关键 */ OLED_WriteCmd(0xAF); /* 打开显示 */ }0x8D后面的0x14是一个容易被忽略的参数。很多廉价OLED模块必须靠内部Charge Pump产生负压如果省掉这个命令屏幕会完全没有字符。0x20和0x02选择Page模式这样后续写字符时可以直接按页操作不强制每列刷新地址。显示坐标有个经典误区128x64的OLEDY方向不是64个像素点直接编址而是分成8页每页8像素。你写第一行字符时其实写的是第0页。判断字库取模时会看到“纵向取模从高到低”这类选项对应到驱动里就是从页首开始逐行显示。资源包里的oled.c一般已经封装好了OLED_ShowString如果你要改成中文取模工具里务必选“阴码、列行式、C51格式”不然显示出来的汉字全是镜像或者乱码。3.2 打地鼠游戏逻辑随机位置、按键命中与分数刷新打地鼠的玩法很简单9个洞地鼠随机出现在其中一个玩家按下对应按键就算打中。难点在于随机地鼠位置不能有明显规律按键判定不能抖动地鼠出现的节拍还要跟OLED刷新配合。先处理随机源。很多新手喜欢用rand()配合srand(time())但在STM32裸机里没有time函数rand()每次复位产生的序列几乎一样再加上固定的系统上电延迟你会看到地鼠永远在同一个洞附近出现。我一般用一个一直在跑的自由计数器TIM2读它的低几位当随机数/* TIM2初始化为自由计数器不产生中断 */ void TIM2_Init(void) { RCC_APB1PeriphClockCmd(RCC_APB1Periph_TIM2, ENABLE); TIM2-PSC 7200 - 1; /* 计数频率10kHz */ TIM2-ARR 0xFFFF; TIM_Cmd(TIM2, ENABLE); } static uint8_t Mole_Random(void) { return (uint8_t)(TIM2-CNT 0x07); /* 取低三位得0~7 */ }这里PSC设置成7199也就是7200分频系统72MHz除以7200得到10kHz的计数时钟。地鼠位置取模时用% 9但取低三位只能得到0到7所以我一般会用TIM2-CNT % 9让分布更均匀。代码块里为了演示简洁用了 0x07实际工程里建议改成取模。游戏状态机的核心在main循环里处理不放在中断中。一个典型的10ms时基中断负责数时间游戏主循环负责判定static uint8_t molePos; /* 当前地鼠所在洞0~80xFF表示无 */ static uint8_t moleTimer; /* 地鼠剩余停留时间单位10ms */ void Game_Tick10ms(void) { if (moleTimer 0) { moleTimer--; if (moleTimer 0) { molePos 0xFF; /* 地鼠消失 */ } } } void Game_Loop(void) { uint8_t key Key_Scan(); if (key molePos) { score; moleTimer 40; /* 打中后下一只地鼠在400ms后出现 */ OLED_ShowNum(score); BEEP_PlayTone(880, 100); molePos 0xFF; /* 本只地鼠被打没 */ } }Game_Tick10ms由定时器中断周期调用责任很单一维护计时状态。Game_Loop则是真正的业务逻辑检测按键并更新分数。这里有个容易搞混的点按键检测不能放在定时器中断里长时间消抖中断里只做置位读键放在主循环里做状态机。按键消抖我建议这样写10ms扫描一次连续两次读到同一个有效键值才确认按下。为什么不用delay(20)消抖因为打地鼠游戏里主循环要做的事很多阻塞延时会导致地鼠消失、OLED刷新、音乐播放的节拍全部乱套。按键状态机留一个变量记录上一次键值比延时可靠得多。3.3 蜂鸣器背景音乐音符频率表、PWM占空比和节拍队列无源蜂鸣器需要PWM方波驱动音高由频率决定。STM32F103C8T6的TIM3_CH2默认映射在PB5正好不跟I2C冲突。频率表可以这样建/* 中音C到高音C单位Hz */ static const uint16_t freqTable[] { 262, 294, 330, 349, 392, 440, 494, 523 };驱动无源蜂鸣器的关键参数是定时器重载值。如果TIM3的预分频PSC71那么计数时钟是72MHz/721MHz一个完整方波的周期为2倍重载值即ARR1000000/(2*freq)-1。void BEEP_PlayTone(uint16_t freq, uint16_t duration_ms) { uint16_t arr; if (freq 0) { TIM_Cmd(TIM3, DISABLE); return; } arr (uint16_t)(1000000UL / (2UL * freq) - 1); TIM3-ARR arr; TIM3-CCR2 arr / 2; /* 50%占空比 */ TIM_Cmd(TIM3, ENABLE); delay_ms(duration_ms); TIM_Cmd(TIM3, DISABLE); }这里TIM3-CCR2设成arr/2占空比就是50%。无源蜂鸣器发声靠电流变化50%占空比方波音色最干净。有些资料里会写“低电平驱动蜂鸣器”那是有源蜂鸣器的接法无源蜂鸣器电流方向变化才会振动单纯给个直流高电平或低电平是不响的。背景音乐不能像上面这样阻塞播放因为游戏还在跑。我常用的做法是做一个音符序列用10ms中断驱动节拍非阻塞切换static const uint16_t melody[] { 523, 523, 587, 0, 659, 659, 587, 0 }; void BEEP_Tick10ms(void) { static uint8_t noteIdx 0; static uint8_t remainTick 0; if (remainTick 0) { remainTick--; if (remainTick 0) { TIM_Cmd(TIM3, DISABLE); /* 音符播完关闭PWM */ } return; } uint16_t note melody[noteIdx]; if (note ! 0) { uint16_t arr (uint16_t)(1000000UL / (2UL * note) - 1); TIM3-ARR arr; TIM3-CCR2 arr / 2; TIM_Cmd(TIM3, ENABLE); remainTick 20; /* 每个音符播200ms */ } noteIdx; if (noteIdx sizeof(melody) / sizeof(melody[0])) { noteIdx 0; } }melody数组里的0表示休止符不驱动PWM。每个音符默认持续20个tick也就是200ms。这种非阻塞音乐的好处是游戏逻辑丢进来的命中音效不会打断背景音乐的队列只需要在BEEP_Tick10ms里加一个优先级判断命中音效先播播完接着背景音乐。4. 避坑OLED花屏、蜂鸣器无声、按键误判、下载失败我拆这类STM32资料包时发现的共性问题集中在四个点OLED花屏、蜂鸣器不出声、按键误触发、下载器连不上。每一条都有规律可循下面按现象、原因、解决记录。4.1 OLED花屏不显示现象OLED上电后有背光但没有字符或者字符变成了满屏雪花点再或者刷新几次后图像残缺。原因最常见的是I2C时序不稳定。STM32的I2C配置为400kHz但OLED模块排线长、上拉电阻阻值大波形沿变缓SSD1306经常收错命令。第二个常见原因是SSD1306的Charge Pump没有打开屏幕没有像素驱动电压。第三个原因在字模数据上汉字取模方式用错显示结果就会像乱码。解决先把I2C_ClockSpeed降到100kHz这是成本最低的排错手段。如果降速后正常那就是布线或者模块质量问题不需要换芯片稳定为主。然后检查初始化序列里有没有0x8D, 0x14没有这个组合OLED就是一块空屏。取模工具里统一选“阴码、列行式、C51格式”并且在发送数据时逐页刷新不要一次性把一整个汉字数组写到当前列。4.2 蜂鸣器无声或声音刺耳现象代码里调BEEP_PlayTone蜂鸣器就是不响或者响起来像破锣一样音调明显不对。原因第一有源蜂鸣器和无源蜂鸣器搞混了。有源蜂鸣器内部自带振荡器通直流电就会响但只能响一个固定频率无法做背景音乐。你把它接到PWM引脚上声音会很奇怪或者干脆没声。第二三极管驱动电路参数不对基极电阻太大进入不了饱和区蜂鸣器两端电压不够。第三定时器分频和重载值算错导致PWM频率不是音符频率。解决先确认蜂鸣器型号看外观有源蜂鸣器底部有一个黑胶封装的小板高度稍厚引脚旁边标注了正极无源蜂鸣器底部没有振荡电路阻抗约8到16欧姆。再量电压用万用表测蜂鸣器两端PWM开启时应该有方波关断后应该为零。最后用已知频率测试直接把freq设成1000听声音是不是清脆的1kHz如果不准检查PSC是否是71如果PSC是71但频率偏高说明系统时钟被配置成了8MHz而不是72MHz。4.3 按键按下没反应或连跳现象按一次键分数有时加一次有时加三次或者地鼠明明在1号洞按1号键却毫无反应。原因按键没有做去抖处理机械抖动会让一个按下动作在几毫秒内产生多次高低电平跳变。如果在外部中断里直接读电平或者在主循环里直接比较没有消除抖动连跳就不可避免。另一个原因是GPIO上下拉配置错了按键一端接地时引脚必须设内部上拉否则引脚悬空读出随机值。解决用10ms扫描周期连续两次读到相同键值才确认。具体做法是Key_Scan()函数里保存上次键值本次扫描结果和上次一致才返回有效值否则返回无按键。确认按键接地正确后把GPIO配置成GPIO_Mode_IPU即内部上拉输入。打地鼠掌机的按键本身按下去时间大约60到100ms10ms消抖不会漏掉快速操作又足以滤掉抖动。不要用外部中断做按键消抖外部中断配合delay(20)会让系统卡死这是很多STM32新手的血泪教训。4.4 下载失败Keil5报Flash Download failed现象点击下载按钮后Keil输出窗口提示“Error: Flash Download failed - Target DLL has been cancelled”或者“No Target connected”LED灯也不闪。原因最可能的是BOOT0引脚状态不对。BOOT0被拉高时芯片上电启动ISP引导不是Flash运行ST-Link连接容易失败。第二个原因是Keil5的调试器配置和芯片包没有装完整。很多资料包是在别人的电脑上打开的目标芯片包没带在工程里你打开后Device是空的。第三个原因是ST-Link驱动异常USB口换过之后驱动还在但接口识别到了别的设备。解决先检查硬件BOOT0用跳线帽接地BOOT1随意。然后打开Keil的Project - Options for Target - Debug右侧下拉选择ST-Link Debugger再进入Settings确认能识别到ST-Link设备。接着在Utilities或新版本Keil的Flash Download里勾选“Erase Full Chip”和“Reset and Run”。如果还不行把ST-Link拔出重插用STM32 ST-LINK Utility执行一次Full Chip Erase。这个顺序能解决九成下载失败问题。5. 拿到代码先做一次分模块验证再往这三个方向扩展如果你是第一次复刻这个STM32打地鼠掌机不建议直接所有模块一起烧进去跑。我现在的习惯是把它拆成四步验证第一步单独烧只有OLED初始化和显示字符的工程确认屏幕不花、能正常写字第二步加蜂鸣器用固定1kHz和2kHz交替播放确认PWM通道和驱动电路正常第三步加按键把按键值通过串口打印出来逐个按一遍确认没有短路和漏键第四步再合入打地鼠游戏逻辑。这四步每一部都控制在十分钟内出问题时你能立刻知道是硬件还是软件。资源和代码本身跑通之后还值得往三个方向做扩展。第一个是游戏难度递增用一个difficulty变量控制地鼠停留时间从初始的60个tick逐步缩短到25个tick每打中5只地鼠升一级这样演示时更有节奏感。第二个是低功耗改进OLED在游戏空闲时执行0xAE关闭显示STM32进入STOP模式用按键外部中断唤醒适合做成真正的掌机。第三个是换掉蜂鸣器音乐把旋律数组改成配合游戏状态的音效队列比如命中时播短促高音漏按时播低沉长音视听反馈更完整。我自己的一个习惯是拿到任何一个STM32资料包先确认三件事启动文件是不是md、I2C1引脚有没有重映射、delay函数是不是阻塞型再把代码烧进去。这三件事里任何一件和你的板子不匹配都会让看似正常的代码翻车。希望这份拆包笔记帮你在做打地鼠掌机时少走几步弯路。本文还有配套的精品资源点击获取