EmbedVerify

Platform-neutral hardware interface verification framework.

The first validated chain is USB Host + USB storage on reComputer J401. Current work is extending the same framework shape to more J401 carrier-board interfaces without moving board-specific command decisions into Fixture code.

Architecture

Suite      test scenario, such as usb_smoke
Case       module workflow, such as usb_host_storage
Function   stable test semantic and stable output format
Capability board/platform-specific command and sysfs implementation
Board      resource and capability declaration

Function output stays compatible with the existing EmbedVerify contract:

{
  "code": 0,
  "message": "...",
  "details": {},
  "metrics": {}
}

Quick Start

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

ev run suites/usb_smoke.yaml \
  --board recomputer_j401

The default board can also be selected from root config.yaml, so the normal command can be:

ev run suites/usb_smoke.yaml

Additional read-only peripheral smoke coverage is available with:

ev run suites/peripheral_smoke.yaml

For hardware currently attached to the J401 carrier board, run:

ev run suites/connected_peripherals_smoke.yaml

connected_peripherals_smoke covers Wi-Fi/BT scan, HDMI/display subsystem detection, and CSI camera Argus capture. UART loopback remains available as cases/uart_loopback.yaml, but it is not part of this suite until the exact header pins and Linux device mapping are confirmed. CSI camera tests expect the correct Jetson camera device-tree overlay to be selected manually with jetson-io.py and the board rebooted before running the suite.

SPI spidev discovery, transfer, and MOSI/MISO loopback are available as standalone functions. With MOSI and MISO shorted, run:

sudo env PYTHONPATH=src python3 -m embedverify.cli.main run-case cases/spi_loopback.yaml

The runner auto-detects the first USB storage device. If the selected partition is not mounted and the command is running as root, the write-speed test mounts it temporarily under /mnt/embedverify-*, writes .ev_write_test.bin, removes the file, and unmounts it after the test.

Manual overrides are still available:

ev run suites/usb_smoke.yaml \
  --board recomputer_j401 \
  --storage-device /dev/sda \
  --mount-point /media/seeed/USB_TEST

Target Dependencies

Install or verify these tools on the board:

sudo apt-get update
sudo apt-get install -y python3 python3-venv python3-pip python3-serial python3-spidev usbutils util-linux coreutils hdparm iproute2 iputils-ping i2c-tools gpiod wireless-tools iw bluetooth bluez x11-xserver-utils gstreamer1.0-tools

Or use the helper script from the repository root:

scripts/bootstrap_target.sh

Run the USB smoke suite with auto-discovery:

scripts/run_usb_smoke.sh

Override the detected device and mount point when needed:

STORAGE_DEVICE=/dev/sdb MOUNT_POINT=/media/seeed/MY_USB scripts/run_usb_smoke.sh

Add Another Board

See boards/README.md and ai_context/BOARD_PORTING_GUIDE.md for the full porting rules. The short version is: add a board profile first, map each Function-facing capability to an implementation, dry-run one suite, then verify one real case on hardware before running a broad suite.

Add a file under boards/, for example:

name: rk3576
platform: linux
adapter: rk
capabilities:
  usb: linux_generic
  storage: linux_generic
  system_info: rk
tools_required:
  - lsusb
  - lsblk
  - findmnt
  - dd

Generic Linux USB and storage functions can be reused across Jetson and RK boards. Only platform-specific capabilities such as system info, thermals, GPU, NPU, or vendor-specific sysfs paths need a board/platform adapter.