Logging File buffer size (FILE_BUFSIZE)

Description

This parameter defines the size of the memory buffer (in kilobytes) allocated for the file-based logging system. This buffer acts as a "waiting room" for data being written to the microSD card.

If the SD card is slow or busy (e.g., during high vibration or when the card is nearly full), this buffer allows ArduPilot to continue collecting sensor data without losing ("dropping") any log messages. A larger buffer provides more protection against "gaps" in your logs.

The Mathematics

The buffer size is a direct allocation of RAM.

$$ RAM\_{logging} = FILE\_BUFSIZE \times 1024 \text{ bytes} $$

If the incoming data rate (bytes per second) exceeds the SD card's write speed for a duration $t$, the buffer fills at a rate:
$$ \Delta Buffer = \int\_0^t (Rate\_{in} - Rate\_{out}) , dt $$

If $\Delta Buffer > FILE\_BUFSIZE$, data is lost.

The Engineer's View

In AP_Logger.cpp, this parameter is defined as _FILE_BUFSIZE.

• High Performance Boards: Default is often 200kB.
• Limited RAM Boards: Default can be as low as 16kB.
• Replay Mode: When LOG_REPLAY is enabled (for EKF diagnostic testing), the data volume increases significantly. In these cases, it is highly recommended to increase FILE_BUFSIZE (to 100-200kB) to ensure the high-frequency sensor data required for a successful replay is not dropped.

Tuning & Behavior

• Default Value: Varies by board (usually 200 on H7/F7, 16 on F4).
• Range: 4 to 256 kB.
• When to Increase: If you see "Log Drop" or "Missing Data" warnings in your Ground Control Station, or if you are using high-rate logging for research or EKF Replay.
• When to Decrease: Almost never, unless you are critically low on RAM for Lua scripts or other features.
• Reboot Required: Yes. RAM allocation happens at startup.

Stop logging to current file on disarm (FILE_DSRMROT)

Description

This parameter controls how ArduPilot handles log file rotation when the vehicle disarms. It allows you to decide if multiple flights on the same battery should be saved in one large file or split into separate, distinct files.

• 0 (Default): Keeps the same log file open until the system is rebooted. This results in one log file containing all activities (even across several arm/disarm cycles).
• 1 (Enabled): Closes the current log file immediately upon disarming. If LOG_DISARMED is enabled, it will then start a brand-new log file for the next session.

The Mathematics

This parameter functions as a boolean gate in the state machine logic:

$$ \text{IF } (\text{Disarmed} \text{ AND } FILE\_DSRMROT == 1) \rightarrow \text{Close current handle} $$

The Engineer's View

In AP_Logger.cpp, this parameter maps to _params.file_disarm_rot.
When the vehicle state changes to disarmed, the logging backend checks this flag.

• If set, AP_Logger_File::stop_logging() is called.
• This is useful for professional operators who want a clean 1-to-1 mapping between a flight mission and a .bin log file, making data analysis much more organized.

Tuning & Behavior

• 0: Preferred for casual flying or if you are troubleshooting ground issues and want a continuous record.
• 1: Recommended for commercial mapping, inspections, or competition flights. It ensures that if one flight is successful and the next crashes, the logs are already segmented and easier to manage.
• Dependencies: Works most effectively when LOG_DISARMED is also set to 1 or 2, ensuring that the "pre-arm" period for the next flight is captured in its own new file.

Logging Minimum Free Space (FILE_MB_FREE)

Description

This parameter manages the "Automatic Cleanup" of your microSD card. It sets a minimum threshold for free space (in megabytes). If the card fills up and the free space drops below this value, ArduPilot will automatically delete the oldest log files to make room for new data.

This ensures that you always have enough space for your current flight and prevents the logging system from crashing or hanging due to a full filesystem.

The Mathematics

The logging backend monitors the available space on the disk.

$$ \text{IF } (\text{DiskFreeMB} < FILE\_MB\_FREE) \rightarrow \text{Delete oldest .BIN file} $$

This loop continues until the condition is no longer met or no more logs can be deleted.

