Struct Session 

pub struct Session<A: AesProvider, S: Sha256Provider, const TX: usize = 1> { /* private fields */ }

Implementations

impl<A: AesProvider, S: Sha256Provider, const TX: usize> Session<A, S, TX>

pub fn new( config: SessionConfig, boot_status: Status, engine: CryptoEngine<A, S>, ) -> Self

boot_status is the retained hardware reset cause, reported by the first PROP_LAST_STATUS get of the first session.

pub fn settings(&self) -> RadioSettings

The active radio settings.

pub fn device_name(&self) -> &str

Current UTF-8 PROP_DEV_NAME value.

pub fn tx_data(&self) -> &[u8]

Payload of the transmit requested by Effect::StartTransmit.

pub fn tx_power(&self) -> TxPower

Power selection for the pending transmit.

pub fn max_tx_power_dbm(&self) -> i8

The board’s maximum transmit power, as configured. The concrete dBm value behind TxPower::Max when a transmit is staged.

pub fn tx_nocca(&self) -> bool

Whether the pending transmit requested TX_FLAG_NOCCA — skip the pre-transmit channel-activity check.

pub fn has_pending_tx(&self) -> bool

Whether a transmit is awaiting Session::on_tx_result.

pub fn queued_frame_count(&self) -> usize

Number of received frames currently waiting for the host.

pub fn dev_domain_version(&self) -> u32

Monotonic generation of the device-domain node tables and the live device key. The firmware caches this and re-syncs the live device node’s MAC whenever it changes (device-node plan increment 3).

Identity provisioning bumps it too, even though a newly provisioned key only takes effect at the next boot (live-state-until-reboot, as with CMD_CLEAR): the old key stops being one the device claims immediately, and the node has to be told so it can stop originating traffic under it.

pub fn dev_channel_keys(&self) -> impl Iterator<Item = [u8; 32]> + '_

The device identity’s provisioned channel keys (raw symmetric keys, not the derived identifiers). The firmware joins each into the device node so it processes multicast on that channel.

pub fn dev_peers(&self) -> impl Iterator<Item = [u8; 32]> + '_

The device identity’s provisioned peer public keys. The firmware registers each with the device node’s MAC.

pub fn dev_admins(&self) -> impl Iterator<Item = [u8; 32]> + '_

The nodes authorized to manage this device over the mesh. The firmware mirrors these to whatever answers Node Management Requests, which admits an exchange only from a key in this set.

pub fn repeater_enabled(&self) -> bool

PROP_MAC_REPEATER_ENABLED: whether the device node should autonomously forward overheard routable frames and advertise NodeRole::Repeater. Part of the device domain, so it changes Session::dev_domain_version and the firmware reconciles it against the live MAC on the next sync.

pub fn repeater_region_codes(&self) -> impl Iterator<Item = [u8; 2]> + '_

PROP_MAC_REPEATER_REGIONS, as the forwarding filter needs it: the 2-octet code derived from each configured region. Empty means no restriction.

pub fn repeater_region_names(&self) -> impl Iterator<Item = &str> + '_

PROP_MAC_REPEATER_REGIONS, as the identity advertises it: the string form of each configured region, in the order it was written.

pub fn repeater_default_region(&self) -> Option<[u8; 2]>

PROP_MAC_REPEATER_DEFAULT_REGION: the code inserted into an untagged flood packet, or None to never tag.

pub fn repeater_min_rssi(&self) -> Option<i16>

PROP_MAC_REPEATER_MIN_RSSI: minimum received RSSI in dBm for flood forwarding, or None for no threshold.

pub fn repeater_min_snr(&self) -> Option<i8>

PROP_MAC_REPEATER_MIN_SNR: minimum received SNR in whole dB for flood forwarding, or None for no threshold.

pub fn dev_key(&self) -> Option<&[u8; 32]>

The live PROP_DEV_KEY value. None once a factory reset (CMD_CLEAR + CMD_RST) completes — the firmware uses this edge to make a running device node dormant.

pub fn reset(&mut self, reason: Status, emit: &mut impl FnMut(&[u8])) -> Effect

