ecu-tests/docs/19_frame_io_and_alm_helpers.md

Hardware Test Helpers — AlmTester (and FrameIO underneath)

Hardware tests under tests/hardware/mum/ go through AlmTester — the contributor-facing API. Test bodies read like a sequence of intents (alm.send_color(red=255), alm.wait_for_led_on(), alm.read_voltage_status()) and never need to know the LDF schema or how FrameIO works.

Module	Scope	What it gives you
tests/hardware/alm_helpers.py	Contributor-facing API	AlmTester class — the only thing tests should reach for. Per-signal read_*, per-action send_*, cross-frame patterns (wait_for_state, assert_pwm_matches_rgb), and re-exported typed enums (LedState, Mode, Update, VoltageStatus, ThermalStatus, NVMStatus).
tests/hardware/frame_io.py	Implementation detail	FrameIO class — generic LDF-driven send/receive used by AlmTester internally. Test bodies should not import this directly; framework-level tests (LDF schema introspection, MUM-only send_raw, end-to-end smoke) are the exception.

Maintenance pact: when the LDF adds a signal or frame that tests should use, the corresponding read_* / send_* method goes into alm_helpers.py. Tests never look past that file.

The split lets the same FrameIO underlay be reused by future ECUs while each ECU's domain vocabulary (the facade methods) lives in its own <ecu>_helpers.py.

---

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.

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).

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.

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

1.4 Introspection

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:

# 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.

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 — hidden inside AlmTester (the recommended path).

# tests/hardware/alm_helpers.py — hand-maintained facade
class AlmTester:
    ...
    def send_color(self, *, red, green, blue, ...) -> None:
        self._fio.send("ALM_Req_A", AmbLightColourRed=red, ...)  # string lives here

# Your test:
def test_red(alm):
    alm.send_color(red=255, green=0, blue=0)        # zero strings in the test body

Same underlying call. Where the string lives is the only difference: in your test (Path A) vs in alm_helpers.py (Path B). Path B catches a signal-name typo as a TypeError at the call site (signal names are real kwarg names of the facade) and a frame-name typo never appears at the test level because the facade hides it. This is the path new contributors should use; Path A is reserved for low-level tests (schema introspection, MUM-only send_raw, end-to-end smoke). A previous Path B variant — an auto-generated typed-wrapper module — was retired in favor of the hand-maintained facade; see 22_generated_lin_api.md and ../deprecated/ for the history.

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:

