企业官网建设流程全解析

简介：本资源是一份基于STM32的智能桌面宠物嵌入式项目完整开发包，面向嵌入式初学者、课程设计学生及电子类竞赛备赛者，提供从硬件驱动到人机交互的全栈实践范例。项目采用分层架构设计（HAL抽象层 + HDL驱动封装层），集成语音识别、蓝牙通信、OLED表情显示、四自由度舵机运动控制及红外/超声波感知模块，支持语音与手机APP双模交互，具备完整的动作协同逻辑与状态反馈能力。压缩包共126个文件，含23组C/H源码（覆盖OLED_SSD1315、TP4056充电管理、语音合成等驱动）、9个XML配置文件、7个STL机械结构模型、5个Java端APP源码（.aia格式）、3个DOCX设计文档及Keil工程文件（.uvprojx/.hex），总大小13.41MB。已有1729人学习下载，资源附带可直接编译运行的工程框架、模块化驱动封装示例及典型外设（DX2002、SSD1315）适配代码，特别适合理解嵌入式分层开发思想与多模态交互系统集成。 桌面上那只一直盯着我看的小家伙，现在总算是"活"过来了。它不是普通的手办摆件，而是一台完全由我一手搭建的基于STM32的智能桌面宠物。我给它装上了OLED眼睛，能显示各种表情，脖子用舵机驱动，会点头摇头，饿了会叹气，被摸了会开心地摇脑袋。整个项目从零开始设计硬件、写固件、做外观，最后我把它整理成了一个zip工程包，里面除了代码，还有完整的设计文档。这篇文章就把这个项目的设计思路、核心代码逻辑以及我踩过的那些坑，一条一条捋清楚。

这个项目本身不难，但涉及的知识点相当密集：STM32的外设配置、定时器PWM、I2C驱动、ADC采样、串口协议、状态机设计，以及硬件供电、机械结构等方面的问题。如果你手里也有一块STM32开发板，也想做个能摆在桌上互动的"活物"，那这篇内容应该能帮你少走大半个月弯路。我会把我实际验证过的方案、参数、接线方式和源码结构都写出来，尽量做到照着做就能跑通。

1. 先把需求说清楚：桌面宠物不是"会动的玩具"

1.1 功能清单：从表情到交互，哪些能做、哪些先砍掉

做这类项目最大的问题不是"做什么"，而是"什么都想做"。一开始我想让桌面宠物能语音对话、能自动巡游、能通过摄像头识别人脸，结果规划完发现光硬件成本就够买一台升阶版手机了。所以第一步是把需求收敛回"桌面宠物"的本分：它需要让人觉得"有生命感"，而不是"功能全但样样糙"。

我最终确定的功能清单是这样的：

• 表情显示：用一块0.96寸OLED屏幕显示卡通脸，至少要有开心、无聊、饥饿、困倦、生气五种基础表情；
• 动作反馈：至少一个舵机驱动头部，能实现点头、摇头、转头看人这几个基本动作；
• 交互输入：两个实体按键，一个用于"喂食"，一个用于"抚摸"；另外加一个光敏传感器让它能感知环境光变化；
• 声音反馈：一个无源蜂鸣器，不同心情事件播放不同频率的提示音；
• 状态感知：温度湿度传感器，当环境超过舒适范围时它会表现出"不舒服"的表情。

砍掉的部分包括：语音识别（STM32F1系列跑本地识别太吃力，离线方案成本又高）、自动避障移动（需要底盘电机驱动、超声模块，结构复杂度翻倍）、联网查天气（需要额外接ESP8266，功耗和代码量都会增加）。这些被砍的内容我放在了扩展接口里，后续想加可以直接照着接口接。

1.2 主控选型：为什么在Arduino满天飞的时候选STM32

做桌面宠物的主控，市面上主流就是Arduino Uno、ESP32、STM32F103系列这几类。我三种都评估过，最终选了STM32F103C8T6，也就是大家常说的"蓝丸"或者"C8T6核心板"。

