Test Tools API Reference
========================

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

.. contents:: Tool Index
   :local:
   :depth: 1

Test Harness
------------

test_harness - Main Test Orchestrator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

.. automodule:: test_harness
   :members:
   :undoc-members:
   :show-inheritance:

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.

.. automodule:: flash
   :members:
   :undoc-members:
   :show-inheritance:

Usage::

    python tools/flash.py build/addvantage3.hex

UART Capture
------------

uart_capture - Telemetry Parser
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Captures and parses UART telemetry output from the firmware.

.. automodule:: uart_capture
   :members:
   :undoc-members:
   :show-inheritance:

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.

.. automodule:: can_capture
   :members:
   :undoc-members:
   :show-inheritance:

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.

.. automodule:: can_validate
   :members:
   :undoc-members:
   :show-inheritance:

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.

.. automodule:: release
   :members:
   :undoc-members:
   :show-inheritance:

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