Domain packages

Install a Trace Domain to add subsystem-specific channel names, displays, observations, and findings. A domain is a .vadomain JSON file. A package is a folder containing that file and any supporting assets, such as an external instrument recorder.

Start with the downloadable domain in the USBX on ThreadX walkthrough, or use the format reference to create a descriptor for your firmware.

Install in ViewAlyzer

Open Trace Domains in the sidebar.
Choose Load Domain File for a .vadomain file, or Load Domain Package for a folder.
Select the file or folder. ViewAlyzer validates the descriptor and installs it in your user configuration folder.
Enable the domain with its toggle. For sampled inputs, select the matching target, probe, ELF, and SVD as required by the domain, then start capture.

Enabled domains apply when you open a recording and when you start a capture. Opening an existing recording uses its saved samples; it does not collect new observations from the target. The original recording remains usable without the domain installed.

Use the gear beside the domain to open its live cards and tables, and the pencil to open the Domain Editor. Turn the toggle off to disable the domain, or use the delete button to uninstall a user-installed domain.

Install in BKPT Debug

Open Trace Domains, choose Install custom trace domain…, and select the .vadomain file. Enable it for the workspace, select the matching ELF and SVD where required, and start or attach a debug session. Run the target to observe changing values.

Installation and activation are separate in BKPT Debug and ViewAlyzer. Install the descriptor in each product you use. The USBX walkthrough shows both workflows and explains their views.

ViewAlyzer search locations

ViewAlyzer and its CLI search these locations in order. A later descriptor with the same id overrides an earlier one.

ORDER	LOCATION	PURPOSE
1	`domains/` beside the executable	Domains bundled with the application.
2	The per-user `ViewAlyzer-GPUI/domains/` folder	Domains installed from the sidebar.
3	The folder named by `VA_DOMAINS_DIR`	A custom collection for your project or automated capture.

The per-user folder is beneath %APPDATA% on Windows, ~/Library/Application Support on macOS, and ~/.config on Linux. Each search location accepts .vadomain files directly and package folders one level below it.

List the exact search paths, loaded domains, and any loading errors:

viewalyzer-cli domains

For example, to load a folder named trace-domains in the current directory in a Bash shell:

VA_DOMAINS_DIR="$PWD/trace-domains" viewalyzer-cli domains

Use the same environment variable for subsequent capture or query commands that need those domains.

Ethernet and IMU examples

The ViewAlyzer domain collection includes an STM32N6 Ethernet pack and an STM32WB six-axis IMU pack. Both require a reader supporting Trace Domain v1, the matching demo firmware ELF and device SVD; the Ethernet ring layout and lwIP offsets are specific to that application.

Ethernet separates traffic cards from folded receive, transmit, errors, stack and raw-register tables; 12 of 34 channels start graphed. The IMU leaves motion and stream cards open and folds sensor configuration and bus details; eight of 19 channels start graphed. Every value remains available, and Graph choices are editable independently. These presentation updates preserve the packs' acquisition and analysis definitions.

Create a package

For a domain containing only display rules, observations, or findings, distribute the .vadomain file itself. Use a package folder when the domain needs additional files:

sensor-monitor/
    sensor-monitor.vadomain
    README.txt
    bin/
        recorder

The recorder in this example is optional. When including one, supply the binary and dependencies for the user's operating system. Reference bundled files relative to the descriptor folder using {dir} in instrument.cmd.

Keep the descriptor's id stable when updating it, and change version to identify the new package version. Document the supported device, firmware configuration, required ELF or SVD, and any instrument setup in your package's instructions.

Record an external instrument

A package's optional instrument section tells ViewAlyzer how to launch its recorder. The recorder writes the external-series format, and its samples are synchronized with the target recording.

After installing the package, set the instrument parameters beneath the domain in the sidebar and enable Record with capture. One live instrument runs per capture. Review alignment quality in Overview after capture; see Instrument time sync for setup.

For descriptor fields and examples, see External instrument recorders.

Troubleshooting

PROBLEM	ACTION
Domain is missing from the list	Run `viewalyzer-cli domains` to check the search folders and loading errors. Check the extension and package folder depth.
Changes to a domain do not appear	Check whether another search location contains the same `id` and overrides your file.
Domain loads but inputs are unavailable	Check its target requirements, matching ELF and SVD, and the reason shown for each unavailable input.
No findings appear	Check that the domain is enabled and all inputs required by its rules are available. Let acquisition run for the rule's required duration; in ViewAlyzer, stop capture to review completed findings.

VIEWALYZER CLI OVERVIEW ALL GUIDES EMAIL SUPPORT