飞控日志系统记录设计方案

1 概述

2 需求分析

2.1 当前日志功能

2.2 新版本日志功能

3 功能性能指标

3.1 功能指标

3.2 性能指标

4 方案设计

4.1 软件设计方案

4.1.1 总体设计方案

4.1.1.1 系统初始化

4.1.1.2 数据采集与uORB主题订阅

4.1.1.3 数据存储到ULog文件

4.1.1.4 扩展日志功能（暂不添加）

4.1.1.5 文件管理与系统退出

4.1.2 软件流程设计

4.1.2.1 系统初始化

• 检查存储设备：系统启动时，首先对存储设备进行检查，以确保有足够的空间记录日志数据。如果存储设备不可用，系统将报告错误并退出，以防止因存储问题导致的数据丢失。

• 加载系统参数：在确认存储设备可用后，系统加载日志记录所需的参数配置。这些参数包括日志记录频率、日志文件的存储路径、以及日志记录的模式（例如自动启动或手动触发等）。

• 检查日志目录：系统会验证日志目录是否已存在。如果不存在，系统将自动创建一个新的日志目录，用于存储日志文件。

• 日志目录命名：在成功创建或确认日志目录存在后，系统会根据当前时间或会话编号对日志目录进行命名。这样可以确保每次飞行的日志文件存储在独立的目录中，便于数据管理和后期分析。

• 创建ULog文件名：接下来，系统为ULog日志文件生成一个文件名，通常基于时间戳，以确保文件名的唯一性。这样可以避免文件覆盖和数据丢失问题。

• 分配内存和缓存资源：系统为日志记录分配必要的内存空间和缓存资源，以支持高频数据记录需求。这一步确保在实际记录过程中有足够的资源进行高效的数据写入和存储。

• 设置日志记录频率和模式：最后，系统根据加载的参数配置设定日志记录频率和模式。设定完成后，系统初始化过程结束，进入日志记录线程，开始数据采集和记录。

4.1.2.2 数据采集与uORB主题订阅

• 获取配置的uORB主题列表：系统根据初始化时加载的配置文件或参数，获取需要记录的uORB主题列表。这些主题代表了系统中不同类型的传感器数据和飞行状态信息，如vehicle_status、sensor_combined等。

• 初始化主题订阅：系统为每个主题创建订阅实例，确保可以实时接收这些主题上发布的数据。通过uORB的发布-订阅机制，系统可以在主题更新时立即获取数据，从而保证数据的实时性。

• 进入数据采样循环：系统进入数据采样循环，开始持续监测和获取已订阅主题上的数据。该循环在日志系统运行期间不断重复，以确保实时数据采样。

• 检测主题是否有新数据：系统在每次循环中检查各个主题是否有新的数据更新。如果有主题更新了数据，说明有新的传感器数据或飞行状态需要记录。

• 采集新数据：当检测到某个主题有新数据发布时，系统立即采集该数据。这样可以确保所有重要的飞行信息在被发布到uORB主题上时，能够立即被日志系统捕捉到。

• 缓存数据：采集到的新数据会暂时存入系统的缓存中，以便后续的批量写入操作。这种做法可以减少频繁的文件写入操作，优化数据存储性能。

• 检查是否达到写入频率：系统检查是否达到了预设的写入频率。只有在满足频率要求时，数据才会从缓存中写入到文件中。这种设计可以有效控制数据存储的频率，防止系统资源被过度消耗。

• 将数据存入缓存区：如果达到写入频率，系统会将当前采集的所有数据存入缓存区，准备批量写入到ULog文件中。否则，数据将继续在缓存中等待，直到下一个满足写入频率的时刻。

4.1.2.3 数据存储到ULog文件

• 开始数据采集：系统开始数据的采集过程。

• 是否启用日志记录：判断是否启用了日志记录功能，如果未启用，则继续数据采集而不记录日志。

• 打开ULog文件：如果日志记录启用，打开对应的 ULog 文件，用于存储数据。