Arduino Uno的优势是上手快，写个程序直接烧，各种库一大把。但它的致命问题有两个：第一是ATmega328P的Flash只有32KB，SRAM只有2KB，我光放一套OLED取模表情数据就差不多吃掉10KB空间，后续再塞状态机、传感器滤波、日志，内存完全不够；第二是如果需要跑FreeRTOS这类系统，Arduino Uno的资源基本没有余量。

ESP32确实性能猛，双核240MHz，自带WiFi蓝牙，但它的功耗高、启动逻辑复杂、GPIO耐压也需要注意，而且对这个项目来说完全是杀鸡用牛刀。另外ESP32的ADC线性度一般，用来做光敏采集、电池电压检测这类模拟量测量反而要额外做校准，折腾。

STM32F103C8T6恰好卡在中间：72MHz主频，64KB Flash，20KB SRAM，片上有3个USART、2个I2C、2个SPI、3个16位定时器、1个12位ADC。性能完全够用，外设资源对这个小项目来说甚至有点富余。最关键的是它的生态太成熟了，网上资料一抓一大把，HAL库配合STM32CubeMX初始化工程，开发效率比直接裸写寄存器高太多了。成本方面，C8T6核心板十几块钱就能拿下，加上周边器件全套下来不到一百块。

1.3 系统数据流：传感器、计算、输出三层的划分

整个系统的逻辑其实可以简化为一个闭环：输入层负责采集外界信息，包括按键信号、光敏电阻的电压、温湿度传感器的数据；计算层是核心的STM32，它运行一个周期性刷新的状态机，根据输入层的数据不断更新宠物的心情和动作决策；输出层把计算结果转化为用户可感知的信号，包括OLED显示的卡通表情、舵机驱动的头部动作、蜂鸣器发出的声音、以及状态指示灯的亮灭。

我当时画了一张简单的数据流图（配合文档里会有），重点不在图，而在信息的转化关系。比如环境光变暗，光敏电阻的ADC值升高，状态机判定"现在是夜晚"，于是宠物的困倦值缓慢上升，等到困倦值超过阈值，表情切换成睡觉状态，同时舵机做一个缓缓低头的动作。再比如按键按下，不是立刻切换表情，而是先把这事件放进一个"交互事件队列"，状态机在下一次刷新时消费这个事件，从而改变宠物的饥饿值或亲密度。这样做的好处是，代码里没有散落各处的if判断，所有行为都由状态机统一调度，后续加功能只需要扩展状态和迁移条件，不用改动主循环结构。

2. 硬件方案落地：从引脚规划到供电，每一路都有来由

2.1 物料清单：全项目花不到100块

硬件选型这块，我走的完全是"能买到、便宜、够用"的路线。下面是完整物料清单，参考单价差不多也就是市场正常价：

总价在70到90元之间，不含工具。我实际用的是3D打印外壳，但文章后面会给一个完全不用3D打印的替代方案。

2.2 引脚分配：为什么I2C给OLED、TIM2给舵机、ADC给光敏

引脚分配是硬件设计里最重要的一步，分配错了后面改起来特别痛苦。我最终用的引脚分配方案如下：

这里有几个容易被新手忽略的点。第一，OLED用I2C而不是SPI，原因很简单，I2C只占两根线，在这个项目里SPI的带宽优势完全用不上，I2C 400kHz的速率刷新128x64的OLED表情足够流畅。第二，舵机必须用定时器的PWM硬件输出，不能用GPIO翻转模拟，因为GPIO模拟PWM会在切换其他任务时产生抖动，舵机对这种抖动极其敏感，会嗡嗡响甚至乱转。第三，ADC光线采集我用的是ADC1的IN1通道，注意ADC1_IN1对应的引脚就是PA1，不要拿去量别的脚，这是F103片上固定的。

