Hosam-Eldin Mostafa
582764d410
The MUM (Melexis Universal Master) adapter is the current default; the
BabyLIN SDK adapter is retained only for backward compatibility with
existing rigs.
Code:
- Emit DeprecationWarning when BabyLinInterface is instantiated and
when tests/conftest.py routes interface.type=='babylin' to it.
- Update module/class docstrings in ecu_framework/{__init__,config,
lin/__init__,lin/babylin}.py to label BabyLIN-specific fields and
paths as deprecated.
Config / scripts / pytest:
- pytest.ini: relabel the babylin marker as deprecated.
- config/{babylin.example,examples,test_config}.yaml: add deprecation
banners and field comments.
- scripts/99-babylin.rules and scripts/pi_install.sh: annotate the
udev-rule install block as legacy-only.
Documentation:
- TESTING_FRAMEWORK_GUIDE.md, docs/08_babylin_internals.md, and
vendor/README.md: prepend explicit "DEPRECATED" banners.
- docs/{README,01,02,04,05,07,09,10,12,13,14,15,18,DEVELOPER_COMMIT_
GUIDE}.md: relabel "legacy" to "deprecated" where babylin is
mentioned, present MUM as the primary path, and steer new work
toward the MUM examples.
No tests, configs, or modules were deleted; existing BabyLIN setups
keep working but now produce a clear DeprecationWarning at runtime.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
92 lines
4.5 KiB
Markdown
92 lines
4.5 KiB
Markdown
# 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`
|
||
|
||
- `connect()` / `disconnect()`
|
||
- `send(frame: LinFrame)`
|
||
- `receive(id: int | None = None, timeout: float = 1.0) -> LinFrame | None`
|
||
- `request(id: int, length: int, timeout: float = 1.0) -> LinFrame | None`
|
||
- `flush()`
|
||
|
||
`LinFrame` validates:
|
||
- ID is 0x00–0x3F (6-bit LIN ID)
|
||
- Data length ≤ 8 bytes
|
||
|
||
## 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.
|