• 初始化日志数据结构：为即将记录的数据初始化 ULog 日志的结构和格式。

• 从uORB主题订阅数据：从飞控系统的 uORB 中订阅相应的主题数据。

• 序列化数据为ULog格式：将采集到的数据按照 ULog 格式进行序列化，以符合 ULog 文件的存储格式。

• 是否需要缓存：判断是否需要将数据缓存，以优化写入效率。若缓存，则先存入缓存区，后续写入；否则直接写入文件。

• 写入ULog文件：将序列化后的数据写入 ULog 文件。

• 日志记录是否结束：判断日志记录是否结束。如果没有结束，则继续从 uORB 主题订阅数据。如果结束，则关闭 ULog 文件并结束整个流程。

• 关闭ULog文件：当日志记录结束时，关闭 ULog 文件，释放资源。

4.1.2.4 扩展日志功能（暂不添加）

• 启用扩展日志功能：启动扩展日志功能，用于记录额外的数据。

• 扩展日志已启用?：检查是否已经启用了扩展日志功能。如果未启用，系统会等待扩展日志的启动。

• 创建扩展日志线程：如果启用了扩展日志功能，创建一个独立的扩展日志线程来处理日志记录。

• 初始化扩展日志数据结构：为扩展日志准备数据结构，确保数据能够正确记录。

• 从uORB主题订阅扩展数据：订阅 uORB 中额外的主题数据，这些数据将被记录到扩展日志中。

• 序列化数据为ULog格式：将订阅到的扩展数据序列化为 ULog 格式，确保数据符合日志格式要求。

• 是否需要缓存?：判断是否需要缓存扩展数据，如果需要，数据会先存入缓存区，稍后再写入。

• 将扩展数据缓存：在需要缓存的情况下，数据会暂时存放在缓存区。

• 写入扩展日志文件：将序列化后的扩展数据写入扩展日志文件。

• 扩展日志记录结束?：判断扩展日志记录是否结束。如果没有结束，则继续订阅和记录数据。如果结束，则关闭日志文件。

• 关闭扩展日志文件：当扩展日志记录结束时，关闭文件并释放相关资源。

• 结束扩展日志线程：结束扩展日志的线程，完成所有记录任务。

• 扩展日志功能结束：扩展日志功能完成，流程结束。

4.1.2.5 文件管理与系统退出

• 日志系统启动：日志系统启动并准备记录日志。

• 日志系统是否运行中?：检查日志系统是否已经运行。如果未运行，系统等待日志系统的启动。

• 检查可用存储空间：检查系统中剩余的存储空间，确保日志能够正常写入。

• 存储空间充足?：判断存储空间是否足够。如果不够，系统会发出存储空间不足的警告。

• 发送存储空间不足警告：当存储空间不足时，向用户发出警告信息，提醒存储空间不足。

• 创建日志文件目录：如果存储空间充足，系统会为本次日志创建新的文件目录。

• 打开日志文件：在文件目录下创建并打开日志文件，准备记录数据。

• 写入日志数据：将日志数据写入到已经打开的日志文件中。

• 日志系统是否需要关闭?：判断日志系统是否需要关闭。如果不需要关闭，则继续写入日志数据。

• 关闭日志文件：当日志系统需要关闭时，首先关闭日志文件，确保数据写入完毕。

• 释放文件句柄：释放文件句柄，确保系统资源得到有效释放。

• 关闭扩展日志线程：关闭扩展日志的线程，结束所有日志记录的操作。

• 系统退出并清理资源：系统退出，并释放所有相关的资源，确保系统清理干净。

• 日志系统退出完成：日志系统退出完成，整个文件管理和系统退出流程结束。

4.2 技术关键点设计

4.2.1 任务调度处理