2.3 供电设计：舵机的"暴力"启动电流怎么镇住

供电是整个项目里最容易出问题的环节，我调试初期超过一半的玄学故障都跟供电有关。

SG90舵机的官方标称工作电压是4.8V到6V，静止时电流大概只有10mA左右，但启动瞬间的堵转电流能冲到500mA甚至更高。而STM32核心板上的AMS1117-3.3稳压芯片标称最大输出电流是1A，但真实情况是，如果舵机直接从同一个3.3V电源轨取电，瞬间掉电会让单片机复位或者OLED花屏，表现就是舵机一转，整机重启。

我最开始的方案是：USB 5V进来，先接到核心板的5V引脚，同时分一路给舵机。这样的接法会带来噪声串扰，后来改成了更稳妥的方式：

• USB 5V/2A电源先经过一个100uF电解电容和10uF陶瓷电容滤波，作为5V主电源轨；
• 舵机的红色电源线直接从5V主电源轨取电，舵机的地线单独走一根粗线回到电源地，不经过核心板的地；
• 主控和其他3.3V器件通过核心板上的AMS1117降压获得3.3V，核心板自己的5V输入也来自5V主电源轨；
• 在舵机电源引脚旁边并联一个470uF电解电容和100nF陶瓷电容，用来吸收启动瞬间的大电流波动。

为什么一定要这样？市面上的核心板上面的AMS1117输入输出压差如果超过1V，热损耗就会明显上升，如果让舵机的大电流也走3.3V，AMS1117不但可能过热进入保护，还会因为瞬间电流导致输出电压下降，单片机就处于"如果允许，它会立刻死机"的边缘状态。分开供电之后，舵机再怎么折腾，只要5V源头撑得住，3.3V轨就是稳定的。

如果你的供电方案是用两节18650电池，建议用一节电池只给舵机供电、另一节负责逻辑电路的方式，或者用一个5V/3A的DC-DC降压模块，直接把电池电压降到5V统一供，不要在电池和逻辑之间省一个隔离级。

2.4 外观结构：没有3D打印机也能做的方案

外壳部分是最容易被过度设计的环节。我见过有人为了桌面宠物专门建模打印一个几十块钱的高精度外壳，结果发现尺寸卡得太死，后面电池都塞不进去，又重做一遍。我的建议是：结构件先简单，功能跑通后再迭代外观。

我有两台方案可供参考：

方案一，完全不用3D打印机：找一个尺寸合适的亚克力小盒子或者硬质纸盒，在正面挖一个方孔放OLED，让OLED的显示面正好卡进孔里；盒子顶部开一个小孔，让舵机转轴穿出来，舵机臂上粘一个小圆片做"头"，表情屏和头部分离设计，这样点头时OLED不动、头上的装饰动，反而更有"宠物在朝人点头"的感觉。用热熔胶固定所有器件，重点是给舵机留出至少1厘米的活动空间，不然转起来会被盒子内壁卡住。

方案二，3D打印：在文件包里我放了一个简单的STL结构设计，包含底座、头壳、舵机支架三件套。设计时注意给螺钉预留沉孔，给舵机线材留走线槽。如果打印耗材是PLA，建议壁厚不小于2mm，否则拧螺丝时容易直接开裂。

还有一个我用下来很舒服的细节：OLED屏和人的视线最好保持一个大约15度的仰角，别让屏幕完全朝上或朝前。桌面上人的视线是从上方斜着看下来的，OLED可视角度又不大，完全朝前的话看表情会偏暗，稍微仰一点正好显示清晰。

3. 软件设计核心：状态机、时间片和显示引擎

3.1 CubeMX初始化：时钟树和外设配置

软件我全程用的是STM32CubeMX生成底层初始化代码，再在生成的工程里写业务逻辑，开发环境是Keil MDK。之所以用CubeMX而不是纯手写寄存器，是因为这个项目的重点在逻辑和系统集成，没必要把时间浪费在核对寄存器位定义上。

