PX4固件移植指南：自制STM32H7飞控从硬件到调试全流程

把PX4固件移植到一块自己设计的STM32H7飞控板上，这事儿在圈子里听起来像是“高手专属”，实际上只要把硬件、固件、bootloader三件事理顺，一个周末就能看到传感器数据在控制台上滚出来。我前前后后做了三块H7板子，踩过的坑比写出来的代码还多，这篇就把从零开始的全流程拆开讲清楚，包括硬件选型思路、PX4板级配置的结构、编译烧录步骤，以及那些文档里不会写的坑。

这篇内容适合两类人：一类是手头已经有一块自制飞控但不知道怎么跑PX4的，另一类是正准备画STM32H7板子、想提前避免引脚和电源设计失误的。如果你只想用现成Pixhawk，那这篇文章帮助不大，但如果你想让自己的板子变成“Pixhawk级”飞控，这里面的经验应该能让你少走至少一个月弯路。

1. 移植前必须想清楚：硬件选型与固件架构

1.1 为什么是STM32H7：性能和中高端的平衡

PX4能跑的MCU不少，从F4到H7都有官方支持。我选STM32H7并不是因为它“新”，而是因为两个实打实的好处：第一是Cortex-M7核心的主频能跑到480MHz，传感器数据融合、姿态解算、位置估计这些实时性要求高的模块，跑起来余量很足；第二是STM32H7内置了双精度FPU，PX4里的EKF2算法虽然主要是单精度矩阵运算，但部分密集计算和中间累积量用双精度能明显减少数值漂移，我在同一块硬件上对比过，编译开双精度后EKF的残差曲线要平滑一些。

STM32H750和STM32H743是同一个芯片家族，H750只有128KB Flash但价格便宜，H743是2MB Flash。PX4固件编译出来大概800KB到900KB，如果把堆栈、启动日志、参数存储也算进去，H750内部Flash根本装不下，除非你额外外挂QSPI Flash并把启动流程改掉——这个工程量我劝新手别碰。老老实实用H743，哪怕是VIT6这种LQFP100封装，手工焊接也就比F405的LQFP48难一点点。

需要强调一点：选用STM32H7意味着整个软件栈要按Cortex-M7来适配，PX4的构建系统对M7支持已经很成熟，但板级配置里的一些细节，比如SCB配置、缓存策略、Flash延迟等待周期，如果沿用F4的配置，跑起来轻则性能打折，重则卡死，这些在后面的board配置文件里都要逐个检查。

1.2 PX4固件的构成：一套代码，换一块板卡

PX4不是一个“单片机裸跑程序”，它跑在NuttX实时操作系统上，应用层由几十个模块组成，比如姿态估计模块、位置估计模块、导航模块、多旋翼控制模块、传感器驱动模块等等。模块之间通过uORB消息总线通信，这种架构意味着，只要板级的东西适配好了，上层应用几乎不用改。

从移植角度，真正需要动的地方是这么几块：

• 板级目录，在源码boards/下面，每个板卡一个文件夹，里面包含CMake配置、NuttX的defconfig、硬件启动脚本、板级board_config.h等；
• bootloader，用于加载固件并实现USB/串口升级；
• 外设驱动，大部分传感器驱动都是现成的，你需要做的就是告诉PX4这些传感器挂在哪条SPI/I2C总线上、片选引脚是多少；
• 飞行器配置文件，即airframe配置，决定这是四旋翼还是固定翼，以及混控器输出。

所以整个移植工作说白了就是给PX4提供一块“新板卡”的说明书，让它知道你的MCU上有哪些外设、每个外设接了什么、输出脚怎么用。明白这一点，后面实际操作的时候你的思路就会很清晰。

1.3 三条移植路线：先定策略再动手

在开始编译之前，先决定你打算怎么“把固件搞上去”，不同路线的难度和工作量差别很大。

第一种是直接基于官方板卡配置着改。最常见的操作是复制一个和你硬件最接近的板卡，比如px4_fmu-v5（对应Pixhawk 4），然后把引脚、传感器型号、闪存配置改成自己的。这是最推荐的路线，因为FMU-v5本身就是STM32F765，虽然和H7不同，但整个板级结构是同类风格，改起来有参考。

第二种是从官方H7板卡开始改。PX4官方有px4_fmu-v6x，它就是STM32H743的板子，和你的方案最接近。如果硬件布局比较接近Pixhawk 6X，你用这个作为起点，改动的面积最小。

第三种是从零自己写板级目录。理论上完全可行，但需要手动处理大量中断映射、时钟树、外设DMA配置，在没有厂家支持的情况下很容易卡住，适合想搞懂PX4底层的人，不适合“快速让飞机飞起来”的目标。