Reset all protocol state to post-reset values, announce the reset with the given reason, and return the radio effect applying the post-reset radio configuration.

Used for CMD_RST (with [Status::RESET_SOFTWARE]). With a saved snapshot the post-reset value of every saved device-domain property is its saved value — including the PHY enable state; the documented defaults apply only when nothing is saved. The host domain always returns to its documented defaults: it is never saved. Queue contents and replay baselines are discarded either way.

pub fn attach(&mut self, link_secure: bool)

A host attached. Resets session state only (spec §Attach): the device and host domains — PHY configuration and enable state, device name, duty accounting, provisioning, and the inbound queue — are untouched, and nothing is emitted; the attach itself produces no notification. Accepted frames are delivered live from here on; queued frames wait for CMD_QUEUE_DRAIN.

link_secure states whether this transport meets its security binding for key provisioning (spec §Provisioning Security): physical possession for serial transports, an encrypted bonded LESC link for BLE. Key-bearing writes are refused while false.

pub fn detach(&mut self)

The host detached. Session state is discarded; the device and host domains keep operating detached: accepted frames are queued instead of delivered (delegated acknowledgement arrives with CAP_HOST_AUTO_ACK).

pub fn handle_frame( &mut self, bytes: &[u8], now_ms: u64, emit: &mut impl FnMut(&[u8]), ) -> Option<Effect>

Handle one decoded ULCP frame from the host.

pub fn handle_frame_budgeted( &mut self, bytes: &[u8], now_ms: u64, reply_budget: usize, emit: &mut impl FnMut(&[u8]), ) -> Option<Effect>

Handle one decoded ULCP frame whose response must fit reply_budget octets.

Only the multi-property commands consult the budget, and only to decide where a sequence stops; every other response is bounded by its own property’s value.

pub fn handle_admin_frame( &mut self, bytes: &[u8], now_ms: u64, reply_budget: usize, emit: &mut impl FnMut(&[u8]), ) -> Option<Effect>

Handle one ULCP frame carried in a Node Management Request from a listed administrator, whose response must fit reply_budget octets.

The caller has already established what this binding requires and the session cannot see: that the packet arrived by unicast or blind unicast, that its source is authenticated, and that the source key is listed in PROP_DEV_ADMINS. Everything else the binding changes is here — the property surface an administrator reaches, the commands it may not use, and the fact that responses are correlated by token rather than by TID, so a frame whose TID is zero (as this binding requires) is still answered.

The binding stays in effect across the deferred round trips of this exchange, which is what lets the ordinary respond_* methods complete it. Call Session::end_admin_exchange when the exchange is over.

pub fn end_admin_exchange(&mut self)

Return to serving the local binding after an administrative exchange, deferred round trips included.

pub fn on_radio_rx( &mut self, data: &[u8], info: &RadioRxInfo, now_ms: u64, emit: &mut impl FnMut(&[u8]), ) -> Option<Effect>

Report a frame received on air at now_ms. While a host is attached, accepted frames are emitted live as CMD_STR_RECV (promiscuous mode bypasses filtering for live delivery only); while detached, accepted frames are placed in the inbound queue, authenticated duplicates coalesce, and a qualifying frame may produce a delegated-acknowledgement transmit effect. Ignored while the PHY is disabled or the frame exceeds the MTU (an unstorable frame is never acknowledged).

pub fn on_tx_result( &mut self, outcome: TxOutcome, now_ms: u64, emit: &mut impl FnMut(&[u8]), ) -> Option<Effect>

Report completion of the transmit started by Effect::StartTransmit.

pub fn resume_multi( &mut self, now_ms: u64, emit: &mut impl FnMut(&[u8]), ) -> Option<Effect>

Continue a multi-property command that was waiting on a deferred value, returning the next effect to serve.

Returns None when no multi-property command is in flight, which is the ordinary case after a single-property deferral.

pub fn respond_rssi( &mut self, tid: u8, rssi: Result<i16, ()>, emit: &mut impl FnMut(&[u8]), )

