📚 课程目录第3章 PX4日志系统基础

3、PX4日志系统基础：日志记录原理、日志文件生成位置、常用日志工具（如ulog2csv、pyulog）的安装与使用

PX4自动驾驶仪在飞行过程中会持续记录大量传感器数据、控制指令、状态估计和PWM输出信号，这些数据被封装为ULog格式的日志文件。ULog（Unified Logging）是PX4自v1.6.0版本起采用的统一日志格式，它取代了早期的SDLog2格式，以二进制方式紧凑存储数据，支持多线程写入和按主题订阅的数据流。理解日志记录原理、掌握日志文件的位置以及熟练使用日志解析工具，是进行回放调试、模型输出与控制指令对齐分析的前提。本章将系统讲解PX4日志系统的底层机制、文件管理方式以及常用工具链的安装与操作流程。

上图展示了PX4日志系统的完整链路。左侧为数据采集层，各模块通过uORB消息总线发布主题数据；中间为存储与生成层，ULog写入器订阅指定主题并序列化写入SD卡；右侧为解析与工具层，开发者通过pyulog、ulog2csv等工具将二进制日志转换为可分析的文本或可视化数据。整个链路中，时间戳对齐是回放调试的核心，所有数据均以微秒级时间戳记录，确保后续可以精确比对模型输出与控制指令的时序关系。

3.1 日志记录原理：uORB主题订阅与ULog封装

PX4的日志系统基于uORB（Micro Object Request Broker）消息总线构建。每个传感器、估计器或控制模块在运行时都会向uORB发布特定主题的数据，例如sensor_imu、vehicle_attitude、actuator_outputs等。日志记录器（logger模块）在启动时会根据配置订阅一组预定义的主题，并将这些主题的数据流写入ULog文件。

ULog文件格式采用分层结构：文件头（Header）包含版本信息和时间戳偏移量；随后是定义区（Definitions），记录消息类型、格式和主题元数据；最后是数据区（Data），按时间顺序存储各主题的实际数据。这种设计使得日志文件自描述，解析工具无需外部配置文件即可理解数据结构。

  核心原理要点：
  主题订阅机制：logger模块通过uORB::Subscription接口订阅主题，默认订阅约50-80个主题，涵盖传感器原始数据、滤波后状态、控制输出、电池电压、GPS位置等。
环形缓冲：为避免高频数据（如IMU 1kHz）阻塞写入，logger使用环形缓冲区暂存数据，后台线程异步写入SD卡。
时间戳对齐：每条日志消息都带有硬件时间戳（基于系统时钟），回放时通过时间戳插值对齐不同频率的数据流。
丢帧处理：当SD卡写入速度跟不上数据产生速率时，logger会丢弃部分低优先级消息，并在日志中记录丢帧计数，便于分析数据完整性。

日志记录频率受限于SD卡写入速度和日志主题数量。默认配置下，PX4以约250Hz记录控制相关数据，以50Hz记录导航数据，以10Hz记录电池和温度等慢变数据。开发者可通过修改SDLOG_RATE参数调整最大记录速率，或通过SDLOG_TOPICS参数自定义需要记录的主题列表。

3.2 日志文件生成位置与命名规则

PX4日志文件默认存储在SD卡的/fs/microsd/log/目录下。每次飞行或地面测试会生成一个新的子目录，命名格式为YYYY-MM-DD，在该目录下，日志文件以HH_MM_SS.ulg格式命名，表示起飞或开始记录的时刻。例如：

/fs/microsd/log/2024-01-15/10_30_45.ulg
/fs/microsd/log/2024-01-15/11_02_18.ulg

如果SD卡不存在或写入失败，PX4会尝试将日志写入内部Flash存储（仅限部分硬件），但容量有限且不推荐长期使用。对于没有SD卡槽的飞控板（如部分Omnibus F4），可以通过USB连接计算机，使用listener命令实时查看日志数据，或通过MAVLink将日志传输到地面站。

