{"id":13651373,"url":"https://github.com/iNavFlight/blackbox-tools","last_synced_at":"2025-04-22T22:31:18.876Z","repository":{"id":38325692,"uuid":"139494421","full_name":"iNavFlight/blackbox-tools","owner":"iNavFlight","description":"Tools for working with blackbox flight logs","archived":false,"fork":true,"pushed_at":"2025-04-20T12:08:21.000Z","size":43657,"stargazers_count":18,"open_issues_count":1,"forks_count":22,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-20T13:26:36.116Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"cleanflight/blackbox-tools","license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iNavFlight.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2018-07-02T20:59:40.000Z","updated_at":"2025-04-20T12:08:25.000Z","dependencies_parsed_at":"2023-02-04T05:04:14.686Z","dependency_job_id":null,"html_url":"https://github.com/iNavFlight/blackbox-tools","commit_stats":null,"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iNavFlight%2Fblackbox-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iNavFlight%2Fblackbox-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iNavFlight%2Fblackbox-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iNavFlight%2Fblackbox-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iNavFlight","download_url":"https://codeload.github.com/iNavFlight/blackbox-tools/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250333940,"owners_count":21413480,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T02:00:48.685Z","updated_at":"2025-04-22T22:31:18.863Z","avatar_url":"https://github.com/iNavFlight.png","language":"C","funding_links":[],"categories":["Telemetry \u0026 Logs 📊"],"sub_categories":["Modules 🧩"],"readme":"# Blackbox flight data recorder tools\n\n![Rendered flight log frame](screenshots/blackbox-screenshot-1.jpg)\n\n## Introduction\n\nThese tools allow you to convert flight data logs recorded by INAV's Blackbox feature into CSV files (comma-separated values) for analysis, or into a series of PNG files which you could turn into a video.\n\nYou can download the latest executable versions of `blackbox_decode` x86_64 on Linux, MacOS or Windows, aarch64 on Linux and MacOS, riscv64 on Linux from the \"releases\" tab. If you're running a different OS/Arch, or you need `blackbox_render`, you can build the tools from source (instructions are further down this page).\n\n## Using the blackbox_decode tool\n\nThis is a *command line* tool. It should be run from a \"shell\" (e.g. \"bash\", \"zsh\", \"cmd\", \"powershell\" etc.)\n\nIn order to converts a flight log binary \".TXT\" file into CSV format, a typical usage (from the command line) would be like:\n\n```bash\nblackbox_decode LOG00001.TXT\n```\n\nThat'll decode the log to `LOG00001.01.csv` and print out some statistics about the log. If you're using Windows, you can drag and drop your log files onto `blackbox_decode` and they'll all be decoded, but this prevents using some of the more useful options listed below. Please note that you shouldn't discard the original \".TXT\" file, because it is required as input for other tools like the PNG image renderer.\n\nIf your log file contains GPS data then a \".gpx\" file will also be produced. This file can be opened in Google Earth or some other GPS mapping software for analysis. You can also include more comprehensive GPS data in the log file, for example:\n\n* Add flight date / time to the CSV\n* Include GPS information in the CSV\n\n```\nblackbox_decode --datetime --merge-gps LOG00042.TXT\n```\n\nUse the `--help` option to show more details and all the options, for example:\n\n```text\nINAV Blackbox flight log decoder by Nicholas Sherlock (v7.0.1 123714c, Jan 19 2024 21:36:10)\n\nUsage:\n     blackbox_decode [options] \u003cinput logs\u003e\n\nOptions:\n   --help                   This page\n   --version                Show version, exit\n   --index \u003cnum\u003e            Choose the log from the file that should be decoded (or omit to decode all)\n   --limits                 Print the limits and range of each field\n   --stdout                 Write log to stdout instead of to a file\n   --datetime               Add a dateTime column with UTC date time\n   --unit-amperage \u003cunit\u003e   Current meter unit (raw|mA|A), default is A (amps)\n   --unit-flags \u003cunit\u003e      State flags unit (raw|flags), default is flags\n   --unit-frame-time \u003cunit\u003e Frame timestamp unit (us|s), default is us (microseconds)\n   --unit-height \u003cunit\u003e     Height unit (m|cm|ft), default is cm (centimeters)\n   --unit-rotation \u003cunit\u003e   Rate of rotation unit (raw|deg/s|rad/s), default is raw\n   --unit-acceleration \u003cu\u003e  Acceleration unit (raw|g|m/s2), default is raw\n   --unit-gps-speed \u003cunit\u003e  GPS speed unit (mps|kph|mph), default is mps (meters per second)\n   --unit-vbat \u003cunit\u003e       Vbat unit (raw|mV|V), default is V (volts)\n   --merge-gps              Merge GPS data into the main CSV log file instead of writing it separately\n   --simulate-current-meter Simulate a virtual current meter using throttle data\n   --sim-current-meter-scale   Override the FC's settings for the current meter simulation\n   --sim-current-meter-offset  Override the FC's settings for the current meter simulation\n   --simulate-imu           Compute tilt/roll/heading fields from gyro/accel/mag data\n   --imu-ignore-mag         Ignore magnetometer data when computing heading\n   --declination \u003cval\u003e      Set magnetic declination in degrees.minutes format (e.g. -12.58 for New York)\n   --declination-dec \u003cval\u003e  Set magnetic declination in decimal degrees (e.g. -12.97 for New York)\n   --debug                  Show extra debugging information\n   --raw                    Don't apply predictions to fields (show raw field deltas)\n   --apply-gframe \u003cflag\u003e    How to apply intermediate G-frames (0=ignore (default), 1=when not \"late\", 2=always (legacy, may cause backwards timestamps))\n```\n\n`blackbox_decode` will display some statistics about the log. It will warn you if it's missing essential metadata that effectively renders the log useless for analysis.\n\n```\n$ blackbox_decode corrupt-header.TXT\nDecoding log 'corrupt-header.TXT' to 'corrupt-header.01.csv'...\n\nLog 1 of 1, start 02:57.817, end 09:45.237, duration 06:47.419\n\nStatistics\nLooptime           1890 avg          460.0 std dev (24.3%)\nI frames   12634  113.7 bytes avg  1437103 bytes total\nP frames  169062   69.0 bytes avg 11660607 bytes total\nH frames     100   10.0 bytes avg     1000 bytes total\nG frames    2119   24.1 bytes avg    50991 bytes total\nE frames       1    6.0 bytes avg        6 bytes total\nS frames       3   45.3 bytes avg      136 bytes total\nFrames    181696   72.1 bytes avg 13097710 bytes total\nData rate  445Hz  36121 bytes/s     361300 baud\n\n3438 frames failed to decode, rendering 20444 loop iterations unreadable. 222863 iterations are missing in total (224438ms, 55.09%)\n\nWARNING: Missing expected metadata - check for log corruption\n\tWarning: No VBAT reference\n\tError: No Firmware type metadata\n\tError: No Firmware revision metadata\n\tError: No P Interval\n\tError: No Acc.1G metadata\n\nGenerated by INAV blackbox_decode 7.0.1 123714c\n```\n\nPlease note that `blackbox_decode` is not intended to insert \"derived values\" in the output CSV files. If this is desired, it can easily be done, perhaps as part of a pipeline, outside of `blacbox_decode`.\n\n## Using the blackbox_render tool\n\nThis tool converts a flight log binary \".TXT\" file into a series of transparent PNG images that you could overlay onto your flight video using a video editor (like [DaVinci Resolve][] ). Typical usage (from the command line) would be like:\n\n```bash\nblackbox_render LOG00001.TXT\n```\n\nThis will create PNG files at 30 fps into a new directory called `LOG00001.01` next to the log file.\n\nUse the `--help` option to show more details:\n\n```text\nBlackbox flight log renderer by Nicholas Sherlock (v7.0.1 for INAV, Jan 19 2024 21:36:12)\n\nUsage:\n     blackbox_render [options] \u003clogfilename.txt\u003e\n\nOptions:\n   --help                 This page\n   --index \u003cnum\u003e          Choose which log from the file should be rendered\n   --width \u003cpx\u003e           Choose the width of the image (default 1920)\n   --height \u003cpx\u003e          Choose the height of the image (default 1080)\n   --fps                  FPS of the resulting video (default 30)\n   --mode \u003cmode\u003e          Stick Mode (1-4)\n   --threads              Number of threads to use to render frames (default 3)\n   --prefix \u003cfilename\u003e    Set the prefix of the output frame filenames\n   --start \u003cx:xx\u003e         Begin the log at this time offset (default 0:00)\n   --end \u003cx:xx\u003e           End the log at this time offset\n   --[no-]draw-pid-table  Show table with PIDs and gyros (default on)\n   --[no-]draw-craft      Show craft drawing (default on)\n   --[no-]draw-sticks     Show RC command sticks (default on)\n   --[no-]draw-time       Show frame number and time in bottom right (default on)\n   --[no-]plot-motor      Draw motors on the upper graph (default on)\n   --[no-]plot-pid        Draw PIDs on the lower graph (default off)\n   --[no-]plot-gyro       Draw gyroscopes on the lower graph (default on)\n   --smoothing-pid \u003cn\u003e    Smoothing window for the PIDs (default 4)\n   --smoothing-gyro \u003cn\u003e   Smoothing window for the gyroscopes (default 2)\n   --smoothing-motor \u003cn\u003e  Smoothing window for the motors (default 2)\n   --unit-gyro \u003craw|degree\u003e  Unit for the gyro values in the table (default raw)\n   --prop-style \u003cname\u003e    Style of propeller display (pie/blades, default pie)\n   --gapless              Fill in gaps in the log with straight lines\n   --raw-amperage         Print the current sensor ADC value along with computed amperage\n```\n\n(At least on Windows) if you just want to render a log file using the defaults, you can drag and drop a log onto the blackbox_render program and it'll start generating the PNGs immediately.\n\n[DaVinci Resolve]: https://www.blackmagicdesign.com/products/davinciresolve\n\n### Assembling video with DaVinci Resolve\n\n![DaVinci Resolve screenshot](screenshots/davinci-resolve-screenshot.jpg)\n\n[DaVinci Resolve][] is one free option for turning your PNGs into a video that is synced with your flight video.\n\nIn Resolve, create a new project. On the Media tab, find your flight video and drag it from the top pane to the bottom one to add it to your media library. When prompted, choose the option to change your framerate/resolution settings to match the video you added. Now add the PNG series that you rendered with `blackbox_render` (it'll be represented as a single file). If the PNGs don't appear in the media library, try right clicking on the folder that contains them and\nselecting \"Refresh\".\n\nNow over on the Edit tab, click File -\u003e New Timeline and click Ok. At the top left, switch over to the Media Pool. Drag and drop your flight video onto the timeline, then drag and drop the Blackbox stream onto the video track above it. You'll need to play around with the alignment between the two tracks to sync things up (I usually sync up the audio from the initial throttle-up with the throttle-up shown on the motor graph).\n\nIf your Blackbox PNGs were rendered using the default settings (30 FPS) and your flight video is 60 FPS, you'll need to right-click on the Blackbox stream and click \"change clip speed\". Enter 30 FPS since this is the FPS that you rendered the Blackbox PNGs at.\n\nSave your viewers' ears by dragging the midpoint of the audio track downwards to reduce its volume, or replace the audio with your own music track!\n\nNow on the Deliver tab, choose something like the \"video sharing export\" Easy Setup preset. On the left pane, choose an output folder for the \"render to:\" setting. Then click the \"add job to render queue\" button on the left. Now click the \"start render\" button on the right to begin rendering the output.\n\n## Building tools\n\nIf you just want to download some prebuilt versions of `blackbox_decode` head to the \"releases\" tab on the GitHub page. However, if you want to build your own binaries, or you're an unsupported platform where we haven't provided binaries, please read on.\n\nThe `blackbox_decode` tool for turning binary flight logs into CSV doesn't depend on any libraries, so can be built by running `make obj/blackbox_decode`. You can add the resulting `obj/blackbox_decode` program to your system path to make it easier to run.\n\nThe `blackbox_render` tool renders a binary flight log into a series of PNG images which you can overlay on your flight video. Please read the section below that most closely matches your operating system for instructions on getting the `libcairo` library required to build the `blackbox_render` tool.\n\n### Version Information\n\nThe version is set in `src/version.h`. If you wish, you may override this with the environment variable `BLACKBOX_VERSION` (e.g. `make BLACKBOX_VERSION=x.y.z-local`).\n\nThe Makefile attempts to evince an environment variable `BLACKBOX_COMMIT`; this is set, the git commit id will also be shown as part of the version. You may override this:\n\n```\n$ blackbox_decode --version\n7.0.1 INAV 123714c\n\n$ BLACKBOX_COMMIT=uncommitted make\n$ blackbox_decode --version\n7.0.1 INAV uncommitted\n```\n\n#### Linux\n\nYou will need `gcc` (or `clang`), `make` and (for `blackbox_render`), `libcairo2` (development files).\n\nFor Debian (Ubuntu etc.), you can get the tools required for building by entering these commands into the terminal:\n\n```bash\nsudo apt-get update\nsudo apt-get install make gcc libcairo2-dev\n```\nOtherwise, search the distro package manager and install equivalents.\n\nThen, build blackbox_render by running `make obj/blackbox_render` (or build both tools by just running `make`).\n\n#### FreeBSD\n\nYou will need `clang` (`cc`), `gmake` and `libcairo2`. Use `pkg` to install.\n\nThen:\n\n```\ngmake\n```\n\n#### MacOSX\n\nThe easiest way to build is to install the `Xcode development tool` (`xcode-select --install`), then install an environment like [Homebrew](https://brew.sh/) or [MacPorts](https://www.macports.org/) (untested) onto your system.\n\nFrom MacPorts / Homebrew you need to install `cairo`.\n\nThen you can run `make` to build.\n\nMacOS `blacbox_decode` can also be cross-compiled on Linux using the supplied `Makefile`.\n\n#### Windows\n\nThe tools can be cross-compiled on Linux (`blackbox_decode.exe` using the supplied `Makefile`, or built natively in MSys2 (Win32 and Win64), using the `Makefile`. You will need to install the required tools and libraries (`pacman -S  make gcc cairo`).\n\nHistorically, the tools could be built with Visual Studio Express 2013; open up the solution in the `visual-studio/` folder. You'll need to include the .DLL files from `lib/win32` in the same directory as your built executable. This is no longer supported and is unlikely to work.\n\n#### Install from build\n\nThe `Makefile` includes an `install` stanza. This may be augmented by `prefix` to specify the installation directory prefix, which otherwise defaults to `/usr/local`.\n\nFor example, with `prefix` set to  `$HOME/.local`:\n\n```\n# Note \"/bin\" is appended by the Makefile\nmake install prefix=~/.local\n```\n\nResults in:\n```\n$HOME/.local/bin/blackbox_decode\n$HOME/.local/bin/blackbox_render\n```\n\n## License\n\nThis project is licensed under GPLv3.\n\nBoth binary and source builds include IMU code from Baseflight https://github.com/multiwii/baseflight (GPLv3)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FiNavFlight%2Fblackbox-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FiNavFlight%2Fblackbox-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FiNavFlight%2Fblackbox-tools/lists"}