ecu-tests/docs/04_lin_interface_call_flow.md

# LIN Interface Call Flow

This document explains how LIN operations flow through the abstraction for the Mock, MUM, and the deprecated BabyLIN adapters.

## Contract (base)

File: `ecu_framework/lin/base.py`

This module is the **polymorphism boundary for LIN I/O**. Everything above it
(tests, fixtures, helpers like `FrameIO`/`AlmTester`) depends only on these
abstractions, so the same code can run against a mock in CI or against real
hardware on a Pi by swapping the concrete adapter.

### `LinFrame` (dataclass)

A validated representation of a single LIN frame:

- `id: int` — frame identifier; enforced to `0x00–0x3F` (classic 6-bit LIN ID range)
- `data: bytes` — payload; coerced from list-of-ints to `bytes` if needed, capped at 8 bytes

Validation runs in `__post_init__`, so any malformed frame fails fast at
construction rather than surfacing as a confusing error deeper in the stack:

- ID outside `0x00–0x3F` → `ValueError`
- `data` not bytes-like and not coercible → `TypeError`
- `len(data) > 8` → `ValueError`

#### How `__post_init__` runs

`__post_init__` is never called explicitly in `base.py` — it is a dataclass
hook invoked automatically by the `__init__` that `@dataclass` generates. For
`LinFrame`, that generated `__init__` is effectively:

```python
def __init__(self, id, data):
    self.id = id
    self.data = data
    self.__post_init__()   # auto-appended because __post_init__ is defined
```

So when someone writes `LinFrame(id=0x10, data=[1, 2, 3])`:

1. The generated `__init__` assigns `self.id` and `self.data` exactly as
   passed in (no validation, no coercion).
2. It then calls `self.__post_init__()` with no arguments.
3. `__post_init__` re-reads `self.id` / `self.data`, validates the ID range,
   coerces `self.data` to `bytes` (which is why a list of ints is accepted
   even though the annotation says `bytes`), and validates length.
4. If validation fails, the raised exception propagates out of the
   `LinFrame(...)` call — so a bad frame never becomes a live object. There
   is no half-constructed `LinFrame` for callers to observe.

Two consequences worth knowing:

- **Order matters.** Type coercion of `data` happens inside `__post_init__`,
  so between the field assignment and the `__post_init__` call there is a
  brief moment where `self.data` may be a `list` rather than `bytes`.
  Nothing observes that window, but it's why the type annotation is slightly
  optimistic.
- **Inheritance.** Any subclass of `LinFrame` that overrides `__post_init__`
  must call `super().__post_init__()` or it loses the validation. No
  subclass exists today; this is purely a future-proofing note.

### `LinInterface` (abstract base class)

The contract every concrete LIN adapter must implement. Abstract methods:

- `connect()` — open the interface connection
- `disconnect()` — close the interface connection
- `send(frame: LinFrame)` — transmit a LIN frame
- `receive(id: int | None = None, timeout: float = 1.0) -> LinFrame | None` — receive a frame, optionally filtered by ID; returns `None` on timeout

Non-abstract methods with default implementations (overridable):

- `request(id: int, length: int, timeout: float = 1.0) -> LinFrame | None` —
  default implementation just calls `receive(id=id, timeout=timeout)`. Adapters
  that need to send a header first (e.g. BabyLIN, MUM) override this.
- `flush()` — no-op hook for clearing RX buffers.

### Concrete implementors

- `ecu_framework/lin/mock.py` — in-memory mock for unit tests and CI
- `ecu_framework/lin/mum.py` — Melexis Universal Master (current hardware path)
- `ecu_framework/lin/babylin.py` — BabyLIN SDK wrapper (deprecated)

### Consumers

`LinFrame` and `LinInterface` are imported across the framework — the conftest
plugin (`tests/conftest.py`), hardware helpers (`tests/hardware/frame_io.py`),
unit tests (`tests/unit/test_linframe.py`, `tests/unit/test_hex_flasher.py`),
and the bulk of `tests/hardware/*` test cases. Tests never import a concrete
adapter directly; the `lin` fixture in `conftest.py` resolves the adapter
based on configuration, which is what makes the same test file runnable
against mock or hardware.

## Mock adapter flow

