PX4 ULog

ULog is the format PX4's logger writes to the flight controller's SD card. It is self-describing: the file defines each message format before the data that uses it. Foxborne reads the completed .ulg with parser ulog 0.9.2.

With a valid clock, PX4 names each log for its date and start time. Run R-0931's flight log in the example dataset is log/2026-09-24/14_13_19.ulg. Without a valid clock, the logger numbers its folders and files instead.

File structure#

A ULog has three sections: a fixed 16-byte header, then definitions, then data. All binary values are little endian.

Header#

Foxborne checks the magic bytes before anything else. The Import page then shows PX4 ULog, version 1 and Magic bytes verified.

Messages#

After the header, the file is a sequence of messages. Each starts with three bytes: msg_size, a uint16 giving the message's size without those three bytes, and msg_type, one character. The definitions section ends where the first subscription or logged string begins.

"Both" means the definitions and the data sections.

Each format with a subscription carries a timestamp field: a uint64 in microseconds that only increases within that subscription. In PX4 it counts from boot, so a sample at 1,132,793,000 µs sits 1,132.793 s after the flight controller started.

PX4 v1.16.0 writes its console messages as L messages. It stores the level as a character, from '0' (EMERG) to '7' (DEBUG), as in the Linux kernel. It writes a synchronization message whenever more than 500 ms have passed since the last one.

How a record is cited#

A flight log event cites its topic and instance, its timestamp, its message number and its byte offset in the file. The evidence inspector shows the original record like this:

topic      obstacle_distance (multi_id 0)
timestamp  1,132,793,000 µs   boot + 1132.793 s
message    1,146,099 of 1,388,540
offset     byte 53,503,302

frame                       12 (MAV_FRAME_BODY_FRD)
sensor_type                 0 (laser)
min_distance                20 cm
max_distance                2000 cm
increment                   5.0 deg
distances[0..7]             412 406 399 401 388 1999 1999 1999

Anyone holding the original file can find message 1,146,099 at byte 53,503,302 and check the values against it.

Topics Foxborne reads#

Foxborne expects a set of topics on each platform. In the example dataset each platform expects 13, and each run logged 11 of them.

The topic_stall rule fires when a logged topic stops updating: no sample for 5 times its median period.

Topics shown as Not logged#

A topic missing from the file shows Not logged under Flight log topics on the run page. The panel's subtitle counts what arrived, for example 11 of 13 expected topics were logged.

A topic can be missing because the logging profile left it out or because nothing on the vehicle published it. A rule that reads a missing topic has nothing to read on that run, so it produces no finding there.

Parameters read from the header#

Foxborne reads parameters from the P messages in the definitions section, which hold the values in force when logging started. It compares them from one run to the next on each vehicle.

The vehicle page lists these values under Failsafe parameters, and any differences in the Changes between runs drawer, opened from that panel's header. On UGV-05 in the example dataset it reads NAV_DLL_ACT 0 (Disabled) to 1 (Hold) in R-0924, 22 Sep. PX4 parameters Foxborne reads gives each parameter's range and default.

The GPS time anchor#

The flight log counts from boot, and sensor_gps ties that count to UTC. Three of its fields do the work:

A fix with a nonzero time_utc_usec reads one instant on both clocks and gives the offset from boot to UTC. Foxborne leaves out the zeros and reports how many fixes it used. For run R-0931 the run page reads GPS time from sensor_gps, 1,081 fixes, which puts the flight controller's boot at 14:13:11.286 UTC.

The information key time_ref_utc is no substitute. PX4 writes it from the SDLOG_UTC_OFFSET parameter, so it holds a configured offset in seconds, not a reading of any clock.

GPS time that reaches the flight controller over a serial link carries latency and jitter. That is why the example dataset carries ±40 ms on flight logs.

A run with no fix has no anchor, and the run page shows Elapsed time only. Clocks, anchors and error bounds covers the anchor in full.

Dropouts and the log_dropout rule#

When the logger cannot keep up, it loses messages and records the gap as an O message with its length in milliseconds. The samples in that gap were never written. The ULog specification names a device that is not fast enough as one cause.

The log_dropout rule turns each dropout of 50 ms or longer into a finding worded Observed: flight log has a dropout. In the example dataset's INC-0133, UAS-05 logged three dropouts of 60 to 140 ms once its logging profile included high-rate IMU topics.

The SD card's write rate had saturated, and moving back to the default logging profile fixed it. See log_dropout.

Truncated logs are quarantined#

A log cut off by a power loss ends partway through a message. Foxborne quarantines the file and shows nothing from it as complete, and the run page offers Replace the file. Run R-0933 in the example dataset gives the reason in full:

The flight log ends inside a data message at 41.2 MB. The file was truncated, most likely when power was cut during logging. Nothing from it is shown as complete.

Encrypted logs are rejected#

An encrypted flight log stops at the first step of the import job, Validate type, size and schema. Run R-0932 in the example dataset reads:

The flight log is encrypted. Foxborne does not decrypt logs. Import the decrypted .ulg exported from your key holder.

Ask whoever holds the log's key for the decrypted .ulg, then replace the file from the run page. Import statuses and fixes walks through both cases.

Related#

• Clocks, anchors and error bounds explains the boot clock and its GPS anchor.
• PX4 parameters Foxborne reads lists each parameter's range and default.
• log_dropout and topic_stall describe the rules that read the log's structure.
• Supported file formats compares the ULog with the other formats.