PX4模块设计之十五：PX4 Log设计

1. PX4 Log介绍

PX4 Log主要是用于记录飞控内部数据状态和信息，应用场景主要有以下几种：

1. 黑匣子数据记录
2. 模拟飞行重现
3. 程序异常记录

为此，PX4 Log在设计上通过以下进行切割：

1. ULog文件格式
2. Logger模块
3. Replay模块
4. HardFault模块

2. ULog文件格式

2.1. ULog文件结构

  +--------------------+
  |       Header       |
  +--------------------+
  |    Definitions     |
  +--------------------+
  |        Data        |
  +--------------------+

2.2. ULog文件头结构

文件头结构

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

• File Magic (7 Bytes): File type indicator that reads “ULogXYZ where XYZ is the magic bytes sequence 0x01 0x12 0x35”
• Version (1 Byte): File format version (currently 1)
• Timestamp (8 Bytes): uint64_t integer that denotes when the logging started in microseconds

2.3. ULog消息结构定义

消息体中的消息头结构

struct message_header_s {
  uint16_t msg_size;
  uint8_t msg_type;
};

2.3.1 B: Flag Bits 消息

struct ulog_message_flag_bits_s {
  struct message_header_s header; // msg_type = 'B'
  uint8_t compat_flags[8];
  uint8_t incompat_flags[8];
  uint64_t appended_offsets[3]; // file offset(s) for appended data if appending bit is set
};

2.3.2 F: Format 消息

struct message_format_s {
  struct message_header_s header; // msg_type = 'F'
  char format[header.msg_size];
};

2.3.3 I: Information 消息

struct ulog_message_info_header_s {
  struct message_header_s header; // msg_type = 'I'
  uint8_t key_len;
  char key[key_len];
  char value[header.msg_size-1-key_len]
};

2.3.4 M: Multi Information 消息

struct ulog_message_info_multiple_header_s {
  struct message_header_s header; // msg_type = 'M'
  uint8_t is_continued; // can be used for arrays
  uint8_t key_len;
  char key[key_len];
  char value[header.msg_size-2-key_len]
};

2.3.5 P: Parameter 消息

struct message_info_s {
  struct message_header_s header; // msg_type = 'P'
  uint8_t key_len;
  char key[key_len];
  char value[header.msg_size-1-key_len]
};

2.3.6 Q: Default Parameter 消息

struct ulog_message_parameter_default_header_s {
  struct message_header_s header; // msg_type = 'Q'
  uint8_t default_types;
  uint8_t key_len;
  char key[key_len];
  char value[header.msg_size-2-key_len]
};

2.4. ULog数据结构定义

2.4.1 A: Subscription 消息

struct message_add_logged_s {
  struct message_header_s header; // msg_type = 'A'
  uint8_t multi_id;
  uint16_t msg_id;
  char message_name[header.msg_size-3];
};

2.4.2 R: Unsubscription 消息

struct message_remove_logged_s {
  struct message_header_s header; // msg_type = 'R'
  uint16_t msg_id;
};

2.4.3 D: Logged Data 消息

struct message_data_s {
  struct message_header_s header; // msg_type = 'D'
  uint16_t msg_id;
  uint8_t data[header.msg_size-2];
};

2.4.4 【*】L: Logged String 消息

struct message_logging_s {
  struct message_header_s header; // msg_type = 'L'
  uint8_t log_level;
  uint64_t timestamp;
  char message[header.msg_size-9]
};

2.4.5 【*】C: Tagged Logged String 消息

struct message_logging_tagged_s {
  struct message_header_s header; // msg_type = 'C'
  uint8_t log_level;
  uint16_t tag;
  uint64_t timestamp;
  char message[header.msg_size-9]
};

2.4.6 S: Synchronization 消息

struct message_sync_s {
  struct message_header_s header; // msg_type = 'S'
  uint8_t sync_magic[8];
};

2.4.7 O: Dropout 消息

struct message_dropout_s {
  struct message_header_s header; // msg_type = 'O'
  uint16_t duration;
};

2.4.8 I: Information 消息

略：与3.3 I: Information 消息共用同样的消息结构体

2.4.9 M: Multi Information 消息

略：与3.4 M: Multi Information 消息共用同样的消息结构体

2.4.10 P: Parameter 消息

略：与3.5 P: Parameter 消息共用同样的消息结构体

2.4.11 Q: Default Parameter 消息

略：与3.6 Q: Default Parameter 消息共用同样的消息结构体

3. Logger模块

pxh> logger

### Description
System logger which logs a configurable set of uORB topics and system printf messages
(`PX4_WARN` and 
Usage: logger <command> [arguments...]
 Commands:

   start
     [-m <val>]  Backend mode
                 values: file|mavlink|all, default: all
     [-x]        Enable/disable logging via Aux1 RC channel
     [-e]        Enable logging right after start until disarm (otherwise only when armed)
     [-f]        Log until shutdown (implies -e)
     [-t]        Use date/time for naming log directories and files
     [-r <val>]  Log rate in Hz, 0 means unlimited rate
                 default: 280
     [-b <val>]  Log buffer size in KiB
                 default: 12
     [-p <val>]  Poll on a topic instead of running with fixed rate (Log rate and topic intervals are ignored if this i
                 values: <topic_name>
     [-c <val>]  Log rate factor (higher is faster)
                 default: 1.0

   on            start logging now, override arming (logger must be running)

   off           stop logging now, override arming (logger must be running)

   stop

   status        print status info

注：模块细节后续给出进一步研究和分析。

4. Replay模块

pxh> replay

### Description
This module is used to replay ULog files.

There are 2 environment variables used for configuration: `
Usage: replay <command> [arguments...]
 Commands:

   start         Start replay, using log file from ENV variable 'replay'

   trystart      Same as 'start', but silently exit if no log file given

   tryapplyparams Try to apply the parameters from the log file

   stop

   status        print status info

注：模块细节后续给出进一步研究和分析。

5. Hardfault模块

pxh> hardfault_log

### Description
Hardfault utility

Used in startup scripts to handle hardfaults
Usage: hardfault_log                   command
   check         Check if there's an uncommited hardfault
   rearm         Drop an uncommited hardfault
   fault         Generate a hardfault (this command crashes the system :)
			     0|1 Hardfault type: 0=divide by 0, 1=Assertion (default=0)
   commit        Write uncommited hardfault to /fs/microsd/fault_-1816558944.txt (and rearm, but don't reset)
   count         Read the reboot counter, counts the number of reboots of an uncommited hardfault (returned as the exit code of the program)
   reset         Reset the reboot counter

注：模块细节后续给出进一步研究和分析。

6. 参考资料

【1】PX4开源软件框架简明简介
【2】PX4 Logging
【3】PX4 ULog File Format
【4】PX4 logger模块
【5】PX4 replay模块
【6】PX4 hardfault log模块