• 1：任务创建与删除设计
在设计中，我们使用VxWorks的taskSpawn函数来替代POSIX的pthread_create实现任务的创建。taskSpawn允许我们为每个任务设定独立的优先级、堆栈大小以及任务入口函数，与此同时，也可以在创建时直接指定任务选项（如任务是否浮点支持等）。为保证资源释放，在任务结束时调用taskDelete替代POSIX的pthread_cancel或pthread_join，从而在VxWorks环境中实现自动资源清理。这样，设计方案确保了任务的创建与销毁过程在VxWorks环境中的平稳过渡。

• 2：任务优先级设置设计
VxWorks任务优先级设置通过taskSpawn的优先级参数完成初始优先级设定，并在需要时使用taskPrioritySet动态调整优先级。相较于POSIX中需要通过pthread_attr_t或pthread_setschedparam进行较为复杂的优先级调整，设计方案直接利用VxWorks的优先级设置机制，以0-255的范围精确控制任务优先级，并通过在关键任务前调用taskPrioritySet提升其优先级，确保高优先级任务及时响应。这一设计可以避免任务阻塞或延迟，提高任务调度的实时性。

• 3：任务状态管理设计
在VxWorks中，任务的多状态管理（READY、SUSPEND、PEND、DELAY等）使得替换POSIX线程状态更加高效。在任务运行过程中，通过taskSuspend和taskResume实现对任务的挂起和恢复，替代POSIX中的pthread_cond_wait和pthread_cond_signal功能。具体设计中，将使用taskSuspend实现对无用或非优先级任务的挂起，当需要恢复任务时，通过taskResume迅速重新激活任务，以达到资源节省和任务管理优化的目的。此设计方案简化了状态管理，增强了任务调度的控制力。

• 4：任务同步机制设计
为了保证任务间同步，设计方案采用VxWorks的信号量和事件标志来替代原有POSIX的pthread_mutex和pthread_cond等同步机制。例如，将VxWorks的semTake和semGive替换pthread_mutex_lock和pthread_mutex_unlock，保证互斥访问。同时，为了实现条件通知，将事件标志eventSend应用于重要信号传递，替代POSIX的条件变量。此替换设计不仅简化了代码结构，还能在高负载情况下提升任务同步的可靠性。

• 5：任务时间控制设计
VxWorks的taskDelay为任务的时间控制提供了简洁的实现方法，取代了POSIX的nanosleep或定时器的复杂实现。在设计中，将通过taskDelay实现任务的延迟控制，确保非实时任务在等待期间不占用系统资源，从而减少系统调度压力。同时，taskDelay的使用确保了每个任务可独立定义时间片，从而实现更精确的任务执行控制，满足系统的实时性需求。

4.2.2 ULog 数据类型

1. 基本数据类型
在这个示例中，我们定义了一个结构体 sensor_combined_s，包含了 uint64_t timestamp、float 数组（用于存储陀螺仪和加速度计数据），以及对齐字节（_padding0 和 _padding1）。这些字段在 ULog 文件中按照顺序存储，以确保数据对齐并避免未定义的行为。
注意：由于C语言的结构体在不同平台上的内存对齐策略可能有所不同，ULog在记录数据时通常需要考虑内存对齐（padding）的问题。为了确保跨平台的一致性，ULog在日志文件中存储数据时会显式地去除这些对齐字节，以保证每个字段的数据紧凑排列。例如，在上述结构体中，float gyro_rad[3] 后面会有一个对齐字节 _padding0 以便接下来的 float accel_m_s2[3] 能够在合适的内存地址上对齐。因此，日志模块在写入或读取数据时需要正确地处理这些对齐字节，确保数据的一致性。

2. 数组类型
在日志中，数组会按照定义的长度依次存储，每个 float 类型占用 4 个字节，总共存储 5 * 4 = 20 字节。

4.2.3 uORB 编译工作流

1. 消息文件配置
在项目的源代码目录中的一个msg子目录（路径为：lkd_kfs_110_vip/modules/uORB/msg），其中存放所有uORB消息定义的.msg文件。每个文件包含一个消息的结构定义，例如传感器数据、控制指令等。这些文件是uORB框架内模块之间交换数据的基础。

