ecu-tests/docs/19_frame_io_and_alm_helpers.md

# Hardware Test Helpers — `FrameIO` and `AlmTester`

Hardware tests under `tests/hardware/` use two helper modules to keep test
bodies focused on intent rather than bus mechanics:

| Module | Scope | What it gives you |
| --- | --- | --- |
| [`tests/hardware/frame_io.py`](../tests/hardware/frame_io.py) | **Generic LDF I/O** | `FrameIO` class — send/receive any LDF-defined frame by name, plus pack/unpack and raw-bus escape hatches. Knows nothing about ALM. |
| [`tests/hardware/alm_helpers.py`](../tests/hardware/alm_helpers.py) | **ALM_Node domain** | `AlmTester` class + constants + pure utilities. Encodes the test patterns specific to the ALM_Req_A / ALM_Status / PWM_Frame / PWM_wo_Comp / Tj_Frame / ConfigFrame set. Built on `FrameIO`. |

The split lets the same `FrameIO` class be reused by future test suites for
other ECUs while keeping ALM-specific knowledge in one place.

---

## 1. Three layers of access

`FrameIO` exposes the same bus three ways. A test picks whichever layer
matches its intent.

### 1.1 High level — by frame and signal name

This is the default for almost every test. The LDF carries the frame ID,
length, and signal layout, so the test code never mentions any of those.

```python
fio.send(
    "ALM_Req_A",
    AmbLightColourRed=255, AmbLightColourGreen=0, AmbLightColourBlue=0,
    AmbLightIntensity=255,
    AmbLightUpdate=0, AmbLightMode=0, AmbLightDuration=10,
    AmbLightLIDFrom=alm.nad, AmbLightLIDTo=alm.nad,
)

decoded = fio.receive("ALM_Status")           # full dict of decoded signals
nad     = fio.read_signal("ALM_Status", "ALMNadNo")   # one signal
```

### 1.2 Mid level — pack / unpack without I/O

Use this when you want to build a payload, inspect or modify it, and then
send it (often via the low-level path).

```python
data = bytearray(fio.pack("ALM_Req_A", AmbLightColourRed=255, ...))
data[7] |= 0x80                                    # tweak a bit by hand
fio.send_raw(fio.frame_id("ALM_Req_A"), bytes(data))

# Decode raw bytes you already have:
decoded = fio.unpack("PWM_Frame", b"\x12\x34..." )
```

### 1.3 Low level — raw bus, bypass the LDF

For cases the LDF doesn't describe, or when you need full control.

```python
fio.send_raw(0x12, bytes([0x00] * 8))
rx = fio.receive_raw(0x11, timeout=0.5)            # returns LinFrame | None
```

### 1.4 Introspection

```python
fio.frame_id("PWM_Frame")        # 0x12
fio.frame_length("PWM_Frame")    # 8
fio.frame("PWM_Frame")           # raw ldfparser Frame object (cached)
fio.lin                          # underlying LinInterface
fio.ldf                          # LdfDatabase
```

---

## 2. How frame names reach `FrameIO`

A common point of confusion when reading the API for the first time is
*"where does FrameIO get the list of frame names from?"* — looking at
`FrameIO.send("ALM_Req_A", ...)` it can seem like the class must hold a
registry of known frames somewhere.

**It doesn't.** `FrameIO` has zero pre-knowledge of any frame name. It's
a **broker** — the caller hands it a string, it forwards that string to
the LDF object it was constructed with, and it uses what comes back.

### 2.1 Where the names actually live

| Location | What it has | Example |
|---|---|---|
| The LDF file on disk (e.g. `vendor/4SEVEN_color_lib_test.ldf`) | Source of truth — frame definitions in LDF syntax | `Frames { ALM_Req_A: 10, Master_Node, 8 { ... } }` |
| `LdfDatabase` (`ecu_framework/lin/ldf.py`, parsed once per pytest session) | Dict-like access to the parsed frames | `db.frame("ALM_Req_A")` returns a `Frame` with `.id`, `.length`, `.pack(...)`, `.unpack(...)` |
| Caller's source code | A **string literal** in a test, or a class-level `NAME = "ALM_Req_A"` in the generated wrapper | `fio.send("ALM_Req_A", ...)` |

`FrameIO` itself is **not** in this table. The class stores only a
reference to the LDF object and an empty cache:

```python
# tests/hardware/frame_io.py:44
class FrameIO:
    def __init__(self, lin: LinInterface, ldf) -> None:
        self._lin = lin
        self._ldf = ldf
        self._frames: dict = {}    # starts empty, fills on demand
```