{
    "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

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 is the contributor-facing surface. Built by the tests/hardware/mum/conftest.py alm fixture; tests just request it.

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

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

    # ─── Per-signal readers (ALM_Status, Tj_Frame, PWM_Frame, PWM_wo_Comp) ─
    def read_led_state(self, timeout: float = STATE_RECEIVE_TIMEOUT) -> int
    def read_nad(self, timeout: float = STATE_RECEIVE_TIMEOUT) -> int | None
    def read_voltage_status(self, timeout: float = STATE_RECEIVE_TIMEOUT) -> int | None
    def read_thermal_status(self, timeout: float = STATE_RECEIVE_TIMEOUT) -> int | None
    def read_nvm_status(self, timeout: float = STATE_RECEIVE_TIMEOUT) -> int | None
    def read_sig_comm_err(self, timeout: float = STATE_RECEIVE_TIMEOUT) -> int | None
    def read_ntc_kelvin(self) -> int | None
    def read_ntc_celsius(self) -> float | None
    def read_pwm(self) -> tuple[int, int, int, int] | None    # (R, G, B1, B2)
    def read_pwm_wo_comp(self) -> tuple[int, int, int] | None  # (R, G, B)

    # ─── Wait helpers ──────────────────────────────────────────────────────
    def wait_for_state(self, target: int, timeout: float
                       ) -> tuple[bool, float, list[int]]
    def wait_for_led_on(self, timeout: float = STATE_TIMEOUT_DEFAULT) -> bool
    def wait_for_led_off(self, timeout: float = STATE_TIMEOUT_DEFAULT) -> bool
    def wait_for_animating(self, timeout: float = STATE_TIMEOUT_DEFAULT) -> bool
    def measure_animating_window(self, max_wait: float
                                 ) -> tuple[float | None, list[int]]

    # ─── Per-action senders (ALM_Req_A) ────────────────────────────────────
    def send_color(self, *, red, green, blue, intensity=255,
                   mode=Mode.IMMEDIATE_SETPOINT,
                   update=Update.IMMEDIATE_COLOR_UPDATE,
                   duration=0,
                   lid_from=None, lid_to=None) -> None         # unicast (defaults to alm.nad)
    def send_color_broadcast(self, *, red, green, blue, ...) -> None  # LID 0x00..0xFF
    def save_color(self, *, red, green, blue, ...) -> None     # Update.COLOR_MEMORIZATION
    def apply_saved_color(self) -> None                        # Update.APPLY_MEMORIZED_COLOR
    def discard_saved_color(self) -> None                      # Update.DISCARD_MEMORIZED_COLOR

    # ─── ConfigFrame sender ────────────────────────────────────────────────
    def send_config(self, *, calibration=0,
                    enable_derating=1, enable_compensation=1,
                    max_lm=3840) -> None

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

    # ─── Cross-frame PWM assertions ────────────────────────────────────────
    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

Quick notes:

• Enum parameters accept int too — both Mode.IMMEDIATE_SETPOINT and plain 0 work because the generated enums inherit from IntEnum.
• lid_from / lid_to default to alm.nad — pass them only for range targeting (or use send_color_broadcast).
• assert_pwm_* helpers read Tj_Frame_NTC (Kelvin), convert to °C, and pass it to compute_pwm so temperature compensation matches what the ECU applies. They sleep PWM_SETTLE_SECONDS (10 LIN frame periods) before sampling the PWM frame. The optional label parameter lets you append a suffix when asserting PWM more than once in the same test.

---

5. Constants and utilities (in alm_helpers)

# 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:

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 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:

@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

from alm_helpers import AlmTester, LedState

def test_red_at_full(alm: AlmTester, rp):
    r, g, b = 255, 0, 0
    alm.send_color(red=r, green=g, blue=b, duration=10)

    assert alm.wait_for_led_on(timeout=1.0)
    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

def test_with_compensation_off(alm: AlmTester, rp):
    try:
        alm.send_config(enable_compensation=0)
        time.sleep(0.2)
        # ... drive the LED, observe non-compensated PWM ...
    finally:
        alm.send_config(enable_compensation=1)
        time.sleep(0.2)

Read one signal periodically

nad = alm.read_nad(timeout=0.5)
if nad is None:
    pytest.skip("ECU silent")

Save / apply / discard a color (AmbLightUpdate semantics)

# Buffer a colour without applying — LED state must not change yet.
alm.save_color(red=0, green=255, blue=0, mode=Mode.FADING_EFFECT_1, duration=10)
assert alm.read_led_state() == LedState.LED_OFF

# Commit later (semantics depend on firmware; not all builds support this).
alm.apply_saved_color()
assert alm.wait_for_led_on(timeout=2.0)

Drop down to fio for cases the facade doesn't model

Schema validation, MUM-only send_raw, or frames AlmTester doesn't yet know about — these legitimately need the low-level surface. The fixture makes fio available alongside alm:

def test_schema_has_frame(fio, alm, rp):
    # AlmTester doesn't expose LDF introspection by design — fio does.
    try:
        fio.frame("ALM_Req_B")
    except Exception:
        pytest.skip("ALM_Req_B not in current LDF")

    # ... continue with raw fio.send / receive ...

If the rare cases become common, add a facade method to alm_helpers.py and use it from then on. The maintenance pact (see §1) keeps test bodies short.

---

8. Writing a new test

8.1 Starting point

A heavily-annotated, copyable template lives at 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.

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. 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 and §5 (session-managed power) for the full reference and the constants to tune for your firmware.

---

9. Related docs

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