The Engineer's View

In AP_Logger_File.cpp, the cleanup logic is part of the maintenance task.

• It uses AP::FS().get_disk_free() to check remaining capacity.
• It iterates through the existing log list (starting from last_log_num backwards) to identify targets for deletion.
• By maintaining a significant buffer (default 500MB), it avoids file fragmentation issues and ensures the filesystem has overhead for metadata updates and other temporary files.

Tuning & Behavior

• Default Value: 500 MB.
• Recommendation: Set this to a value larger than your longest expected flight log (e.g., if a 1-hour flight produces a 100MB log, 500MB is a very safe buffer).
• Agile Development: If you fly many short missions and don't want to manually clear your card, this parameter is your best friend.
• Critical Data: If you cannot afford to lose old logs, you should set this lower and monitor your card manually, or better yet, increase the SD card size.

Maximum logging rate for file backend (FILE_RATEMAX)

Description

This parameter acts as a "Data Governor" for the logging system. It sets a global cap on how frequently (in Hz) streaming log messages can be written to the SD card.

By setting a limit, you can prevent the autopilot from overwhelming a slow microSD card with too much data, which can cause lag or CPU spikes. This is particularly useful on vehicles with many high-frequency sensors or complex Lua scripts that generate a lot of custom logging.

The Mathematics

The logging backend tracks the last time a message of a specific type was written.

$$ \Delta T\_{min} = \frac{1}{FILE\_RATEMAX} $$

If the time elapsed since the last log write is less than $\Delta T\_{min}$, the current message is skipped.

The Engineer's View

In AP_Logger_File.cpp, the streaming write logic checks _params.file_ratemax.

• 0: Unlimited rate. The system logs every message as soon as it arrives (subject to buffer space).
• Non-Zero: Applies a per-instance throttle.
• Note that this only affects "streaming" messages (periodic sensor updates); critical events (errors, mode changes, parameters) are always logged immediately to ensure they are never missed.

Tuning & Behavior

• Default Value: 0 (Rate limiting disabled).
• Range: 0 to 1000 Hz.
• When to Use: If you see "High CPU" or "IO Performance" warnings in your logs, or if your .BIN files are becoming unnecessarily large for long endurance flights.
• Typical Value: Setting this to 50Hz or 100Hz is often sufficient for standard flight analysis while significantly reducing the load on the SD card interface.

Timeout before giving up on file writes (FILE_TIMEOUT)

Description

This parameter sets a "Safety Watchdog" for SD card operations. If the autopilot attempts to write to the microSD card and the operation hangs or fails repeatedly for a period longer than this timeout, the autopilot will give up and close the log file.

This is a critical safety feature: it prevents a faulty or slow SD card from "locking up" the main flight control loop, which could cause the aircraft to crash. It is better to lose the log than to lose the aircraft.

The Mathematics

The logging backend tracks the last successful write timestamp ($t\_{success}$).

$$ \text{IF } (t\_{now} - t\_{success} > FILE\_TIMEOUT) \text{ AND } \text{WriteFailureActive} \rightarrow \text{Abort Logging} $$

The default value is 5 seconds.

The Engineer's View

In AP_Logger_File.cpp, this parameter maps to _params.file_timeout.

• It is used in the AP_Logger_File::periodic task.
• If a write failure persists beyond the threshold, the file handle is invalidated (_fd = -1).
• The system will then wait for a separate "Re-open" period (typically 5 seconds) before trying to initialize a new log file, ensuring the system doesn't enter a tight loop of failing I/O.

Tuning & Behavior

• Default Value: 5 seconds.
• Recommendation: Leave at 5s.
• Increasing: May be necessary for extremely high-volume logging on slower industrial cards, but increases the risk of "CPU Hang" during write retries.
• Decreasing: Makes the system more aggressive at cutting off logging if the card is slow.
• Symptom of Timeout: If your logging stops mid-flight but the aircraft continues to fly normally, your SD card likely exceeded this timeout due to write latency.
  • Fix: Format the card, use a Class 10/U3 card, or increase FILE_BUFSIZE.