Skip to main content

Report

Struct Report 

Source
#[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
Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional 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

Source

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.

Source

pub fn age_ms(self, ms: u64) -> Self

How old this snapshot is. See Report::age_ms.

Source

pub fn time_on_air_ms(self, ms: u64) -> Self

Cumulative channel occupancy.

Source

pub fn retransmits(self, n: u64) -> Self

Transmissions made only because an earlier attempt was lost.

Source

pub fn bytes_wasted(self, n: u64) -> Self

Slot bytes paid for and not used.

Source

pub fn rx_errors(self, n: u64) -> Self

Frames received and not accepted.

Source

pub fn duty_cycle(self, duty: DutyCycle) -> Self

Whether the medium may transmit now.

Source

pub fn signal_bars(self, bars: u8) -> Self

Signal strength on the device’s own 0–5 scale.

Source

pub fn rssi(self, milli_dbm: i32) -> Self

Received signal strength, milli-dBm.

Source

pub fn rsrp(self, milli_dbm: i32) -> Self

Reference signal received power, milli-dBm.

Source

pub fn rsrq(self, milli_db: i32) -> Self

Reference signal received quality, milli-dB.

Source

pub fn snr(self, milli_db: i32) -> Self

Signal-to-noise ratio, milli-dB.

Source

pub fn error_rate(self, milli_percent: i32) -> Self

Error rate, milli-percent.

Source

pub fn rx_rate(self, bps: u64) -> Self

Current receive data rate, bit/s.

Source

pub fn tx_rate(self, bps: u64) -> Self

Current transmit data rate, bit/s.

Source

pub fn rx_max_rate(self, bps: u64) -> Self

Maximum receive data rate, bit/s.

Source

pub fn tx_max_rate(self, bps: u64) -> Self

Maximum transmit data rate, bit/s.

Source

pub fn latency(self, us: u64) -> Self

Latency, microseconds.

Source

pub fn resources(self, milli_percent: i32) -> Self

Resources available on the link, milli-percent.

Source

pub fn rx_quality(self, milli_percent: i32) -> Self

Relative receive link quality, milli-percent.

Source

pub fn tx_quality(self, milli_percent: i32) -> Self

Relative transmit link quality, milli-percent.

Source

pub fn registration(self, r: Registration) -> Self

Network registration.

Source

pub fn access_technology(self, t: AccessTechnology) -> Self

The access technology the bearer is on.

Trait Implementations§

Source§

impl Clone for Report

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Copy for Report

Source§

impl Debug for Report

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Default for Report

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl Eq for Report

Source§

impl PartialEq for Report

Source§

fn eq(&self, other: &Self) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl StructuralPartialEq for Report

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.