Getting started

This page is the path from a firmware that records nothing to a recording on screen. Do the steps in order; each one has a way to check it worked before you move on.

• 1. Put the recorder in the firmware
• 2. Install and start ViewAlyzer
• 3. Describe the connection
• 4. Record
• 5. Open, save and share recordings
• 6. Give the app your ELF
• 7. Read your first recording
• 8. Snapshots: recording without a cable
• Troubleshooting

1. Put the recorder in the firmware

ViewAlyzer's recorder is a few C files you compile into your firmware. It has no library, package manager or build step of its own. There are three integration paths, and the choice is made by what your firmware runs on:

The recorder sources and the per-path READMEs live in the ViewAlyzerRecorder directory of the ViewAlyzer repository. The integration in one sentence: compile the recorder's .c files into your firmware, add its two include paths, set a handful of defines (VA_ENABLED, the RTOS selection, the transport), and call VA_Init(cpu_freq) once at startup with the real CPU clock.

Pick a transport

The transport is how trace bytes leave the chip. Set it with the VA_TRANSPORT define (Zephyr: Kconfig) and remember which one you chose, because the app must be told the same thing in step 3.

Or start from a working example

The ViewAlyzer-Examples repository has complete, buildable projects for Zephyr, FreeRTOS and bare metal on common Nucleo boards, each with a build.py that builds and flashes, and each shipping the .vacf connection config that matches it. If you own one of those boards, flashing an example is the quickest way to see a real recording before touching your own code. Every example is also a reference to diff your own project against; the repository's AI_INTEGRATION.md is the one-page integration recipe.

2. Install and start ViewAlyzer

ViewAlyzer is a single executable on Windows, macOS and Linux. If you were given a package, install it and start it. To build it from source you need a Rust toolchain and, on Windows, the Microsoft C++ Build Tools; then run python build_app.py build in the ViewAlyzer-RS checkout and start target/debug/viewalyzer (viewalyzer.exe on Windows). The README in that checkout has the per-platform build notes.

Probe access

• Windows: ST-LINK needs the ST-LINK USB driver from ST (or WinUSB); J-Link needs the SEGGER J-Link software. Both are the normal vendor installs you already have if the board's IDE works.
• Linux: add the udev rules for your probe so it is accessible without root (ST and SEGGER both publish rule files; probe-rs documents a combined set). Replug the probe after installing them.
• macOS: nothing to install; the probe is a plain USB device.

The app stores its settings, recordings and installed domains in a per-user folder:

Recordings you make land in recordings/ under that folder until you save them somewhere else.

3. Describe the connection

Everything the app needs to reach the target lives in the sidebar. The two sections that matter for a first capture are Connection and Software Trace; the rest can wait.

Connection

Software Trace

When Hardware Trace → Profiling Source enables debug-port PC sampling on RAM Buffer or RTT, CPU Clock (MHz) appears in Hardware Trace. It converts the cycle interval into a probe polling cadence; it is not used for recorder timestamps and remains hidden for an ordinary software-trace capture.

Save the connection

Save Config writes all of this to a .vacf file; Load Config reads one back. Commit one per board next to your firmware, and nobody re-enters probe settings again. The same file drives the command line (viewalyzer-cli capture --config board.vacf ...), and the example projects ship theirs.

4. Record

The capsule in the middle of the top bar is the record button:

• Click the centre to start. It shows LINK while the probe attaches, then REC 00:12 counting up with the data rate. Click again to stop; SAVING appears while the file is finalised, then every view fills in.
• - and + set a timed capture in 30-second steps (the centre shows the duration, 01:30). At IDLE the capture runs until you stop it.
• The card icons around the capsule open and close the views; the capsule's hover text names the card under the pointer.

While recording, the Trace panel and the Profiler are live; the other views show "Recording" and fill in when the capture stops.

Everything the app does during a session (attach, ring found, losses, warnings) goes to the log sidebar, opened with the panel icon at the far right of the top bar. When something looks wrong, read the log first.

5. Open, save and share recordings

• OPEN on the capsule opens a recording from disk; the chevron beside it lists the recordings you opened or saved most recently. viewalyzer <file.vadb> on the command line opens one at startup.
• SAVE writes the current recording to a location of your choice. It lights up blue when the recording in memory has not been saved yet.
• A .vadb is the complete, shareable recording. It carries the raw capture, decoded events, and derived data such as task statistics and communication paths.
• A .va is the raw byte log written while a capture is running. The app may keep it beside a .vadb with the same name. When both exist, open or share the .vadb; it also preserves probe-polled samples, PC samples, and external instrument data that are not part of the recorder byte stream.
• The command line also defaults to .vadb. Pass --keep-va when you want to retain its raw byte log, or give --output a .va extension to save only that log. A 1 KiB .va contains only its header and means the capture received no trace bytes.
• Recordings made by the app and by viewalyzer-cli share the same recordings/ folder and index (viewalyzer-cli recordings lists them).

