pub struct Recovery { /* private fields */ }Expand description
§5.9’s Network Recovery state: how a node that has lost its network asks for a new one.
A node whose Wi-Fi password changed underneath it is not broken and not commissionable — it still holds its fabric, its NOC and its ACL. §5.9 is the way back: advertise over BLE or Wi-Fi PAF, let an administrator open a CASE session over that channel, and take new network credentials through it.
Three rules carry the flow, and all three are here rather than in the application because all three are about timing and are the ones a device gets wrong by being helpful:
- §5.9.3 step 3: a node “SHALL continue to attempt to connect to the operational network for a duration of at least 120 seconds using its existing credentials” before it may advertise. “Given that temporary network outages occur with some frequency, waiting before entering Network Recovery mode and commencing announcement limits wireless spectrum pollution/interference and helps to limit attack opportunities.”
- §5.9.3 step 10: on the CASE session the node “SHALL autonomously arm the fail-safe timer for a timeout of 60 seconds”, against an administrator that connects and then wanders off.
- §5.9.3 step 16: “The Recovery Node SHALL reject the CommissioningComplete that is not received over the operational network.” Completing over the recovery channel would declare success at the exact moment nothing had been proved to work.
Implementations§
Source§impl Recovery
impl Recovery
Sourcepub const fn new(identifier: u64) -> Self
pub const fn new(identifier: u64) -> Self
A node whose network is working, with the identifier it was given at factory reset.
Sourcepub const fn identifier(&self) -> u64
pub const fn identifier(&self) -> u64
RecoveryIdentifier (§11.10.6.11).
Sourcepub fn reason(&self) -> Option<NetworkRecoveryReason>
pub fn reason(&self) -> Option<NetworkRecoveryReason>
NetworkRecoveryReason (§11.10.6.12), null unless the node is in recovery.
Sourcepub fn is_announcing(&self) -> bool
pub fn is_announcing(&self) -> bool
Whether the node is advertising for recovery.
Sourcepub fn network_lost(&self, now: Instant, reason: NetworkRecoveryReason)
pub fn network_lost(&self, now: Instant, reason: NetworkRecoveryReason)
The node cannot reach its operational network.
Idempotent: the clock starts at the first failure, so a device that calls this on every retry does not keep pushing its own hold-off out.
Sourcepub fn network_restored(&self)
pub fn network_restored(&self)
The network came back, or recovery finished.
§11.10.6.12: the reason “SHALL be null when the Node is not undergoing a Network Recovery flow”, so it goes with the state rather than lingering as a diagnostic.
Sourcepub fn may_announce(&self, now: Instant) -> bool
pub fn may_announce(&self, now: Instant) -> bool
Whether §5.9.3 step 3’s hold-off has elapsed, so announcement may begin.
Sourcepub fn begin_announcing(&self, now: Instant) -> bool
pub fn begin_announcing(&self, now: Instant) -> bool
Begins announcing, if §5.9.3 step 3 allows it yet.
Returns whether it did. A device that announced early would be advertising through every brief outage its access point has.
Sourcepub fn may_complete(&self, over_operational_network: bool) -> bool
pub fn may_complete(&self, over_operational_network: bool) -> bool
Whether a CommissioningComplete arriving over operational_network may be accepted
(§5.9.3 step 16).
Outside a recovery flow this is always true — an ordinary commissioning completes over whatever channel it ran on.