blackbox-log-ts

This is a TypeScript library to parse blackbox log files from Betaflight & INAV on the web & cross-platform without needing the official blackbox_decode, which is somewhat out-of-date. The parser itself is this Rust library compiled to WebAssembly.

Important

This library is no longer being actively maintained. All of my projects have moved to using the Rust library directly in a custom WebAssembly library. If you are interested in using this library and/or helping develop/maintain it, please open an issue.

Installation

Install from NPM under the name blackbox-log:

$ pnpm add blackbox-log  # or npm or yarn

This package uses conditional exports. To make use of the included types, you will need "moduleResolution": "nodenext" in your tsconfig.json and at least TypeScript version 4.7. It will also work with the new "moduleResolution": "bundler" introduced in TS 5.0.

Usage

See the full API docs built from the latest release. The API is designed to parallel the Rust API.

The default export (ie importing from blackbox-log) provides the full API along with the inlined WebAssembly. Alternatively, importing from blackbox-log/slim may reduce bundle size, but does require the WebAssembly file (blackbox-log/wasm) to be loaded separately and served with the application/wasm mime type.

Example

import { Parser, getWasm } from 'blackbox-log';

// Initialize the parser with the inlined WebAssembly module
const parser = await Parser.init(getWasm());

// Or:

import { Parser } from 'blackbox-log/slim';
import wasmUrl from 'blackbox-log/wasm?url'; // This is for vite; check your bundler docs

// Download and initialize from the url
const parser = await Parser.init(wasmUrl);

// ---

const rawFile = new File(); // From a file input on the web, the filesystem in Node, etc
const buffer = await rawFile.arrayBuffer();

const file = parser.loadFile(buffer);
const logCount = file.logCount;
const log = 0;

const headers = file.parseHeaders(log); // Parse just the headers of the first log
console.log(
	`Log ${log + 1} of ${logCount + 1}: ${headers.firmwareKind} v${headers.firmwareVersion}`.concat(
		headers.craftName ? ` named '${headers.craftName}'` : '',
	),
);

const data = await headers.getDataParser();
for (const { kind, data } of data) {
	// Handle each event/frame
}

See the ParserEvent docs for details on the type of kind and data.

Contributing

Note: This library does not itself handle any of the parsing. It is just a wrapper for the Rust library of the same name. Most bug reports and features likely belong there.

All contributions are welcome. Feel free to open bug reports and create pull requests at the GitHub repository.

As this project is a mix of Rust & TypeScript, ideally contributors will have both set up. Alternatively, download a pre-built blackbox-log.wasm from GitHub actions and place it in src/.