我的建议是：如果目标是尽快跑起来，路线二优先；如果只是学习，路线一和路线三都能学到东西。我自己第一块板子走的就是路线二，从px4_fmu-v6x拷贝配置，改到自家硬件上。

2. 自制飞控硬件要点：传感器、电源与引脚规划

2.1 传感器选型与SPI挂载细节

飞控的传感器其实就那几类：IMU（陀螺仪+加速度计）、磁力计、气压计。PX4对主流传感器驱动支持都很完整，但你在画板子的时候就要想好“每个传感器挂在哪个总线、用什么通信接口”，因为这直接决定固件配置里怎么写。

我常用的是BMI088作为主力IMU，它温度稳定性好，而且陀螺仪和加速度计内部是分开的两个芯片，噪声特性不错，PX4里对BMI088的驱动很成熟；再搭配一颗ICM20602作为冗余IMU，两者都走SPI。磁力计用IST8310，走I2C，也可以考虑把外部磁力计放到GPS模块上的方案，但自制的第一版还是板载的简单。气压计用MS5611，走SPI，SPI通信速度比I2C稳定，而且MS5611在任何温度下都还算靠谱。

这里要特别提醒SPI总线规划的一个经验：不要把所有传感器全挂到同一条SPI总线上。我在第一块板设计时图省事，把BMI088、ICM20602、MS5611全挂在SPI1上，结果固件起来后三个传感器都能读到ID，但跑EKF时数据偶尔出现延迟抖动，后来排查发现是SPI总线上三个器件共用DMA通道，争抢导致。后面第二版我把IMU放在SPI1、气压计放在SPI2，问题就消失了。

传感器供电也要单独注意。BMI088的VDD_IO如果和主控I/O电压不一致，SPI通信会话出现乱码，所以设计时把所有IMU的IO供电统一接到3.3V，并且用RC滤波把数字电源和模拟电源分开，PCB布局时传感器尽量靠近MCU，走线短一点，信号完整性会好很多。

2.2 电源树与电压/电流采集

很多自制飞控翻车不是在传感器上，而是在电源设计上。STM32H743对供电要求比F4严格，内核电压是1.2V左右，VDDA要稳定，主电源最好用一颗低压差LDO或者DC-DC模块先把锂电池电压降到5V，再通过第二级LDO降到3.3V。我见过有人直接用AMS1117从2S锂电池取电给MCU供电，一推油门MCU就复位，后面查明原因就是压差太大、发热严重，AMS1117热保护了。

电压电流采集也不能省。PX4里有一个battery_status模块，它通过ADC采集电压分压值，从而估算剩余电量。电压分压电阻的计算很简单：如果电池最高电压是4S即16.8V，而ADC参考电压是3.3V，分压比至少要留出20%余量，也就是16.8V分到大约2.2V，那么上分压电阻和下分压电阻的比值大约是（16.8 - 2.6）/ 2.6，选68K和15K比较合适，然后在ADC引脚并联一个0.1uF电容滤除高频噪声。

电流采集通常用电流互感器或者采样电阻加运放，PX4支持通过模拟输入读取电流。如果你第一版不想做电流采集，可以先把引脚留出来，后续再补。

2.3 引脚映射：给固件留好后路

引脚分配是整个硬件设计中决定移植成本最关键的一环。PX4板级配置里，对每个外设的引脚定义都是集中放在board_config.h或者dts相关的文件里，设计PCB时就要把这些引脚固定下来，否则后续固件改引脚会牵一发动全身。

我给自己这块H7飞控定的引脚分配大致长这样：

这个表不是让你照抄，而是想说一个原则：串口尽量选有DMA支持的，PWM输出脚尽量集中在同一个定时器的不同通道上，这样混控器输出的时候定时器配置最省事。如果以后想支持DShot，还必须确保这些引脚能连到定时器的PWM输出。这个在你画板子之前就要查好参考手册，不然焊完板子再想改引脚，只能用飞线，体验极差。

3. 固件移植实操：从复制板卡到第一次编译

3.1 环境准备：Ubuntu下的交叉编译链

PX4官方推荐在Ubuntu 20.04或22.04下编译，最简单的方式是使用PX4官方的Docker镜像，但我个人还是习惯直接在Ubuntu里装工具链，方便查编译错误。

主要依赖就这几样：git、CMake、ninja或make、arm-none-eabi-gcc交叉编译器，以及Python3和一些pip包。PX4源码自带了工具链安装脚本，搜索项目里的Tools/setup/ubuntu.sh，直接跑一遍就能把依赖装齐。

我用的是PX4 v1.14.3版本，这个版本对STM32H7的支持要比早期版本好很多，EKF2也稳定。拉源码的时候注意要用带子模块的完整克隆，PX4依赖了NuttX、uORB的独立仓库以及一系列驱动库，不拉子模块编译必失败：