存储位置	路径/接口	适用场景	注意事项
SD卡（推荐）	/fs/microsd/log/	正常飞行测试、长时间记录	确保SD卡格式为FAT32，写入速度≥10MB/s
内部Flash	/fs/mtd/	紧急备份、无SD卡环境	容量小（通常1-4MB），仅记录关键数据
MAVLink流	通过QGC或MAVProxy	实时调试、短时数据采集	受限于数传带宽，不适合高频数据

在回放调试前，应首先确认日志文件是否完整生成。可以通过检查文件大小（正常飞行10分钟约产生50-200MB日志）和文件末尾的结束标志（ULog文件以0x00结尾）来判断日志是否正常关闭。异常断电或强制关机可能导致日志文件损坏，此时需要借助pyulog的容错解析功能尝试恢复数据。

3.3 常用日志工具安装与使用

PX4官方提供了一套完整的Python日志工具链，主要包括pyulog库和若干命令行工具。这些工具支持跨平台运行（Windows/Linux/macOS），是进行日志解析、数据提取和格式转换的基础。

3.3.1 pyulog库的安装

pyulog是PX4日志解析的核心Python库，可以通过pip直接安装：

# 安装pyulog及其命令行工具
pip install pyulog

# 验证安装
python -c "import pyulog; print(pyulog.__version__)"

安装完成后，系统会提供ulog_info、ulog_messages、ulog2csv、ulog2kml等命令行工具。如果希望使用最新开发版本，可以从GitHub克隆源码并执行pip install -e .安装。

3.3.2 ulog2csv：将ULog转换为CSV格式

ulog2csv是最常用的日志转换工具，它将ULog中的每个主题数据提取为独立的CSV文件，便于在Excel、MATLAB或Python pandas中进一步分析。基本用法如下：

# 转换单个日志文件
ulog2csv flight_2024-01-15.ulg

# 指定输出目录
ulog2csv flight.ulg -o ./csv_output/

# 只提取特定主题
ulog2csv flight.ulg -m vehicle_attitude -m actuator_outputs

转换完成后，输出目录中会生成多个CSV文件，命名格式为主题名_时间戳.csv。每个CSV文件的第一列为时间戳（微秒），后续列为该主题的各个字段。例如vehicle_attitude_0.csv包含timestamp、q[0]、q[1]、q[2]、q[3]等列，分别对应四元数的四个分量。

经验提示：当需要分析模型输出与控制指令的对齐关系时，建议同时提取vehicle_attitude（模型姿态）、vehicle_attitude_setpoint（期望姿态）、actuator_controls（控制指令）和actuator_outputs（实际PWM输出）四个主题。使用pandas的merge_asof函数可以按时间戳近似匹配不同频率的数据。

3.3.3 ulog_info与ulog_messages：快速查看日志摘要

在深入分析之前，先用ulog_info查看日志的基本信息，包括持续时间、主题列表、消息类型和错误计数：

ulog_info flight.ulg

# 输出示例
Log file: flight.ulg
Size: 128 MB
Duration: 623.5 s
Number of messages: 152340
Topics:
  - actuator_controls_0: 12450 msgs
  - actuator_outputs: 12450 msgs
  - sensor_imu: 623500 msgs
  - vehicle_attitude: 6235 msgs
  ...

ulog_messages用于提取日志中记录的文本消息（如警告、错误、调试信息），这些消息对于排查故障原因至关重要：

ulog_messages flight.ulg

# 输出示例
[ 12.345] WARN: EKF2 IMU0 stopped NAV
[ 45.678] ERROR: PWM output saturation detected on channel 3

3.4 实战案例：使用pyulog提取并对比姿态数据

下面通过一个完整的案例演示如何使用pyulog库编写Python脚本，提取姿态数据并对比模型输出与控制指令的时间对齐关系。假设我们有一份包含异常偏航行为的日志yaw_drift.ulg，需要分析偏航角速率指令与实际响应之间的延迟。

import pyulog
import pandas as pd
import numpy as np

# 1. 加载ULog文件
ulog = pyulog.Pyulog('yaw_drift.ulg')

# 2. 提取偏航角速率设定值（控制指令）
ctrl_data = ulog.get_dataset('vehicle_rates_setpoint')
ctrl_df = pd.DataFrame({
    'timestamp': ctrl_data.data['timestamp'],
    'yaw_rate_sp': ctrl_data.data['yaw']
})

