BKPT LabsDOCS/ARCHITECTURE AS OF 2026-08-25
BKPT Labs, platform architecture

BKPT Architecture Brief

One C recorder in the customer's firmware, probes driven natively over USB, one UI-free Rust engine, one integration surface (CLI, SDK, file formats), and thin frontends on top: ViewAlyzer for trace, BKPT Studio for the whole firmware loop. Nothing above the engine owns a parser.

as of 2026-08-25 recorder 1.0.5 VS Code extension 1.0.6 SDK 1.0.0 on PyPI

Layers, and what crosses each boundary

What you seethin frontends on the host; they render the engine and own no parsing
FrontendsGPUI (Rust), VS Code
ViewAlyzer desktoptrace timeline, tasks and CPU load, timers, communication map, ETM instruction trace, Trace Tune. Rust/GPUI; renders the shared engine, owns no parsing.
BKPT Studiofirmware IDE: editor with clangd, terminal, project tooling, debugging and flashing, and ViewAlyzer's views rendered inside Studio tiles from the same view library. Rust/GPUI.
VS Code extensioncapture and the same views inside VS Code; bundles a pinned ViewAlyzer release.
JSON envelopes, [headless] progress lines, .vadb files, Python objects
What runs headlesson the host, no UI: one engine, its integration surface, and the probe drivers; scriptable end to end
Integration surfacethe contract other tools code against
va-cli (headless)capture, snapshot, load/export, tiered JSON queries, probe/port/target discovery.
viewalyzer-sdkPython package on PyPI wrapping the CLI; streaming in the next release.
Agent harnessPython: the tool layer an AI assistant calls (Studio's chat runs on it): trace and debug tools over the CLI, workflows, a permission model.
File formats.vadb recordings (SQLite), .vacf connection configs, .vadomain custom event domains.
C ABIthin C-callable layer over the engine for in-process embedding: open a recording, run the same tiered queries, JSON in and out.
semantic rows: lanes, spans, series, findings
EngineRust, UI-free, enforced in CI
va-wirecontainer, sync, COBS, packet decode to raw records. Knows no RTOS.
va-domain, va-domain-rtosTrace Domains: the seam that turns raw records into semantic rows; FreeRTOS / Zephyr / bare metal built in, custom domains as data.
va-storesemantic store over .vadb; lanes, spans, series for any consumer.
va-analysisgeneric detectors composed into named verdicts by domain rules.
va-captureconnection config, transport to decoder to store on a worker thread; post-mortem snapshots.
va-svd, va-tuneCMSIS-SVD resolution; Trace Tune formula graph.
bytes from the target
Probes and transportsdriven natively over USB
Native ST-LINK driverour own implementation of the ST-LINK USB protocol (V2, V2.1, V3): SWO and RTT streaming, RAM-buffer reads on a running core, hot-plug attach that never halts or resets the target. No ST software required.
Debug chain (BKPT Studio)on the same native ST-LINK and J-Link drivers: memory and DAP access on a running core, our own gdbserver, flashing with CMSIS-Pack FLM algorithms run by our own runner. ViewAlyzer itself only captures; it never programs a part.
va-transportprobe-rs over USB in the Rust engine: ST-LINK, J-Link and CMSIS-DAP for RAM-buffer drain over SWD, RTT and SWO/ITM.
BKPT#1 probeour own FPGA probe and host tools: ETM instruction trace, on-chip and probeless modes.
OptionalSEGGER's J-Link library for J-Link owners, loaded at runtime; vendor gdbservers (ST-LINK gdbserver / CubeProgrammer, J-Link) as an alternative debug path in Studio, located automatically; OpenOCD as a subprocess to drain on-chip trace buffers.
RTT, SWO/ITM, or a RAM buffer read over SWD
What you shipyour firmware: the recorder, the only code that leaves our hands
Target firmwareC, Apache-2.0, ships inside the customer's build
ViewAlyzer Recorder coreevent encoder, COBS framing, config template; one C file to compile on bare metal, one adapter file more for FreeRTOS or Zephyr; zero vendored third-party source.
AdaptersZephyr (Kconfig + west module), FreeRTOS (trace hooks), bare metal (core alone).
TransportsRTT, ITM/SWO, RAM buffer; selected by config, same event stream.
proprietary BKPT codeopen format or Apache-2.0 (what leaves our hands)arrows: direction of data, target to frontends

How an outside toolchain plugs in

  • Firmware side: the recorder is plain C under Apache-2.0 with no vendored dependencies, packaged for Zephyr modules and FreeRTOS hooks; it fits an IDE-generated project or a vendor pack without modification.
  • Tool side: everything the desktop apps do is reachable through the headless CLI with stable JSON, the Python SDK, or the C ABI; an IDE or a monitoring tool integrates without touching Rust.
  • Data side: recordings are SQLite files with a documented schema; connection configs and custom event domains are JSON.
  • Probe side: ST-LINK, J-Link and CMSIS-DAP are driven over USB directly, so nothing else has to be installed: ViewAlyzer captures over them, BKPT Studio debugs and flashes over them; parts, SVDs and flash algorithms are catalog data, so any vendor's parts are first-class without a code fork.

Licence and IP posture

  • Applications, engine and probe tools are proprietary; only the recorder (Apache-2.0) and the file formats leave our hands.
  • Dependencies are Apache-2.0 / MIT; MPL-2.0 (file-level) admitted for four named crates. GPL, LGPL and AGPL in the link graph fail the build (cargo deny in CI); unknown or git-sourced crates are refused.
  • GPUI (Apache-2.0) is consumed from crates.io only; Zed's GPL editor crates are not used or read. The code editor comes from an Apache-2.0 component library.
  • Every transcribed asset is recorded in a provenance file per repo; third-party notices ship with each product.
  • A ScanCode-based SCA pass (August 2026) covered the recorder and the shipping app; findings are tracked with the notices written.

Inventory

ComponentLanguageWhat it is
ViewAlyzer RecorderCShips inside the customer's firmware. Zephyr, FreeRTOS and bare-metal adapters; RTT, SWO/ITM and RAM-buffer transports; example projects for 13 boards across STM32 families and ADI MAX32657.
Engine + CLIRust12 crates, UI-free by construction. The headless CLI is the integration surface used by both apps, the SDK and automation.
ViewAlyzer desktopRust/GPUITimeline, tasks and CPU, timers, comms, ETM views, Trace Tune; renders the shared engine, owns no parsing. Captures only; never programs a part.
BKPT StudioRust/GPUIFirmware IDE: editor with clangd, terminal, project tooling; debugging and flashing over the native probe drivers (own gdbserver, CMSIS-Pack FLM runner); ViewAlyzer's views as tiles.
Agent harnessPythonTools over the CLI for an AI assistant, workflows with a permission model, package and toolchain setup.
viewalyzer-sdkPythonOn PyPI; wraps the CLI for scripts, CI and notebooks.
VS Code extensionTypeScriptOn the Marketplace; bundles a pinned ViewAlyzer release.
Device catalogDataParts, CMSIS-SVD files and (for Studio) FLM flash algorithms, fetched by id into a per-machine cache; STM32 families first.
BKPT#1 probe + host toolsFPGA, CETM instruction trace, on-chip and probeless modes for ViewAlyzer; the native-USB debug chain (gdbserver, flashing) for Studio.

What lives in your firmware

The only code that ships inside your product is the ViewAlyzer Recorder: plain C under the Apache-2.0 licence, with no third-party source inside it. It uses your tree's RTT, CMSIS, FreeRTOS or Zephyr, never a copy of them, so there is nothing to reconcile with your own licence review.

  • Zephyr: added as a west module; enable it with Kconfig.
  • FreeRTOS: the standard trace hooks, one include in FreeRTOSConfig.h.
  • Bare metal: the core alone, you call the event functions where they matter.

The transport is a configuration choice, not a code path: RTT and SWO stream live, the RAM buffer works with nothing but a debug probe and is the recommended way to start.

What you get back

A recording is a .vadb file: SQLite, with a documented schema. Open it in ViewAlyzer, query it with sqlite3, keep it next to the build it came from, or attach it to a bug report. Connection settings live in a .vacf JSON file you can commit; custom event definitions in a .vadomain file. Nothing leaves your machine: there is no cloud component and no account required to capture.

Scriptable by design

The desktop apps are thin. Everything they do goes through the same engine the command line exposes, so a capture in CI, a nightly regression on a bench board, or an agent that reads a trace all use one interface with stable JSON output and progress lines you can parse. The Python SDK wraps it for scripts and notebooks.

In CI

Flash, capture for ten seconds, export the CPU load per task as JSON, fail the build on a threshold.

On the bench

Record a reproduction, save the .vadb, hand it to whoever owns the driver. They open it without hardware.

With agents

The same CLI is the tool an assistant calls to answer "why did the control loop stall", from the actual trace.

Your probe, your parts

ST-LINK, J-Link and CMSIS-DAP probes are driven over USB directly, with our own implementation of the ST-LINK protocol: capture and memory reads while your firmware keeps running work with nothing else installed, and BKPT Studio adds a gdb server and flashing with CMSIS-Pack algorithms on the same drivers. If you prefer the vendor tools (ST-LINK gdbserver, STM32CubeProgrammer, the J-Link software), they are supported too and located where you installed them, never hard-coded. Parts, their SVD register descriptions and flash algorithms are catalog data, so a new device is a data update, not a new release. For instruction trace, the BKPT#1 probe adds ETM capture, on-chip trace and probeless modes.

One engine, every app

ViewAlyzer, BKPT Studio and the VS Code extension do not each parse recordings. They render one shared engine: the wire decoder, the Trace Domains that give raw records their meaning, the store and the analysis. A timeline in the IDE is the same timeline as in the desktop app, reading the same store. When a domain learns a new kernel object or a detector gains a new finding, every app has it.

Licensing you can audit

PARTLICENCEWHAT THAT MEANS FOR YOU
ViewAlyzer RecorderApache-2.0Ships in your product with no obligations beyond the notice; no vendored third-party code inside.
File formatsOpenSQLite and JSON; readable without our software.
Apps, CLI, SDK, engineProprietaryOur code. Dependencies are Apache-2.0 and MIT; copyleft licences are excluded from the build by policy and checked on every build. Third-party notices ship with each product.
BKPT#1 probeHardwareWorks with the same apps and CLI; the recorder is unchanged.