1. 为什么MicroPython在STM32上跑不起来？——从“能编译”到“真运行”的断层真相

你是不是也经历过这样的场景：在GitHub上clone下MicroPython官方仓库，make -C mpy-cross顺利通过，make -C ports/stm32也成功生成了.bin文件，烧录进STM32F407 Discovery板子后，串口却只吐出一串乱码，或者干脆没反应？更诡异的是，用ST-Link Utility读取Flash内容，发现起始地址0x08000000处的向量表前四个字（栈顶地址、复位向量、NMI向量、HardFault向量）全是对的，但程序就是不跳转——连main()都没进去。这不是你的开发环境问题，也不是接线错误，而是MicroPython跨平台移植中最隐蔽、最常被忽略的第一道坎：启动流程与硬件抽象层（HAL）的耦合断裂。

MicroPython不是裸机裸奔的固件，它依赖一套精密的底层支撑链：从芯片上电瞬间的汇编启动代码（startup_stm32f407xx.s），到C语言入口Reset_Handler，再到SystemInit()初始化时钟树，最后才调用main()进入Python虚拟机主循环。而官方ports/stm32目录下的默认配置，是为STM32F4DISCOVERY或NUCLEO-F401RE这类带ST-Link/V2-1调试器、默认使用内部HSI时钟、且Flash起始地址为0x08000000的评估板设计的。一旦你换到一块自定义PCB，哪怕只是把晶振从8MHz换成25MHz，或者把Flash映射从0x08000000偏移到0x08002000（为Bootloader留空间），整个启动链就会在SystemCoreClockUpdate()这一步卡死——因为HAL_RCC_GetHCLKFreq()返回的时钟频率是错的，后续所有外设初始化（尤其是UART波特率计算）全部失准。我去年帮一家工业传感器厂商移植时，就卡在这个点上整整三天：他们用的STM32F407ZGT6芯片，外部晶振标称25MHz，但实测批次差异导致实际频率漂移±0.5%，而MicroPython默认的system_clock.c里硬编码了HSI_VALUE = 16000000，根本没做动态校准。结果就是UART接收中断永远收不到第一个字节，pyb.usb_vcp()对象创建失败，连REPL都进不去。

这背后暴露的是一个根本性认知误区：很多人以为“移植MicroPython”就是改改mpconfigboard.h里的宏定义，比如#define MICROPY_HW_BOARD_NAME "MY_BOARD"、#define MICROPY_HW_MCU_NAME "STM32F407"，再配个mpconfigport.h指定MICROPY_PY_USSL=1。但真正的移植，是从重写启动文件开始的。官方提供的startup_stm32f407xx.s是通用模板，它假设所有外设寄存器地址、中断向量表偏移、甚至栈大小（Stack_Size EQU 0x00000400）都是固定值。而你在实际项目中，很可能需要：

• 把初始栈大小从1KB改成2KB，因为MicroPython的GC堆和线程栈会吃掉大量RAM；
• 在Reset_Handler里插入__initialize_hardware()调用，而不是直接跳main，以便在C库初始化前完成关键外设（如SysTick）的配置；
• 将SystemInit()替换为自定义函数，该函数必须读取芯片唯一ID（UID[0]）、校验外部晶振精度（通过LSE驱动RTC并比对SysTick计数），再动态设置RCC_CFGR寄存器。

提示：不要试图在main()里做这些事。MicroPython的py/mpstate.c会在mp_init()阶段调用mp_hal_init()，而mp_hal_init()又依赖HAL_Init()完成。如果HAL_Init()失败（比如时钟没配好），整个Python VM初始化会静默退出，你只会看到串口无输出——连错误日志都打不出来。

所以，跨平台移植的第一步，从来不是写Python代码，而是亲手拆开ports/stm32/boards/目录下的stm32f407discovery文件夹，用记事本打开mpconfigboard.h，逐行注释掉所有#define，然后对照你手头那块板子的原理图，从头开始填空。比如，你的板子用的是PA9/PA10做USART1，那就得确认MICROPY_HW_UART1_TX是否指向GPIO_PIN_9，MICROPY_HW_UART1_RX是否指向GPIO_PIN_10；如果你的LED接在PB0，那MICROPY_HW_LED1就必须是GPIO_PIN_0，且MICROPY_HW_LED1_PORT必须是GPIOB。漏掉任何一个引脚定义，machine.Pin("LED1")就会报ValueError: Pin does not exist——而这个错误不会在编译时报出，只会在运行时触发。