# 3. 提取实际偏航角速率（模型输出）
rate_data = ulog.get_dataset('vehicle_rates')
rate_df = pd.DataFrame({
    'timestamp': rate_data.data['timestamp'],
    'yaw_rate': rate_data.data['yaw']
})

# 4. 按时间戳对齐（使用merge_asof近似匹配）
ctrl_df = ctrl_df.sort_values('timestamp')
rate_df = rate_df.sort_values('timestamp')
merged = pd.merge_asof(ctrl_df, rate_df, on='timestamp', direction='nearest', tolerance=5000)

# 5. 计算延迟（通过互相关或峰值检测）
# 简化方法：计算设定值变化到实际值变化的时间差
diff_sp = np.diff(merged['yaw_rate_sp'])
diff_act = np.diff(merged['yaw_rate'])
# 找到设定值阶跃点
step_idx = np.where(np.abs(diff_sp) > 0.5)[0]
if len(step_idx) > 0:
    first_step = step_idx[0]
    # 查找实际值达到90%目标值的时间
    target = merged['yaw_rate_sp'].iloc[first_step+1]
    actual = merged['yaw_rate'].iloc[first_step:]
    reach_idx = np.where(np.abs(actual - target) < 0.1 * np.abs(target))[0]
    if len(reach_idx) > 0:
        delay_us = merged['timestamp'].iloc[first_step+1+reach_idx[0]] - merged['timestamp'].iloc[first_step]
        print(f"偏航角速率响应延迟: {delay_us/1000:.1f} ms")
    else:
        print("未找到响应达到目标的时间点")
else:
    print("未检测到明显的设定值阶跃")

该脚本首先从ULog中提取vehicle_rates_setpoint（控制指令）和vehicle_rates（模型输出）两个主题的数据，然后通过时间戳近似匹配将两组数据对齐，最后通过检测设定值阶跃和实际响应达到90%目标值的时间差来计算系统延迟。在实际调试中，如果发现延迟超过50ms，通常表明控制回路存在异常，需要检查滤波器参数或执行机构响应速度。

风险提示：在分析日志时，务必注意时间戳的单位。PX4日志中的时间戳默认以微秒（µs）为单位，而部分工具（如FlightPlot）可能显示为毫秒或秒。统一单位是避免误判的关键。另外，不同主题的记录频率差异较大（IMU可达1kHz，而GPS仅5-10Hz），在对比低频数据时，应使用插值或重采样方法，避免直接使用最近邻匹配导致的时间偏差。

3.5 常见误区与总结复盘

在日志系统使用过程中，开发者常遇到以下问题，需要特别注意：

误区/问题	现象	解决方案
日志文件不完整	文件大小异常小，或解析时报错	检查SD卡剩余空间和写入速度；使用`ulog_info`查看是否有"unclean shutdown"标记
时间戳不同步	不同主题的时间戳偏移明显	确认所有模块使用同一时钟源；检查是否存在时钟跳变（如GPS PPS校正）
数据频率不足	控制指令曲线呈阶梯状	降低`SDLOG_RATE`参数值，或通过`SDLOG_TOPICS`减少不必要主题的记录
误用CSV时间戳	时间轴显示异常	ulog2csv输出的时间戳为微秒，转换为秒需除以1e6

总结复盘：PX4日志系统是飞行调试的“黑匣子”，其核心价值在于提供了完整的、时间对齐的飞行数据。掌握日志记录原理有助于理解数据来源和潜在误差；熟悉日志文件位置和命名规则能快速定位目标日志；熟练使用pyulog和ulog2csv等工具则是进行深度分析的前提。在实际调试中，建议建立标准化的日志分析流程：先使用ulog_info快速检查日志健康度，再通过ulog_messages查看异常消息，最后针对具体问题提取相关主题进行定量分析。对于模型输出与控制指令的对齐问题，务必关注时间戳精度和不同主题间的频率差异，必要时采用插值或重采样技术确保数据可比性。