前面六篇都在讲系统怎么跑。这篇换个角度——跑完之后怎么查。

每次飞行结束，SD卡里会多出一个.ulg文件。这个文件就是PX4的"黑匣子"，记录了飞行过程中几乎所有uORB topic的数据。出问题了翻日志，调参看日志，复盘也看日志。不会看日志，等于白飞。

我把uLog的格式、记录机制、分析工具链和常见排查套路整理一遍。

uLog文件格式：自描述的二进制流

uLog是PX4专用的日志格式，核心设计原则是自描述——文件里包含了自己的schema，解析器不需要外部定义文件就能读懂内容。

文件分三段：Header、Definitions、Data。

Header（16字节，固定长度）

| 0x55 0x4c 0x6f 0x67 0x01 0x12 0x35 | 0x01         | uint64_t       |
| File magic (7B)                    | Version (1B) | Timestamp (8B) |

Magic字节是"ULog"加三个固定字节0x01 0x12 0x35。Version目前是1。Timestamp是日志开始时间（微秒）。就这16字节，简单粗暴。

Definitions段：schema在这里

这一段记录了消息格式定义、系统版本、初始参数。每条消息前面有个3字节的header（msg_size: uint16 + msg_type: uint8），msg_type用单字符标识：

'F'消息是最关键的，它定义了每个uORB topic的结构。比如：

sensor_combined:uint64_t timestamp;float[3] gyro_rad;float[3] accel_m_s2;

解析器读到这条定义后，就知道Data段里sensor_combined类型的消息该怎么拆字段了。这就是"自描述"——格式定义和数据一起存，不需要额外的IDL或proto文件。

Data段：飞行数据主体

'D'消息占Data段99%以上的空间。每条'D'消息只有3字节header + 2字节msg_id + 数据体，非常紧凑。

'L'消息是PX4运行时的printf输出，按Linux内核日志级别分类：0=EMERG、1=ALERT、2=CRIT、3=ERR、4=WARNING、5=NOTICE、6=INFO、7=DEBUG。出问题时先看'L'消息的WARNING和ERR，通常能直接定位。

'O'消息记录数据丢失。SD卡写入速度跟不上的时候，Logger会丢弃部分数据，记一个Dropout。如果看到大量Dropout，要么换更快的SD卡，要么减少记录的topic数量。

Logger模块：谁在写日志

Logger模块（src/modules/logger/）是uLog的写入引擎。它订阅uORB上的topic，按定义格式写入SD卡。

启动逻辑

Logger在系统启动时就运行，但默认只在解锁后才开始写日志（SDLOG_MODE=0）。写入流程：

1. 解锁触发 → start_log_file() → 写Header + Definitions
2. Definitions包括：write_header、write_version、write_formats、write_parameters、write_parameter_defaults
3. 进入主循环，按配置的topic列表订阅并写入Data段
4. 上锁触发 → stop_log_file() → 关闭文件

记录哪些topic

Logger有一个默认的topic列表，定义在logged_topics.cpp里。默认记录的核心topic包括：

• sensor_combined：IMU原始数据
• vehicle_attitude：姿态（四元数）
• vehicle_local_position：本地位置估计
• vehicle_global_position：全局位置估计
• vehicle_status：飞行状态和模式
• actuator_controls：PID输出
• actuator_outputs：电机PWM
• battery_status：电池状态
• estimator_status：EKF状态
• vehicle_gps_position：GPS数据

这些是飞行分析的最小集合。需要更多数据时，通过SDLOG_PROFILE切换记录配置。

记录频率

默认约50Hz记录大多数topic。高优先级的topic（如sensor_combined）可以更高频率。如果开了高频率日志profile（SDLOG_PROFILE bit 3），IMU原始数据可以到kHz级别。

SD卡选择

SD卡写入速度直接影响日志质量。低速卡会导致Dropout，极端情况下Logger跟不上会丢数据。PX4官方建议用Class 10或U3卡。SanDisk Extreme系列实测比较稳定。

SD卡空间不足时，Logger会自动删除最旧的日志目录（阈值约50MiB），保证始终有空间记录新数据。

日志配置参数

SDLOG_MODE选项：

SDLOG_PROFILE是位掩码，按需开启：

调PID的时候建议开bit 3（高频率IMU），能看清角速率环的跟踪细节。调完记得关掉，否则日志文件会很大。

分析工具链

Flight Review：在线快速看

Flight Review（https://logs.px4.io）是PX4官方的在线日志分析工具。上传.ulg文件后自动生成报告，包括：

• 飞行轨迹2D/3D地图
• 姿态跟踪曲线
• 振动频谱图（加速度PSD）
• 电池电压/电流曲线
• GPS精度指标
• 控制器跟踪性能

优点是零配置，拖拽上传就行。缺点是交互能力有限，不能自由选择topic和字段。快速排查用Flight Review，深度分析用PlotJuggler。

PlotJuggler：深度分析利器

PlotJuggler是PX4推荐的桌面分析工具，功能远超Flight Review：

基本操作：左侧topic列表搜索 → 拖拽字段到右侧图表。支持多面板分屏，时间轴同步。

四元数转欧拉角：搜vehicle_attitude → 展开q[4] → Tools菜单 → Quaternion to RPY → 自动生成roll/pitch/yaw曲线。

2D轨迹：Ctrl选中vehicle_local_position的x和y → 右键拖拽 → 生成2D散点图，直接看飞行轨迹。

多面板关联：水平/垂直分屏，同时显示姿态、速度、电池电流。移动时间游标，所有面板同步联动——这是排查问题的关键能力，单张图很难定位根因。

自定义函数：支持对数据做数学变换，比如速度取模、角速度求差，不需要导出CSV再到MATLAB算。

