Test Tools API Reference

Python tools for hardware-in-loop (HIL) testing and validation.

Test Harness

test_harness - Main Test Orchestrator

The primary test harness that flashes firmware and validates boot behavior.

Usage Example:

python tools/test_harness.py --hex build/addvantage3.hex --expected-version 3.2.7

Command Line Options:

• --hex - Path to firmware .hex file (required)

• --port - Serial port (auto-detect if not specified)

• --expected-version - Expected version string to verify

• --skip-flash - Skip flashing, just test UART

• --can-validate - Run CAN bus validation

• --can-tolerance - Tolerance percentage for CAN validation (default: 10%)

Flash Utilities

flash - J-Link Programming

Flash programming utilities using SEGGER J-Link.

J-Link flash utility for AddVantage PPG firmware. Cross-platform (Windows/Linux/macOS)

flash.find_jlink()

Find J-Link Commander executable.

Return type:

str

flash.flash_firmware(hex_path, verify=True)

Flash firmware using J-Link Commander.

Parameters:

• hex_path (str) – Path to .hex file

• verify (bool) – Whether to verify after flashing

Return type:

bool

Returns:

True if successful, False otherwise

flash.reset_target()

Reset the target MCU.

Return type:

bool

Usage:

python tools/flash.py build/addvantage3.hex

UART Capture

uart_capture - Telemetry Parser

Captures and parses UART telemetry output from the firmware.

Data Classes:

• BootMessage - Parsed boot message with version and baud rate

• BootTelemetry - Initial boot telemetry with firmware info

• Telemetry - Regular telemetry updates (sent every 1 second)

Parsing Functions:

• parse_version_string() - Extract firmware version from boot output

• parse_boot_telemetry() - Parse initial boot telemetry string

• parse_telemetry_line() - Parse regular telemetry updates

• count_telemetry_lines() - Count telemetry messages (for stability check)

• count_version_strings() - Count boot messages (for loop detection)

CAN Bus Tools

can_capture - J1939 Message Capture

Captures and parses J1939 CAN messages using PCAN-USB adapter.

Supported PGNs:

• EEC1 (61444) - Engine Speed, Torque

• ET1 (65262) - Engine Temperature

• LFE (65266) - Fuel Economy

can_validate - CAN vs ECU Validation

Validates CAN bus data against ECU telemetry using statistical comparison.

Key Classes:

• Statistics - Collects samples and computes mean, stddev, min, max

• ValidationResult - Result of comparing CAN data to telemetry

Usage:

python tools/can_validate.py --duration 10 --tolerance 5

can_viewer - Real-time CAN GUI

Tkinter-based GUI for real-time CAN bus visualization with ECU comparison.

Features:

• Gauge widgets for RPM, Torque, Temperature

• Time series graphs with ECU overlay

• Side-by-side CAN vs ECU comparison table

• Percentage difference highlighting

Usage:

python tools/can_viewer.py

Release Automation

release - HIL-Gated Release

Automated release process with hardware-in-loop validation gate.

Release script for AddVantage PPG firmware.

This script: 1. Builds all firmware targets (standalone, DFU, bootloader, combined) 2. Runs HIL tests (flash + UART verification) 3. If tests pass, creates a git tag and pushes to trigger GitHub release

Usage:

python release.py –version 3.2.8 python release.py –version 3.2.8 –skip-test # Dangerous: skip HIL test python release.py –version 3.2.8 –test-dfu # Also test DFU upload

release.run_command(cmd, cwd=None, check=True)

Run a command and return the result.

Return type:

CompletedProcess

Parameters:

• cmd (list)

• cwd (str)

• check (bool)

release.validate_version(version)

Validate version string format (X.Y.Z).

Return type:

bool

Parameters:

version (str)

release.get_project_root()

Get the project root directory.

Return type:

Path

release.build_firmware(project_root, version)

Build all firmware targets with specified version.

Return type:

dict

Parameters:

• project_root (Path)

• version (str)

release.run_hil_test(project_root, hex_file, version, port=None)

Run HIL test harness for standalone firmware.

Return type:

bool

Parameters:

• project_root (Path)

• hex_file (Path)

• version (str)

• port (str)

release.run_dfu_test(project_root, files, version, port=None)

Run DFU upload test.

This test: 1. Flashes the combined image (bootloader + app) 2. Verifies application boots 3. Triggers DFU mode 4. Uploads DFU binary via XMODEM 5. Verifies new application boots

Requires device connected via both J-Link and USB-Serial.

Return type:

bool

Parameters:

• project_root (Path)

• files (dict)

• version (str)

• port (str)

release.create_tag_and_push(version, project_root)

Create git tag and push to origin.

Return type:

None

Parameters:

• version (str)

• project_root (Path)

release.main()

The release process:

1. Build firmware

2. Run test harness (flash + UART validation)

3. Optionally run CAN validation

4. Create tagged release if all tests pass