It learns names exactly when a caller hands one over.

### 2.2 A concrete call trace

Watching the string flow through `fio.send("ALM_Req_A", AmbLightColourRed=255)`:

```
Test code (a hardware test in tests/hardware/mum/)
   |
   |  fio.send("ALM_Req_A", AmbLightColourRed=255, ...)
   v
FrameIO.send(frame_name="ALM_Req_A", **signals)            # frame_io.py:77
   |
   |  f = self.frame(frame_name)
   v
FrameIO.frame(name="ALM_Req_A")                            # frame_io.py:61
   |
   |  Not in cache? Look it up via the duck-typed ldf:
   |  f = self._ldf.frame("ALM_Req_A")
   v
LdfDatabase.frame(name="ALM_Req_A")                        # ecu_framework/lin/ldf.py
   |
   |  Returns the parsed Frame object
   v
Frame(id=0x0A, length=8, signals={...})                    # has .id, .pack, .unpack
   |
   |  Back in FrameIO.frame: cache the result so the next call is O(1)
   |  self._frames["ALM_Req_A"] = f
   |  return f
   v
Back in FrameIO.send:
   data = f.pack(AmbLightColourRed=255, ...)               # Frame builds the byte payload
   self._lin.send(LinFrame(id=f.id, data=data))            # wire it out via LinInterface
```

At no point did `FrameIO` ever store, import, or hard-code the string
`"ALM_Req_A"`. The string travelled:

```
test source -> FrameIO -> LdfDatabase -> ldfparser -> byte layout
```

`FrameIO`'s only contribution was **caching the LDF lookup** so a second
`fio.send("ALM_Req_A", ...)` skips the re-parse.

### 2.3 Where the caller gets the name from

Two paths, your choice per test file:

**Path A — stringly-typed: caller writes the literal.**

```python
def test_red(fio):
    fio.send("ALM_Req_A", AmbLightColourRed=255, ...)   # string in test source
```

The string `"ALM_Req_A"` lives in the test file. Typo it and you get a
`KeyError` (or `FrameNotFound`) at runtime when
`self._ldf.frame("ALM_Req_a")` fails.

**Path B — typed wrapper: name lives in a generated class.**

```python
# tests/hardware/_generated/lin_api.py (auto-generated from the LDF)
class AlmReqA:
    NAME = "ALM_Req_A"                          # the string lives here
    FRAME_ID = 0x0A
    ...
    @classmethod
    def send(cls, fio, **signals):
        fio.send(cls.NAME, **signals)           # still goes through fio.send as a string

# Your test:
def test_red(fio):
    AlmReqA.send(fio, AmbLightColourRed=255, ...)
```

Same underlying call. The only difference is **where the string lives**:
in your test (Path A) vs in a generated class (Path B). Path B catches
the typo at import time (`AlmReqB` -> `ImportError` / mypy error), Path A
catches it at runtime. See [`22_generated_lin_api.md`](22_generated_lin_api.md)
for the full design rationale for Path B.

Either way, `FrameIO` itself sees only an incoming string and forwards it.

### 2.4 The cache lifecycle

`self._frames` starts empty. Each unique `frame_name` passed in adds one
entry on its first use. So after a test session that touched
`ALM_Req_A`, `ALM_Status`, and `PWM_Frame`, the cache is:

```python
{
    "ALM_Req_A":  Frame(id=0x0A, ...),
    "ALM_Status": Frame(id=0x11, ...),
    "PWM_Frame":  Frame(id=0x12, ...),
}
```

…and `FrameIO` still has no idea those names exist *until* a caller
asked for them. The LDF object had them all along; `FrameIO` just
learned them lazily.

### 2.5 The mental model

`FrameIO` is a broker with two contracts:

1. *"Give me a name, I'll look it up in whatever LDF you gave me at
   construction time, then I'll send the resulting frame over whatever
   `LinInterface` you gave me."*
2. *"…and I'll cache the lookup so you don't pay for it twice."*

That's the whole class. It doesn't know your ECU, your project, your
frame names, or your LDF revision. It's a generic glue layer. Swap the
LDF (different ECU project), the same `FrameIO` works without
modification — that's the architectural payoff for keeping it
name-agnostic.

---

## 3. `FrameIO` API reference