pyulog：命令行工具集

pyulog是Python解析库，附带一组命令行工具：

# 查看日志概要
ulog_info flight.ulg

# 提取所有参数
ulog_params flight.ulg > params.txt

# 查看printf日志
ulog_messages flight.ulg

# 转CSV
ulog2csv flight.ulg

# 转KML（Google Earth看轨迹）
ulog2kml flight.ulg

ulog_info输出里最值得关注的是Dropout统计和topic列表。Dropout多说明SD卡有问题，topic列表告诉你实际记录了哪些数据。

pyulog也可以当Python库用，写自定义分析脚本：

import pyulog
ulg = pyulog.ULog('flight.ulg')
attitude = ulg.get_dataset('vehicle_attitude')
timestamps = attitude.data['timestamp']
roll_rate = attitude.data['rollspeed']  # rad/s

pyFlightAnalysis：3D可视化

pyFlightAnalysis支持3D姿态可视化，可以回放飞行过程。适合分析特定时刻的飞机姿态变化，比如降落阶段的俯仰角变化。不过日常用PlotJuggler就够了。

常见排查套路

震动分析

震动是最常见的问题。高震动导致EKF发散、定高定点漂移。

排查步骤：

1. Flight Review看加速度PSD图——好的震动是低频区黄线，高频区蓝/绿；差的是大面积黄色
2. PlotJuggler打开sensor_combined的accel_m_s2，缩放到悬停段——Z轴应该是一条细线，如果Z轴曲线碰到X/Y轴，震动过大
3. 开启SDLOG_PROFILE bit 3/5/6获取高频率IMU数据，用FFT看频谱峰值位置

经验值：悬停时加速度Z轴峰峰值超过2-3 m/s²就有问题，需要减震或调滤波器。如果频谱在50Hz附近有强峰值（起落架松动），80Hz低通滤波器挡不住。

GPS异常

GPS跳变会导致位置估计突变，飞机突然猛飞。

排查步骤：

1. 看vehicle_gps_position的hdop和satellites_used——hdop < 1.5好，> 2.0差；卫星数 < 12差
2. estimator_status的pos_test_ratio——GPS数据一致性检验比率，> 1说明GPS数据被EKF拒了
3. 关联vehicle_local_position的位置跳变时刻和GPS的hdop恶化时刻

电池健康

电池老化会导致内阻增大，大油门时电压骤降触发failsafe。

排查步骤：

1. battery_status的voltage_v和current_a——画在同一时间轴上
2. 看大油门时电压跌落幅度——新电池跌0.3-0.5V正常，跌1V以上内阻过大
3. battery_status的discharged_mah看实际消耗容量，跟标称容量对比

PID跟踪性能

调完PID必须看日志验证。

排查步骤：

1. vehicle_attitude的角速度（rollspeed/pitchspeed/yawspeed）vs actuator_controls的设定值
2. PlotJuggler分屏同时看设定值和实际值，间距越小跟踪越好
3. 开SDLOG_PROFILE bit 3获取高频率数据，看清角速率环的细节

断电/崩溃

日志在中途截断，飞机在空中突然没数据了。

排查步骤：

1. 先看SD卡根目录有没有fault_*.log文件——STM32的hard fault日志
2. ulog_info看最后一条消息的时间戳，判断是否在飞行中截断
3. 如果没有fault文件且最后一条是正常数据，大概率是电源问题（电压瞬降导致复位）
4. 看battery_status最后几秒的电压曲线，是否有骤降

与ArduPilot DFLog对比

uLog最大的优势是自描述——不同版本的PX4可以生成不同的topic结构，解析器不需要升级就能读。DFLog是固定格式，新字段加了旧解析器可能不认识。

uLog的劣势是社区生态小一些。ArduPilot的DFLog有MAVExplorer这个成熟工具，脚本扩展性很强。uLog主要靠PlotJuggler和pyulog，生态在完善中。

踩坑记录

1. 日志没写上

最常见的原因是SDLOG_MODE=0（默认），只有解锁后才写。如果开机到解锁之间出了问题（比如传感器初始化失败），这段数据没记。排查启动问题设SDLOG_MODE=2（开机到关机）。

2. 高频日志把卡写满了

开了SDLOG_PROFILE bit 3（高频率IMU），一条5分钟的日志可能上百MB。32GB的SD卡也就存几十条。调完参记得关掉。

3. Dropout太多

ulog_info显示Dropout count很高。检查SD卡速度（换U3卡），减少记录的topic（用SDLOG_PROFILE只开需要的），或者降低记录频率。

4. PlotJuggler打不开.ulg

Windows上最新版PlotJuggler有时不兼容.ulg，回退到v2.8.4可以解决。Linux用AppImage没问题。

5. 时间戳对不上

uLog里的timestamp是系统启动后的微秒数（boot time），不是UTC时间。要对应实际时间，加上SDLOG_UTC_OFFSET和Header里的起始时间。

小结

uLog是PX4的飞行数据记录系统，自描述二进制格式，Logger模块在解锁时自动写SD卡。分析工具有三层：Flight Review快速看、PlotJuggler深度分析、pyulog命令行处理。常见排查套路就那几个：震动看加速度PSD、GPS看hdop和卫星数、电池看电压跌落、PID看角速率跟踪、断电看fault日志。

系列到这基本把PX4的核心模块都过了一遍：数据流全貌→EKF2融合→uORB通信→PID控制链路→Commander决策→Navigator路径规划→uLog事后分析。从传感器到电机，从起飞到落地，从实飞到复盘，整条链路串起来了。

本文代码为简化后的核心逻辑，方向正确但不是PX4真实代码。参数名和默认值已对照PX4官方文档校验。