modem-device 0.2.0

The seam between the zenoh-modem driver and a physical or simulated medium
Documentation

modem-device

The seam between the driver and a device: trait Device, trait Medium: Device and the types they speak in. Was modem-backend with one trait Backend until #117, which split the seam along the planes of docs/design/device-planes.md and changed no behaviour.

This crate deliberately depends on nothing but async-trait, thiserror and optional serde — and in particular no Zenoh and no tokio. CI holds the first with a dependency-graph guard, because the moment this could parse a key expression the second policy plane invariant I1 forbids would exist. The absence of tokio is why DeviceEvent is a plain struct rather than a channel: putting a watch::Receiver on the trait would drag a runtime into the crate whose entire job is to be the seam.

An out-of-tree backend needs this and nothing else. It is published together with modem-contract and modem-mgmt, one version for the three (#97); the history is in CHANGELOG.md.

What an implementor does first

  1. Pick the plane. A device whose bytes you carry is a Medium; a device whose bytes the kernel carries is a Netdev. Both are a Device.
  2. Implement the four required Medium methods (capabilities, send, recv, metrics) and say the truth in Capabilities: reliable only if the hardware never loses (I2), and the SDU sizes the frame really holds. send blocks to apply backpressure and never splits an SDU (I3, I4).
  3. Run the conformance kit from your own tests: conformance::device, and conformance::netdev for a netdev, then assert_clean. Passing it is what conforming means; udp-medium/tests/conformance.rs is a ten-line example.
  4. Then the defaulted methods, as the device has them: report, oper, identity, next_event, configuration, actions, close. A device that says nothing about itself is still a legitimate device.

Two things it must never do: retry on its own initiative (I1: there is no reset, and recovery is a restart, of the device or of the daemon), and publish a reading it does not have (an absent value, never a zero).

The traits

Device is what the management plane serves — every method defaulted, so a device that says nothing about itself is a legitimate device. Medium: Device is the SDU data plane: implementations own everything below the driver — framing on the air, vendor APIs, contact scheduling, radio state — and nothing above it. A device whose data plane is the kernel's is a Netdev: Device — it names its interface, and the lanes never see it (#118, #130).

Device method
report() defaulted Sync on purpose — answer from a cache, never from I/O (#49)
next_event() defaulted Edge-triggered: one Raised, one Cleared, never a repeat (#51)
close() defaulted Called once, on the way down (#50)
configuration() defaulted The configuration plane (config::Configure: schema, read-back, apply), None for a device with nothing to configure; the Iridium terminal and the LoRa simulator declare one (#125)
Medium method
capabilities() required Read once at startup to size lanes
send(lane, sdu) required Must block rather than queue. Backpressure by not returning is what invariant I3 asks for
recv() required Returns the lane it arrived on, so the driver routes without inspecting the payload
metrics() required
configure_lanes(lanes) defaulted What lanes exist, so recv need not guess (#52)
Netdev method
interface() required The interface name, as the kernel spells it (#118)
close() defaulted Called after every lane stops. A simulator never needs telling; a radio does (#50)

The defaults are why the conformance kit's decorator check exists: a decorator that forgets one no longer fails to compile, it silently answers for itself.

There is no reset, and that is a decision. A medium that reopened itself would need a policy for when to retry and when to give up, and a policy inside the driver is the second policy plane I1 forbids. Recovery is a restart, and next_event is what tells a supervisor to perform one.

Implementors

fake-medium (three of them) and sbd-medium. sbd-medium is the first to implement close and next_event for real.

Conformance

modem_device::conformance (#131) is the tests that kept this workspace's implementors honest, with the medium taken out, so an implementor written elsewhere runs them from its own suite. Every check returns the Failures it found rather than panicking — the kit's own tests hand it one deliberately broken implementor per check — and assert_clean is the one-line form:

let mut f = conformance::device(&my_device, tokio::time::sleep(window)).await;
f.extend(conformance::netdev(&my_device, 3, || tokio::time::sleep(poll)).await);
conformance::assert_clean("MyDevice", &f);
Check What it holds a device to
device_decorator_forwards, medium_decorator_forwards, netdev_decorator_forwards every method of the trait reaches the wrapped device and its answer comes back unchanged
core report, oper, identity agree across two calls; a report with a reading says its age
events_are_edge_triggered the same words with the same edge twice in a row is a repeat, not an edge
schema_is_valid, effective_within_schema names that can be spelled in a key, bounds that do not cross, a read-back inside the schema, no sensitive value in it
contract_refused a contract group answers ConfigError::Contract, naming the restart
read_back_and_undo after apply, effective shows the change; after the Undo, the previous values
sensitive_never_read_back a value written to a sensitive parameter is in no read-back and no Debug
netdev within one presence epoch no counter goes backwards

Nothing here needs a runtime: the timed checks take a deadline or a tick future from the caller. What the kit cannot check is that the sync methods do no I/O; it checks what follows from the contract instead. The wire-level half — against a running plane — is modem_mgmt::conformance.

Where the rules are

Descriptive; ../docs/architecture.md is normative — §4.8 for the seam, §2 for the invariants the doc comments cite by number.