Use hardware-smoke to validate real USB behavior after risky serial or CLI changes. The command is opt-in, never runs in the default test suite or public CI, and is read-only unless you pass --mutate.

​
Assumptions

  • A charged VEX V5 brain connected over a data-capable USB cable.
  • Linux, macOS, or Windows with the standalone v5x CLI installed, or with @v5x/cli installed under Bun 1.3.14 or newer.
  • Permission to access the serial device, and no other app currently owns the port.
  • A writable local directory for the PNG screenshot.

​
Prepare

Run the brain path first:
The harness checks the connection and refreshed device status, inspects the user-file directory, and captures a 480x272 screenshot. It records the OS, architecture, Bun and CLI versions, device path, USB vendor/product IDs, and brain firmware versions. It deliberately omits the USB serial number, brain unique ID, directory filenames, and file contents. The output path must not already exist. This keeps a previous validation artifact from being silently overwritten.

​
Controller path

Connect the controller over USB with a brain linked over VEXnet, then run:
--expect prevents a brain run from accidentally being recorded as controller validation, or vice versa. Keep both JSON reports and screenshots with the release or pull-request validation notes. Firmware variants and both physical paths still require a person with the corresponding hardware.

​
Optional mutation check

The default command performs no writes to the V5 device. To test an end-to-end file transfer, add --mutate:
Mutation mode refuses to run if v5x_smoke.txt already exists in the user directory. Otherwise it writes that temporary file, reads it back byte for byte, and removes it in a finally cleanup step. It never uploads a program, changes a key/value setting, starts a program, or flashes firmware. Do not pass --mutate on hardware whose user storage you are not authorized to change. If the command reports a cleanup failure, inspect the user directory and remove only v5x_smoke.txt after confirming it belongs to this run:

​
Results and cleanup

Successful runs exit with 0. Invalid options use 2, missing devices use 3, device or protocol failures use 4, and local screenshot I/O failures use 5. Other unexpected harness failures use 1. These codes are stable so a private hardware lab can wrap the command without putting hardware in public CI. After either path, visually inspect the screenshot, disconnect the USB cable, and confirm the device remains in its original operating state. Delete local PNG/JSON artifacts when they are no longer needed.
Hardware smoke harness - v5x