SDK API reference

Everything exported by viewalyzer_sdk. Every method that calls the CLI returns the CLI's JSON envelope as a dict (keys as the CLI queries page lists them), raises ViewAlyzerError on an error envelope, and prefixes the argv with --headless (the flag form every viewalyzer-cli build accepts).

ViewAlyzer

class ViewAlyzer(binary=None, *, query_timeout_s=30.0)

binary is a path to viewalyzer-cli (or the app binary), an argv prefix (a list, for a wrapper), or None to discover one (VIEWALYZER env, PATH, install locations; BinaryNotFound when nothing is found). query_timeout_s bounds every query call; captures compute their own timeout from the duration.

Target and environment

Recording

va = ViewAlyzer()
img = va.hwtrace_dry_run(arch="v7m", cpu_clock_hz=170_000_000, swo_freq_hz=10_000_000,
                         hardware_trace={"dwt": {"enable": True, "exception-trace": True, "pc-sample-cyc": 16384}})
print([w["reg"] for w in img["writes"]], img["refused"])

Recording

class Recording(client, *, recording_id=None, path=None, info=None)

Returned by record(), snapshot(), record_polls(), open() and recordings(). recording_id (12 hex, when registered), path (a Path, when known), info (the CLI's summary dict for a fresh capture: events, lost_events, duration_us, os, cpu_hz, transport), ref (the id or the path, whatever names it to the CLI).

Queries (one CLI call each)

rec = va.open("run.vadb")
hot = rec.profile(elf="firmware.elf")["data"]["hotspots"][:5]
exc = rec.dwt_exc()["data"]["exceptions"]
text = [l["text"] for p in rec.itm_console(port=0)["data"]["ports"] for l in p["lines"]]
samples = rec.user_traces(tier="raw", t_start_us=1_000_000, t_end_us=1_010_000, channels="Sine Wave")["samples"]

The file itself (no CLI call)

with rec.connect() as db:
    kinds = db.execute("select kind, count(*) from va_events group by kind").fetchall()

Streaming types

StreamSession, StreamMeta(id, name, type), StreamSample(id, t_us, value, is_float, name, stream_type) with t_s, and StreamEvent(t, t_us, data) with t_s: see Live streaming.

Errors and warnings

class ViewAlyzerError(Exception):   # .code, .message, .suggestion, .limits
class BinaryNotFound(ViewAlyzerError)   # code "binary_missing"
class ViewAlyzerWarning(UserWarning)

ViewAlyzerError is raised for every CLI error envelope, keyed on the error field rather than the exit status: code is the CLI's token (bad_config, no_such_recording, window_too_wide, empty_capture, cooldown_active, no_hw_trace, ...), suggestion and limits carry the envelope's hints (limits["retry_after_s"] on a cooldown). SDK-side codes: binary_missing, timeout, bad_output (the CLI printed no JSON), record_failed, command_failed, file_not_found, bad_arguments.

ViewAlyzerWarning is emitted (through warnings) for parameters this CLI does not act on, such as symbols on record().

Discovery and constants

The public API is a contract: names, parameters and behaviour are kept across releases and only added to, the same rule the CLI follows.