# MUM Adapter Internals (Melexis Universal Master)

This document describes how the `MumLinInterface` adapter wraps the Melexis
`pymumclient` and `pylin` packages, how frames flow across the LIN bus, and
which MUM-specific behaviors callers need to understand.

## Overview

- Location: `ecu_framework/lin/mum.py`
- Vendor reference scripts: `vendor/automated_lin_test/` (`test_led_control.py`, `test_auto_addressing.py`, `power_cycle.py`)
- Default MUM endpoint: `192.168.7.2` over USB-RNDIS
- LIN device name on MUM: `lin0`
- Power-control device on MUM: `power_out0`
- Required Python packages: `pylin`, `pymumclient` (Melexis-supplied; not on PyPI). See `vendor/automated_lin_test/install_packages.sh`.

## What the MUM gives you that BabyLIN doesn't

- **Built-in power control** on `power_out0` — the adapter calls `power_up()` in `connect()` and `power_down()` in `disconnect()`. No external Owon PSU needed for the standard flow.
- **Network access**: the MUM is IP-reachable, so the host machine (Windows, Linux, Pi) does not need vendor native libraries — only the two Python packages.
- **Direct transport-layer access** for sending raw frames with LIN 1.x **Classic** checksum (required for BSM-SNPD diagnostic frames).

## What it doesn't give you

- **No passive listen.** The MUM is master-driven. To "receive" a slave-published frame, the master sends a header on that frame ID and the slave must respond. `MumLinInterface.receive(id=None)` raises `NotImplementedError` for that reason.
- **No SDF / schedule manager.** The adapter does not run a schedule; tests publish frames explicitly (or pull slave frames explicitly) on each call.

## Mermaid: connect / receive / send

```mermaid
sequenceDiagram
  autonumber
  participant T as Test/Fixture
  participant A as MumLinInterface
  participant MM as pymumclient (MelexisUniversalMaster)
  participant PL as pylin (LinDevice22 / TransportLayer)
  participant E as ECU

  T->>A: connect()
  A->>MM: MelexisUniversalMaster()
  A->>MM: open_all(host)
  A->>MM: get_device('power_out0')
  A->>MM: get_device('lin0')
  A->>MM: linmaster.setup()
  A->>PL: LinBusManager(linmaster)
  A->>PL: LinDevice22(lin_bus); set baudrate
  A->>PL: get_device('bus/transport_layer')
  A->>MM: power_control.power_up()
  Note over A: sleep(boot_settle_seconds)
  A-->>T: connected

  T->>A: receive(id=0x11)
  A->>PL: send_message(master_to_slave=False, frame_id=0x11, data_length=4)
  PL->>E: header for 0x11
  E-->>PL: response bytes
  PL-->>A: bytes
  A-->>T: LinFrame(id=0x11, data=...)

  T->>A: send(LinFrame(0x0A, payload))
  A->>PL: send_message(master_to_slave=True, frame_id=0x0A, data_length=8, data=payload)
  PL->>E: header + payload (Enhanced checksum)

  T->>A: send_raw(b"\x7F\x06\xB5...")
  A->>PL: transport_layer.ld_put_raw(data, baudrate)
  Note over PL,E: LIN 1.x Classic checksum (required for BSM-SNPD)

  T->>A: disconnect()
  A->>MM: power_control.power_down()
  A->>MM: linmaster.teardown()
```

## Public API

`MumLinInterface(host, lin_device='lin0', power_device='power_out0', baudrate=19200, frame_lengths=None, default_data_length=8, boot_settle_seconds=0.5)`

LinInterface contract (matches Mock and BabyLIN adapters):

- `connect()` — opens MUM, sets up LIN, **and powers up the ECU**
- `disconnect()` — powers down and tears down (best-effort)
- `send(frame: LinFrame)` — publishes a master-to-slave frame using Enhanced checksum
- `receive(id: int, timeout: float = 1.0) -> LinFrame | None` — triggers a slave read for `id`. The `timeout` argument is informational; the underlying `pylin` call is synchronous. Any pylin exception is treated as "no data" and returns `None`. Passing `id=None` raises `NotImplementedError`.

MUM-only extras:

