很多人做STM32的第一个工程都是照着教程把灯点亮然后截图发个朋友圈就结束了。但如果你打算把AI编程真正拉进嵌入式开发流程里第一个工程的意义完全不一样——它不是一个Hello World仪式而是你为后面所有AI协作定下规矩的那次奠基。工程目录怎么摆、库用哪一版、命名习惯是什么、约束条件写在哪里这些东西一旦定型后面AI每次给你补代码都要吃这套上下文。定得好AI给你的代码一次能跑定得烂你会在编译报错—粘贴错误—再报错的循环里耗掉一整晚。这篇就把我搭这个工程时的完整思路、每一步的取舍理由以及事后复盘出来的坑全部摊开讲一遍。1. 第一个STM32工程真正要立的规矩不是点灯而是可被AI接管的工程骨架1.1 为什么第一个工程值得被单独拎出来对待新手常见的做法是打开Keil5新建工程勾几个库文件写个main烧进去灯亮了收工。这个过程本身没错问题在于它没有留下任何结构。等你到第十个工程想加串口、加定时器、加状态机你会发现原来的目录是平的所有代码都堆在main.c里AI读进去也是一头雾水只能瞎猜你的意图。我见过太多人抱怨AI写的STM32代码感觉对但跑不起来绝大多数时候不是AI不行而是你给的工程上下文太脏了。所以我把第一个工程的目标重新定义了它不是一次点灯演示而是一次工程规范的最小实践。最小意味着内容不要多一个GPIO输出就够实践意味着目录分层、命名规则、库版本、编译配置这些都要在这个最小工程里体现出来。之后所有工程都可以直接复制这个骨架AI每次进来都能在同一种结构里工作命中率会高得离谱。1.2 我给这个工程定的三条验收标准光有目标不够得能验证。我给自己定了三条你也可以直接抄能编译、能烧录、现象可复现灯按预期闪烁断电重启行为一致这是底线。目录结构可解释任何一个文件我能一句话说清它为什么在这里。说不清的说明分层是多余的。AI能在不看我注释的情况下猜出主要逻辑这条最狠也最有用。我会把main.c的注释全删掉让AI解释代码在干嘛如果它能说对八成说明命名和结构是自洽的说不对就回去改命名。三条标准里第三条是我从踩坑里悟出来的。早期我写注释写得很勤结果AI反而被我啰嗦的注释带偏因为它把注释当权威而注释和代码一旦有偏差它信任的是文字不是逻辑。后来我把注释砍到只剩必要的约束说明命名做扎实AI的表现立刻稳定了。1.3 这个工程最终长什么样先说结论免得你看到后面迷路。最终成品是一个基于STM32F103C8T6的最小工程用标准外设库Keil5编译一个LED接在PB12避开了默认的JTAG引脚1Hz闪烁闪烁逻辑用SysTick中断实现而不是死循环delay。目录上分成Core、Drivers、App三层AI要改的代码集中在App层Core和Drivers层基本不动。为什么是F103C8T6因为它便宜、资料多、最小系统板满地都是作为第一个工程的载体容错成本最低。为什么用标准库不用HAL这一点后面第3章会展开讲核心原因是第一个工程里我希望每一行代码我都能追到寄存器HAL把太多东西藏起来了对建立直觉不友好。等你对底层有感觉了再切HAL或LL都行。2. 环境搭建里最容易翻车的三件事芯片包、库版本和目录结构2.1 Keil5与STM32芯片包版本不匹配是头号杀手安装Keil MDK这一步本身没什么好说的一路下一步就行真正的坑在芯片包。Keil5装完之后默认不一定带STM32F1的器件支持包Device Family Pack你需要用Pack Installer在线装或者离线导入.pack文件。问题在于很多人装了个比较新的F1包然后从网上抄了一份老工程结果编译时报一堆寄存器宏找不到的错误。我的建议很朴素先确定你要用的库版本再倒推芯片包版本。如果你用标准外设库SPL 3.5.0那就装一个和它年代相近的F1器件包如果你用HAL那就用较新的CubeMX生成的工程配套包。混搭没有绝对的错但对新手来说混搭带来的报错足够劝退。还有一个细节值得强调装了包不等于工程里引用了包。Keil工程新建时如果选择从已有工程复制或者空工程器件型号是要在Options for Target里手动指定的RTE里要不要勾组件也决定了你是走CMSIS组件还是走你手动加的头文件路径。我见过有人纠结为什么我头文件路径加了还是找不到stm32f10x.h最后发现根本没在RTE里选器件。2.2 目录结构为什么必须按AI友好的方式来组织先看一个我早期觉得很整洁、后来被AI骂的目录Project/ main.c stm32f10x.h stm32f10x_gpio.c stm32f10x_rcc.c delay.c led.c ...平铺什么都在根目录。人看还行AI看就是灾难——它无法判断哪个文件是你要改的业务逻辑哪个是厂商库。它经常会去优化厂商库文件给你改出一些莫名其妙的宏定义你还得逐个回滚。我后来改成这样Project/ Core/ startup_stm32f10x_md.s system_stm32f10x.c Drivers/ CMSIS/ STM32F10x_StdPeriph_Driver/ App/ main.c app_led.c app_led.h app_tick.c app_tick.h Doc/ README.md pinmap.md关键不在于分几层而在于边界清晰Drivers层是AI不许动的区域App层是AI的主战场Core层是只读区域。这个规则我会明确写进README里因为AI读工程时README往往是它最先吃进去的文件。把约束写在它第一眼能看到的地方比你在对话里反复强调有效得多。2.3 用命令行工具链做一次交叉验证Keil的图形界面很好用但它有个隐性风险编译通过不代表你的代码没有依赖IDE的隐含配置。我习惯在搭完工程后用arm-none-eabi-gcc加一条Makefile再编一遍。这一步不是必须但价值很大——它逼你把所有宏定义、头文件路径、链接脚本都显式写出来。具体来说我会写一个最小的Makefile把-D STM32F10X_MD -D USE_STDPERIPH_DRIVER这些宏、启动文件、链接脚本都列清楚。如果命令行能编过说明你的工程配置是自洽的AI给你的代码也更可能在其他环境下复用。这一步我第一次做的时候折腾了半天主要是链接脚本的Flash和RAM地址要对着F103C8T6的规格填64K Flash、20K RAM中间还踩了个栈大小设太小的坑程序一进中断就跑飞。提示命令行验证不是要你放弃Keil而是给你一个第二意见。当AI生成的代码在Keil里行为诡异时用命令行编译一次能快速排除是IDE配置问题还是代码问题。3. 手写一版最小工程时钟、启动文件和GPIO的取舍逻辑3.1 新建工程时那几个选项为什么这么选在Keil里新建工程选好器件STM32F103C8后会问你是否复制启动文件。这里我选择复制启动文件到工程目录而不是引用。原因很简单AI无法访问Keil安装目录下的文件它只能看见你工程里的东西。把启动文件放进工程AI才能理解你的中断向量表长什么样才可能帮你正确地添加中断服务函数。启动文件我选的是startup_stm32f10x_md.smd代表medium density对应F103C8的64K Flash规格。这个选择不是随意的F103系列有ld、md、hd、xl几种选错了中断向量表偏移就不对第一个中断触发时直接HardFault。我第一次搭工程时就踩过这个坑用的是别人工程里的hd启动文件结果SysTick一中断就死查了两小时才发现是密度等级不匹配。至于USE_STDPERIPH_DRIVER这个宏它是标准库的开关不定义的话你include了头文件也调不到库函数。这个宏写在Options → C/C → Define里同时记得把STM32F10X_MD也写进去两个缺一不可。3.2 system文件做了什么为什么值得花十分钟看懂system_stm32f10x.c这个文件经常被无视但它决定了你芯片的时钟树。F103上电默认走内部8MHz RCHSI经过PLL倍频后可以跑到72MHz。库里的SystemInit()函数会把时钟配到72MHz如果你的宏定义选对了但很多人不知道这个函数是被启动文件在进入main之前调用的。看懂这一点的价值在于当AI帮你调时钟时你要能验证它有没有改对。比如你想从72MHz降到48MHzAI可能会给你改PLL倍频系数但忘了改Flash的等待周期Latency。时钟越高Flash读取需要插入的等待周期越多72MHz要2个等待周期48MHz要1个。改错了不一定立刻崩但在高频下会出现偶发的读取错误这种问题极难排查。所以我在App层单独写了一个app_clock.c把时钟配置逻辑从system文件里抽出来让AI改这块时有个明确的落点也方便我自己审。3.3 GPIO点灯从寄存器到库函数的完整映射点灯这件事我坚持先用寄存器写一遍再用库函数写一遍。不是为了炫技而是为了建立库函数背后是什么的直觉。寄存器版本大概是这样先开GPIOB的时钟RCC_APB2ENR的位3然后配置PB12为推挽输出50MHzCRH寄存器的对应四位最后写ODR的第12位控制电平。用库函数则是RCC_APB2PeriphClockCmd、GPIO_Init、GPIO_SetBits/ResetBits。两版对照着看你会发现库函数就是把这些位操作包了一层。为什么要费这个劲因为当AI给你一段GPIO代码时你如果能秒懂它配置的是哪个引脚、什么模式、什么速度你就有能力一眼看出它有没有写错。比如AI偶尔会把GPIO_Mode_Out_PP写成GPIO_Mode_IPU上拉输入代码能编译灯就是不亮这时候你如果对模式位没感觉就得靠反复试错。注意PB12这个引脚选择是有讲究的。STM32F103默认把PA13、PA14、PA15、PB3、PB4用作JTAG/SWD调试口如果你把LED接在这些脚上下载完程序后调试口被占用下次可能连不上。避开它们能省掉一堆麻烦。我做的引脚分配表放在Doc/pinmap.md里格式很简单引脚功能模式备注PB12LED_RUN推挽输出低电平点亮PA9UART1_TX复用推挽调试串口PA10UART1_RX浮空输入调试串口PA13SWDIO复用调试口勿占用这张表的价值在于AI每次改代码前我都会让它先读这张表。有了明确的外部约束它乱配引脚的概率会大幅下降。4. 让AI真正参与进来提示词结构、上下文投喂和验证闭环4.1 直接把需求丢给AI为什么必然翻车帮我写个STM32点灯程序——这种提示词你丢给任何AI得到的都是一段泛泛的、基于HAL的、引脚随机指定的代码。它不知道你用哪个库不知道你的引脚表不知道你的目录结构甚至不知道你用的是F1还是F4。它只能给你一个统计学上最常见的答案而这个答案大概率跟你的工程对不上。我早期就是这么干的结果得到的代码里时钟使能写的是__HAL_RCC_GPIOB_CLK_ENABLE()而我工程里是标准库根本没有这个宏。来回解释了好几轮AI还是会在后续对话里忘记我用的是标准库。问题不在AI的智力在于我没有把工程约束变成它每次都能看到的固定上下文。4.2 我常用的三段式提示词结构改法其实不复杂我把每次给AI的提示词固定成三段背景段一句话交代芯片型号、库类型、编译器。STM32F103C8T6标准外设库SPL 3.5.0Keil MDK5目录结构见附件README。约束段把不可违反的规则列出来。不要修改Drivers目录下任何文件LED在PB12低电平点亮时钟已配置为72MHz不要改时钟。约束写具体别写请遵循最佳实践这种空话。任务段说清要做什么、验收标准是什么。在App/app_led.c里实现一个LED闪烁函数用SysTick中断实现1Hz翻转不要用delay死等。完成后说明你改了哪些文件、为什么这样改。这三段里最容易被忽视的是约束段。我实测下来约束越具体AI跑偏的概率越低而且这个收益是边际递增的写上三条关键约束代码一次通过率能从三成提到七成写上引脚和时钟约束能到八成五以上。4.3 把编译结果和现象反馈给AI形成闭环AI看不到你的板子它只能看你给它的信息。所以每次它给完代码我都会做同一套动作编译看有没有warning烧录看现象然后把编译输出原封不动贴回去包括warning。这一步很关键因为warning里经常藏着AI的疏忽比如类型不匹配、未使用的变量、隐式的函数声明。举个例子AI有一版代码里用了一个自定义的delay_ms()但从没定义过Keil给了个隐式声明warning程序能编过但delay完全不起作用因为链接到了别处的同名符号。如果我不把warning贴回去AI会以为一切正常。贴回去之后它立刻发现了问题补上了实现。更进阶一点我会让它自己先做一遍静态检查。提示词里加一句在给出代码前先逐行检查是否引用了未定义的符号、是否所有使用的外设都已使能时钟。这一句话能让不少低级错误在它输出前就被自己拦下来。4.4 AI能在哪些环节帮上真正的忙可能有人会问说了半天规矩AI到底能帮什么以这个最小工程为例我实际让AI干了这些活根据我的引脚表生成GPIO初始化代码省掉我查寄存器的功夫把我手写的寄存器版点灯代码翻译成库函数版两版对照验证逻辑一致帮我写SysTick中断服务函数的骨架包括中断优先级配置的说明审我的启动文件密度等级选得对不对把我的工程整理成一份README逼我自己把目录规范写清楚这些活的共同点是有明确的、可验证的输入输出且我能快速判断对错。反过来我绝不会让AI去干帮我设计整个系统的架构这种事它给的架构脱离硬件约束看着漂亮落地一地鸡毛。5. 从点灯到定时器把骨架扩展成真正能用的模板5.1 用SysTick替代死循环delay顺手解决卡死问题第一个工程里如果只用delay_ms死等来闪烁那么这个程序除了点灯什么都干不了。死等期间CPU完全被占用你没法同时处理按键、串口、传感器。更隐蔽的问题是很多网上的delay实现靠空循环计数循环次数和编译器优化等级强相关优化一开1秒可能变成0.2秒。热词里那个stm32延时函数delay卡死的搜索多半就是这类实现踩的坑。我的做法是用SysTick。SysTick是Cortex-M内核自带的24位递减计数器配置成1ms中断一次在中断里维护一个全局的tick计数。这样主循环可以用非阻塞的方式判断时间volatile uint32_t g_tick 0; void SysTick_Handler(void) { g_tick; } uint8_t time_elapsed(uint32_t start, uint32_t interval) { return (g_tick - start) interval; }注意这里用减法而不是直接比较大小是为了处理计数器回绕。g_tick - start在无符号运算下即使回绕也能得出正确的差值这是个很实用的小技巧AI如果给你直接写g_tick start interval长时间运行后会出问题。主循环变成这样uint32_t last 0; while (1) { if (time_elapsed(last, 500)) { last g_tick; GPIOB-ODR ^ (1 12); // 翻转PB12 } // 这里可以放其他任务 }灯还是1Hz闪但CPU空出来了。这个改动看着小却是我认为第一个工程最值得做的事——它把点灯从玩具变成了任务调度的雏形。5.2 串口打印是调试的第一双眼睛灯只能告诉你程序在跑串口能告诉你程序跑到哪了、变量是多少。所以我在这个最小工程里就把UART1接上了波特率115200PA9/PA10。不改动库的前提下用标准库的USART_SendData配一个重定向的printf就够了。这里有个AI经常搞错的点printf重定向需要实现fputc而且要在Keil工程里勾选Use MicroLIB或者自己实现_sys_write否则程序链接时会报缺符号。我让AI写这段时它第一次只给了fputc没提MicroLIB结果链接失败。后来我在约束段里加了一句工程已启用MicroLIB它就没再犯过。有了串口之后AI的调试价值直线上升。我可以把串口输出贴给它它能根据打印信息推断程序状态。比如我打印tick值发现它一直是0AI立刻指出SysTick的中断优先级没配对被其他中断屏蔽了。5.3 把工程整理成可复用的模板到这一步工程已经能跑、能调、有自己的规范了。最后一步是把它固化下来把不需要改的部分Core、Drivers归档把App层的命名规则、引脚表、README整理好下次新工程直接复制这个目录。我习惯在README里写三样东西目录说明、构建步骤、AI协作约定。第三样是这份模板的灵魂比如App层文件命名统一为app_xxx.c/h新增外设必须在pinmap.md登记修改时钟配置需同时更新LatencyDrivers层只读。这些约定写下来下次AI进来先读README再动手跑偏的概率会低很多。提示模板不要过度设计。我第一版模板分了七层目录结果每个小工程都要建一堆空文件夹反而累赘。三层Core/Drivers/App是甜点区够用且清爽。6. 复盘这个工程里我实际踩过的四个坑6.1 芯片包与库文件版本对不上前面提过一次这里说细节。我一开始用的F1器件包是较新的版本然后从一份老教材里抄了标准库的工程配置结果stm32f10x.h里的某些宏在库文件里找不到对应定义编译报一堆未定义。排查过程很绕先去库文件里搜索这个宏发现确实不存在再去看教材的库版本才意识到是版本差异。解决办法是统一到SPL 3.5.0这一套器件包也用配套的。这个坑的教训不是要用某个特定版本而是工程里所有依赖的版本要能互相说清。我在README里加了一节工具链与库版本把Keil版本、器件包版本、库版本都记下来。之后交接或者换电脑重装直接照着装省了重复排查。6.2 AI生成的代码能编译但不工作有一版AI给的SysTick初始化它用了SysTick_Config(SystemCoreClock / 1000)这个CMSIS函数。看着很优雅但问题是它把SysTick的中断优先级设成了最低默认值而我的串口中断优先级比它高。更麻烦的是这个函数在配置失败时会返回1AI没检查返回值。结果我板子上跑起来tick偶尔跳变查了半天。这件事让我形成了一个习惯AI给的每一行初始化代码我都要问一遍如果这一步失败会怎样。SysTick_Config可能失败、外设时钟可能没使能、GPIO模式可能被后续代码覆盖这些失败路径AI基本不会主动考虑需要我用提问逼它补上。6.3 调试引脚复用后连不上板子这个坑最经典。我早期把LED接在PB4上因为手头板子那个位置好焊烧录一次之后Keil就再也连不上了。原因是PB4默认是JTAG的NJTRST引脚程序跑起来把它配成了GPIO输出调试口就废了。解决办法要么是按住复位键在复位瞬间下载要么是用STM32的启动模式跳到系统存储器。最省事的当然是一开始就别用这些引脚。后来我在pinmap.md里专门加了一行PA13/PA14/PA15/PB3/PB4 保留为调试用途并且把这个文件作为AI每次必读的上下文。这个动作之后我再没遇到过AI给我把LED或者其他功能分配到调试脚上的情况。6.4 优化等级改变了延时行为有一次为了看效果我把Keil的优化等级从-O0改成-O2结果灯的闪烁频率明显变快了。原因是某个用于微调的循环被编译器优化掉了。这件事提醒我任何依赖指令执行时间的代码在改优化等级后都要重新验证。既然我用的是SysTick中断计时理论上不受优化影响但中断服务函数本身如果被过度优化也可能出问题。稳妥做法是给中断里访问的全局变量加volatile这一点AI有时候会漏需要你补。我后来把这个检查也写进了给AI的约束段中断服务函数中访问的全局变量必须声明为volatile。一句话省掉无数玄学问题。最后分享一个我自己的习惯。每次搭完一个新工程的最小骨架我会在README的最后写一段给未来的自己和AI的话就三五句说清这个工程是干嘛的、哪些地方是故意这么设计的、哪些地方暂时不用管。这段话写的时候觉得多余隔一个月回来看它能让你在两分钟内重新进入状态也能让AI在第一次接触这个工程时少问很多问题。第一个STM32工程的价值从来不是那盏灯而是你借它把规矩立下来了。