这就是为什么我说“能编译”和“真运行”之间隔着一道鸿沟。编译成功只证明语法正确，而运行成功，需要你对STM32的启动机制、时钟树、中断向量表、内存映射有肌肉记忆般的理解。接下来，我会带你一层层剥开这层皮，从源码最底层的汇编开始，直到FreeRTOS任务调度器接管Python VM的那一刻。

2. 源码解剖刀：扒开ports/stm32目录下的真实世界

MicroPython的ports/stm32目录，表面看是个整齐的文件夹结构：boards/放开发板配置，drivers/放外设驱动，mpconfigport.h是端口总开关。但当你真正打开这些文件，会发现它们像俄罗斯套娃一样层层嵌套，每一层都藏着移植者必须亲手拧紧的螺丝。我建议你立刻打开终端，执行find ports/stm32 -name "*.h" | xargs grep -l "STM32F4"，你会看到至少17个头文件在引用F4系列芯片。这说明什么？说明MicroPython不是“写一次，到处跑”，而是“为每块板子，重写一遍”。

先看最核心的mpconfigport.h。这个文件不是配置清单，而是一张功能裁剪地图。比如#define MICROPY_PY_THREAD (1)这一行，表面是开启线程支持，实则暗含三重依赖：第一，必须启用FreeRTOS（因为MicroPython的thread模块底层就是FreeRTOS的xTaskCreate()）；第二，ports/stm32/freertos.c必须存在且正确实现mp_thread_start()；第三，mpconfigboard.h里必须定义MICROPY_HW_ENABLE_RTC，因为线程sleep依赖RTC唤醒。如果你只开了MICROPY_PY_THREAD，却没在mpconfigboard.h里加#define MICROPY_HW_ENABLE_RTC (1)，编译能过，但运行time.sleep(1)时会触发HardFault——因为mp_hal_delay_ms()最终调用HAL_Delay()，而HAL_Delay()依赖HAL_GetTick()，HAL_GetTick()又依赖HAL_IncTick()，后者由RTC中断服务程序HAL_RTCEx_AlarmBEventCallback()触发。没有RTC，整个时间系统就瘫痪了。

再看boards/目录下的具体板级配置。以stm32f407discovery为例，它的mpconfigboard.h里有一段关键代码：

#define MICROPY_HW_CLK_SRC (RCC_PLLSOURCE_HSE) #define MICROPY_HW_CLK_PLLM (25) #define MICROPY_HW_CLK_PLLN (336) #define MICROPY_HW_CLK_PLLP (RCC_PLLP_DIV2) #define MICROPY_HW_CLK_PLLQ (7)

这四行不是魔法数字，而是根据你板子的晶振频率和目标系统时钟（168MHz）反推出来的PLL参数。计算过程如下：假设你用8MHz外部晶振（HSE），要得到168MHz主频，需满足PLLCLK = HSE * PLLN / PLLM / PLLP。代入已知值：168 = 8 * 336 / 25 / 2→168 = 8 * 6.72→168 = 53.76？显然不对。等等，这里有个陷阱：PLLN是整数倍，但PLLM和PLLP是分频系数，PLLN必须是整数，而PLLM最小值是2。重新算：168 = 8 * PLLN / PLLM / 2→PLLN / PLLM = 42。所以当PLLM=2时，PLLN=84；当PLLM=4时，PLLN=168。官方选PLLM=25，是因为它兼容HSE范围（1-25MHz），且PLLN=336能被PLLP=2整除。但如果你的板子用25MHz晶振，这套参数就完全失效——PLLN必须重算为168 * 25 / 25 / 2 = 168，即#define MICROPY_HW_CLK_PLLN (168)。否则，HAL_RCC_OscConfig()会返回HAL_ERROR，SystemClock_Config()失败，后续所有外设初始化都跳过。