```python
class FrameIO:
    def __init__(self, lin: LinInterface, ldf): ...

    # high level
    def send(self, frame_name: str, **signals) -> None
    def receive(self, frame_name: str, timeout: float = 1.0) -> dict | None
    def read_signal(self, frame_name: str, signal_name: str, *,
                    timeout: float = 1.0, default=None) -> Any

    # mid level
    def pack(self, frame_name: str, **signals) -> bytes
    def unpack(self, frame_name: str, data: bytes) -> dict

    # low level
    def send_raw(self, frame_id: int, data: bytes) -> None
    def receive_raw(self, frame_id: int, timeout: float = 1.0) -> LinFrame | None

    # introspection
    def frame(self, name: str)
    def frame_id(self, name: str) -> int
    def frame_length(self, name: str) -> int

    # injected refs
    @property
    def lin(self) -> LinInterface
    @property
    def ldf(self)
```

Notes:

- `send()` / `pack()` require **every** signal in the frame; ldfparser
  raises if one is missing. Use `receive()` first if you want to merge a
  change into the current state.
- `receive()` returns `None` on timeout (rather than raising), so polling
  loops stay simple.
- All frame lookups are cached per `FrameIO` instance — repeated calls to
  `send`/`receive`/`frame` for the same name don't re-walk the LDF.

---

## 4. `AlmTester` API reference

`AlmTester` bundles a `FrameIO` and a NAD, and exposes ALM-specific test
patterns. Build it once in a fixture and pass it into tests.

```python
class AlmTester:
    def __init__(self, fio: FrameIO, nad: int): ...

    @property
    def fio(self) -> FrameIO            # the underlying FrameIO
    @property
    def nad(self) -> int                # bound node NAD

    # ALM_Status polling
    def read_led_state(self, timeout: float = STATE_RECEIVE_TIMEOUT) -> int
    def wait_for_state(self, target: int, timeout: float
                       ) -> tuple[bool, float, list[int]]
    def measure_animating_window(self, max_wait: float
                                 ) -> tuple[float | None, list[int]]

    # LED control
    def force_off(self) -> None         # drives mode=0, intensity=0; sleeps to settle

    # PWM assertions (use rgb_to_pwm.compute_pwm() under the hood)
    def assert_pwm_matches_rgb(self, rp, r, g, b, *, label: str = "") -> None
    def assert_pwm_wo_comp_matches_rgb(self, rp, r, g, b, *, label: str = "") -> None
```

The `assert_pwm_*` helpers:

- Read `Tj_Frame_NTC` (Kelvin), convert to °C, and pass it to `compute_pwm`
  so temperature compensation matches what the ECU is applying.
- Sleep `PWM_SETTLE_SECONDS` (10 LIN frame periods) before reading PWM
  frames so the slave's TX buffer has time to refresh.
- Record both expected and actual values as report properties via the
  `rp(...)` helper from `tests/conftest.py`. The optional `label`
  parameter lets you append a suffix when you assert PWM more than once
  in the same test.

---

## 5. Constants and utilities (in `alm_helpers`)

```python
# ALMLEDState (from LDF Signal_encoding_types: LED_State)
LED_STATE_OFF        = 0
LED_STATE_ANIMATING  = 1
LED_STATE_ON         = 2

# Test pacing — chosen against the 10 ms LIN frame periodicity
STATE_POLL_INTERVAL       = 0.05    # 50 ms between polls (5 LIN periods)
STATE_RECEIVE_TIMEOUT     = 0.2     # per-poll receive timeout
STATE_TIMEOUT_DEFAULT     = 1.0     # default wait_for_state ceiling
PWM_SETTLE_SECONDS        = 0.1     # let the slave refresh PWM_Frame TX buffer
DURATION_LSB_SECONDS      = 0.2     # AmbLightDuration scale: 1 LSB = 200 ms
FORCE_OFF_SETTLE_SECONDS  = 0.4     # pause after the OFF command

# PWM tolerances
KELVIN_TO_CELSIUS_OFFSET = 273.15
PWM_ABS_TOL = 3277      # ±5% of 16-bit full scale
PWM_REL_TOL = 0.05      # ±5% of expected, whichever is larger

# Pure utilities
def ntc_kelvin_to_celsius(ntc_raw: int) -> float
def pwm_within_tol(actual: int, expected: int) -> bool
```

---

## 6. Fixture wiring

`fio`, `alm`, `nad`, and the autouse `_reset_to_off` are provided by
`tests/hardware/mum/conftest.py` — session-scoped (except `_reset_to_off`,
which must be function-scoped) and shared by every MUM test. A new MUM test
just lists them in its signature:

```python
def test_red_at_full(fio, alm, rp):
    fio.send("ALM_Req_A", ...)
    alm.assert_pwm_matches_rgb(rp, 255, 0, 0)
```