CubeMX里我做了这些关键配置：

• RCC：HSE外部晶振开启，时钟树配置成最高72MHz（PLL倍频9倍）；
• SYS：Debug选Serial Wire（SWD），调试口只用SWDIO和SWCLK，给后面复用PA15、PB3、PB4留出空间；
• I2C1：标准模式400kHz，7位地址，用于OLED；
• I2C2：标准模式400kHz，用于AHT20温湿度传感器；
• TIM2：Channel1配置为PWM Generation CH1，Prescaler为71，Counter Period为19999，这样72MHz/72=1MHz，1MHz/20000=50Hz，正好是舵机的标准PWM周期；
• TIM1：Channel1配置为PWM Generation CH1，用于蜂鸣器音调控制；
• ADC1：开启1个通道并用DMA循环采样，注意选择Scan模式关闭、Continuous开启，DMA设为Circular，这样MCU不用干预，ADC会自动把连续采样的结果通过DMA搬进内存，CPU只需要读数组。

生成代码之后，一定先烧一个默认程序测试板子能跑、LED能闪，再开始写业务逻辑。不要在还没有烧录验证的板上直接开始写几百行代码，出了错很难定位是硬件问题还是软件问题。

3.2 心情系统：一组状态变量怎么演化出"活生生"的宠物

桌面宠物的核心体验是"它有自己的状态"。所以我设计了一套简单的"心情系统"，用三个基础量化指标驱动所有行为：

• hunger（饥饿值）：范围0到100，随时间线性增加，喂食按键按下后归零；
• energy（精力值）：范围0到100，随时间线性减少，当环境光很暗时减少速度加快（相当于进入夜间疲劳模式），抚摸按键按下时会小幅回升；
• affection（亲密度）：范围0到100，每次抚摸增加10点，长时间不互动会缓慢下降。

最终的心情状态就是这三个指标的加权映射，我把它们映射成四个基础表情状态：

状态迁移图在文档里有画，但代码实现其实很简单，核心就是一个mood_update()函数，每秒钟执行一次：