Complete a deferred PROP_PHY_RSSI read requested via Effect::SampleRssi. rssi is the sampled value in dBm, or Err if the radio read failed. Quote the same tid the effect carried.

pub fn respond_identity_blob( &mut self, tid: u8, blob: Result<&[u8], ()>, emit: &mut impl FnMut(&[u8]), )

Complete a deferred PROP_IDENT read requested via Effect::SignIdentity. blob is the complete signed node-identity payload — the canonical unsigned encoding followed by its 64-octet detached signature — or Err if it could not be produced. Quote the same tid the effect carried.

pub fn ident_role(&self) -> Option<u8>

PROP_IDENT_ROLE: the advertised ROLE byte, or None to let the device derive it from its live forwarding state.

pub fn ident_mobile(&self) -> bool

PROP_IDENT_MOBILE: whether the device identity advertises the MOB capability bit.

pub fn ident_location(&self) -> &[u8]

PROP_IDENT_LOCATION: the position the advertised node identity carries, in the variable-precision encoding, or empty for none.

pub fn ident_altitude_m(&self) -> Option<i32>

PROP_IDENT_ALTITUDE: meters above the WGS-84 ellipsoid, or None.

pub fn absorb_ident_fix( &mut self, location: &[u8], altitude_m: Option<i32>, ) -> bool

Offer a fix to the advertised position.

A no-op unless the device is set to update its identity from fixes, so the platform can hand over every fix without first asking whether this one counts. The location is clamped to PROP_GNSS_IDENT_PRECISION before it is stored.

Returns whether anything changed. A stationary node’s fixes all clamp into the same cell, and re-signing an identity that says what the last one said would spend airtime to no purpose.

pub fn dev_discoverable(&self) -> bool

PROP_DEV_DISCOVERABLE: whether the device identity answers Identity Requests.

pub fn advert_interval_s(&self) -> u32

PROP_ADVERT_INTERVAL: seconds between unsolicited advertisements, 0 for none.

pub fn beacon_interval_s(&self) -> u32

PROP_BEACON_INTERVAL: seconds between unsolicited beacons, 0 for none.

pub fn startup_beacon(&self) -> bool

PROP_STARTUP_BEACON: whether one beacon goes out at bring-up.

pub fn tz_offset_min(&self) -> i16

PROP_TZ_OFFSET: minutes east of UTC.

pub fn gnss_enabled(&self) -> bool

PROP_GNSS_ENABLED: whether the receiver should be powered.

Always false on a board without CAP_GNSS, so a platform can act on it without first asking whether it has a receiver.

pub fn gnss_ident_update(&self) -> bool

PROP_GNSS_IDENT_UPDATE: whether fixes refresh the advertised node identity’s location.

pub fn ble_enabled(&self) -> bool

PROP_BLE_ENABLED: whether the device is reachable over Bluetooth.

Always false on a board without CAP_BLE, so a platform can act on it without first asking whether it has a transport.

pub fn ble_bond_count(&self) -> u8

PROP_BLE_BOND_COUNT: how many bonds the transport last reported.

pub fn ble_link(&self) -> BleLinkState

PROP_BLE_LINK: how far the Bluetooth transport has got with whoever is on the other end of it.

Always None on a board without CAP_BLE, so a platform can act on it without first asking whether it has a transport.

pub fn ble_pairing(&self) -> bool

PROP_BLE_PAIRING: whether a pairing window is open.

pub fn gnss_ident_precision(&self) -> u8

PROP_GNSS_IDENT_PRECISION: the precision the advertised location is clamped to.

pub fn gnss_time_trust(&self) -> bool

PROP_GNSS_TIME_TRUST: whether receiver-derived time may set the wall clock.

pub fn alert(&self) -> AlertState

PROP_ALERT: what the device is currently doing to draw attention to itself.

pub fn alert_deadline_ms(&self) -> Option<u64>

When the running alert gives itself up, as a monotonic millisecond deadline on the caller’s clock, or None when no alert is running.