The MUM gate (`if config.interface.type != "mum": pytest.skip(...)`) is a
session-scoped autouse `_require_mum` in the same conftest — no per-test
opt-in needed.

The `lin`, `ldf`, and `config` fixtures are provided globally by
`tests/conftest.py`; see [`24_test_wiring.md`](24_test_wiring.md) for the
full three-layer fixture topology and the rationale behind the access
control.

### Overriding the autouse reset

A module that needs a richer baseline (e.g. `tests/hardware/mum/test_overvolt.py`
restores the PSU rail in addition to the LED) overrides `_reset_to_off`
locally — the local definition shadows the conftest's:

```python
@pytest.fixture(autouse=True)
def _reset_to_off(psu, alm):
    apply_voltage_and_settle(psu, NOMINAL_VOLTAGE, validation_time=0.2)
    alm.force_off()
    yield
    apply_voltage_and_settle(psu, NOMINAL_VOLTAGE, validation_time=0.2)
    alm.force_off()
```

---

## 7. Cookbook

### Drive the LED to a color and verify both PWM frames

```python
def test_red_at_full(fio, alm, rp):
    r, g, b = 255, 0, 0
    fio.send("ALM_Req_A",
             AmbLightColourRed=r, AmbLightColourGreen=g, AmbLightColourBlue=b,
             AmbLightIntensity=255,
             AmbLightUpdate=0, AmbLightMode=0, AmbLightDuration=10,
             AmbLightLIDFrom=alm.nad, AmbLightLIDTo=alm.nad)

    reached, _, history = alm.wait_for_state(LED_STATE_ON, timeout=1.0)
    assert reached, history
    alm.assert_pwm_matches_rgb(rp, r, g, b)
    alm.assert_pwm_wo_comp_matches_rgb(rp, r, g, b)
```

### Toggle a single ConfigFrame bit and restore it

```python
def test_with_compensation_off(fio, alm, rp):
    try:
        fio.send("ConfigFrame",
                 ConfigFrame_Calibration=0,
                 ConfigFrame_EnableDerating=1,
                 ConfigFrame_EnableCompensation=0,
                 ConfigFrame_MaxLM=3840)
        time.sleep(0.2)
        # ... drive the LED, observe non-compensated PWM ...
    finally:
        fio.send("ConfigFrame",
                 ConfigFrame_Calibration=0,
                 ConfigFrame_EnableDerating=1,
                 ConfigFrame_EnableCompensation=1,
                 ConfigFrame_MaxLM=3840)
        time.sleep(0.2)
```

### Read one signal periodically

```python
nad = fio.read_signal("ALM_Status", "ALMNadNo", timeout=0.5, default=None)
if nad is None:
    pytest.skip("ECU silent")
```

### Build a malformed payload and send it raw

```python
data = bytearray(fio.pack("ALM_Req_A",
                          AmbLightColourRed=0, AmbLightColourGreen=0,
                          AmbLightColourBlue=0, AmbLightIntensity=0,
                          AmbLightUpdate=0, AmbLightMode=0, AmbLightDuration=0,
                          AmbLightLIDFrom=0, AmbLightLIDTo=0))
data[2] = 0xFF                              # corrupt one byte
fio.send_raw(fio.frame_id("ALM_Req_A"), bytes(data))
```

---

## 8. Writing a new test

### 8.1 Starting point

A heavily-annotated, copyable template lives at
[`tests/hardware/_test_case_template.py`](../tests/hardware/_test_case_template.py).
The leading underscore stops pytest from collecting it, so the example
bodies don't run on the bench.

Copy it to a new file named `test_<feature>.py` under `tests/hardware/`
and edit. The template includes:

- The standard imports for `frame_io` and `alm_helpers`
- The three module-level fixtures (`fio`, `alm`, `_reset_to_off`) with
  inline explanations of fixture scope, `autouse`, and `yield`
- Three skeleton bodies (one per common shape — see §7.3)
- An appendix listing the most-reached-for patterns

### 8.2 The four-phase test pattern

Every hardware test that mutates ECU state beyond just the LED should
follow a **SETUP / PROCEDURE / ASSERT / TEARDOWN** structure with a
`try`/`finally` so the teardown runs even when an assertion fails.