- `send_raw(bytes)` — sends a raw LIN frame using **Classic** checksum via the transport layer's `ld_put_raw`. Use this for BSM-SNPD diagnostic frames; the firmware will reject them if Enhanced is used.
- `power_up()` / `power_down()` — direct control over `power_out0`
- `power_cycle(wait=2.0)` — convenience: `power_down()`, sleep, `power_up()`, then `boot_settle_seconds` sleep

## Frame-length resolution

Because the MUM is master-driven, every receive needs to know how many bytes
to ask for. The adapter resolves this from `frame_lengths`:

1. Built-in defaults for the 4SEVEN library (ALM_Status=4, ALM_Req_A=8, ConfigFrame=3, PWM_Frame=8, VF_Frame=8, Tj_Frame=8, PWM_wo_Comp=8, NVM_Debug=8).
2. Anything in the constructor's `frame_lengths` argument **overrides** the defaults.
3. If a frame ID isn't in the map, `default_data_length` (default 8) is used.

In YAML, hex keys work:

```yaml
interface:
  type: mum
  frame_lengths:
    0x0A: 8
    0x11: 4
```

The config loader coerces hex strings (`"0x0A"`) and integers alike.

## Diagnostic frames (BSM-SNPD)

The vendor's `test_auto_addressing.py` flow runs LIN 2.1 BSM-SNPD via raw
frames on `0x3C` (MasterReq). The framework supports the same flow:

```python
# inside a test that already has the MUM 'lin' fixture
data = bytearray([
    0x7F,  # NAD broadcast
    0x06,  # PCI: 6 data bytes
    0xB5,  # SID: BSM-SNPD
    0xFF,  # Supplier ID LSB
    0x7F,  # Supplier ID MSB
    0x01,  # subfunction (INIT)
    0x02,  # param 1
    0xFF,  # param 2
])
lin.send_raw(bytes(data))
```

`send_raw()` calls `transport_layer.ld_put_raw(data=..., baudrate=...)`
which uses LIN 1.x Classic checksum. Using `lin.send()` for these frames
would compute Enhanced checksum and the firmware would discard the frame.

## Error surfaces

- **`pymumclient is not installed`** / **`pylin is not installed`** — raised on `connect()` if the Melexis packages aren't importable. The error message points at `vendor/automated_lin_test/install_packages.sh`.
- **`MUM not connected`** — calling `send` / `receive` / `send_raw` before `connect()` (or after `disconnect()`).
- **`MUM transport layer not available`** — raised by `send_raw` when the LIN device didn't expose `bus/transport_layer`. Practically always available on MUM firmware that supports diagnostic frames.
- **pylin exceptions during `receive`** — converted to `None` (treated as a timeout / no-data). Use this to drive timeout-tolerant tests without try/except in the test body.

## Unit testing without hardware

The adapter accepts `mum_module=` and `pylin_module=` constructor arguments
that bypass the real package imports. Tests in
`tests/unit/test_mum_adapter_mocked.py` use simple in-memory fakes to drive
the connect / send / receive / send_raw / power-cycle paths end to end. See
that file for a complete shim implementation.

```python
from ecu_framework.lin.mum import MumLinInterface

iface = MumLinInterface(
    host="10.0.0.1",
    boot_settle_seconds=0.0,
    mum_module=fake_mum,
    pylin_module=fake_pylin,
)
iface.connect()
# ... assertions ...
iface.disconnect()
```

## Notes and pitfalls

- **Boot settling**: After `power_up()` the adapter sleeps `boot_settle_seconds` (default 0.5 s) so the ECU has time to come up before the first frame. Increase if your ECU boots slowly.
- **Owon PSU coexistence**: the MUM provides power on `power_out0` independently of `ecu_framework/power/`. Leave `power_supply.enabled: false` for the standard MUM flow; enable it only for over/under-voltage scenarios that need a separate, programmable rail.
- **Networking**: USB-RNDIS bring-up can take a few seconds after plugging in the MUM. If `connect()` fails with a connection-refused, `ping 192.168.7.2` first.
- **Multiple MUMs**: only one MUM is supported per `MumLinInterface` instance. Different `host` addresses can run different fixture sessions side-by-side.