6. Give the app your ELF

Several views need to know the firmware's symbols, and all of them read the same file: ELF / Symbols > ELF File in the sidebar (the button beside the field browses for it, the chevron lists recent ELFs). Set it once per project and it persists. Load Config has the same chevron for recent .vacf files.

What it unlocks:

• Symbols: browse variables and mark them for polling over the debug port, with no firmware change.
• Memory: flash and RAM usage of the build, section by section.
• Profiler: PC samples resolved to functions, and Source Root lets the Source view show the annotated file.
• Timers: k_work handlers named by symbol instead of address.
• Overview: the memory summary section.

A stale ELF (from a different build than the one on the board) resolves symbols to the wrong addresses. Rebuild both together, or keep the ELF next to the firmware image it belongs to.

The Memory view reads the ELF directly; it does not require arm-none-eabi-nm or another external tool. Tools > ARM Toolchain Path is for workflows that explicitly launch GNU Arm tools, not for normal ELF memory accounting.

7. Read your first recording

The first-run layout puts CPU and the Event Table above the Timeline. A good first pass through a fresh recording:

1. Overview for the headline numbers: duration, event count, CPU load, tasks, stack headroom. Its Copy button puts the whole report on the clipboard as Markdown, which makes a good first line in a bug report.
2. Timeline to see the shape of the run. Zoom with Ctrl+wheel (Cmd on macOS), drag to pan, hover to move the cursor. Click a slice: the Details panel describes that task instance.
3. Analyzer for what the app already found: priority inversions, jitter outliers, failed kernel operations. Click a finding and the Timeline jumps there.
4. Trace for your own channels, Timers and Comms for kernel timers and message paths, Profiler if you enabled PC sampling.

The views share one time model: one zoom window, one hover cursor, one pinned cursor and one selected region, described in The workspace. Zooming the Timeline zooms the charts; pinning the cursor in a chart selects the row in the Event Table.

8. Snapshots: recording without a cable

With the RAM buffer transport the recorder keeps the most recent trace window in the ring at all times. Take Snapshot (Software Trace section) reads that ring out through the probe without resetting the target, so a board that ran unattended for an hour still gives you the seconds before it stopped. Firmware can freeze the ring from a fault handler (VA_SnapshotFreeze()), which keeps the moment of the crash intact until you get to the board. The snapshot opens as a recording like any other.

Troubleshooting

The capsule goes LINK then back to IDLE with an error. The probe could not attach. Check the log sidebar: a wrong Target Device name, a probe in use by another program (an IDE debug session, ST-LINK server), or a missing driver / udev rule are the usual causes. viewalyzer-cli probes lists what the app can see.

The recording has zero events. The attach worked but no trace bytes arrived. In order of likelihood:

• Trace Source does not match the firmware's VA_TRANSPORT.
• The recorder is compiled out (VA_ENABLED not set) or VA_Init() is never reached. On FreeRTOS the recorder's defines must be visible to the kernel sources too, not just to your application files.
• RAM buffer: the ring was not found. Give RAM Buffer Address the address of _VA_RAMBUF from the map file, or widen the scan window.
• SWO: SWO Freq (kHz) or Trace Clock (MHz) differ from the target.
• The target is halted (a breakpoint left by a debugger survives sessions). Power-cycle the board.
• Hot attach (Reset on Connect off) to a firmware that has been idle: the recorder emits its setup bundle every 2 s, so wait a few seconds before judging.

Events arrive but timestamps look wrong. On SWO, Trace Clock (MHz) is wrong. On RAM Buffer or RTT, the recorder's timestamp source or reported tick frequency is wrong (the recorder reports ERR:TS_DEAD in the log when the source is not running).

Losses reported in the log. The transport cannot keep up. Trace less (the recorder's selective tracing defines), lower the rate of user traces, or on RTT give the recorder its own channel with a bigger buffer.

The Symbols / Memory / Profiler views say "No ELF loaded". Step 6.

A view says "No recording" while the capsule reads REC. Expected: only the Trace and Profiler views stream live. Stop the capture and the view fills in.