void mood_update(void) { if (g_pet.hunger < 60 && g_pet.energy > 40) { g_pet.mood = MOOD_HAPPY; } else if (g_pet.hunger >= 60) { g_pet.mood = MOOD_HUNGRY; } else if (g_pet.energy <= 30) { g_pet.mood = MOOD_SLEEPY; } else if (g_pet.affection < 20 && g_pet.hunger > 80) { g_pet.mood = MOOD_ANGRY; } // 同一表情不会重复触发动作，只在状态切换时执行对应动作序列 if (g_pet.mood != g_pet.last_mood) { emotion_action(g_pet.mood); g_pet.last_mood = g_pet.mood; } }

状态切换才触发动作，这个逻辑很关键。如果不加这个判断，状态机会在每次刷新时反复执行点头动作，看起来就像一只在抽风的宠物。

3.3 时间片轮询：别让裸机程序变成一团乱麻

有些初学者会把所有业务逻辑都写进一个while(1)，用HAL_Delay一路延时下去。这样写的问题很明显：延时期间程序卡死，按按键没反应，OLED刷新被其他任务阻塞。这块通过简单的轮询调度就能解决。

我在main函数里开了一个1ms系统tick（CubeMX默认用SysTick实现），然后用时间片轮询的方式安排任务：

while (1) { uint32_t now = HAL_GetTick(); if (now - last_tick_key >= 5) { key_scan(); // 按键扫描，5ms一次 last_tick_key = now; } if (now - last_tick_sensor >= 100) { sensor_read(); // 光敏、温湿度读取，100ms一次 last_tick_sensor = now; } if (now - last_tick_display >= 300) { display_update(); // OLED刷新，300ms一次 last_tick_display = now; } if (now - last_tick_mood >= 1000) { mood_update(); // 心情更新，1s一次 last_tick_mood = now; } }

为什么按键要5ms扫一次？因为机械按键按下时会有约5到15ms的抖动，频率太低会漏掉快速点按，频率太高反而需要在代码里额外加去抖逻辑。而OLED300ms刷新一次，看起来还能接受低频动画，但对这个项目来说表情切换本来就不需要高帧率，300ms一帧很自然。

如果后续要跑多任务，比如让舵机运动、OLED动画、串口收包同时进行，这个时间片轮询就不太够用了，可以考虑上FreeRTOS。但至少在这个项目规模下，裸机时间片轮询完全够用，而且更好调试。

3.4 OLED表情引擎：从取模到局部刷新

OLED驱动是SSD1306，我用的0.96寸是128x64像素，I2C接口。SSD1306内部有一块1KB的GRAM，上电后要发初始化序列才能点亮，包括设置显示时钟分频、多路复用比、显示偏移、启动电荷泵、设置内存地址模式等。网上现成的初始化驱动一大把，顺手还能封装成oled_init()和oled_clear()。

但要让屏幕显示一张"可爱脸"，还得解决取模问题。我用的方法是：先用画图软件把表情图片做成128x64的BMP，然后用PCtoLCD2002取模软件生成C语言数组，取模方式选"纵向取模，字节倒序"。为什么选纵向取模？因为SSD1306的GRAM组织方式就是按页（8行一页）纵向排列的，纵向取模后数据可以直接按顺序刷进GRAM，不需要做行列重排。

刷屏策略很关键。我最初直接每次把整屏1024字节通过I2C刷新，结果表情切换时屏幕明显闪烁、残影重。后面改成了"framebuffer + 局部刷新"方案：

• 在RAM里维护一个128字节的显存数组（注意这里不是整个framebuffer，是当前页的显示内容），128x64总共8页，所以数组是8行，每行128字节；
• 每次要显示新表情时，先把新数据写入这个显存数组；
• 然后比较显存数组和当前GRAM上已有的数据，只有发生变化的页面才发送I2C写命令去刷新，注意页面地址需要挨个设置。

这样做的结果就是，表情切换只需要重刷变化的几行，大部分情况下只有中间面部区域那几页会变化，刷新速度快了一个数量级，画面也不会闪了。

3.5 舵机运动控制：用平滑曲线替代生硬跳变

舵机控制看起来简单：给PWM波，舵机就能转到指定角度。但直接用__HAL_TIM_SET_COMPARE(&htim2, TIM_CHANNEL_1, value)跳变式地让它从0度瞬间转到90度，动物玩具就会像机器人断电一样"咔"一下弹过去，毫无生命感。

我封装了一个smooth_move()函数，核心是插值：

void smooth_move(uint16_t target_pwm, uint16_t step_ms) { uint16_t current_pwm = __HAL_TIM_GET_COMPARE(&htim2, TIM_CHANNEL_1); if (target_pwm > current_pwm) { for (uint16_t pwm = current_pwm; pwm <= target_pwm; pwm += 5) { __HAL_TIM_SET_COMPARE(&htim2, TIM_CHANNEL_1, pwm); HAL_Delay(step_ms); } } else if (target_pwm < current_pwm) { // 同理向下插值 } }

这里有两个参数需要仔细调：步长和延时。步长太大会跳变，步长太小动作慢得像蜗牛。我实测SG90在PWM周期20000、脉宽范围500到2500的情况下，步长取5，延时取20ms，转动60度大约需要800ms，看起来比较接近自然的头部转动速度。点头会更快一点，步长取10，延时15ms。

要注意的是，HAL_Delay在中断里不能随便用，这个问题我下一章专门讲。

动作序列我预置了几组：点头（低头-抬头-低头-抬头）、摇头（左-右-左-右）、困倦（缓慢低头并保持）、开心（小幅快速点头两次）。每个动作序列就是一个函数，内部调用smooth_move()，这样状态机里的emotion_action()只需要根据当前心情调用对应动作函数就行。

另外舵机还有一个"复位"问题。SG90没有反馈，断电后再上电会停留在当前角度而不是自动回中。所以开机时我做了一次初始化动作：先把舵机慢慢转到0度位置，再转回90度初始位，这样用户一上电就能看到宠物"动了一下"，同时也能确认舵机工作正常。

4. 调试实录：五个让我抓狂又不得不服的坑

4.1 上电黑屏：I2C地址0x3C还是0x3D？

我的OLED第一次上电黑屏，检查接线没问题、供电正常，最后用逻辑分析仪抓I2C波形才发现，SCL上一直没数据。问题出在哪？我搜资料时发现，不同商家出的SSD1306模块，I2C地址可能不一样，常见的是0x3C，但也有0x3D的。我代码里写死的是0x3C，结果买到的一个模块实际地址是0x3D，I2C通信自然完全没反应。

排查方法：在代码里先写一个I2C扫描函数，把所有可能的地址都探测一遍，看看哪个地址有ACK。这个函数调试I2C外设时极其有用，建议直接加到项目里留着备用：

void i2c_scan(void) { for (uint8_t addr = 0x01; addr < 0x7F; addr++) { HAL_StatusTypeDef status = HAL_I2C_IsDeviceReady(&hi2c1, addr << 1, 2, 10); if (status == HAL_OK) { printf("Found I2C device at 0x%02X\r\n", (unsigned int)addr); } } }

顺带提醒，0.96寸OLED还有个常见问题是I2C上拉电阻。有些模块板上已经焊了4.7k上拉电阻到3.3V，如果你的模块没有上拉，就一定要在SCL和SDA上各加一个4.7k到10k的电阻上拉到3.3V，否则总线信号边沿太缓，通讯不稳定。

4.2 舵机乱抖：PWM频率和脉宽的"标准答案"只有一套

舵机第一次上电时疯狂乱抖，还发出尖锐的嗡嗡声。我一开始以为是供电不足，加了电容也没完全解决。后来用示波器看PWM波形，发现频率根本不对。

原因是我在CubeMX里把TIM2的时钟分频搞错了。STM32F103的APB1定时器时钟最高是72MHz，但只有TIM2、TIM3、TIM4挂在APB1时如果APB1分频系数为2，定时器时钟会自动倍频到72MHz。我之前的Prescaler和Period算出来对应的是36MHz时的结果，算出来频率是25Hz，而SG90舵机要求的PWM频率是50Hz（周期20ms），两者差了整整一倍。

正确的计算过程是：72MHz / 72分频 = 1MHz，然后1MHz / 20000 = 50Hz，所以Prescaler=71，Period=19999。最后用HAL_TIM_PWM_Start(&htim2, TIM_CHANNEL_1)启动后，PWM确实输出50Hz。对照上位机看，舵机立刻安静了。

顺带说一句，不同品牌舵机的脉宽范围有差异，SG90一般是0.5ms到2.4ms，对应PWM比较值为500到2400。如果你的舵机买回来发现0度位置偏了，可以在软件里做一次校准，实测出左右极限PWM值，不要直接套用别人的参数。

4.3 JTAG引脚复用：PB3/PB4为什么点不亮

这个问题是我的一个老同事都容易踩的坑。我要把PA15（JTDI）当作普通GPIO用，把PB3（JTDO）、PB4（JNTRST）拿来做按键，结果发现无论怎么操作，这几个引脚的电平都不受控制。

原因在于STM32F103复位后的默认状态是JTAG功能使能，PA13、PA14、PA15、PB3、PB4被JTAG/SWD调试接口占用。如果你只用了SWD调试，其实只需要PA13和PA14两根线，PA15、PB3、PB4完全可以释放出来。

解决方法是调用SDK里的引脚重映射函数，关闭JTAG但保留SWD：

__HAL_AFIO_REMAP_SWJ_NOJTAG();

注意这条语句要在GPIO初始化之前调用，而且前提是在CubeMX的SYS配置里把Debug选成Serial Wire。否则即使调用了函数，引脚配置也会被后续初始化覆盖。

4.4 HAL_Delay卡死：中断嵌套优先级背后的雷

这里有个非常迷惑的故障：我在串口接收中断回调函数里调用了HAL_Delay(50)，程序一旦收到串口数据就卡死，按复位键也没用，只能断电重启。

排查了很久才发现问题出在HAL_Delay的实现上。HAL_Delay依赖SysTick中断来维护uwTick全局变量，而SysTick中断的默认优先级是在HAL_InitTick里面设置的。如果当前正处于某个串口中断处理中，而这个串口中断的优先级高于SysTick中断，那么SysTick中断永远无法进入，uwTick就不再递增，HAL_Delay里的while循环一直等不到时间到，程序就死锁在中断里了。

这个问题的彻底规避办法是：中断回调函数里尽量不调用HAL_Delay。需要延时的场景，改用非阻塞式状态机或者DWT时钟周期计数器。DWT是Cortex-M3内核的调试单元，里面有一个CYCCNT寄存器，每时钟周期加1，用它实现微秒级延时不需要依赖SysTick：

uint32_t DWT_Delay_Init(void) { CoreDebug->DEMCR |= CoreDebug_DEMCR_TRCENA_Msk; DWT->CYCCNT = 0; DWT->CTRL |= DWT_CTRL_CYCCNTENA_Msk; return 1; } void DWT_Delay_us(uint32_t us) { uint32_t start = DWT->CYCCNT; uint32_t ticks = us * 72; // 72MHz主频 while ((DWT->CYCCNT - start) < ticks); }

实测下来，DWT延时非常精准，而且不占用额外定时器，推荐在中断里或者对时序要求高的地方使用。

4.5 串口切菜式丢包：不定长数据的完整收包方案

这个坑是当我准备给桌面宠物接ESP8266做联网扩展时踩的。ESP8266模块用AT指令通过串口和STM32通信，AT指令是变长数据，比如+IPD,12:hello,world，每次接收的字节数不固定。我最初用逐字节接收：每收到一个字节进一次中断，把字节存到缓冲区，然后自己判断什么时候算"一帧结束"。

结果在高波特率下频繁丢包。因为每收一个字节都要进一次中断，如果主循环正在做OLED刷新这种耗时操作，中断被阻塞，硬件接收寄存器里的数据就被下一个新到的字节覆盖了。

后来我改成HAL_UART_Receive_DMA + 空IDLE中断的方案。核心思路是：启用DMA让数据自动搬运到环形缓冲区，不占用CPU，然后用USART的空闲中断（IDLE）来标志一帧数据结束：

static uint8_t rx_buffer[256]; void HAL_UARTEx_RxEventCallback(UART_HandleTypeDef *huart, uint16_t Size) { if (huart == &huart1) { // Size就是本次接收到的字节数，直接从rx_buffer取用 process_at_command(rx_buffer, Size); HAL_UARTEx_ReceiveToIdle_DMA(&huart1, rx_buffer, sizeof(rx_buffer)); } }

这个方案的优势是：DMA在后台收数据，一个字节都不会丢，只有当串口空闲下来（比如收到一个完整的AT指令）才触发一次回调，把这么一段数据交给上层处理。而且CubeMX生成的HAL库代码里已经预留了HAL_UARTEx_RxEventCallback这个回调函数，直接在用户代码里实现即可。

实际测试下来，115200波特率下，连续发几百条AT指令都稳定不丢包。这个接收框架强烈建议移植到自己项目里，以后接任何串口模块（蓝牙、WiFi、GPS）都用得上。

5. 把工程打包好：设计文档的价值不亚于代码

5.1 README和目录：一个陌生工程师拿到zip后的5分钟

项目做到后期我把所有文件整理成了一个zip压缩包，命名就叫"基于STM32的智能桌面宠物设计.zip"。我给自己定的标准是：一个从没见过这个项目的工程师，拿到这个zip后，5分钟内应该能搞清楚这是什么、怎么接线、怎么烧录、改哪个文件。

所以我在zip根目录放了一个README.md，内容包含：

• 项目简介和功能演示GIF（或者B站视频链接）；
• 完整接线表（哪个引脚接哪个外设，必须精确到引脚号）;
• 开发环境说明：Keil MDK版本（我用的5.36）、STM32CubeMX版本、HAL库版本（F1系列1.8.x）;
• 如何打开工程、如何编译、如何烧录（ST-Link连哪几个引脚，以及烧录失败的排查）;
• 三段式目录说明：/Doc放设计文档、/Hardware放原理图和PCB、/Firmware放KEIL工程、/Structure放3D打印文件。

很多老手会把所有精力放在代码上，文档最后草草写一段。但我可以负责任地说，半年后你自己回头写一篇博客介绍这个项目时，这份文档能救你的命。我现在复盘上个月写的代码，如果没有文档和注释，光看工程文件名根本想不起某些设计意图。

5.2 设计文档的四个核心模块

设计文档我拆成了四个模块：

硬件设计文档：包含原理图PDF（不是工程源文件，是导出的PDF，方便任何人不用装EDA软件也能看）、PCB布线图截图、BOM清单。BOM清单要标注器件位号、封装、参考价格、购买链接。这一部分的价值在于，别人想复刻时不用对着电路图一个个自己画封装，直接照着买器件、焊接就行。

软件设计文档：包含源码目录结构说明、每个模块的功能描述、关键函数的调用关系、以及状态机的迁移条件说明。我在里面画了状态机文字版，不用工具画图，直接用文本描述每种状态、每个事件、迁移后的新状态，这样放在任何平台都不会丢格式。

结构设计文档：包含STL和STEP两种格式的3D模型文件，STEP文件是为了方便别人用SolidWorks或Fusion360继续修改。同时有装配说明，比如舵机臂和头壳是怎么固定的、OLED屏嵌在哪个位置。

调试与测试报告：记录了我遇到的所有异常现象、原因分析、解决方法和最终验证结果。这一部分看起来可加可不加，但实际价值极高。比如"舵机抖动：原因是TIM2时钟配置错误"这个记录，别人在做类似项目时如果遇到同样问题，直接就能定位，不用从头再查一遍。

5.3 可复现性自查清单

在最终发布zip前，我按这个清单逐项自查过：

• 所有文件是否在压缩包内？尤其别把CubeMX生成的.ioc配置漏掉，别人打开工程才能看到完整的外设配置；
• 接线图是否与代码中的引脚定义完全一致？如果只改了代码没改文档，或者反过来，都会让人抓狂；
• 源码是否能在干净的Keil工程下直接编译通过？建议删掉编译中间产物（OBJ、List等）再压缩，减小体积也避免别人打开工程时出现路径冲突；
• 是否提供了烧录说明？如果别人手头用的是J-Link而非ST-Link，也需要说明如何切换调试器型号；
• 已知问题是否写清楚？比如我用的OLED屏在低温环境下刷新会变慢，这种问题不写出来，别人排查时会怀疑是自己焊接有问题。

对照这份清单走一遍之后，这份zip才算真正达到了"可复现"的标准。

最后再分享一个小经验：做嵌入式小项目，别急着追求高大上的方案，先把一个最朴素的版本跑通。我最初用的是一块带OLED的手环废壳，把屏幕直接贴在纸盒子外面，程序也写得乱七八糟，但那个版本里的状态机和表情数据模型，一直完整保留到了最终版里。功能可以迭代，设计骨架从一开始就要打好，这才是这个zip里最值钱的部分。

本文还有配套的精品资源，点击获取