The driver arms a timer on this and calls Session::poll_alert when it fires. Enforcing the bound centrally is what keeps the spec’s “a device MUST bound how long it will remain in ALERT_LOCATE” from being a promise each board has to remember to keep.

pub fn poll_alert( &mut self, now_ms: u64, emit: &mut impl FnMut(&[u8]), ) -> Option<Effect>

Expire a running alert whose deadline has passed, returning the effect that stops the board’s indication.

Safe to call at any time: it does nothing until the deadline is actually reached, so a driver that polls it on every loop iteration behaves identically to one that arms a precise timer.

pub fn cancel_alert(&mut self, emit: &mut impl FnMut(&[u8])) -> Option<Effect>

Cancel a running alert from the device itself — the button press of whoever found the radio.

Returns the effect that stops the indication, or None when no alert was running (so a board can use the return to decide whether the press was consumed).

pub fn toggle_gnss(&mut self, emit: &mut impl FnMut(&[u8])) -> Option<bool>

Flip PROP_GNSS_ENABLED from the device itself — a button on a board that offers the receiver as a user-facing switch.

Returns the new state, or None on a device without CAP_GNSS (so a board can report a press unconditionally).

pub fn toggle_gnss_ident_update( &mut self, emit: &mut impl FnMut(&[u8]), ) -> Option<bool>

Flip PROP_GNSS_IDENT_UPDATE from the device itself.

Whether the device knows where it is and whether it says so are two decisions, and a board that offers the first as a switch owes the user the second: nothing else on the device distinguishes a position kept for the screen from one put on the air.

pub fn toggle_repeater(&mut self, emit: &mut impl FnMut(&[u8])) -> Option<bool>

Flip PROP_MAC_REPEATER_ENABLED from the device itself.

Every device carries the repeater, so this never refuses — the return is the new state rather than an availability answer.

pub fn toggle_ble(&mut self, emit: &mut impl FnMut(&[u8])) -> Option<bool>

Flip PROP_BLE_ENABLED from the device itself.

The one toggle whose own effect can carry away the host that would have watched it: clearing it drops the attached link, so the announcement below is the last thing that host hears.

pub fn force_ble_on(&mut self, emit: &mut impl FnMut(&[u8])) -> Option<bool>

Force PROP_BLE_ENABLED on for a physical gesture at the device — the hold-through-power-on ceremony that must always end with a reachable radio, including one whose operator turned Bluetooth off and walked away. A toggle would re-strand the ones already on.

Returns Some(true) only when the flag actually moved, so the caller persists a snapshot for the same reason a toggle does and stays quiet when there was nothing to change.

pub fn publish_battery( &mut self, sample: BatteryStatus, emit: &mut impl FnMut(&[u8]), ) -> bool

Publish an unsolicited PROP_BATTERY snapshot (spec §PROP_BATTERY, Asynchronous Updates: Yes).

The platform decides when a measurement is worth announcing — it owns the sampling cadence and the charge-state edges, and it is the only layer that sees every sample. This publishes what it hands over, so the session keeps its rule that it never caches a reading: nothing here can answer a later CMD_PROP_GET.

Returns whether a frame was emitted. Nothing is published while no host is attached (there is nobody to notify), and a snapshot populating a field the configured BatteryFields never claimed is dropped rather than sent — an unsolicited notification has no transaction to fail. A snapshot that merely omits an advertised field is published as-is: absence is how the device says the value is not knowable right now.

pub fn respond_battery( &mut self, tid: u8, sample: Result<BatteryStatus, ()>, emit: &mut impl FnMut(&[u8]), )

Complete a deferred PROP_BATTERY read requested via Effect::SampleBattery. sample is the platform’s snapshot, or Err if the measurement failed. Quote the same tid the effect carried.

A snapshot populating a field the configured BatteryFields never claimed is refused as STATUS_FAILURE; one that omits an advertised field is answered as-is, since a field the platform cannot currently substantiate is reported by its absence.

pub fn respond_illuminance( &mut self, tid: u8, millilux: Option<u32>, emit: &mut impl FnMut(&[u8]), )

