#[non_exhaustive]pub struct Report {Show 22 fields
pub age_ms: Option<u64>,
pub time_on_air_ms: Option<u64>,
pub retransmits: Option<u64>,
pub bytes_wasted: Option<u64>,
pub rx_errors: Option<u64>,
pub duty_cycle: Option<DutyCycle>,
pub signal_bars: Option<u8>,
pub rssi: Option<i32>,
pub rsrp: Option<i32>,
pub rsrq: Option<i32>,
pub snr: Option<i32>,
pub error_rate: Option<i32>,
pub rx_rate: Option<u64>,
pub tx_rate: Option<u64>,
pub rx_max_rate: Option<u64>,
pub tx_max_rate: Option<u64>,
pub latency: Option<u64>,
pub resources: Option<i32>,
pub rx_quality: Option<i32>,
pub tx_quality: Option<i32>,
pub registration: Option<Registration>,
pub access_technology: Option<AccessTechnology>,
}Expand description
What a device says about itself, as far as it knows.
Capabilities is what the medium can carry and is read once; Metrics is
what the driver counted and is what a test asserts on. This is the third
thing, and the one that fell off the edge: what the hardware knows about its
own condition. modem-device named the gap years before it had a shape —
“radio-specific figures such as RSSI belong on the management plane” — and
then never built the other side of it (#49).
Every field is Option, and that is load-bearing twice over. A device
that cannot answer says None rather than zero, because a zeroed counter is
a claim and absence is not. And several implementors in this workspace are
decorators wrapping another Medium; a decorator that forgets to forward
this method inherits the default, whose every field is None — the same
answer as “I do not know”, rather than a confident wrong number belonging to
the medium underneath.
#[non_exhaustive] because #49 lists eleven quantities and hardware will
suggest twenty more. As fields on one struct behind one defaulted method,
adding signal.rssi_dbm later touches the backend that fills it and the
publisher that reads it — as methods, each would be an eight-implementor
event for ever.
Fields (Non-exhaustive)§
This struct is marked as non-exhaustive
Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.age_ms: Option<u64>How long ago this snapshot was taken.
Device::report is sync, so a backend cannot do I/O in it and
must answer from a cache. A cache with no age is a lie the moment the
modem stops answering, which is exactly when an operator is reading it —
so the age rides along, and a report older than a consumer’s tolerance is
published as absent rather than as current.
time_on_air_ms: Option<u64>Cumulative channel occupancy, in milliseconds.
What the medium has actually spent on the air. On a service billed in
airtime this is the bill; lease-tuning-in-a-cell.md is the measurement
that made the distinction between this and a message count matter.
retransmits: Option<u64>Transmissions made only because an earlier attempt was lost.
The medium’s own ARQ, which rf-arq-requirement.md makes a hardware
selection requirement. Counted by every simulator in the tree today and
reachable through none of them.
bytes_wasted: Option<u64>Slot bytes paid for and not used.
A per-message service charges for the whole slot; M2 measured 9.4% utilisation at the defaults. This is the same figure from the medium’s side, for a deployment rather than for a measurement.
rx_errors: Option<u64>Frames the medium received and could not accept: FIFO overrun, collision, CRC or header failure.
Distinct from Metrics::dropped, which is accepted-then-lost on
transmit. #49 describes these as conflated; they are not — no shipped
medium puts receive-side errors into dropped — but they are counted
(sim.rs’s lost_attempts, cell.rs’s collisions and overruns) and
have had no way out of the crate at all.
duty_cycle: Option<DutyCycle>Whether the medium may transmit now, and how long until it may.
signal_bars: Option<u8>Received signal strength, on the device’s own 0–5 scale.
Bars, not dBm, and the distinction is the point. An Iridium ISU
answers AT+CSQF with an integer 0–5 and has no dBm to give; an
SX1262 reads a dBm out of a packet-status register and has no bars.
A field spelled rssi_dbm would force one of them to invent a number,
which is the failure Report’s all-Option shape exists to
avoid — a device says what it knows and stays quiet about the rest. A
dBm field arrives with the backend that measures one (#49, #76).
rssi: Option<i32>Received signal strength, milli-dBm (ModemManager Modem.Signal,
an SX1262’s packet status).
rsrp: Option<i32>Reference signal received power, milli-dBm (LTE, NR).
rsrq: Option<i32>Reference signal received quality, milli-dB.
snr: Option<i32>Signal-to-noise ratio, milli-dB.
error_rate: Option<i32>Error rate, milli-percent.
rx_rate: Option<u64>Current receive data rate, bit/s (DLEP, RFC 8175 §13 — session level; per-destination metrics are not device-level and are not here).
tx_rate: Option<u64>Current transmit data rate, bit/s.
rx_max_rate: Option<u64>Maximum receive data rate, bit/s.
tx_max_rate: Option<u64>Maximum transmit data rate, bit/s.
latency: Option<u64>Latency, microseconds.
resources: Option<i32>Resources available on the link, milli-percent.
rx_quality: Option<i32>Relative receive link quality, milli-percent.
tx_quality: Option<i32>Relative transmit link quality, milli-percent.
registration: Option<Registration>Network registration, for a bearer that registers with one.
access_technology: Option<AccessTechnology>The access technology the bearer is on.
Implementations§
Source§impl Report
impl Report
Sourcepub fn new() -> Self
pub fn new() -> Self
An empty report — the same thing Device::report’s default
returns, and the starting point for a backend that fills some of it.
The setters below take and return self so a backend names only what it
knows: Report::new().retransmits(n).rx_errors(m). That shape is
what makes #[non_exhaustive] free rather than annoying — this type is
implemented from outside this crate, so a struct literal would make
every new field a breaking change, which is exactly the churn #49’s
eleven-and-counting quantities would cause.
Sourcepub fn age_ms(self, ms: u64) -> Self
pub fn age_ms(self, ms: u64) -> Self
How old this snapshot is. See Report::age_ms.
Sourcepub fn time_on_air_ms(self, ms: u64) -> Self
pub fn time_on_air_ms(self, ms: u64) -> Self
Cumulative channel occupancy.
Sourcepub fn retransmits(self, n: u64) -> Self
pub fn retransmits(self, n: u64) -> Self
Transmissions made only because an earlier attempt was lost.
Sourcepub fn bytes_wasted(self, n: u64) -> Self
pub fn bytes_wasted(self, n: u64) -> Self
Slot bytes paid for and not used.
Sourcepub fn duty_cycle(self, duty: DutyCycle) -> Self
pub fn duty_cycle(self, duty: DutyCycle) -> Self
Whether the medium may transmit now.
Sourcepub fn signal_bars(self, bars: u8) -> Self
pub fn signal_bars(self, bars: u8) -> Self
Signal strength on the device’s own 0–5 scale.
Sourcepub fn error_rate(self, milli_percent: i32) -> Self
pub fn error_rate(self, milli_percent: i32) -> Self
Error rate, milli-percent.
Sourcepub fn rx_max_rate(self, bps: u64) -> Self
pub fn rx_max_rate(self, bps: u64) -> Self
Maximum receive data rate, bit/s.
Sourcepub fn tx_max_rate(self, bps: u64) -> Self
pub fn tx_max_rate(self, bps: u64) -> Self
Maximum transmit data rate, bit/s.
Sourcepub fn resources(self, milli_percent: i32) -> Self
pub fn resources(self, milli_percent: i32) -> Self
Resources available on the link, milli-percent.
Sourcepub fn rx_quality(self, milli_percent: i32) -> Self
pub fn rx_quality(self, milli_percent: i32) -> Self
Relative receive link quality, milli-percent.
Sourcepub fn tx_quality(self, milli_percent: i32) -> Self
pub fn tx_quality(self, milli_percent: i32) -> Self
Relative transmit link quality, milli-percent.
Sourcepub fn registration(self, r: Registration) -> Self
pub fn registration(self, r: Registration) -> Self
Network registration.
Sourcepub fn access_technology(self, t: AccessTechnology) -> Self
pub fn access_technology(self, t: AccessTechnology) -> Self
The access technology the bearer is on.