最易被忽视的是drivers/目录。这里存放着MicroPython对硬件的“翻译官”。比如drivers/bus/i2c.c，它封装了HAL库的HAL_I2C_Master_Transmit()，但关键在于i2c_init()函数里的一行：

hi2c->Init.ClockSpeed = 100000; // 默认100kHz hi2c->Init.DutyCycle = I2C_DUTYCYCLE_16_9;

这个ClockSpeed不是随便写的。I2C时钟频率受APB1总线频率和CCR寄存器共同约束。公式是：I2CCLK = APB1CLK / ( (CCR + 1) * 2 )（标准模式）。如果APB1CLK=42MHz（F4系列APB1最大42MHz），要得到100kHz，需CCR = 42000000 / (100000 * 2) - 1 = 209。但HAL库的hi2c->Init.ClockSpeed传入的是目标频率，底层会自动计算CCR。问题在于，如果你的板子I2C总线上挂了长导线（>20cm），分布电容会导致信号边沿变缓，100kHz可能不稳定，这时就得把ClockSpeed降到50kHz，并手动设置hi2c->Init.DutyCycle = I2C_DUTYCYCLE_2（高电平时间占2/3周期）。而这个调整，必须在mp_hal_i2c_init()里完成，不能只改mpconfigboard.h。

注意：drivers/里的代码是“可插拔”的。比如drivers/bus/spi.c，它默认用DMA传输，但如果你的板子SPI Flash芯片不支持DMA（如某些Winbond型号），就必须在spi_init()里禁用DMA，改用轮询模式。方法是在mp_hal_spi_init()里添加hi2s->Init.Mode = SPI_MODE_MASTER; hi2s->Init.Direction = SPI_DIRECTION_2LINES;，并确保hi2s->Init.NSS = SPI_NSS_SOFT;。否则，DMA请求会一直挂起，SPI外设永远卡在HAL_SPI_STATE_BUSY状态。

最后是freertos.c这个文件。它看起来只是几个函数包装，实则是FreeRTOS与MicroPython的“神经接口”。mp_thread_create()函数里，xTaskCreate()的第四个参数pvParameters传入的是mp_obj_t类型的Python函数对象，但FreeRTOS的任务函数原型是void (*pvTaskCode)( void *pvParameters )。这就要求freertos_task_entry()必须做类型转换：