2. 生成uORB头文件
使用 px_generate_uorb_topic_files.py 脚本，根据消息文件（msg文件）生成对应的uORB头文件。该脚本通过em模板引擎将消息定义转换为C++代码，用于描述消息的结构和类型。具体步骤如下：
1. 脚本解析传入的命令行参数，指定生成头文件的操作。
2. 使用 msg_loader 模块加载消息定义，提取每个字段的信息。
3. 通过em模板引擎处理模板文件，将字段信息填充到模板中，以生成每个消息类型的C++头文件。
命令如下（假设源码位于$SOURCE_DIR，消息文件位于$SOURCE_DIR/modules/uORB/msg，并且当前位于$SOURCE_DIR，生成的文件将存放在$SOURCE_DIR/module/uORB/topics中）：

3. 生成uORB压缩字段文件
为了优化消息占用的带宽和存储，使用 px_generate_uorb_compressed_fields.py 脚本生成压缩的uORB消息字段的C++源文件和头文件。该脚本解析上一步生成的JSON文件，并通过heatshrink压缩算法对消息字段进行压缩，以减少占用空间。具体方法如下：
1. 脚本首先解析输入的JSON文件，提取每个消息的字段定义和依赖关系。
2. 使用深度优先搜索的方式，按照依赖关系对字段进行排序，以确保嵌套类型优先生成。
3. 使用 heatshrink_encode 模块对字段进行压缩，并生成对应的C++代码，其中包括用于解压缩的函数。
4. 最终生成的文件包括压缩后的字段定义和辅助函数，用于在运行时进行解压缩。
命令如下（假设源码位于$SOURCE_DIR，消息文件位于$SOURCE_DIR/modules/uORB/msg，并且当前位于$SOURCE_DIR，生成的文件将存放在$SOURCE_DIR/modules/uORB/topics_sources中）：

4. 生成microcdr头文件
使用 px_generate_uorb_topic_files.py 脚本，根据消息文件生成与microcdr相关的头文件，这些头文件用于支持微型序列化和反序列化操作，通常用于高效的数据传输。具体步骤如下：
1. 脚本解析传入的命令行参数，指定生成microcdr头文件的操作。
2. 使用em模板引擎处理模板文件，生成与消息相关的microcdr头文件，以支持数据的高效传输和序列化。
命令如下（假设源码位于$SOURCE_DIR，消息文件位于$SOURCE_DIR/modules/uORB/msg，并且当前位于$SOURCE_DIR，生成的文件将存放在$SOURCE_DIR/modules/uORB/ucdr中）：

5. 生成uORB源文件
最后，使用 px_generate_uorb_topic_files.py 脚本，根据消息文件生成对应的uORB源文件。这些源文件实现了消息发布、订阅以及消息数据的读取与写入功能。具体步骤如下：
1. 脚本解析传入的命令行参数，指定生成源文件的操作。
2. 使用 msg_loader 模块加载消息定义，并通过em模板引擎将字段信息填入模板文件中，生成对应的C++源文件。
3. 生成的源文件实现了对每个消息类型的操作函数，例如消息的发布与订阅，以支持PX4系统中的模块间通信。
命令如下（假设源码位于$SOURCE_DIR，消息文件位于$SOURCE_DIR/modules/uORB/msg，并且当前位于$SOURCE_DIR，生成的文件将存放在$SOURCE_DIR/modules/uORB/topics_sources中）：

4.2.4 ULog 日志生成

1. 订阅uORB消息：
日志模块通过uORB的API来订阅相关的消息主题，这些主题对应在项目中定义的.msg文件。通过订阅，日志模块能够实时接收与飞控系统相关的数据更新。
PX4 Autopilot使用orb_subscribe()函数来订阅消息主题。例如：
订阅后，日志模块通过调用orb_check()函数来检测消息是否更新，如果有更新则使用orb_copy()函数来读取消息内容。
回调函数处理是通过一个循环不断检查消息更新，然后对收到的数据进行处理并写入日志。例如：