```python
def test_xyz(fio, alm, rp):
    """..."""
    # ── SETUP ──────────────────────────────────────
    # Bring the ECU to the exact state THIS test needs, beyond what the
    # autouse reset already gave us. Anything you change here MUST be
    # undone in TEARDOWN below.
    fio.send("ConfigFrame", ConfigFrame_EnableCompensation=0, ...)
    time.sleep(0.2)

    try:
        # ── PROCEDURE ──────────────────────────────
        # The actions whose effects you are validating.
        fio.send("ALM_Req_A", ...)
        reached, _, history = alm.wait_for_state(LED_STATE_ON, timeout=1.0)

        # ── ASSERT ─────────────────────────────────
        # Bus-observable expectations. Use `rp("key", value)` to attach
        # diagnostics to the report, then assert.
        rp("led_state_history", history)
        assert reached, history
        alm.assert_pwm_wo_comp_matches_rgb(rp, r, g, b)

    finally:
        # ── TEARDOWN ───────────────────────────────
        # Always runs. Restores anything SETUP perturbed.
        fio.send("ConfigFrame", ConfigFrame_EnableCompensation=1, ...)
        time.sleep(0.2)
```

### Why this gives you test independence

Pytest runs tests in a deterministic order (the order they appear in the
file). Without strict teardown, a failure midway through one test can
leave the ECU in a non-default state that breaks every subsequent test
— turning a single bug into a cascade. The four-phase pattern prevents
that with two layers:

| Layer | What it covers | Where it lives |
|---|---|---|
| Common baseline | LED → OFF | autouse `_reset_to_off` fixture |
| Per-test specifics | ConfigFrame, schedules, mode flags, anything else | the test's own `try`/`finally` |

The autouse fixture handles the universal baseline so individual tests
don't have to think about it; the per-test `try`/`finally` handles
whatever that specific test mutated.

### When you can skip the four phases

If your test only sends a frame and observes the LED state (i.e. the
*only* mutable state involved is something the autouse reset already
restores), the explicit SETUP/TEARDOWN sections are dead weight — just
write the procedure straight through. Flavor A in the template
illustrates this minimal shape.

### 8.3 Three flavors in the template

| Flavor | When to use it |
|---|---|
| **A — minimal** | Test only drives the LED and asserts on PWM/state. The autouse reset is enough. |
| **B — with isolation** | Test changes any persistent ECU state (ConfigFrame, schedules, NAD, …). Use the `try`/`finally` pattern. |
| **C — single-signal probe** | "Ask the ECU one thing and check the answer." Uses `fio.read_signal(...)`, no state mutation. |

Pick the closest one, delete the others, rename the function and fill
in the docstring.

### 8.4 Tests that drive the PSU and observe the LIN bus

For *combined* PSU + LIN scenarios (overvoltage / undervoltage
tolerance, brown-out behaviour, supply transients) there is a
dedicated template at
[`tests/hardware/_test_case_template_psu_lin.py`](../tests/hardware/_test_case_template_psu_lin.py).
It adds a `psu` fixture (cross-platform port resolution + safe-off
on close), an autouse `_park_at_nominal` fixture, a
`wait_for_voltage_status` polling helper, and three flavors:

| Flavor | Demonstrates |
|---|---|
| A — overvoltage | Drive PSU above the OV threshold, expect `ALMVoltageStatus = 0x02`, restore. |
| B — undervoltage | Symmetric for UV (`0x01`). |
| C — sweep | Parametrized walk over `(V, expected_status)` tuples. |

For the *settling time* characterization that feeds these tests'
detect timeouts, see `tests/hardware/psu/test_psu_voltage_settling.py`
(opt-in via `pytest -m psu_settling`).

See [`docs/14_power_supply.md` §6](14_power_supply.md#6-run-the-hardware-test) and [§5 (session-managed power)](14_power_supply.md#5-session-managed-power-the-bench-powers-the-ecu-through-the-psu)
for the full reference and the constants to tune for your firmware.

---

## 9. Related docs

- [`04_lin_interface_call_flow.md`](04_lin_interface_call_flow.md) — what
  `LinInterface.send`/`receive` does under the hood for each adapter.
- [`16_mum_internals.md`](16_mum_internals.md) — MUM-specific behaviour
  the helpers rely on (master-driven receive, frame-length map, …).
- [`17_ldf_parser.md`](17_ldf_parser.md) — how the LDF is loaded and how
  `pack` / `unpack` are implemented.
- [`13_unit_testing_guide.md`](13_unit_testing_guide.md) — unit-test
  conventions, markers, coverage.
- [`15_report_properties_cheatsheet.md`](15_report_properties_cheatsheet.md)
  — the standard `rp("key", value)` keys these helpers emit.