File: `ecu_framework/lin/mock.py`

- `connect()`: initialize buffers and state
- `send(frame)`: enqueues the frame and (for echo behavior) schedules it for RX
- `receive(timeout)`: waits up to timeout for a frame in RX buffer
- `request(id, length, timeout)`: synthesizes a deterministic response of the given length for predictability
- `disconnect()`: clears state

Use cases:
- Fast local dev, deterministic responses, no hardware
- Timeout and boundary behavior validation

## MUM adapter flow (Melexis Universal Master)

File: `ecu_framework/lin/mum.py`

The MUM is a networked LIN master (default IP `192.168.7.2`) with built-in
power control on `power_out0`. It is **master-driven**: there is no passive
listen — to read a slave-published frame, the master triggers a header on
that frame ID. Diagnostic frames (BSM-SNPD, service ID 0xB5) require LIN 1.x
**Classic** checksum and are sent through the transport layer's
`ld_put_raw`, not the regular `send_message`.

- `connect()`: lazy-imports `pymumclient` + `pylin`; opens MUM
  (`MelexisUniversalMaster.open_all(host)`), gets the LIN device
  (`linmaster`) and power device (`power_control`), runs `linmaster.setup()`,
  builds `LinBusManager` + `LinDevice22`, sets `lin_dev.baudrate`, fetches
  the transport layer (`get_device("bus/transport_layer")`), and finally
  `power_control.power_up()` followed by a `boot_settle_seconds` sleep
- `send(frame)`: `lin_dev.send_message(master_to_slave=True, frame_id, data_length, data)`
- `receive(id, timeout)`: `lin_dev.send_message(master_to_slave=False, frame_id=id, data_length=frame_lengths.get(id, default_data_length))`
  — pylin returns the response bytes (or raises on timeout, which we treat as `None`).
  `id=None` raises `NotImplementedError` because the MUM cannot listen passively.
- `disconnect()`: best-effort `power_control.power_down()` followed by `linmaster.teardown()`
- MUM-only extras: `send_raw(bytes)` (Classic checksum via `ld_put_raw`),
  `power_up()`, `power_down()`, `power_cycle(wait)`

Configuration:

- `interface.host` is required; `interface.lin_device` and `interface.power_device` default to MUM conventions
- `interface.bitrate` is the actual LIN baudrate the MUM drives
- `interface.frame_lengths` lets you map slave frame IDs to their fixed data lengths so `receive(id)` can fetch the correct number of bytes; built-in defaults cover ALM_Status (4) and ALM_Req_A (8)

## BabyLIN adapter flow (SDK wrapper) — DEPRECATED

> Retained only so existing BabyLIN rigs can keep running. New work should use the MUM flow above.

File: `ecu_framework/lin/babylin.py` (emits `DeprecationWarning` on instantiation)

- `connect()`: import SDK `BabyLIN_library.py`, discover ports, open first, optionally `BLC_loadSDF`, get channel handle, and `BLC_sendCommand("start schedule N;")`
- `send(frame)`: calls `BLC_mon_set_xmit(channelHandle, frameId, data, slotTime=0)`
- `receive(timeout)`: calls `BLC_getNextFrameTimeout(channelHandle, timeout_ms)` and converts returned `BLC_FRAME` to `LinFrame`
- `request(id, length, timeout)`: prefers `BLC_sendRawMasterRequest(channel, id, length)`; falls back to `(channel, id, bytes)`; if unavailable, sends a header and waits on `receive()`
- `disconnect()`: calls `BLC_closeAll()`
- Error handling: uses `BLC_getDetailedErrorString` (if available)

Configuration:
- `interface.sdf_path` locates the SDF to load
- `interface.schedule_nr` sets the schedule to start upon connect
- `interface.channel` selects the channel index

## Edge considerations

- Ensure the correct architecture (x86/x64) of the DLL matches Python
- Channel/bitrate must match your network configuration
- Some SDKs require initialization/scheduling steps before transmit/receive
- Time synchronization and timestamp units vary per SDK — convert as needed

Note on master requests:
- Our mock wrapper returns a deterministic byte pattern when called with the `length` signature.
- When only the bytes signature is available, zeros of the requested length are used in tests.