Article

Betaflight Blackbox logging: storage, logging rate, test flights and a first look in Blackbox Explorer

Blackbox is Betaflight's flight recorder. While the quad is armed it writes down stick commands, gyro readings, what the P, I and D terms are doing and the command sent to each motor, along with battery voltage, current, RSSI and GPS if you have them. According to the Betaflight docs this data is stored without approximation, so even subtle problems show up in the log. Oscar Liang points out that you can tune a quad without it. Blackbox earns its place when a quad behaves oddly and you want to see what actually happened instead of guessing.

Sat, 17 Oct 2026

Where the log goes

Betaflight can write the log to three kinds of storage:

  • Onboard flash chip. Most current flight controllers have one. Oscar says a 16 MB chip holds about 5-10 minutes of flight depending on the logging rate. When it fills up, Betaflight stops recording, so erase it before each session.
  • SD card slot. Space is practically unlimited, but the card matters. Betaflight supports SDSC and SDHC cards formatted as FAT16 or FAT32 (1 to 32 GB); SDXC cards are not supported. Slow cards drop frames. The first time you boot with a new card, Betaflight collects the free space into a file called FREESPAC.E. Do not edit it or defragment the card. That file is capped at 4 GB, so once 4 GB of logs have been written, delete it (or reformat the card) and Betaflight creates a new one.
  • External logger on a UART. If the board has neither, an OpenLog on a spare hardware serial port works. Betaflight recommends at least 115200 baud and 250000 at 3.2 kHz or 8 kHz loop rates, wiring only the flight controller's TX to the OpenLog's RXI. The port cannot be shared with GPS or telemetry. SoftSerial is limited to 19200 baud and is not recommended.

Settings that matter

Betaflight's guide starts in the Configuration tab: tick the BLACKBOX feature and save. Then open the Blackbox tab and pick the logging device (onboard flash or SD card). The same choice in the CLI is blackbox_device with the values SPIFLASH, SDCARD or SERIAL.

Logging rate. Blackbox logs a fraction of PID loop iterations, set with blackbox_sample_rate (1/1, 1/2, 1/4, 1/8 or 1/16, default 1/4). With the usual 8 kHz loop, 1/4 gives about 2 kHz and 1/8 about 1 kHz. Betaflight recommends 2 kHz for detailed tuning and calls 1 kHz enough for general use. Oscar normally leaves it at 2 kHz (1.6 kHz on a BMI270 gyro) and recommends that for filter and noise work, since it shows vibrations up to 1 kHz. At 1/16 you can still spot gross problems, but the Betaflight docs say you lose subtle ones like vibration and tuning artifacts.

Logged fields. Oscar switches off fields he rarely needs for tuning to keep logs small: accelerometer, attitude, RSSI, altitude, magnetometer, battery, GPS and servo. Turn GPS back on if you want the log to show where the quad was.

Debug mode. Only one debug mode can be active at a time. For ordinary logging set it to NONE. Oscar uses FFT_FREQ when he wants to see which frequencies the dynamic notch filters are tracking, which is useful in PIDtoolbox. Pick other modes only when you are chasing a specific problem.

When it records. By default Blackbox starts when you arm and stops when you disarm or the storage is full. If you would rather not fill the flash on every pack, add a BLACKBOX mode on an AUX switch in the Modes tab: logging then runs only while the mode is active, though a log header is still written at every arm. The CLI setting blackbox_mode = ALWAYS logs even while disarmed. After disarming, wait a few seconds before unplugging the battery or pulling the SD card; Betaflight says at least 5 seconds for the card so the file can be closed.

Getting the files off

On F4, G4, F7 and H7 boards, the quickest way is mass storage mode: the "Activate Mass Storage Device Mode" button in the Blackbox tab, or msc in the CLI. The flight controller shows up as a USB drive and you copy the .bbl files. It stops working as a flight controller until you power cycle it. For onboard flash this is much faster than the older "Save flash to file" button, which according to Betaflight can take 2 or 3 minutes.

How files are split depends on storage. On flash, everything recorded between power-ups goes into one file, and each arm-disarm cycle becomes a separate log you choose from a drop-down in Blackbox Explorer. On an SD card every arm starts a new file. In mass storage mode you may also see btfl_all.bbl, which holds all logs combined; skip it if you already know which log you want.

Fly something worth reading

A log of random cruising tells you very little. For troubleshooting, repeat whatever reproduces the problem. For general tuning Oscar flies a fixed set of moves, keeping each axis separate:

  1. A few seconds of hover, then steady forward flight.
  2. Two or three smooth throttle ramps to full over 3-5 seconds, to show oscillation at different throttle levels.
  3. Full rolls, flips and yaw spins in both directions.
  4. Fast throttle pumps, for example 20% to 70% and back, a few times. Nose dips here can point to too little I term.
  5. Split-S and sharp 180° turns, which show propwash.
  6. Straight forward flight with no stick input in an open area, ideally in light wind, to judge how stable the quad holds a line.

First look in Blackbox Explorer

Blackbox Explorer runs in the browser at blackbox.betaflight.com, or you can download it from the project's GitHub releases. Open the .bbl file and click the info icon in the top left. The log header shows the Betaflight settings the quad had during that flight, which saves a lot of confusion when you compare logs from before and after a change.

A few shortcuts make it usable: I and O set in and out points so you can cut off takeoff and landing, M drops a marker and shows the time and frequency between markers, and Alt with the arrow keys steps one sample at a time.

Start with these traces:

  • Setpoint against gyro. Setpoint is what you asked for, gyro is what the quad did. The closer gyro sits on setpoint, the more locked-in it flies. Gyro lagging behind can call for more feedforward or P. Overshoot is what D is there to damp, but too much D amplifies noise and heats motors.
  • Motors. If gyro still lags and the motors are already at 100%, the quad has reached its physical limit and more PID will not help. One motor working clearly harder than the others in a hover usually means a motor or ESC problem. Oscar's test is to swap motors: if the same position still works harder, suspect the ESC. A motor command that suddenly shoots to 100% can mean an ESC desync: the motor stalled and Betaflight keeps asking it for more.
  • Gyro and gyro_scaled. gyro_scaled is the raw gyro and gyro the filtered one. Markers on the same feature in both show how much delay your filtering adds.
  • RC command and setpoint. RC command has small steps, one per radio packet, and the time between them gives you the packet rate. Setpoint and feedforward should be smooth. Spikes in feedforward suggest the RC smoothing is not keeping up.

The Spectrum Analyzer in the menu bar shows noise against frequency for gyro and D term, which is where filter tuning starts. When you compare two logs this way, trim them to roughly the same length first. Oscar warns that a longer log produces a taller spectrum and can look noisier than it is.

If you shoot onboard footage, Explorer can overlay the graphs on the video. Use raw, unstabilized MP4. Place a marker where the stick input for the first roll begins, find the frame where the roll starts, and press Alt+M to sync. Betaflight also suggests the arming beep, if you have a buzzer: the start of the first long beep appears as a blue line in the log. Oscar rarely bothers, but it helps when you want to see a wobble rather than infer it.

A tune is decent when gyro follows setpoint closely with little overshoot. Past that point, more PID changes are mostly about feel.