Complete a deferred PROP_ILLUMINANCE read requested via Effect::SampleIlluminance. millilux is the measurement, or None when the sensor could not be read. Quote the same tid the effect carried.

A failed read is the empty value rather than an error status: the property is a measurement, and “no reading right now” is the same answer PROP_TIME gives for a clock that has never been set.

pub fn respond_time( &mut self, tid: u8, epoch: Option<u32>, emit: &mut impl FnMut(&[u8]), )

Complete a deferred PROP_TIME read requested via Effect::ReadTime. epoch is the platform’s wall clock in Unix seconds, or None when the device does not know what time it is. Quote the same tid the effect carried.

Not knowing is a legitimate answer, not a failure: it is reported as the empty value, which is precisely what tells a host — and a device’s own display — that there is no clock to show.

pub fn publish_time( &mut self, epoch: Option<u32>, emit: &mut impl FnMut(&[u8]), ) -> bool

Publish an unsolicited PROP_TIME (spec §PROP_TIME, Asynchronous Updates: Yes).

The platform decides what is worth announcing — it owns the clock and is the only layer that sees every source that touches it. A clock going from unknown to known is the announcement that matters most; a fresh fix agreeing with the clock to the second is not.

Returns whether a frame was emitted; nothing is published while no host is attached.

pub fn respond_gnss( &mut self, tid: u8, key: u32, sample: Result<GnssSnapshot, ()>, emit: &mut impl FnMut(&[u8]), )

Complete a deferred positioning read requested via Effect::SampleGnss. sample is the receiver’s current view, or Err if it could not be obtained. Quote the same tid and key the effect carried.

A receiver that is off or still searching is not a failure — it reports [GnssSnapshot::SEARCHING], which answers zero for the facts it is sure of and empty for the position it does not have.

pub fn publish_gnss( &mut self, key: u32, snapshot: &GnssSnapshot, emit: &mut impl FnMut(&[u8]), ) -> bool

Publish one positioning property as an unsolicited CMD_PROP_IS (spec §PROP_GNSS_LOCATION / §PROP_GNSS_FIX, Asynchronous Updates: Yes).

The platform decides the cadence, as it does for PROP_BATTERY: it sees every sentence the receiver produces and is the only layer that can tell a meaningful change from a jittering last digit.

Returns whether a frame was emitted. key must be a positioning property; anything else, and any publication while no host is attached, is dropped.

pub fn drain_step(&mut self, now_ms: u64, emit: &mut impl FnMut(&[u8])) -> bool

Advance the drain started by Effect::DrainQueue one step, emitting either the next covered frame (oldest first, as CMD_STR_RECV with buffered metadata) or, once the covered set is exhausted, the completion status. Returns true while another call is needed; flush the transport between calls.

pub fn encode_snapshot(&self, out: &mut [u8]) -> Option<usize>

Encode the current device and host domains as a snapshot for Effect::SaveSnapshot. out must hold SNAPSHOT_MAX bytes.

pub fn restore_at_boot(&mut self, bytes: &[u8]) -> Result<Effect, SnapshotError>

Restore a stored snapshot at boot, before any host command is processed. On success the saved configuration is applied — the returned effect re-enables the PHY if it was enabled when saved, and detached operation (filtering, queueing, delegation) begins immediately.

The payload is decoded and validated into a candidate state first and committed in one step, so a malformed option arriving late in the decode cannot leave the device half-configured. On rejection nothing is modified and the caller should offer the next-older committed generation; see [Session::note_snapshot_ rejected] for what the device reports when none decodes.

pub fn note_snapshot_rejected(&mut self)

Record that a stored generation was rejected at boot.

Called once per rejected generation. If a later, older generation restores, PROP_SAVED reports SavedStatus::Fallback — the device is working but running on stale configuration, which is both more actionable and more urgent than “something was wrong”. If none restores it reports SavedStatus::Unreadable, which a host can tell apart from “nothing saved”.

pub fn saved_status(&self) -> SavedStatus

What PROP_SAVED reports (spec §Saved State).