2. 读取和解压缩消息格式：
日志模块使用MessageFormatReader类来读取uORB的压缩消息格式。在MessageFormatReader::readMore()函数中，日志模块通过heatshrink解码器对压缩的消息格式进行解压缩，从而获得完整的消息字段定义。MessageFormatReader通过读取orb_compressed_message_formats()返回的压缩数据，对其进行解码，以获取原始的消息定义，这样日志模块可以对所有字段进行正确的处理。

3. 处理消息数据：
当日志模块订阅的消息有更新时，日志模块会调用MessageFormatReader的相关方法来读取具体的消息字段数据。解压缩后的消息数据被存储在日志模块的内部缓冲区中，通过调用MessageFormatReader::readNextField()等函数，可以逐一解析各个字段，并将这些数据写入日志文件中。

4. 日志写入：
日志模块会将解压缩后的数据按照指定的格式写入到日志文件中。日志文件通常采用ULog格式，以便于后续的分析和调试。在写入过程中，日志模块会根据消息字段的数据类型和内容调用适当的写入函数，将数据按照预定的二进制格式进行存储，以提高日志的写入效率并减少存储空间的占用。例如：
通过这样的方式，所有的消息数据都会被高效地记录到日志文件中。

5. 错误处理和恢复：
在消息读取和写入过程中，如果遇到缓冲区不足或数据格式不匹配等问题，日志模块会记录错误信息，例如使用LOG_ERR宏打印错误日志，并尝试进行恢复。在解压缩过程中，如果遇到解码错误，MessageFormatReader会将状态设置为失败，停止进一步的处理，以防止无效数据导致系统的不稳定。例如，在缓冲区容量不足时，日志模块会输出如下错误：
同时，日志模块会根据情况清空缓冲区或重新分配资源，确保系统能够继续运行并尽可能保留已有的有效数据。

4.2.5 ULog 日志结构

1. ULog日志文件创建与文件名生成 (get_log_file_name)
在get_log_file_name函数中，根据当前的时间戳或文件编号生成日志文件名称。文件名称的生成方式包括基于时间戳的命名格式，如/fs/microsd/log/2024-11-01/12_34_56.ulg，确保日志文件具有唯一性。此外，还为文件指定了.ulg后缀，以表示其为ULog格式文件。
PX4 Autopilot使用如下函数创建日志文件：

2. ULog 文件头信息 (write_header)
ULog文件头是日志文件的开端，定义了文件的基础信息。文件的头部是固定大小的（16 字节），包含ULog文件的标识符“ULog”和版本号（当前为1），以及日志的初始时间戳。写入文件头信息可以帮助ULog日志读取器识别文件格式，确保文件是ULog兼容的。
PX4 Autopilot使用如下函数创建文件头信息：
ULog文件头部示例如下：

3. 定义数据格式 (write_formats)
ULog日志文件中包含数据格式描述，定义了日志文件中将使用的消息格式。例如，PX4 autopilot会定义包含传感器数据的格式，包括字段名称和数据类型，如timestamp、gps_position、attitude等。此信息使用ULog格式的ulog_message_format_s结构写入，以便日志解析器知道如何解码每条数据记录。
PX4 Autopilot使用如下函数定义数据格式：
ULog文件数据格式如下：
这个定义表示了一个 sensor_data 消息，包含两个字段：温度（temperature）和压力（pressure），它们的数据类型都是 float。

4. 写入系统和参数信息 (write_info)
系统和参数信息写入是ULog日志中重要的一部分，包括系统版本信息、硬件信息以及参数设置。write_info函数用于写入单项系统信息，如硬件型号、固件版本、操作系统版本等。还可以记录关键的控制参数，如飞控板中的attitude_control_gain等，以便在日志分析中了解飞行器的配置。
PX4 Autopilot使用如下函数写入系统和参数信息：
目前支持的预定义如下表所示：