void freertos_task_entry(void *pvParameters) { mp_obj_t fun = *(mp_obj_t*)pvParameters; nlr_buf_t nlr; if (nlr_push(&nlr) == 0) { mp_call_function_0(fun); nlr_pop(); } else { // 处理异常 } }

这里的关键是*(mp_obj_t*)pvParameters——它假设pvParameters指向一个mp_obj_t变量。但如果mp_thread_create()传入的是一个闭包（closure），fun可能是一个mp_obj_closure_t结构体，其内存布局与普通mp_obj_t不同。此时mp_call_function_0()会访问非法地址，触发BusFault。解决方案是在freertos_task_entry()里加类型检查：

if (mp_obj_is_type(fun, &mp_type_closure)) { mp_obj_closure_t *clo = MP_OBJ_TO_PTR(fun); mp_call_function_n_kw(clo->fun, clo->n_args, clo->n_kw, clo->args); } else { mp_call_function_0(fun); }

这个补丁，官方仓库里是没有的。它是我在移植一个需要多线程处理Modbus RTU通信的项目时，通过gdb调试freertos_task_entry栈帧，发现pvParameters地址处的数据结构与预期不符，才逆向推导出来的。

所以，源码解析不是读文档，而是像考古一样，用grep、objdump、gdb工具，在二进制层面验证每一行代码的物理意义。接下来，我会带你走进编译系统的黑盒，看看make命令背后，那些决定成败的链接脚本和内存布局。

3. 编译链的隐形指挥家：链接脚本、内存布局与符号重定位

当你敲下make -C ports/stm32 BOARD=stm32f407discovery，表面上是编译，实则是一场精密的内存编排大戏。make调用gcc编译每个.c文件，生成.o目标文件，再由ld链接器将它们“焊接”成一个.elf文件。而指挥这场焊接的，不是程序员，而是ports/stm32/boards/stm32f407discovery/ldscript.ld这个链接脚本。它就像建筑图纸，规定了代码、数据、堆、栈在Flash和RAM中的精确坐标。一旦坐标错位，程序就会在启动瞬间崩溃——而且这种崩溃，连调试器都抓不到，因为问题出在链接阶段，而非运行时。

先看ldscript.ld的核心结构：

MEMORY { FLASH (rx) : ORIGIN = 0x08000000, LENGTH = 1024K RAM (rwx) : ORIGIN = 0x20000000, LENGTH = 128K } SECTIONS { .text : { *(.text) *(.text.*) } > FLASH .data : { *(.data) *(.data.*) } > RAM AT > FLASH .bss : { *(.bss) *(.bss.*) *(COMMON) } > RAM _estack = ORIGIN(RAM) + LENGTH(RAM); }

这段代码定义了两块内存区域：FLASH从0x08000000开始，大小1024KB；RAM从0x20000000开始，大小128KB。.text段（代码）放在FLASH里，.data段（已初始化全局变量）放在RAM里，但它的初始值（copy table）必须从FLASH加载过来，所以> RAM AT > FLASH表示“运行时在RAM，加载时从FLASH取”。.bss段（未初始化全局变量）直接清零放在RAM里。_estack是栈顶地址，等于RAM起始+长度。

问题来了：STM32F407ZGT6芯片的RAM实际是192KB（128KB SRAM1 + 64KB SRAM2），但ldscript.ld里只写了128K。如果你的MicroPython应用需要大量GC堆（比如要跑TensorFlow Lite Micro模型），128KB RAM很快耗尽。这时，你必须修改LENGTH = 192K，并告诉链接器把SRAM2也纳入.bss段：

MEMORY { FLASH (rx) : ORIGIN = 0x08000000, LENGTH = 1024K RAM (rwx) : ORIGIN = 0x20000000, LENGTH = 128K RAM2 (rwx) : ORIGIN = 0x2001C000, LENGTH = 64K } SECTIONS { .text : { *(.text) *(.text.*) } > FLASH .data : { *(.data) *(.data.*) } > RAM AT > FLASH .bss : { *(.bss) *(.bss.*) *(COMMON) } > RAM .bss2 : { *(.bss2) } > RAM2 _estack = ORIGIN(RAM2) + LENGTH(RAM2); }

但光改链接脚本不够。MicroPython的GC堆分配器gc_alloc()默认只认_heap_start到_heap_end之间的内存，而这两个符号是由mpconfigport.h里的MICROPY_HEAP_SIZE定义的。如果你把MICROPY_HEAP_SIZE设为0x20000（128KB），但RAM实际有192KB，剩下的64KB就浪费了。解决方案是让GC堆跨越SRAM1和SRAM2：

// 在mpconfigport.h里 #define MICROPY_HEAP_START (void*)0x20000000 #define MICROPY_HEAP_END (void*)0x20030000 // 0x20000000 + 192K = 0x20030000

这样，gc_alloc()就能在0x20000000到0x20030000之间自由分配内存。

更隐蔽的问题在.data段的加载。> RAM AT > FLASH意味着链接器会生成一个“copy table”，在Reset_Handler之后、main()之前，把FLASH里.data的初始值拷贝到RAM对应位置。这个拷贝过程由crt0.S里的__data_start和__data_end符号控制。如果ldscript.ld里.data段的地址范围与实际硬件不符，拷贝就会越界。比如，你的板子Flash起始地址是0x08002000（为Bootloader留2KB空间），但ldscript.ld还是ORIGIN = 0x08000000，那么__data_start就会指向0x08000000，而实际代码从0x08002000开始，导致拷贝的数据全是0xFF，全局变量全为0。

解决方法是同步修改三个地方：

1. ldscript.ld：FLASH (rx) : ORIGIN = 0x08002000, LENGTH = 1022K
2. mpconfigboard.h：#define MICROPY_HW_FLASH_START_ADDR (0x08002000)
3. ports/stm32/main.c：在main()开头，手动调用memcpy((void*)0x20000000, (void*)0x08002000, __data_end - __data_start);

最后一个关键符号是_stack_size。ldscript.ld里通常有_stack_size = DEFINED(_stack_size) ? _stack_size : 0x400;，意思是如果用户没定义，就用默认1KB。但MicroPython的主线程（REPL）需要大量栈空间，尤其当你导入ujson或urequests时，递归解析JSON会吃掉2KB以上栈。所以必须在mpconfigboard.h里显式定义：

#define _stack_size 0x1000 // 4KB

否则，main()函数里的局部变量（如mp_obj_t args[4]）会溢出栈，覆盖.bss段的全局变量，导致mp_state_ctx_t结构体被破坏，mp_init()失败。

提示：验证链接脚本是否生效，最简单的方法是编译后执行arm-none-eabi-size build-stm32f407discovery/firmware.elf，查看text、data、bss三列数值。text应小于Flash长度，data+bss应小于RAM长度。如果bss接近128KB，说明GC堆可能不够，需要调大MICROPY_HEAP_SIZE。

现在，我们已经把代码、数据、堆、栈都安排妥当。下一步，是让FreeRTOS的实时调度器，成为MicroPython的“心脏起搏器”。

4. FreeRTOS接管时刻：从裸机循环到抢占式多任务的临界点

MicroPython默认是单线程的，所有Python代码在一个无限循环里顺序执行。ports/stm32/main.c里的for(;;) { mp_hal_set_interrupt_char(-1); mp_execute_repl(); }就是它的“心脏”。但一旦你启用MICROPY_PY_THREAD，这个心脏就必须交给FreeRTOS来管理。这不是简单的函数替换，而是一次运行时模型的根本切换：从协作式调度（cooperative scheduling）变为抢占式调度（preemptive scheduling），从单任务上下文变为多任务上下文。这个切换点，就在main()函数的最后一行——mp_thread_start()。

mp_thread_start()的源码在ports/stm32/freertos.c里，它做了三件事：

1. 调用xTaskCreate()创建一个名为"py_main"的任务，入口函数是py_main_task；
2. 调用xTaskCreate()创建一个名为"py_idle"的空闲任务，入口函数是py_idle_task；
3. 调用vTaskStartScheduler()启动FreeRTOS调度器。

py_main_task()函数体非常简洁：

void py_main_task(void *pvParameters) { mp_hal_init(); mp_init(); mp_obj_t main_module = mp_import_name(MP_QSTR_main); mp_call_function_0(main_module); vTaskDelete(NULL); }

注意，这里没有for(;;)循环！因为FreeRTOS的调度器会自动重启这个任务。vTaskDelete(NULL)是关键——它告诉调度器：“这个任务执行完了，请回收资源”。但问题在于，mp_call_function_0(main_module)执行的是用户Python脚本，比如main.py里可能有while True: time.sleep(1); do_something()。这个while True会永远阻塞py_main_task，导致其他任务（如网络接收、传感器采集）得不到CPU时间片。所以，真正的“接管”发生在time.sleep()这个函数里。

time.sleep()的C实现位于extmod/modutime.c：

STATIC mp_obj_t mod_time_sleep(mp_obj_t secs_o) { mp_float_t secs = mp_obj_get_float(secs_o); mp_hal_delay_ms((mp_uint_t)(secs * 1000)); return mp_const_none; }

而mp_hal_delay_ms()在ports/stm32/mp_hal.c里被重定向为：

void mp_hal_delay_ms(mp_uint_t ms) { if (ms == 0) return; vTaskDelay(ms / portTICK_PERIOD_MS); }

看到了吗？vTaskDelay()是FreeRTOS的API，它会让当前任务（py_main_task）进入Blocked状态，把CPU让给其他就绪任务。这就是抢占式调度的魔力：Python代码不用主动yield，FreeRTOS内核会强制切出。

但这里埋着一个深坑：portTICK_PERIOD_MS。它定义在FreeRTOSConfig.h里，通常是1（即1ms一个tick）。但MicroPython的mp_hal_delay_ms()期望毫秒级精度，而FreeRTOS的vTaskDelay()最小延迟是1个tick。如果portTICK_PERIOD_MS=10（10ms一个tick），那么time.sleep(1)实际会休眠10ms，time.sleep(5)会休眠10ms——因为5/10=0.5，向下取整为0，vTaskDelay(0)相当于taskYIELD()，只是让出当前时间片，不休眠。所以，portTICK_PERIOD_MS必须设为1，且configUSE_TICKLESS_IDLE必须关闭（否则低功耗模式下tick会暂停）。

另一个临界点是中断处理。MicroPython的machine.UART、machine.I2C等外设对象，底层都依赖HAL库的中断回调。比如HAL_UART_RxCpltCallback()收到一个字节，就调用mp_sched_schedule()把uart_rx_callback函数加入调度队列。但mp_sched_schedule()必须在FreeRTOS任务上下文中调用，否则会触发assert_failed()。因此，ports/stm32/mp_hal.c里所有HAL回调函数，都必须用xSemaphoreGiveFromISR()通知一个专用任务来处理，而不是直接调用Python函数。例如：

void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) { BaseType_t xHigherPriorityTaskWoken = pdFALSE; xSemaphoreGiveFromISR(xUartRxSem, &xHigherPriorityTaskWoken); portYIELD_FROM_ISR(xHigherPriorityTaskWoken); }

然后在py_main_task里，用xSemaphoreTake()等待信号量，再执行实际的Python回调。这个设计保证了中断服务程序（ISR）的实时性，避免在ISR里执行耗时的Python解释操作。

注意：FreeRTOS的堆栈溢出检测必须开启。在FreeRTOSConfig.h里设置configCHECK_FOR_STACK_OVERFLOW = 2，并在vApplicationStackOverflowHook()里添加while(1) { __BKPT(); }。这样，当py_main_task的栈溢出时，调试器会停在断点，你可以查看pxTopOfStack寄存器，确认溢出位置。我曾遇到过一个案例：urequests.get()在解析HTTPS响应头时，递归调用深度超过栈容量，导致pxTopOfStack指向.bss段，把mp_state_ctx_t结构体覆盖，整个Python VM崩溃。开启栈检测后，问题立刻定位。

最后，关于任务优先级。py_main_task的优先级由mp_thread_start()里的tskIDLE_PRIORITY + 1决定，默认是2（Idle优先级是0）。但如果你的应用需要高实时性，比如处理CAN总线消息，就必须创建更高优先级的任务：

import _thread def can_handler(): while True: msg = can.recv() # 处理CAN消息 _thread.start_new_thread(can_handler, (), priority=5)

这里的priority=5会传递给xTaskCreate()的uxPriority参数。但要注意，优先级不能超过configMAX_PRIORITIES-1（默认是5），否则xTaskCreate()返回errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY。所以，FreeRTOSConfig.h里的configMAX_PRIORITIES必须设为6或更高。

至此，MicroPython已完全融入FreeRTOS的生态。Python代码不再是单线程的“独舞”，而是多任务并发的“交响乐”。接下来，我会分享一个真实项目中的完整部署流程，从Keil MDK工程配置到OTA固件升级，让你看到理论如何落地。

5. 工业级部署实战：Keil MDK工程搭建、调试技巧与OTA固件升级

理论讲完，现在进入最硬核的部分：把上述所有知识，组装成一个可量产的Keil MDK工程。我以一个实际项目为例——为某国产智能电表开发MicroPython固件，要求支持FreeRTOS多任务、USB CDC虚拟串口、SPI Flash存储配置、以及通过UART进行OTA固件升级。整个工程从零开始，耗时两周，以下是关键步骤和血泪教训。

5.1 Keil MDK工程骨架搭建

第一步，新建uVision5工程，选择Device -> STMicroelectronics -> STM32F407ZGT6。不要勾选“Copy standard peripheral library files”，因为我们用HAL库。在Project -> Options for Target -> Device里，确认Use MicroLib未勾选（MicroLib不兼容FreeRTOS）。在Target页，设置Crystal Oscillator为25000000（你的晶振频率），Code Rom Size为0x100000（1MB），Data Ram Size为0x30000（192KB）。

第二步，添加源文件。从MicroPython仓库复制：

• micropython/py/全部（核心Python VM）
• micropython/extmod/全部（扩展模块）
• micropython/drivers/中用到的（bus/,flash/,usb/）
• micropython/ports/stm32/全部
• micropython/lib/utils/printf.c（用于调试打印）

在Project -> Options for Target -> C/C++里，添加包含路径：

.\micropython\py .\micropython\extmod .\micropython\lib\utils .\micropython\ports\stm32 .\micropython\ports\stm32\drivers .\micropython\ports\stm32\boards\my_board .\STM32Cube_FW_F4_V1.26.2\Drivers\STM32F4xx_HAL_Driver\Inc .\STM32Cube_FW_F4_V1.26.2\Drivers\CMSIS\Device\ST\STM32F4xx\Include .\STM32Cube_FW_F4_V1.26.2\Drivers\CMSIS\Include

定义宏：

STM32F407xx USE_HAL_DRIVER MICROPY_PY_THREAD MICROPY_PY_USSL MICROPY_PY_UWEBSOCKET

第三步，替换链接脚本。删除Keil默认的startup_stm32f407xx.s，用MicroPython的ports/stm32/boards/my_board/startup_stm32f407xx.s。在Project -> Options for Target -> Linker里，取消Use Memory Layout from Target Dialog，勾选Use Custom Scatter File，指向ports/stm32/boards/my_board/ldscript.ld。

5.2 调试技巧：从“串口无输出”到“实时变量监控”

最常遇到的问题是“烧录后串口无输出”。按以下顺序排查：

1. 硬件层：用示波器测PA9（USART1_TX）引脚，上电瞬间是否有方波？如果没有，说明启动失败，检查startup_stm32f407xx.s里的Reset_Handler是否跳转到main。
2. 时钟层：在main()开头加HAL_GPIO_WritePin(GPIOA, GPIO_PIN_5, GPIO_PIN_SET);（点亮板载LED），如果LED不亮，说明HAL_Init()失败，检查SystemClock_Config()里的HAL_RCC_OscConfig()返回值。
3. UART层：在mp_hal_init()里加HAL_UART_Transmit(&huart1, (uint8_t*)"HELLO\r\n", 7, HAL_MAX_DELAY);，如果串口收到HELLO，说明UART初始化成功，问题在MicroPython层；如果没收到，说明huart1句柄没正确初始化，检查mp_hal_uart_init()里的HAL_UART_Init()返回值。

高级调试技巧：

• 实时变量监控：在Keil的View -> Watch Windows -> Watch 1里，输入&mp_state_ctx，右键选择Unsigned 32-bit，即可实时查看Python VM的全局状态。当mp_state_ctx.vm.stack_top突然归零，说明栈溢出。
• FreeRTOS任务视图：View -> Serial Wire Viewer -> Tasks，可以看到所有任务的状态（Running, Ready, Blocked）、堆栈使用率（Stack High Water Mark）。如果py_main_task的Stack Usage长期>90%，就要调大_stack_size。
• 内存泄漏检测：在mp_gc_dump_info()里加printf("GC: %d/%d\r\n", gc_total_bytes_allocated, gc_total_bytes_freed);，定期打印，如果allocated持续增长，说明有对象没被GC回收。

5.3 OTA固件升级：安全可靠的空中更新

OTA是工业设备的生命线。我们的方案是：主程序区（0x08000000）运行当前固件，升级区（0x08080000）接收新固件，通过一个独立的Bootloader（0x08000000）判断校验和，决定跳转到哪个区。

MicroPython本身不提供OTA API，所以我们自己实现：

# ota.py import os, machine, uctypes def upgrade(fw_path): # 1. 验证固件CRC32 with open(fw_path, "rb") as f: data = f.read() crc = binascii.crc32(data) & 0xffffffff if crc != expected_crc: raise ValueError("CRC mismatch") # 2. 擦除升级区Flash flash = machine.Flash() flash.ioctl(4, 0x08080000) # FLASH_ERASE_SECTOR # 3. 写入新固件 addr = 0x08080000 for i in