pub fn respond_save( &mut self, tid: u8, result: Result<(), ()>, emit: &mut impl FnMut(&[u8]), )

Complete the durable write requested via Effect::SaveSnapshot, quoting the same tid. On Ok the captured state becomes the post-reset baseline; on Err the previous snapshot (if any) must have been left intact by the caller and remains in effect.

pub fn note_snapshot_saved(&mut self)

Note that the live state was persisted without a host having asked — a device-initiated save, such as a switch the operator flipped at the board.

Required after any such write. The session answers CMD_RST and CMD_RESTORE from its own copy of the snapshot rather than by re-reading flash, so a save it was not told about would leave the device restoring the values it had at boot and silently undoing what the operator did.

pub fn respond_clear( &mut self, tid: u8, result: Result<(), ()>, emit: &mut impl FnMut(&[u8]), )

Complete the durable erase requested via Effect::ClearSaved, quoting the same tid. Live state is unaffected either way: the live device identity in particular remains in effect until the CMD_RST that completes a factory reset.

pub fn identity_request(&self) -> Option<IdentitySource>

The staged PROP_DEV_PRIVATE_KEY provisioning awaiting Effect::ProvisionIdentity execution.

pub fn respond_identity( &mut self, tid: u8, result: Result<[u8; 32], ()>, emit: &mut impl FnMut(&[u8]), )

Complete the device-identity provisioning requested via Effect::ProvisionIdentity, quoting the same tid. result carries the new identity’s public key once the keypair is durably stored — success is announced as CMD_PROP_IS for PROP_DEV_KEY and the private key is never emitted (spec §PROP_DEV_PRIVATE_KEY). On Ok the new identity is adopted even if the transaction was abandoned by a detach: the durable write already happened, and flash is the source of truth.

pub fn set_boot_identity(&mut self, public_key: [u8; 32])

Install the independently persisted device identity’s public key at boot, before any host command: the post-reset value of PROP_DEV_KEY is the persisted identity, snapshot or not.

pub fn respond_pin_set( &mut self, tid: u8, result: Result<(), ()>, emit: &mut impl FnMut(&[u8]), )

Complete a deferred write of the write-only BLE pairing PIN.

pub fn respond_ble_clear_bonds( &mut self, tid: u8, result: Result<(), ()>, emit: &mut impl FnMut(&[u8]), )

Complete a deferred CMD_BLE_CLEAR_BONDS.

pub fn set_ble_bond_count(&mut self, count: u8, emit: &mut impl FnMut(&[u8]))

The number of Bluetooth bonds the platform is holding, as reported by PROP_BLE_BOND_COUNT. Bonding is the transport’s business, so the session mirrors what it is told rather than counting anything.

A change is announced like any the host did not command: enrolling or forgetting a bond happens at the device, so an attached host would otherwise have to poll to notice.

pub fn set_ble_link( &mut self, state: BleLinkState, emit: &mut impl FnMut(&[u8]), )

How far the Bluetooth transport has got with whoever is on the other end of it, as reported by PROP_BLE_LINK.

Announced like the bond count, and for the same reason: a host connecting or walking away is a transition nobody asked for. An announcement only ever reaches a host on some other binding — the Bluetooth host that would hear “attached” is the one that caused it, and by the time the state is None there is nobody there to tell.

pub fn set_ble_pairing(&mut self, open: bool, emit: &mut impl FnMut(&[u8]))

Whether a pairing window is open, as reported by PROP_BLE_PAIRING.

The transport calls this on every transition, commanded or not — and “or not” is the whole reason the window is a property: it closes by itself on a new bond or a timeout, and a host showing a toggle has to see it flip back.

pub fn respond_ble_pairing( &mut self, tid: u8, result: Result<bool, ()>, emit: &mut impl FnMut(&[u8]), )

Complete a deferred PROP_BLE_PAIRING write.

Ok(state) quotes the state the transport is now in, which answers the write the way any set is answered — with the property’s value. Err(()) is a window the device cannot open right now: locked out after repeated pairing failures, or Bluetooth disabled.