键	描述	值示例
char[value_len] sys_name	系统名称	"PX4"
char[value_len] ver_hw	硬件版本（板卡）	"PX4FMU_V4"
char[value_len] ver_hw_subtype	板卡子版本（变体）	"V2"
char[value_len] ver_sw	软件版本（git标签）	"7f65e01"
char[value_len] ver_sw_branch	git分支	"master"
uint32_t ver_sw_release	软件版本（见下文）	0x010401ff
char[value_len] sys_os_name	操作系统名称	"Linux"
char[value_len] sys_os_ver	操作系统版本（git标签）	"9f82919"
uint32_t ver_os_release	操作系统版本（见下文）	0x010401ff
char[value_len] sys_toolchain	工具链名称	"GNU GCC"
char[value_len] sys_toolchain_ver	工具链版本	"6.2.1"
char[value_len] sys_mcu	芯片名称和修订版本	"STM32F42x, rev A"
char[value_len] sys_uuid	车辆唯一标识符（如MCU ID）	"392a93e32fa3"...
char[value_len] log_type	日志类型（如未指定则为完整日志）	"mission"
char[value_len] replay	重放模式下重放的日志文件名	"log001.ulg"
int32_t time_ref_utc	UTC时间偏移（以秒为单位）	-3600

5. 写入参数 (write_parameters)
write_parameters函数将日志记录时的系统参数写入日志文件。参数记录可帮助分析不同配置对系统行为的影响，如飞控增益、PID参数和传感器偏移量等。
PX4 Autopilot使用如下函数写入参数信息：

6. 数据写入 (write_message)
write_message函数用于将实际的数据记录写入ULog日志中。每条数据消息包含时间戳、消息类型和具体的传感器或控制数据。例如，通过ULogMessage结构体可以记录每个时间点的传感器数据（如GPS位置、姿态信息等）。此函数确保了数据的准确写入，并通过对齐确保数据结构的正确性。
PX4 Autopilot使用如下函数写入数据消息：
数据部分包含了实际的日志记录内容，它使用前面定义的消息格式来记录每一条数据，其格式如下：

7. ULog文件关闭 (stop_log_file)
stop_log_file函数用于在记录结束时关闭ULog文件，确保所有数据已写入文件，避免数据丢失。关闭文件之前会清空缓冲区并写入文件末尾的必要信息，保证文件的完整性。

4.2.5 ULog 日志解析

1. 未知消息处理
假设日志文件中包含一个解析器尚未支持的消息类型。
在这种情况下，解析器应当忽略此消息，并输出警告信息。日志解析过程不会因此中断。

2. 文件中断处理
日志文件在传输过程中可能会中断，导致某条消息不完整。
解析器应当丢弃未完成的消息，并继续解析后续完整的消息，而不会崩溃或报错。

3. 处理附加数据
某些日志文件可能会在记录结束后附加数据，例如硬故障崩溃信息。
解析器应读取 appended_offsets 指定的偏移位置，并将附加数据视为正常的日志数据进行解析。

4.2.4 可用的第三方解析器

1. pyulog（Python 实现）
pyulog 是一个 Python 库，能够方便地读取和解析 ULog 文件。通过 ULog 类，开发者可以轻松获取日志中的所有消息。

2. FlightPlot（Java 实现）
FlightPlot 是一个开源的 Java 应用程序，能够对 ULog 文件进行可视化操作。用户可以通过图形界面选择不同的日志数据并生成时间序列图。

3. PlotJuggler（C++ 实现）
PlotJuggler 是一个 C++/Qt 应用，支持从 ULog 文件生成图表和时间序列数据。开发者可以使用这个工具进行复杂的数据分析和展示。

5 功能性能指标符合性分析

6 附录1：ULog日志记录数据类型表（待补充）

• 数据类型为uORB结构体类型，该结构体中存在大量的未使用字段，目前日志记录程序只对下表中的参数进行记录（代码中已注释的部分未添加到表格中）。

• 日志记录参数的类型参考uORB结构体的类型，表中展示的日志记录参数可通过第三方ULog解析程序解析。