git clone --recursive --branch v1.14.3 https://github.com/PX4/PX4-Autopilot.git cd PX4-Autopilot git submodule update --init --recursive

3.2 复制板卡目录与px4board配置

进入boards目录，你会发现结构按照厂商/板卡名组织，比如px4/fmu-v6x。我现在要做的就是把官方H7板卡复制成自己的板卡。

cp -r boards/px4/fmu-v6x boards/h7fc/h7fc_v1 cd boards/h7fc/h7fc_v1

复制后主要干三件事：改板卡名、改CMake配置、改引脚定义。CMake配置文件名一般是fmu-v6x.px4board，改成你的板卡名，比如h7fc.px4board。打开这个文件，里面的内容会告诉你PX4的模块系统是怎么组织的：

px4_add_board( VENDOR h7fc MODEL h7fc_v1 PLATFORM nuttx TOOLCHAIN arm-none-eabi ARCHITECTURE cortex-m7 ROMFSROOT px4fmu_common DRIVERS barometer/ms5611 imu/bmi088 imu/icm20602 magnetometer/ist8310 ... SERIAL_PORTS UART7: SERIAL_7 ... )

这里每一个DRIVERS条目对应一个驱动目录，SERIAL_PORTS告诉PX4哪些串口暴露给用户，比如UART7对应配置参数SERIAL_7。如果你板子上没接某个传感器，就直接从列表里删掉，PX4不会去初始化不存在的设备，甚至可以省内存。

引脚配置在src/board_config.h里。这个文件里定义了各类引脚的GPIO、片选、LED、中断等宏。你需要拿着这个文件和自己的原理图对照，把引脚的GPIO编号改成你实际的连接。改完别急着编译，先检查中断号是否对应，否则传感器数据根本进不来。

3.3 启动脚本与NuttX配置

PX4板卡目录下有一个ROMFS/px4fmu_common/init.d/的启动脚本，它决定了启动时哪些模块会被拉起来、传感器怎么配置、混控器是否默认加载。你复制板卡后，启动脚本也要跟着改。最关键的几个脚本是rcS和rc.board_defaults，里面一般长这样：

ms5611 start bmi088 start icm20602 start ist8310 start -i 0 param set SENS_EN_BMI088 1 param set SENS_EN_ICM20602 1

如果你在CMake里已经通过DRIVERS配置了驱动，启动脚本其实可以更简洁，PX4后续版本倾向于让驱动自动探测。但自动探测依赖设备在启动时能被正确识别，如果你的传感器片选引脚配置不对，这里就会卡住。

NuttX配置在nuttx-config/nsh/defconfig里，这里面包含的是NuttX操作系统的配置，比如堆栈大小、任务数量、文件系统、串口驱动、SPI驱动。对H7来说，你要确认RAM的大小分配够EKF2跑，一般建议设置用户堆不小于2MB——注意H743的RAM有1MB左右，但ECC会占用一部分，实际可用没那么奢侈，别把堆栈设得太大导致内存不足。

3.4 编译与常见报错

完成以上修改后，回到源码根目录编译：

make h7fc_h7fc_v1

第一次编译通常不会一次通过，常见报错有这么几类：

乱码或者“undefined reference”多半是子模块没拉全，重新git submodule update --init --recursive一般能解决。编译到一半报“board_config.h not found”则是你复制的目录里少了文件，把fmu-v6x里的src完整复制过来。链接时Flash超大小，H743 2MB理论上够，但如果开了太多驱动功能，还是会爆，这时候砍掉不用的驱动最直接。

编译完成后，固件文件一般在build/h7fc_h7fc_v1/下面，格式是.px4，这就是后面要烧录的文件。

4. Bootloader烧录与首次上电调试

4.1 烧录PX4 bootloader

固件不能直接烧到0x08000000，PX4的固件格式和普通STM32固件不一样，前面有一段bootloader尾部的App描述符，包含CRC和版本信息。你必须先把PX4的bootloader烧进MCU，PX4原生固件里带了升级逻辑，可以让你在bootloader阶段通过USB或者串口刷固件，以后调试会非常方便。

bootloader的源码在https://github.com/PX4/Bootloader，编译对应目标后得到*.bin，然后你用STM32CubeProgrammer或者ST-Link把它烧到Flash起始地址。烧完后，正常现象是板载LED会慢闪，同时USB插入电脑会出现一个“Pixhawk Bootloader”的串口设备。

之后刷固件我有两种方式，一种是在bootloader模式下通过QGroundControl里的“固件升级”功能，选择本地.px4文件；另一种是直接用串口工具发upload命令，这个更常用来调试。日常迭代我基本都用QGC，稳定且可以顺便检查参数。

4.2 进入NuttShell检查外设

如果你通过USB连上飞控，可能会看到一个/dev/ttyACM0的串口设备，波特率在PX4下通常是115200。打开串口终端，飞控应该会进入NuttShell，提示符是nsh>或者pxh>，这里有一个看起来像Linux命令行的控制台，PX4的很多调试命令都在这里跑。

第一次上电，什么叫“移植成功”？我定义的标准是：在控制台里输入listener sensor_combined，能看到实时的IMU数据往外刷。如果没有数据，就按下面顺序排查：

先top看进程是否正常，有没有模块反复崩溃。再用ms5611 start、bmi088 start这类命令手动启动某个驱动，看有没有“device not found”的报错。如果驱动启动正常但没数据，十有八九是SPI速度或者引脚配置问题，回board_config.h检查。

串口输出中文乱码不是问题，NuttX默认英文环境，不要在这上面浪费时间。真正要注意的是param show SYS_AUTOSTART这个参数，它决定了系统启动后加载哪个机型配置文件，如果还是默认的Pixhawk 4，你的混控器输出可能全错，上电时电机会有异常。

4.3 QGroundControl连接与校准

当控制台的传感器数据正常后，用USB线连上QGroundControl，如果一切正常，地面站会自动识别飞控并提示你校准传感器。先做加速度计校准，把飞控按六个方向依次摆放，这一步对有外壳的飞控格外重要，因为芯片贴片方向如果和机架方向不一致，校准后姿态会偏。

然后是陀螺仪校准，必须把飞控放平静止，点击开始后不要碰它。磁力计校准要远离金属和电机，我通常把飞控拿到窗边或者室外空旷处转圈校准。气压计校准很简单，保持静止几秒就行。

电机校准是地面站里“功率设置”做的，PWM输出和电机一一对应，接错的要记录并修改混控器参数。这里有一个非常重要的操作：校准电机之前，务必把螺旋桨全部拆掉。我第一次调试就踩着这个教训，还好当时电机没上桨，不然很危险。

5. 避坑指南：实测最容易翻车的15个坑

这部分是我最想说的，很多坑是连官方文档都没写清楚的，按照硬件、固件、调试三类分开列。

5.1 硬件层面的坑

5.2 固件与软件层面的坑

5.3 调试与验证的独门技巧

如果条件允许，一块板子到手先不要急着装整机，先上测试架，把电机全部拆掉，用扎带把飞控固定在一个稳定的底座上，然后通过QGroundControl查看姿态数据，拿手模拟翻滚和俯仰，观察地面站里的虚拟飞机是否同样旋转。这一步能验证IMU方向对不对。

另一个很实用的技巧是看日志。PX4的ulog文件记录了所有传感器原始数据、估计器输出和控制指令，真机出现问题后，下载日志打开Flight Review网页上传，能自动生成一份分析报告，哪里出现了EKF警告、哪里振动超标，一目了然。这比自己瞎猜高效太多。

还有一条关于避震的经验。STM32H7飞控常见的“EKF加速度计数据不一致”报错，很多时候不是传感器坏了，而是PCB板上没有做减震。飞控安装时用那种带泡棉的双面胶或者专用的减震球，能过滤掉电机高频振动对IMU的影响。我第一版直接裸板装在机架上，EKF的innovation值一直偏高，加了减震之后立刻就正常了。

关于电源我最后再说一句：不要把飞控和电调的电源地混在一起长距离走线。电调打火瞬间电流非常大，地线上的压降会直接干扰到MCU的ADC采样和IMU数据，严重的时候整个板子都会瞬间掉电重启。飞控电源输入处加一个大容量钽电容或者固态电容，是我认为成本最低、效果最明显的稳定性改造。

写在最后给的几点心得

这套H7飞控从画板到调通，我实际花了大概三周，但其实真正卡住我的只有两件事：一个是SPI总线的DMA冲突，另一个是第一次烧录bootloader后应用固件老是加载不起来。前者是硬件设计问题，后者则是因为我直接用旧的Pixhawk bootloader，而它和v1.14固件不兼容，换成官方针对H7的新bootloader后，一切就顺了。

如果你也准备做这件事，我的建议是先把官方px4_fmu-v6x的板子跑起来，哪怕用现成的Pixhawk 6X飞控，也要先在QGC里刷一次固件、看一遍日志，感受一下PX4“正常”的状态数据长什么样。这样当你自己板子出现异常时，才能快速判断问题出在硬件还是固件配置。整个过程最核心的不是“代码”，而是把硬件设计与PX4的软件框架对齐，只要引脚对、时钟对、供电稳，PX4基本一次就能跑起来。