Skip to main content

zigbee_host/
host.rs

1//! The coordinator host.
2
3use std::collections::{BTreeMap, HashMap, HashSet};
4use std::path::PathBuf;
5use std::sync::atomic::{AtomicBool, AtomicU8, Ordering};
6use std::sync::{Arc, Mutex, MutexGuard};
7use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
8
9use tokio::sync::{mpsc, oneshot, Semaphore};
10use zigbee_primitives::{Ieee, Key, NodeId, BROADCAST_ROUTERS};
11use zigbee_zcl::foundation::{self, Global, ReadRecord, ReportingConfig};
12use zigbee_zcl::{Direction, Frame, FrameType, Value};
13use zigbee_zdo::{Body, Message, Neighbor};
14
15use crate::adapter::{
16    Adapter, AdapterEvent, AdapterInfo, Aps, JoinPolicy, NetworkInfo, StartMode, StartOutcome,
17};
18use crate::backup::Backup;
19use crate::device::{Device, InterviewStage};
20use crate::error::HostError;
21use crate::install_code;
22use crate::store::{self, Dirty};
23use crate::topology::{Link, Topology};
24
25mod ota_server;
26pub use ota_server::OtaOffer;
27
28/// The host's endpoint, which devices bind to.
29pub const HOST_ENDPOINT: u8 = 1;
30
31/// Host settings.
32#[derive(Debug, Clone)]
33pub struct HostConfig {
34    /// Where the device store lives; `None` keeps devices in memory only.
35    pub store_path: Option<PathBuf>,
36    /// Where the latest backup is written; `None` writes none.
37    pub backup_path: Option<PathBuf>,
38    /// Trust center join policy.
39    pub join: JoinPolicy,
40    /// Bind and configure reporting for standard clusters at interview.
41    pub configure_reporting: bool,
42    /// How long to wait for each device response.
43    pub request_timeout: Duration,
44    /// Attempts per interview request.
45    pub request_attempts: u32,
46    /// Periodic backups (also taken after joins and leaves).
47    pub backup_interval: Duration,
48    /// How long a new device has to obtain a unique link key before it is
49    /// removed, when legacy devices are not allowed.
50    pub legacy_grace: Duration,
51    /// Requests in flight at once, so the NCP's buffers are never exhausted.
52    pub max_in_flight: usize,
53    /// A directory of OTA upgrade images; `None` serves none.
54    pub ota_dir: Option<PathBuf>,
55    /// How long to wait for a device's OTA query after notifying it.
56    pub ota_query_timeout: Duration,
57}
58
59impl Default for HostConfig {
60    fn default() -> Self {
61        HostConfig {
62            store_path: None,
63            backup_path: None,
64            join: JoinPolicy::default(),
65            configure_reporting: true,
66            request_timeout: Duration::from_secs(10),
67            request_attempts: 3,
68            backup_interval: Duration::from_secs(3600),
69            legacy_grace: Duration::from_secs(30),
70            max_in_flight: 8,
71            ota_dir: None,
72            ota_query_timeout: Duration::from_secs(60),
73        }
74    }
75}
76
77/// What happened on the network.
78#[derive(Debug, Clone)]
79pub enum HostEvent {
80    /// The network is up.
81    Started {
82        /// Resumed, formed or restored.
83        outcome: StartOutcome,
84        /// The network.
85        network: NetworkInfo,
86        /// The NCP.
87        adapter: AdapterInfo,
88    },
89    /// Joining opened (seconds > 0) or closed.
90    PermitJoin {
91        /// Seconds open, 0 when closed.
92        seconds: u8,
93        /// The router it was opened on, if not everywhere.
94        via: Option<Ieee>,
95    },
96    /// A device joined or rejoined.
97    DeviceJoined {
98        /// The device.
99        ieee: Ieee,
100        /// Its network address.
101        nwk: NodeId,
102        /// A rejoin.
103        rejoin: bool,
104    },
105    /// A device announced itself (after joining or a power cycle).
106    DeviceAnnounced {
107        /// The device.
108        ieee: Ieee,
109        /// Its network address.
110        nwk: NodeId,
111    },
112    /// A device asked for an OTA image (on its own, or after
113    /// [`Host::ota_check`] or [`Host::ota_update`]).
114    OtaQuery {
115        /// The device.
116        ieee: Ieee,
117        /// The file version it runs.
118        current_version: u32,
119        /// The newest newer version in the image directory.
120        available: Option<u32>,
121    },
122    /// An OTA download advanced (every 10%).
123    OtaProgress {
124        /// The device.
125        ieee: Ieee,
126        /// Percent downloaded.
127        percent: u8,
128    },
129    /// An OTA upgrade ended.
130    OtaFinished {
131        /// The device.
132        ieee: Ieee,
133        /// The version it ran.
134        from: u32,
135        /// The version it downloaded.
136        to: u32,
137        /// The device applied it.
138        success: bool,
139        /// The device's upgrade end status.
140        status: u8,
141    },
142    /// The network moved to another channel.
143    ChannelChanged {
144        /// The network now.
145        network: NetworkInfo,
146    },
147    /// A device left the network.
148    DeviceLeft {
149        /// The device.
150        ieee: Ieee,
151    },
152    /// The host removed a device.
153    DeviceRemoved {
154        /// The device.
155        ieee: Ieee,
156        /// Why.
157        reason: String,
158    },
159    /// An interview started or resumed.
160    InterviewStarted {
161        /// The device.
162        ieee: Ieee,
163    },
164    /// An interview step finished.
165    InterviewStep {
166        /// The device.
167        ieee: Ieee,
168        /// The step that finished.
169        stage: InterviewStage,
170    },
171    /// An interview finished.
172    InterviewDone {
173        /// The device as interviewed.
174        device: Box<Device>,
175    },
176    /// An interview stopped on a failure; it resumes when the device next
177    /// talks.
178    InterviewFailed {
179        /// The device.
180        ieee: Ieee,
181        /// The step that failed.
182        stage: InterviewStage,
183        /// Why.
184        error: String,
185    },
186    /// Attribute values arrived (a report, or an unsolicited read response).
187    Attributes {
188        /// The device.
189        ieee: Ieee,
190        /// Its endpoint.
191        endpoint: u8,
192        /// The cluster.
193        cluster: u16,
194        /// Attribute ids and values.
195        attributes: Vec<(u16, Value)>,
196        /// Last hop link quality.
197        lqi: u8,
198    },
199    /// A device sent a cluster command (a remote's button, an alarm).
200    Command {
201        /// The device.
202        ieee: Ieee,
203        /// Its endpoint.
204        endpoint: u8,
205        /// The cluster.
206        cluster: u16,
207        /// Command id.
208        command: u8,
209        /// Its name, when the cluster library knows it.
210        name: Option<&'static str>,
211        /// Decoded fields, when known.
212        fields: Vec<(&'static str, Value)>,
213        /// Sent by the cluster's server (true) or a client.
214        from_server: bool,
215    },
216    /// A ZCL frame from a device, exactly as received, with how it arrived.
217    /// Sent for every frame that is not a reply to the host's own request,
218    /// before the decoded [`HostEvent::Attributes`] or
219    /// [`HostEvent::Command`], so a device library can decode what the
220    /// host does not.
221    Frame {
222        /// The device.
223        ieee: Ieee,
224        /// How it arrived.
225        link: FrameLink,
226        /// The ZCL frame: header and payload.
227        frame: Vec<u8>,
228    },
229    /// A backup was written.
230    BackupWritten {
231        /// The file.
232        path: PathBuf,
233    },
234    /// The NCP failed; the host has stopped. Restart it.
235    AdapterFailed {
236        /// Why.
237        reason: String,
238    },
239}
240
241/// How a frame arrived.
242#[derive(Debug, Clone, Copy, PartialEq, Eq)]
243pub struct FrameLink {
244    /// The sender's network address.
245    pub nwk: NodeId,
246    /// The sender's endpoint.
247    pub source_endpoint: u8,
248    /// The endpoint it was sent to.
249    pub destination_endpoint: u8,
250    /// Application profile.
251    pub profile: u16,
252    /// Cluster.
253    pub cluster: u16,
254    /// The group, for a multicast.
255    pub group: Option<u16>,
256    /// Sent as a broadcast or multicast.
257    pub broadcast: bool,
258    /// Last hop link quality.
259    pub lqi: u8,
260    /// Last hop signal strength, dBm, when the coordinator reports it
261    /// (EmberZNet and deCONZ do; Z-Stack does not).
262    pub rssi: Option<i8>,
263    /// The device the frame came from on its last hop: the last relay of
264    /// the sender's recorded route, or the sender itself.
265    pub last_hop: NodeId,
266}
267
268/// A ZCL frame for [`Host::zcl_raw`].
269#[derive(Debug, Clone, PartialEq, Eq)]
270pub struct RawZcl {
271    /// The device's endpoint.
272    pub endpoint: u8,
273    /// Cluster.
274    pub cluster: u16,
275    /// The ZCL frame (header and payload); its sequence number is replaced.
276    pub frame: Vec<u8>,
277    /// Application profile; the endpoint's own when `None`.
278    pub profile: Option<u16>,
279    /// The host's endpoint to send from.
280    pub source_endpoint: u8,
281    /// Wait for the device's reply.
282    pub response: bool,
283    /// How long to wait; the host's request timeout when `None`.
284    pub timeout: Option<Duration>,
285}
286
287#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
288enum WaitKey {
289    Zdo { nwk: NodeId, cluster: u16, tsn: u8 },
290    Zcl { nwk: NodeId, cluster: u16, seq: u8 },
291}
292
293/// A reply, decoded and as received.
294enum Reply {
295    Zdo(Message, Vec<u8>),
296    Zcl(Frame, Vec<u8>),
297}
298
299#[derive(Default)]
300struct Waiters {
301    pending: HashMap<WaitKey, oneshot::Sender<Result<Reply, HostError>>>,
302    tags: HashMap<u16, WaitKey>,
303    /// Sends that wait only for APS delivery, by tag.
304    deliveries: HashMap<u16, oneshot::Sender<bool>>,
305    /// The latest delivery reports, for a report that arrives before its
306    /// sender has registered the tag.
307    recent: std::collections::VecDeque<(u16, bool)>,
308}
309
310/// How many delivery reports are remembered.
311const RECENT_DELIVERIES: usize = 64;
312
313impl Waiters {
314    fn recent_delivery(&self, tag: u16) -> Option<bool> {
315        self.recent
316            .iter()
317            .rev()
318            .find(|(t, _)| *t == tag)
319            .map(|(_, d)| *d)
320    }
321}
322
323#[derive(Default)]
324struct State {
325    devices: BTreeMap<Ieee, Device>,
326    by_nwk: HashMap<NodeId, Ieee>,
327    install_codes: HashMap<Ieee, Key>,
328    permit_generation: u64,
329    legacy_deadlines: HashMap<Ieee, Instant>,
330    topology: Topology,
331    interviewing: HashSet<Ieee>,
332    last_interview: HashMap<Ieee, Instant>,
333    last_scan: HashMap<Ieee, Instant>,
334    removing: HashSet<Ieee>,
335    ota: HashMap<Ieee, ota_server::OtaSession>,
336    backup_wanted: bool,
337    last_backup: Option<Instant>,
338}
339
340impl State {
341    fn put_device(&mut self, device: Device) {
342        self.by_nwk.retain(|_, ieee| *ieee != device.ieee);
343        self.by_nwk.insert(device.nwk, device.ieee);
344        self.devices.insert(device.ieee, device);
345    }
346}
347
348struct Inner<A: Adapter> {
349    adapter: A,
350    config: HostConfig,
351    network: Mutex<NetworkInfo>,
352    state: Mutex<State>,
353    waiters: Mutex<Waiters>,
354    seq: AtomicU8,
355    events: mpsc::UnboundedSender<HostEvent>,
356    dirty: Dirty,
357    in_flight: Semaphore,
358    stopped: AtomicBool,
359    shutdown: tokio::sync::watch::Sender<bool>,
360    backup_lock: tokio::sync::Mutex<()>,
361}
362
363/// A running coordinator host. Clones share it.
364pub struct Host<A: Adapter> {
365    inner: Arc<Inner<A>>,
366}
367
368impl<A: Adapter> Clone for Host<A> {
369    fn clone(&self) -> Self {
370        Host {
371            inner: self.inner.clone(),
372        }
373    }
374}
375
376impl<A: Adapter> std::fmt::Debug for Host<A> {
377    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
378        f.debug_struct("Host")
379            .field("network", &*lock(&self.inner.network))
380            .finish_non_exhaustive()
381    }
382}
383
384pub(crate) fn now_unix() -> u64 {
385    SystemTime::now()
386        .duration_since(UNIX_EPOCH)
387        .map(|d| d.as_secs())
388        .unwrap_or(0)
389}
390
391fn lock<T>(m: &Mutex<T>) -> MutexGuard<'_, T> {
392    m.lock().unwrap_or_else(|e| e.into_inner())
393}
394
395/// Seconds since 2000-01-01, the ZCL time epoch.
396fn zcl_time_now() -> u32 {
397    now_unix().saturating_sub(946_684_800) as u32
398}
399
400impl<A: Adapter> Host<A> {
401    /// Start the network on `adapter` and run the host. Events arrive on the
402    /// returned receiver until the adapter fails.
403    pub async fn start(
404        adapter: A,
405        adapter_events: mpsc::UnboundedReceiver<AdapterEvent>,
406        mode: StartMode,
407        config: HostConfig,
408    ) -> Result<(Host<A>, mpsc::UnboundedReceiver<HostEvent>), HostError> {
409        let devices = match &config.store_path {
410            Some(path) => store::load(path).map_err(|e| HostError::Io(e.to_string()))?,
411            None => BTreeMap::new(),
412        };
413        let (outcome, network) = adapter.start(mode).await?;
414        tracing::info!(?outcome, ieee = %network.ieee, channel = network.channel, pan = format!("{:04x}", network.pan_id), "network up");
415        let info = adapter.info();
416        let (events, rx) = mpsc::unbounded_channel();
417        let mut state = State::default();
418        for (_, device) in devices {
419            state.put_device(device);
420        }
421        state.backup_wanted = outcome != StartOutcome::Resumed;
422        let max_in_flight = config.max_in_flight.max(1);
423        let host = Host {
424            inner: Arc::new(Inner {
425                adapter,
426                config,
427                network: Mutex::new(network.clone()),
428                state: Mutex::new(state),
429                waiters: Mutex::new(Waiters::default()),
430                seq: AtomicU8::new(1),
431                events,
432                dirty: Dirty::default(),
433                in_flight: Semaphore::new(max_in_flight),
434                stopped: AtomicBool::new(false),
435                shutdown: tokio::sync::watch::channel(false).0,
436                backup_lock: tokio::sync::Mutex::new(()),
437            }),
438        };
439        host.emit(HostEvent::Started {
440            outcome,
441            network,
442            adapter: info,
443        });
444        tokio::spawn(host.clone().event_loop(adapter_events));
445        tokio::spawn(host.clone().store_writer());
446        tokio::spawn(host.clone().ticker());
447        Ok((host, rx))
448    }
449
450    fn emit(&self, event: HostEvent) {
451        let _ = self.inner.events.send(event);
452    }
453
454    fn state(&self) -> MutexGuard<'_, State> {
455        lock(&self.inner.state)
456    }
457
458    fn next_seq(&self) -> u8 {
459        self.inner.seq.fetch_add(1, Ordering::Relaxed)
460    }
461
462    /// The network.
463    pub fn network(&self) -> NetworkInfo {
464        lock(&self.inner.network).clone()
465    }
466
467    /// The NCP.
468    pub fn adapter_info(&self) -> AdapterInfo {
469        self.inner.adapter.info()
470    }
471
472    /// The adapter, for NCP-specific calls.
473    pub fn adapter(&self) -> &A {
474        &self.inner.adapter
475    }
476
477    /// Every device.
478    pub fn devices(&self) -> Vec<Device> {
479        self.state().devices.values().cloned().collect()
480    }
481
482    /// One device.
483    pub fn device(&self, ieee: Ieee) -> Option<Device> {
484        self.state().devices.get(&ieee).cloned()
485    }
486
487    /// The device with a network address.
488    pub fn device_by_nwk(&self, nwk: NodeId) -> Option<Device> {
489        let state = self.state();
490        state
491            .by_nwk
492            .get(&nwk)
493            .and_then(|ieee| state.devices.get(ieee))
494            .cloned()
495    }
496
497    pub(crate) fn update_device(&self, ieee: Ieee, f: impl FnOnce(&mut Device)) -> Option<Device> {
498        let updated = {
499            let mut state = self.state();
500            let device = state.devices.get_mut(&ieee)?;
501            f(device);
502            device.clone()
503        };
504        self.inner.dirty.mark();
505        Some(updated)
506    }
507
508    /// Give a device a name.
509    pub fn set_name(&self, ieee: Ieee, name: Option<String>) -> Result<(), HostError> {
510        self.update_device(ieee, |d| d.name = name)
511            .map(|_| ())
512            .ok_or(HostError::UnknownDevice(ieee))
513    }
514
515    fn nwk_of(&self, ieee: Ieee) -> Result<NodeId, HostError> {
516        if ieee == self.network().ieee {
517            return Ok(self.network().nwk);
518        }
519        self.state()
520            .devices
521            .get(&ieee)
522            .map(|d| d.nwk)
523            .ok_or(HostError::UnknownDevice(ieee))
524    }
525
526    // ---- requests -------------------------------------------------------
527
528    async fn request(
529        &self,
530        key: WaitKey,
531        nwk: NodeId,
532        aps: Aps,
533        payload: Vec<u8>,
534        timeout: Duration,
535    ) -> Result<Reply, HostError> {
536        if self.inner.stopped.load(Ordering::SeqCst) {
537            return Err(HostError::Stopped);
538        }
539        let _permit = self
540            .inner
541            .in_flight
542            .acquire()
543            .await
544            .map_err(|_| HostError::Stopped)?;
545        let (tx, rx) = oneshot::channel();
546        lock(&self.inner.waiters).pending.insert(key, tx);
547        let tag = match self.inner.adapter.send_unicast(nwk, aps, payload).await {
548            Ok(tag) => tag,
549            Err(e) => {
550                lock(&self.inner.waiters).pending.remove(&key);
551                return Err(e);
552            }
553        };
554        {
555            let mut w = lock(&self.inner.waiters);
556            if w.recent_delivery(tag) == Some(false) {
557                w.pending.remove(&key);
558                return Err(HostError::DeliveryFailed(nwk));
559            }
560            w.tags.insert(tag, key);
561        }
562        let result = tokio::time::timeout(timeout, rx).await;
563        {
564            let mut w = lock(&self.inner.waiters);
565            w.pending.remove(&key);
566            w.tags.remove(&tag);
567        }
568        match result {
569            Ok(Ok(reply)) => reply,
570            Ok(Err(_)) => Err(HostError::Stopped),
571            Err(_) => Err(HostError::Timeout(nwk)),
572        }
573    }
574
575    fn timeout_for(&self, nwk: NodeId) -> Duration {
576        let sleepy = self.device_by_nwk(nwk).is_some_and(|d| d.is_sleepy());
577        if sleepy {
578            self.inner.config.request_timeout * 2
579        } else {
580            self.inner.config.request_timeout
581        }
582    }
583
584    /// Send a frame and wait for its APS delivery report.
585    async fn send_confirmed(
586        &self,
587        nwk: NodeId,
588        aps: Aps,
589        payload: Vec<u8>,
590        timeout: Duration,
591    ) -> Result<(), HostError> {
592        if self.inner.stopped.load(Ordering::SeqCst) {
593            return Err(HostError::Stopped);
594        }
595        let _permit = self
596            .inner
597            .in_flight
598            .acquire()
599            .await
600            .map_err(|_| HostError::Stopped)?;
601        let tag = self.inner.adapter.send_unicast(nwk, aps, payload).await?;
602        let rx = {
603            let mut w = lock(&self.inner.waiters);
604            if let Some(delivered) = w.recent_delivery(tag) {
605                return if delivered {
606                    Ok(())
607                } else {
608                    Err(HostError::DeliveryFailed(nwk))
609                };
610            }
611            let (tx, rx) = oneshot::channel();
612            w.deliveries.insert(tag, tx);
613            rx
614        };
615        let result = tokio::time::timeout(timeout, rx).await;
616        lock(&self.inner.waiters).deliveries.remove(&tag);
617        match result {
618            Ok(Ok(true)) => Ok(()),
619            Ok(Ok(false)) => Err(HostError::DeliveryFailed(nwk)),
620            Ok(Err(_)) => Err(HostError::Stopped),
621            Err(_) => Err(HostError::Timeout(nwk)),
622        }
623    }
624
625    /// Send a ZCL frame given as bytes, for a caller that builds frames
626    /// itself (a device library). The frame's transaction sequence number
627    /// is overwritten with the host's own. With `response`, waits for the
628    /// device's reply with that sequence number and returns it exactly as
629    /// received; otherwise waits for APS delivery and returns `None`.
630    pub async fn zcl_raw(&self, ieee: Ieee, request: RawZcl) -> Result<Option<Vec<u8>>, HostError> {
631        let nwk = self.nwk_of(ieee)?;
632        let mut frame = request.frame;
633        let tsn_at = match frame.first() {
634            Some(control) if control & 0x04 != 0 => 3,
635            Some(_) => 1,
636            None => return Err(HostError::Invalid("empty ZCL frame".into())),
637        };
638        if frame.len() < tsn_at + 2 {
639            return Err(HostError::Invalid(
640                "ZCL frame shorter than its header".into(),
641            ));
642        }
643        let seq = self.next_seq();
644        if let Some(b) = frame.get_mut(tsn_at) {
645            *b = seq;
646        }
647        let profile = request.profile.unwrap_or_else(|| {
648            self.device(ieee)
649                .map(|d| d.profile_of(request.endpoint))
650                .unwrap_or(zigbee_zcl::PROFILE_HOME_AUTOMATION)
651        });
652        let aps = Aps {
653            profile,
654            cluster: request.cluster,
655            source_endpoint: request.source_endpoint,
656            destination_endpoint: request.endpoint,
657        };
658        let timeout = request.timeout.unwrap_or_else(|| self.timeout_for(nwk));
659        if !request.response {
660            return self
661                .send_confirmed(nwk, aps, frame, timeout)
662                .await
663                .map(|_| None);
664        }
665        let key = WaitKey::Zcl {
666            nwk,
667            cluster: request.cluster,
668            seq,
669        };
670        match self.request(key, nwk, aps, frame, timeout).await? {
671            Reply::Zcl(_, raw) => Ok(Some(raw)),
672            Reply::Zdo(..) => Err(HostError::BadFrame("ZDO reply to a ZCL request".into())),
673        }
674    }
675
676    /// Send a ZDO request given as bytes (transaction sequence number
677    /// first, then the request). The sequence number is overwritten with
678    /// the host's own. With `response`, returns the response payload
679    /// exactly as received (sequence number first); otherwise waits for
680    /// APS delivery and returns `None`.
681    pub async fn zdo_raw(
682        &self,
683        ieee: Ieee,
684        cluster: u16,
685        mut payload: Vec<u8>,
686        response: bool,
687        timeout: Option<Duration>,
688    ) -> Result<Option<Vec<u8>>, HostError> {
689        if cluster & 0x8000 != 0 {
690            return Err(HostError::Invalid(format!(
691                "{cluster:#06x} is a ZDO response, not a request"
692            )));
693        }
694        let nwk = self.nwk_of(ieee)?;
695        let tsn = self.next_seq();
696        match payload.first_mut() {
697            Some(b) => *b = tsn,
698            None => return Err(HostError::Invalid("empty ZDO payload".into())),
699        }
700        let aps = Aps {
701            profile: zigbee_zdo::PROFILE_ID,
702            cluster,
703            source_endpoint: 0,
704            destination_endpoint: 0,
705        };
706        let timeout = timeout.unwrap_or_else(|| self.timeout_for(nwk));
707        if !response {
708            return self
709                .send_confirmed(nwk, aps, payload, timeout)
710                .await
711                .map(|_| None);
712        }
713        let key = WaitKey::Zdo {
714            nwk,
715            cluster: cluster | 0x8000,
716            tsn,
717        };
718        match self.request(key, nwk, aps, payload, timeout).await? {
719            Reply::Zdo(_, raw) => Ok(Some(raw)),
720            Reply::Zcl(..) => Err(HostError::BadFrame("ZCL reply to a ZDO request".into())),
721        }
722    }
723
724    /// Send a ZDO request to `nwk` and wait for its response.
725    pub async fn zdo_request(&self, nwk: NodeId, body: Body) -> Result<Message, HostError> {
726        let tsn = self.next_seq();
727        let (cluster, payload) = Message { tsn, body }.encode();
728        let key = WaitKey::Zdo {
729            nwk,
730            cluster: cluster | 0x8000,
731            tsn,
732        };
733        let aps = Aps {
734            profile: zigbee_zdo::PROFILE_ID,
735            cluster,
736            source_endpoint: 0,
737            destination_endpoint: 0,
738        };
739        match self
740            .request(key, nwk, aps, payload, self.timeout_for(nwk))
741            .await?
742        {
743            Reply::Zdo(m, _) => Ok(m),
744            Reply::Zcl(..) => Err(HostError::BadFrame("ZCL reply to a ZDO request".into())),
745        }
746    }
747
748    /// [`Host::zdo_request`] with the configured retries.
749    pub async fn zdo_request_retry(&self, nwk: NodeId, body: Body) -> Result<Message, HostError> {
750        let mut last = HostError::Timeout(nwk);
751        for attempt in 0..self.inner.config.request_attempts.max(1) {
752            if attempt > 0 {
753                tokio::time::sleep(Duration::from_millis(500)).await;
754            }
755            match self.zdo_request(nwk, body.clone()).await {
756                Ok(m) => return Ok(m),
757                Err(
758                    e @ (HostError::Timeout(_) | HostError::DeliveryFailed(_) | HostError::Ncp(_)),
759                ) => last = e,
760                Err(e) => return Err(e),
761            }
762        }
763        Err(last)
764    }
765
766    /// Send a ZCL frame to a device's endpoint and wait for the reply with
767    /// the same sequence number. The frame's sequence number is assigned
768    /// here.
769    pub async fn zcl_request(
770        &self,
771        ieee: Ieee,
772        endpoint: u8,
773        cluster: u16,
774        mut frame: Frame,
775    ) -> Result<Frame, HostError> {
776        let nwk = self.nwk_of(ieee)?;
777        let profile = self
778            .device(ieee)
779            .map(|d| d.profile_of(endpoint))
780            .unwrap_or(zigbee_zcl::PROFILE_HOME_AUTOMATION);
781        frame.header.seq = self.next_seq();
782        let key = WaitKey::Zcl {
783            nwk,
784            cluster,
785            seq: frame.header.seq,
786        };
787        let aps = Aps {
788            profile,
789            cluster,
790            source_endpoint: HOST_ENDPOINT,
791            destination_endpoint: endpoint,
792        };
793        match self
794            .request(key, nwk, aps, frame.encode(), self.timeout_for(nwk))
795            .await?
796        {
797            Reply::Zcl(f, _) => Ok(f),
798            Reply::Zdo(..) => Err(HostError::BadFrame("ZDO reply to a ZCL request".into())),
799        }
800    }
801
802    async fn zcl_request_retry(
803        &self,
804        ieee: Ieee,
805        endpoint: u8,
806        cluster: u16,
807        frame: Frame,
808    ) -> Result<Frame, HostError> {
809        let mut last = HostError::UnknownDevice(ieee);
810        for attempt in 0..self.inner.config.request_attempts.max(1) {
811            if attempt > 0 {
812                tokio::time::sleep(Duration::from_millis(500)).await;
813            }
814            match self
815                .zcl_request(ieee, endpoint, cluster, frame.clone())
816                .await
817            {
818                Ok(f) => return Ok(f),
819                Err(
820                    e @ (HostError::Timeout(_) | HostError::DeliveryFailed(_) | HostError::Ncp(_)),
821                ) => last = e,
822                Err(e) => return Err(e),
823            }
824        }
825        Err(last)
826    }
827
828    fn global_reply(frame: &Frame, what: &str) -> Result<Global, HostError> {
829        let g = Global::decode(frame.header.command, &frame.payload)
830            .map_err(|e| HostError::BadFrame(e.to_string()))?;
831        if let Global::DefaultResponse { status, .. } = g {
832            if status != zigbee_zcl::status::SUCCESS {
833                return Err(HostError::Status {
834                    what: what.into(),
835                    status,
836                });
837            }
838        }
839        Ok(g)
840    }
841
842    /// Read attributes. Returns one record per attribute the device answered.
843    pub async fn read_attributes(
844        &self,
845        ieee: Ieee,
846        endpoint: u8,
847        cluster: u16,
848        attributes: &[u16],
849    ) -> Result<Vec<ReadRecord>, HostError> {
850        let frame = Frame::global(
851            Direction::ClientToServer,
852            0,
853            foundation::id::READ_ATTRIBUTES,
854            Global::ReadAttributes(attributes.to_vec()).encode(),
855        );
856        let reply = self
857            .zcl_request_retry(ieee, endpoint, cluster, frame)
858            .await?;
859        match Self::global_reply(&reply, "read attributes")? {
860            Global::ReadAttributesResponse(records) => Ok(records),
861            other => Err(HostError::BadFrame(format!("unexpected reply {other:?}"))),
862        }
863    }
864
865    /// Write attributes. Returns (status, attribute) records; one success
866    /// record means every write succeeded.
867    pub async fn write_attributes(
868        &self,
869        ieee: Ieee,
870        endpoint: u8,
871        cluster: u16,
872        values: Vec<(u16, Value)>,
873    ) -> Result<Vec<(u8, Option<u16>)>, HostError> {
874        let frame = Frame::global(
875            Direction::ClientToServer,
876            0,
877            foundation::id::WRITE_ATTRIBUTES,
878            Global::WriteAttributes(values).encode(),
879        );
880        let reply = self
881            .zcl_request_retry(ieee, endpoint, cluster, frame)
882            .await?;
883        match Self::global_reply(&reply, "write attributes")? {
884            Global::WriteAttributesResponse(records) => Ok(records),
885            other => Err(HostError::BadFrame(format!("unexpected reply {other:?}"))),
886        }
887    }
888
889    /// Configure attribute reporting.
890    pub async fn configure_reporting(
891        &self,
892        ieee: Ieee,
893        endpoint: u8,
894        cluster: u16,
895        configs: Vec<ReportingConfig>,
896    ) -> Result<Vec<foundation::ReportingStatus>, HostError> {
897        let frame = Frame::global(
898            Direction::ClientToServer,
899            0,
900            foundation::id::CONFIGURE_REPORTING,
901            Global::ConfigureReporting(configs).encode(),
902        );
903        let reply = self
904            .zcl_request_retry(ieee, endpoint, cluster, frame)
905            .await?;
906        match Self::global_reply(&reply, "configure reporting")? {
907            Global::ConfigureReportingResponse(records) => Ok(records),
908            other => Err(HostError::BadFrame(format!("unexpected reply {other:?}"))),
909        }
910    }
911
912    /// Send a cluster command by name, with field values in order (trailing
913    /// optional fields may be left out). Returns the device's reply: its
914    /// default response or the command's own response.
915    pub async fn command(
916        &self,
917        ieee: Ieee,
918        endpoint: u8,
919        cluster: u16,
920        name: &str,
921        values: &[Value],
922    ) -> Result<Frame, HostError> {
923        let def = zigbee_zcl::cluster(cluster)
924            .and_then(|c| c.command_by_name(Direction::ClientToServer, name))
925            .ok_or_else(|| {
926                HostError::Invalid(format!("cluster {cluster:#06x} has no command {name:?}"))
927            })?;
928        let payload = def
929            .encode(values)
930            .map_err(|e| HostError::Invalid(e.to_string()))?;
931        let reply = self
932            .zcl_request(
933                ieee,
934                endpoint,
935                cluster,
936                Frame::cluster(Direction::ClientToServer, 0, def.id, payload),
937            )
938            .await?;
939        if reply.header.frame_type == FrameType::Global {
940            Self::global_reply(&reply, name)?;
941        }
942        Ok(reply)
943    }
944
945    /// Bind a device's cluster to the host's endpoint, so its reports come here.
946    pub async fn bind_to_host(
947        &self,
948        ieee: Ieee,
949        endpoint: u8,
950        cluster: u16,
951    ) -> Result<(), HostError> {
952        let nwk = self.nwk_of(ieee)?;
953        let body = Body::BindReq(zigbee_zdo::Binding {
954            source: ieee,
955            source_endpoint: endpoint,
956            cluster,
957            target: zigbee_zdo::BindTarget::Endpoint {
958                ieee: self.network().ieee,
959                endpoint: HOST_ENDPOINT,
960            },
961        });
962        let m = self.zdo_request_retry(nwk, body).await?;
963        match m.status() {
964            Some(zigbee_zdo::status::SUCCESS) => Ok(()),
965            Some(status) => Err(HostError::Status {
966                what: "bind".into(),
967                status,
968            }),
969            None => Err(HostError::BadFrame("bind response without status".into())),
970        }
971    }
972
973    // ---- joining --------------------------------------------------------
974
975    /// Open the network for joining for `seconds` (at most 254; 0 closes
976    /// it), everywhere or only through one router. Opening through a router
977    /// leaves the coordinator's own radio closed.
978    pub async fn permit_join(&self, seconds: u8, via: Option<Ieee>) -> Result<(), HostError> {
979        let seconds = seconds.min(254);
980        let join = self.inner.config.join.clone();
981        let local = via.is_none() || seconds == 0;
982        self.inner
983            .adapter
984            .permit_join(if local { seconds } else { 0 }, &join)
985            .await?;
986        if !local && seconds > 0 {
987            // The trust center must accept joins even with its radio closed.
988            self.inner.adapter.permit_join(0, &join).await?;
989        }
990        if seconds > 0 {
991            let codes: Vec<(Ieee, Key)> = self
992                .state()
993                .install_codes
994                .iter()
995                .map(|(i, k)| (*i, *k))
996                .collect();
997            for (ieee, key) in codes {
998                self.inner.adapter.add_join_key(ieee, key).await?;
999            }
1000        }
1001        let tsn = self.next_seq();
1002        let (cluster, payload) = Message {
1003            tsn,
1004            body: Body::MgmtPermitJoiningReq {
1005                duration: seconds,
1006                tc_significance: 1,
1007            },
1008        }
1009        .encode();
1010        let aps = Aps {
1011            profile: zigbee_zdo::PROFILE_ID,
1012            cluster,
1013            source_endpoint: 0,
1014            destination_endpoint: 0,
1015        };
1016        match via {
1017            Some(router) => {
1018                let nwk = self.nwk_of(router)?;
1019                self.inner.adapter.send_unicast(nwk, aps, payload).await?;
1020            }
1021            None => {
1022                self.inner
1023                    .adapter
1024                    .send_broadcast(BROADCAST_ROUTERS, aps, payload)
1025                    .await?
1026            }
1027        }
1028        let generation = {
1029            let mut state = self.state();
1030            state.permit_generation += 1;
1031            state.permit_generation
1032        };
1033        self.emit(HostEvent::PermitJoin { seconds, via });
1034        if seconds > 0 {
1035            let host = self.clone();
1036            tokio::spawn(async move {
1037                let mut shutdown = host.inner.shutdown.subscribe();
1038                tokio::select! {
1039                    _ = tokio::time::sleep(Duration::from_secs(u64::from(seconds))) => {}
1040                    _ = shutdown.wait_for(|stop| *stop) => return,
1041                }
1042                if host.state().permit_generation == generation {
1043                    // The NCP closed itself; restore the rejoin-only policy.
1044                    if let Err(e) = host
1045                        .inner
1046                        .adapter
1047                        .permit_join(0, &host.inner.config.join)
1048                        .await
1049                    {
1050                        tracing::warn!(error = %e, "closing the network");
1051                    }
1052                    host.emit(HostEvent::PermitJoin {
1053                        seconds: 0,
1054                        via: None,
1055                    });
1056                }
1057            });
1058        }
1059        Ok(())
1060    }
1061
1062    /// Accept a device's install code (with its CRC). The derived key is
1063    /// given to the NCP now and whenever joining opens, until the device
1064    /// joins. Install codes are kept in memory only.
1065    pub async fn add_install_code(
1066        &self,
1067        ieee: Ieee,
1068        code_with_crc: &[u8],
1069    ) -> Result<(), HostError> {
1070        let key =
1071            install_code::link_key(code_with_crc).map_err(|e| HostError::Invalid(e.to_string()))?;
1072        self.state().install_codes.insert(ieee, key);
1073        self.inner.adapter.add_join_key(ieee, key).await
1074    }
1075
1076    /// Replace every install code the host holds with `entries` (IEEE
1077    /// address, install code with its CRC). All are checked before any is
1078    /// taken. Returns how many there are now.
1079    pub async fn set_install_codes(&self, entries: &[(Ieee, Vec<u8>)]) -> Result<usize, HostError> {
1080        let mut keys = HashMap::new();
1081        for (ieee, code) in entries {
1082            let key = install_code::link_key(code)
1083                .map_err(|e| HostError::Invalid(format!("{ieee}: {e}")))?;
1084            keys.insert(*ieee, key);
1085        }
1086        let n = keys.len();
1087        self.state().install_codes = keys.clone();
1088        for (ieee, key) in keys {
1089            self.inner.adapter.add_join_key(ieee, key).await?;
1090        }
1091        Ok(n)
1092    }
1093
1094    /// Other networks heard on every channel (an active scan).
1095    pub async fn active_scan(&self) -> Result<Vec<crate::adapter::Beacon>, HostError> {
1096        self.inner.adapter.active_scan(0x07FF_F800).await
1097    }
1098
1099    /// Leave the network and erase it from the coordinator, then forget
1100    /// every device. The host stops; start a new one to form again.
1101    pub async fn leave(&self) -> Result<(), HostError> {
1102        self.inner.adapter.leave().await?;
1103        let devices: Vec<Ieee> = self.state().devices.keys().copied().collect();
1104        for ieee in devices {
1105            self.forget(ieee, None);
1106        }
1107        self.state().backup_wanted = false;
1108        self.inner.dirty.mark();
1109        self.flush().await?;
1110        self.stop();
1111        Ok(())
1112    }
1113
1114    /// Ask a device to leave and forget it. With `force`, it is forgotten
1115    /// even if it does not answer (a dead or sleepy device).
1116    pub async fn remove(&self, ieee: Ieee, force: bool) -> Result<(), HostError> {
1117        self.remove_because(ieee, force, "removed").await
1118    }
1119
1120    async fn remove_because(&self, ieee: Ieee, force: bool, reason: &str) -> Result<(), HostError> {
1121        let nwk = self.nwk_of(ieee)?;
1122        self.state().removing.insert(ieee);
1123        let result = self
1124            .zdo_request(nwk, Body::MgmtLeaveReq { ieee, flags: 0 })
1125            .await;
1126        if let Err(e) = &result {
1127            if !force {
1128                self.state().removing.remove(&ieee);
1129                return Err(e.clone());
1130            }
1131            tracing::warn!(%ieee, error = %e, "device did not acknowledge leave; forgetting it");
1132        }
1133        self.forget(ieee, None);
1134        self.state().removing.remove(&ieee);
1135        self.emit(HostEvent::DeviceRemoved {
1136            ieee,
1137            reason: reason.into(),
1138        });
1139        Ok(())
1140    }
1141
1142    /// Drop a device's record; `reason` is reported as a removal, `None`
1143    /// for a device that left by itself.
1144    fn forget(&self, ieee: Ieee, reason: Option<&str>) {
1145        let removed = {
1146            let mut state = self.state();
1147            let removed = state.devices.remove(&ieee);
1148            if let Some(d) = &removed {
1149                state.by_nwk.remove(&d.nwk);
1150                state.topology.remove_node(d.nwk);
1151            }
1152            state.legacy_deadlines.remove(&ieee);
1153            state.interviewing.remove(&ieee);
1154            state.backup_wanted = true;
1155            removed.is_some()
1156        };
1157        if removed {
1158            self.inner.dirty.mark();
1159            if let Some(reason) = reason {
1160                self.emit(HostEvent::DeviceRemoved {
1161                    ieee,
1162                    reason: reason.into(),
1163                });
1164            }
1165        }
1166    }
1167
1168    // ---- topology -------------------------------------------------------
1169
1170    /// Current links, with addresses resolved to IEEE where known.
1171    pub fn topology(&self) -> Vec<(Option<Ieee>, Option<Ieee>, Link)> {
1172        let state = self.state();
1173        let coordinator = (self.network().nwk, self.network().ieee);
1174        let resolve = |nwk: NodeId| {
1175            if nwk == coordinator.0 {
1176                Some(coordinator.1)
1177            } else {
1178                state.by_nwk.get(&nwk).copied()
1179            }
1180        };
1181        state
1182            .topology
1183            .links()
1184            .into_iter()
1185            .map(|l| (resolve(l.from), resolve(l.to), l))
1186            .collect()
1187    }
1188
1189    /// Read a router's (or the coordinator's) whole neighbor table. At most
1190    /// once a minute per device.
1191    pub async fn scan_neighbors(&self, ieee: Ieee) -> Result<Vec<Neighbor>, HostError> {
1192        {
1193            let mut state = self.state();
1194            if state
1195                .last_scan
1196                .get(&ieee)
1197                .is_some_and(|t| t.elapsed() < Duration::from_secs(60))
1198            {
1199                return Err(HostError::Invalid(
1200                    "neighbor scans are limited to one a minute per device".into(),
1201                ));
1202            }
1203            state.last_scan.insert(ieee, Instant::now());
1204        }
1205        let nwk = self.nwk_of(ieee)?;
1206        let mut neighbors = Vec::new();
1207        let mut start = 0u8;
1208        loop {
1209            let m = self
1210                .zdo_request_retry(nwk, Body::MgmtLqiReq { start_index: start })
1211                .await?;
1212            match m.body {
1213                Body::MgmtLqiRsp {
1214                    status: zigbee_zdo::status::SUCCESS,
1215                    total,
1216                    neighbors: page,
1217                    ..
1218                } => {
1219                    let got = page.len();
1220                    neighbors.extend(page);
1221                    if got == 0 || neighbors.len() >= usize::from(total) || neighbors.len() >= 255 {
1222                        break;
1223                    }
1224                    start = neighbors.len() as u8;
1225                }
1226                Body::MgmtLqiRsp { status, .. } => {
1227                    return Err(HostError::Status {
1228                        what: "Mgmt_Lqi".into(),
1229                        status,
1230                    })
1231                }
1232                _ => return Err(HostError::BadFrame("unexpected Mgmt_Lqi reply".into())),
1233            }
1234        }
1235        let now = now_unix();
1236        let mut state = self.state();
1237        for n in &neighbors {
1238            state.topology.neighbor(nwk, n.nwk, n.lqi, now);
1239        }
1240        Ok(neighbors)
1241    }
1242
1243    /// Move the network to `channel` (11 to 26): broadcast a network
1244    /// update with the next update id and wait until the coordinator runs
1245    /// on the new channel. Devices follow the broadcast; sleepy ones that
1246    /// miss it find the network again when they next rejoin.
1247    pub async fn change_channel(&self, channel: u8) -> Result<NetworkInfo, HostError> {
1248        if !(11..=26).contains(&channel) {
1249            return Err(HostError::Invalid(format!(
1250                "channel {channel} is not 11 to 26"
1251            )));
1252        }
1253        let current = self.network();
1254        if current.channel == channel {
1255            return Ok(current);
1256        }
1257        let update_id = current.nwk_update_id.wrapping_add(1);
1258        let (cluster, payload) = Message {
1259            tsn: self.next_seq(),
1260            body: Body::MgmtNwkUpdateReq {
1261                channel_mask: 1 << channel,
1262                scan_duration: 0xFE,
1263                scan_count: None,
1264                nwk_update_id: Some(update_id),
1265                manager: None,
1266            },
1267        }
1268        .encode();
1269        let aps = Aps {
1270            profile: zigbee_zdo::PROFILE_ID,
1271            cluster,
1272            source_endpoint: 0,
1273            destination_endpoint: 0,
1274        };
1275        self.inner
1276            .adapter
1277            .send_broadcast(zigbee_primitives::BROADCAST_RX_ON_WHEN_IDLE, aps, payload)
1278            .await?;
1279        // Devices switch after the broadcast has spread (nwkNetworkBroadcast
1280        // DeliveryTime); the coordinator with them.
1281        let deadline = Instant::now() + Duration::from_secs(20);
1282        loop {
1283            tokio::time::sleep(Duration::from_millis(500)).await;
1284            let mut now = self.inner.adapter.network_info().await?;
1285            if now.channel == channel {
1286                // Z-Stack does not report the update id: keep the one sent.
1287                if now.nwk_update_id == 0 {
1288                    now.nwk_update_id = update_id;
1289                }
1290                *lock(&self.inner.network) = now.clone();
1291                self.state().backup_wanted = true;
1292                self.inner.dirty.mark();
1293                tracing::info!(
1294                    channel,
1295                    update_id = now.nwk_update_id,
1296                    "network moved to a new channel"
1297                );
1298                self.emit(HostEvent::ChannelChanged {
1299                    network: now.clone(),
1300                });
1301                return Ok(now);
1302            }
1303            if Instant::now() > deadline {
1304                return Err(HostError::Ncp(format!(
1305                    "the coordinator is still on channel {} after asking for {channel}",
1306                    now.channel
1307                )));
1308            }
1309        }
1310    }
1311
1312    /// Measure every channel's energy (channel, max RSSI in dBm).
1313    pub async fn energy_scan(&self) -> Result<Vec<(u8, i8)>, HostError> {
1314        self.inner.adapter.energy_scan(0x07FF_F800).await
1315    }
1316
1317    // ---- backups and the store -------------------------------------------
1318
1319    /// Take a backup now, and write it if a backup path is configured.
1320    pub async fn backup(&self) -> Result<Backup, HostError> {
1321        let _one_at_a_time = self.inner.backup_lock.lock().await;
1322        let mut backup = self.inner.adapter.backup().await?;
1323        {
1324            let state = self.state();
1325            let coordinator = self.network().nwk;
1326            for entry in &mut backup.devices {
1327                if let Some(d) = state.devices.get(&entry.ieee_address) {
1328                    entry.nwk_address = Some(d.nwk);
1329                    entry.is_child = d.parent == Some(coordinator);
1330                }
1331            }
1332            for d in state.devices.values() {
1333                if !backup.devices.iter().any(|e| e.ieee_address == d.ieee) {
1334                    backup.devices.push(crate::backup::BackupDevice {
1335                        nwk_address: Some(d.nwk),
1336                        ieee_address: d.ieee,
1337                        is_child: d.parent == Some(coordinator),
1338                        link_key: None,
1339                    });
1340                }
1341            }
1342        }
1343        if let Some(path) = &self.inner.config.backup_path {
1344            let json = backup.to_json();
1345            let target = path.clone();
1346            tokio::task::spawn_blocking(move || store::write_atomic(&target, json.as_bytes()))
1347                .await
1348                .map_err(|e| HostError::Io(e.to_string()))?
1349                .map_err(|e| HostError::Io(format!("writing backup {}: {e}", path.display())))?;
1350            self.emit(HostEvent::BackupWritten { path: path.clone() });
1351        }
1352        let mut state = self.state();
1353        state.backup_wanted = false;
1354        state.last_backup = Some(Instant::now());
1355        Ok(backup)
1356    }
1357
1358    /// Stop the host: write the device store, end its tasks and release the
1359    /// adapter (and with it the port) once every clone is dropped.
1360    pub async fn shutdown(&self) -> Result<(), HostError> {
1361        self.stop();
1362        let _ = self.inner.shutdown.send(true);
1363        self.flush().await
1364    }
1365
1366    /// Write the device store now.
1367    pub async fn flush(&self) -> Result<(), HostError> {
1368        let Some(path) = self.inner.config.store_path.clone() else {
1369            return Ok(());
1370        };
1371        let bytes = store::serialize(&self.state().devices);
1372        tokio::task::spawn_blocking(move || store::write_atomic(&path, &bytes))
1373            .await
1374            .map_err(|e| HostError::Io(e.to_string()))?
1375            .map_err(|e| HostError::Io(e.to_string()))
1376    }
1377
1378    async fn store_writer(self) {
1379        if self.inner.config.store_path.is_none() {
1380            return;
1381        }
1382        loop {
1383            self.inner.dirty.changed().await;
1384            tokio::time::sleep(store::WRITE_DELAY).await;
1385            if let Err(e) = self.flush().await {
1386                tracing::error!(error = %e, "writing the device store");
1387            }
1388            if self.inner.stopped.load(Ordering::SeqCst) {
1389                return;
1390            }
1391        }
1392    }
1393
1394    async fn ticker(self) {
1395        let mut tick = tokio::time::interval(Duration::from_secs(1));
1396        tick.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay);
1397        loop {
1398            tick.tick().await;
1399            if self.inner.stopped.load(Ordering::SeqCst) {
1400                return;
1401            }
1402            let now = Instant::now();
1403            let (expired, backup_due) = {
1404                let mut state = self.state();
1405                let expired: Vec<Ieee> = state
1406                    .legacy_deadlines
1407                    .iter()
1408                    .filter(|(_, t)| now >= **t)
1409                    .map(|(i, _)| *i)
1410                    .collect();
1411                for ieee in &expired {
1412                    state.legacy_deadlines.remove(ieee);
1413                }
1414                let interval_due = state
1415                    .last_backup
1416                    .is_none_or(|t| t.elapsed() >= self.inner.config.backup_interval);
1417                let settled = state
1418                    .last_backup
1419                    .is_none_or(|t| t.elapsed() >= Duration::from_secs(10));
1420                state.topology.expire(now_unix());
1421                (
1422                    expired,
1423                    self.inner.config.backup_path.is_some()
1424                        && ((state.backup_wanted && settled) || interval_due),
1425                )
1426            };
1427            for ieee in expired {
1428                tracing::warn!(%ieee, "device did not request a unique link key; removing it (legacy devices are not allowed)");
1429                let host = self.clone();
1430                tokio::spawn(async move {
1431                    let reason = "no unique link key (pre-Zigbee 3.0 devices are not allowed)";
1432                    if host.remove_because(ieee, true, reason).await.is_err() {
1433                        host.forget(ieee, Some(reason));
1434                    }
1435                });
1436            }
1437            if backup_due {
1438                if let Err(e) = self.backup().await {
1439                    tracing::error!(error = %e, "taking a backup");
1440                    self.state().last_backup = Some(Instant::now());
1441                }
1442            }
1443        }
1444    }
1445
1446    // ---- incoming --------------------------------------------------------
1447
1448    async fn event_loop(self, mut events: mpsc::UnboundedReceiver<AdapterEvent>) {
1449        let mut shutdown = self.inner.shutdown.subscribe();
1450        loop {
1451            let event = tokio::select! {
1452                event = events.recv() => match event {
1453                    Some(event) => event,
1454                    None => break,
1455                },
1456                _ = shutdown.wait_for(|stop| *stop) => return,
1457            };
1458            match event {
1459                AdapterEvent::Message {
1460                    source,
1461                    source_ieee,
1462                    aps,
1463                    broadcast,
1464                    group,
1465                    lqi,
1466                    rssi,
1467                    payload,
1468                } => self.on_message(
1469                    source,
1470                    source_ieee,
1471                    aps,
1472                    broadcast,
1473                    group,
1474                    lqi,
1475                    rssi,
1476                    payload,
1477                ),
1478                AdapterEvent::Joined {
1479                    nwk,
1480                    ieee,
1481                    parent,
1482                    rejoin,
1483                } => self.on_joined(nwk, ieee, parent, rejoin),
1484                AdapterEvent::Left { ieee, .. } => {
1485                    tracing::info!(%ieee, "device left");
1486                    let ours = self.state().removing.contains(&ieee);
1487                    self.forget(ieee, None);
1488                    if !ours {
1489                        self.emit(HostEvent::DeviceLeft { ieee });
1490                    }
1491                }
1492                AdapterEvent::KeyExchange { ieee, success } => {
1493                    if success {
1494                        self.state().legacy_deadlines.remove(&ieee);
1495                        self.update_device(ieee, |d| d.unique_link_key = true);
1496                    }
1497                }
1498                AdapterEvent::RouteRecord {
1499                    source,
1500                    ieee,
1501                    relays,
1502                    lqi,
1503                    rssi,
1504                } => {
1505                    let coordinator = self.network().nwk;
1506                    let mut state = self.state();
1507                    state.topology.route_record(
1508                        source,
1509                        &relays,
1510                        coordinator,
1511                        lqi,
1512                        rssi,
1513                        now_unix(),
1514                    );
1515                    let known = ieee.filter(|i| state.devices.contains_key(i));
1516                    if let (false, Some(ieee)) = (state.by_nwk.contains_key(&source), known) {
1517                        if let Some(mut d) = state.devices.get(&ieee).cloned() {
1518                            d.nwk = source;
1519                            state.put_device(d);
1520                        }
1521                    }
1522                }
1523                AdapterEvent::Delivery { tag, delivered } => {
1524                    let mut w = lock(&self.inner.waiters);
1525                    if w.recent.len() >= RECENT_DELIVERIES {
1526                        w.recent.pop_front();
1527                    }
1528                    w.recent.push_back((tag, delivered));
1529                    if let Some(tx) = w.deliveries.remove(&tag) {
1530                        let _ = tx.send(delivered);
1531                    }
1532                    if let Some(key) = w.tags.remove(&tag) {
1533                        if !delivered {
1534                            let nwk = match key {
1535                                WaitKey::Zdo { nwk, .. } | WaitKey::Zcl { nwk, .. } => nwk,
1536                            };
1537                            if let Some(tx) = w.pending.remove(&key) {
1538                                let _ = tx.send(Err(HostError::DeliveryFailed(nwk)));
1539                            }
1540                        }
1541                    }
1542                }
1543                AdapterEvent::NetworkUp => tracing::info!("network up"),
1544                AdapterEvent::NetworkDown => tracing::warn!("network down"),
1545                AdapterEvent::Failed(reason) => {
1546                    tracing::error!(%reason, "adapter failed");
1547                    self.stop();
1548                    self.emit(HostEvent::AdapterFailed { reason });
1549                    return;
1550                }
1551            }
1552        }
1553        self.stop();
1554        self.emit(HostEvent::AdapterFailed {
1555            reason: "adapter events ended".into(),
1556        });
1557    }
1558
1559    fn stop(&self) {
1560        self.inner.stopped.store(true, Ordering::SeqCst);
1561        let mut w = lock(&self.inner.waiters);
1562        for (_, tx) in w.pending.drain() {
1563            let _ = tx.send(Err(HostError::Stopped));
1564        }
1565        self.inner.dirty.mark();
1566    }
1567
1568    fn on_joined(&self, nwk: NodeId, ieee: Ieee, parent: NodeId, rejoin: bool) {
1569        let is_new = {
1570            let mut state = self.state();
1571            let mut device = state
1572                .devices
1573                .get(&ieee)
1574                .cloned()
1575                .unwrap_or_else(|| Device::new(ieee, nwk, now_unix()));
1576            let is_new = !state.devices.contains_key(&ieee);
1577            device.nwk = nwk;
1578            device.parent = Some(parent);
1579            state.put_device(device);
1580            state.install_codes.remove(&ieee);
1581            if is_new
1582                && !rejoin
1583                && !self.inner.config.join.allow_legacy
1584                && self.inner.adapter.info().reports_key_exchange
1585            {
1586                state
1587                    .legacy_deadlines
1588                    .insert(ieee, Instant::now() + self.inner.config.legacy_grace);
1589            }
1590            state.backup_wanted = true;
1591            is_new
1592        };
1593        self.inner.dirty.mark();
1594        tracing::info!(%ieee, nwk = format!("{nwk:#06x}"), rejoin, "device joined");
1595        self.emit(HostEvent::DeviceJoined { ieee, nwk, rejoin });
1596        if is_new {
1597            // Most devices announce themselves right after joining; start
1598            // the interview then, or shortly after if no announce comes.
1599            let host = self.clone();
1600            tokio::spawn(async move {
1601                tokio::time::sleep(Duration::from_millis(1500)).await;
1602                host.maybe_interview(ieee, true);
1603            });
1604        }
1605    }
1606
1607    fn on_announce(&self, nwk: NodeId, ieee: Ieee) {
1608        let is_new = {
1609            let mut state = self.state();
1610            let is_new = !state.devices.contains_key(&ieee);
1611            let mut device = state
1612                .devices
1613                .get(&ieee)
1614                .cloned()
1615                .unwrap_or_else(|| Device::new(ieee, nwk, now_unix()));
1616            device.nwk = nwk;
1617            state.put_device(device);
1618            if is_new {
1619                state.backup_wanted = true;
1620            }
1621            is_new
1622        };
1623        self.inner.dirty.mark();
1624        if is_new {
1625            // A coordinator that reports no joins (deCONZ): the announce is
1626            // the first the host hears of the device.
1627            tracing::info!(%ieee, nwk = format!("{nwk:#06x}"), "device joined (announce)");
1628            self.emit(HostEvent::DeviceJoined {
1629                ieee,
1630                nwk,
1631                rejoin: false,
1632            });
1633        }
1634        self.emit(HostEvent::DeviceAnnounced { ieee, nwk });
1635        self.maybe_interview(ieee, true);
1636    }
1637
1638    /// Interview a device again from the start (after a firmware update, or
1639    /// to reconfigure reporting).
1640    pub fn reinterview(&self, ieee: Ieee) -> Result<(), HostError> {
1641        self.update_device(ieee, |d| d.interview = crate::device::Interview::default())
1642            .ok_or(HostError::UnknownDevice(ieee))?;
1643        self.state().last_interview.remove(&ieee);
1644        self.maybe_interview(ieee, true);
1645        Ok(())
1646    }
1647
1648    /// Start or resume an interview unless one is running, done, or was
1649    /// tried too recently.
1650    fn maybe_interview(&self, ieee: Ieee, eager: bool) {
1651        {
1652            let mut state = self.state();
1653            let Some(device) = state.devices.get(&ieee) else {
1654                return;
1655            };
1656            if device.interview.is_done() || state.interviewing.contains(&ieee) {
1657                return;
1658            }
1659            let backoff = if eager {
1660                Duration::ZERO
1661            } else {
1662                Duration::from_secs(30)
1663            };
1664            if state
1665                .last_interview
1666                .get(&ieee)
1667                .is_some_and(|t| t.elapsed() < backoff)
1668            {
1669                return;
1670            }
1671            state.interviewing.insert(ieee);
1672            state.last_interview.insert(ieee, Instant::now());
1673        }
1674        let host = self.clone();
1675        tokio::spawn(async move {
1676            crate::interview::run(&host, ieee).await;
1677            host.state().interviewing.remove(&ieee);
1678        });
1679    }
1680
1681    #[allow(clippy::too_many_arguments)]
1682    fn on_message(
1683        &self,
1684        source: NodeId,
1685        source_ieee: Option<Ieee>,
1686        aps: Aps,
1687        broadcast: bool,
1688        group: Option<u16>,
1689        lqi: u8,
1690        rssi: Option<i8>,
1691        payload: Vec<u8>,
1692    ) {
1693        let now = now_unix();
1694        let known = {
1695            let mut state = self.state();
1696            if let Some(ieee) = source_ieee {
1697                if state.by_nwk.get(&source) != Some(&ieee) {
1698                    if let Some(mut d) = state.devices.get(&ieee).cloned() {
1699                        d.nwk = source;
1700                        state.put_device(d);
1701                    }
1702                }
1703            }
1704            let coordinator = self.network().nwk;
1705            state.topology.last_hop(source, coordinator, lqi, rssi, now);
1706            let ieee = state.by_nwk.get(&source).copied();
1707            if let Some(d) = ieee.and_then(|i| state.devices.get_mut(&i)) {
1708                d.last_seen_unix = Some(now);
1709                d.last_lqi = Some(lqi);
1710                d.last_rssi = rssi.or(d.last_rssi);
1711            }
1712            ieee
1713        };
1714
1715        if aps.profile == zigbee_zdo::PROFILE_ID {
1716            match Message::parse(aps.cluster, &payload) {
1717                Ok(m) if aps.cluster & 0x8000 != 0 => self.resolve(
1718                    WaitKey::Zdo {
1719                        nwk: source,
1720                        cluster: aps.cluster,
1721                        tsn: m.tsn,
1722                    },
1723                    Reply::Zdo(m, payload.clone()),
1724                ),
1725                Ok(Message {
1726                    body: Body::DeviceAnnce { nwk, ieee, .. },
1727                    ..
1728                }) => self.on_announce(nwk, ieee),
1729                Ok(_) => {}
1730                Err(e) => {
1731                    tracing::debug!(source, cluster = aps.cluster, error = %e, "dropping malformed ZDO frame")
1732                }
1733            }
1734            return;
1735        }
1736
1737        let frame = match Frame::parse(&payload) {
1738            Ok(f) => f,
1739            Err(e) => {
1740                tracing::debug!(source, cluster = aps.cluster, error = %e, "dropping malformed ZCL frame");
1741                return;
1742            }
1743        };
1744        let key = WaitKey::Zcl {
1745            nwk: source,
1746            cluster: aps.cluster,
1747            seq: frame.header.seq,
1748        };
1749        let is_reply = lock(&self.inner.waiters).pending.contains_key(&key) && !broadcast;
1750        if is_reply {
1751            self.resolve(key, Reply::Zcl(frame, payload));
1752        } else if let Some(ieee) = known {
1753            let last_hop = self
1754                .state()
1755                .topology
1756                .route(source)
1757                .and_then(|r| r.last().copied())
1758                .unwrap_or(source);
1759            self.emit(HostEvent::Frame {
1760                ieee,
1761                link: FrameLink {
1762                    nwk: source,
1763                    source_endpoint: aps.source_endpoint,
1764                    destination_endpoint: aps.destination_endpoint,
1765                    profile: aps.profile,
1766                    cluster: aps.cluster,
1767                    group,
1768                    broadcast,
1769                    lqi,
1770                    rssi,
1771                    last_hop,
1772                },
1773                frame: payload,
1774            });
1775            self.on_zcl(ieee, source, aps, broadcast, lqi, frame);
1776        } else {
1777            tracing::debug!(
1778                source = format!("{source:#06x}"),
1779                cluster = aps.cluster,
1780                "ZCL frame from an unknown device"
1781            );
1782        }
1783        if let Some(ieee) = known {
1784            self.maybe_interview(ieee, false);
1785        }
1786    }
1787
1788    fn resolve(&self, key: WaitKey, reply: Reply) {
1789        if let Some(tx) = lock(&self.inner.waiters).pending.remove(&key) {
1790            let _ = tx.send(Ok(reply));
1791        }
1792    }
1793
1794    fn on_zcl(&self, ieee: Ieee, source: NodeId, aps: Aps, broadcast: bool, lqi: u8, frame: Frame) {
1795        let h = frame.header;
1796        let mut wants_default_response = !h.disable_default_response && !broadcast;
1797        match h.frame_type {
1798            FrameType::Global => match Global::decode(h.command, &frame.payload) {
1799                Ok(Global::ReportAttributes(attributes)) => {
1800                    self.emit(HostEvent::Attributes {
1801                        ieee,
1802                        endpoint: aps.source_endpoint,
1803                        cluster: aps.cluster,
1804                        attributes,
1805                        lqi,
1806                    });
1807                }
1808                Ok(Global::ReadAttributesResponse(records)) => {
1809                    let attributes: Vec<(u16, Value)> = records
1810                        .into_iter()
1811                        .filter_map(|r| r.value.map(|v| (r.attribute, v)))
1812                        .collect();
1813                    self.emit(HostEvent::Attributes {
1814                        ieee,
1815                        endpoint: aps.source_endpoint,
1816                        cluster: aps.cluster,
1817                        attributes,
1818                        lqi,
1819                    });
1820                    wants_default_response = false;
1821                }
1822                Ok(Global::ReadAttributes(ids)) => {
1823                    self.answer_read(source, aps, h.seq, ids);
1824                    wants_default_response = false;
1825                }
1826                Ok(Global::DefaultResponse { .. }) => wants_default_response = false,
1827                Ok(_) => {}
1828                Err(e) => tracing::debug!(%ieee, error = %e, "malformed global command"),
1829            },
1830            FrameType::Cluster
1831                if aps.cluster == crate::ota::CLUSTER
1832                    && h.direction == Direction::ClientToServer
1833                    && h.manufacturer.is_none() =>
1834            {
1835                self.on_ota(ieee, source, aps, h.seq, h.command, &frame.payload);
1836                return;
1837            }
1838            FrameType::Cluster => {
1839                let from_server = h.direction == Direction::ServerToClient;
1840                let def = if h.manufacturer.is_none() {
1841                    zigbee_zcl::cluster(aps.cluster).and_then(|c| c.command(h.direction, h.command))
1842                } else {
1843                    None
1844                };
1845                let fields = def
1846                    .and_then(|d| d.decode(&frame.payload).ok())
1847                    .unwrap_or_default();
1848                if aps.cluster == zigbee_zcl::cluster_id::IAS_ZONE
1849                    && from_server
1850                    && h.command == zigbee_zcl::response::ias_zone::ZONE_ENROLL_REQUEST
1851                {
1852                    let host = self.clone();
1853                    let endpoint = aps.source_endpoint;
1854                    tokio::spawn(async move {
1855                        if let Err(e) =
1856                            crate::interview::enroll_response(&host, ieee, endpoint).await
1857                        {
1858                            tracing::warn!(%ieee, error = %e, "IAS enroll response");
1859                        }
1860                    });
1861                }
1862                self.emit(HostEvent::Command {
1863                    ieee,
1864                    endpoint: aps.source_endpoint,
1865                    cluster: aps.cluster,
1866                    command: h.command,
1867                    name: def.map(|d| d.name),
1868                    fields,
1869                    from_server,
1870                });
1871            }
1872        }
1873        if wants_default_response {
1874            let reply = Frame {
1875                header: zigbee_zcl::Header {
1876                    frame_type: FrameType::Global,
1877                    manufacturer: h.manufacturer,
1878                    direction: h.direction.reverse(),
1879                    disable_default_response: true,
1880                    seq: h.seq,
1881                    command: foundation::id::DEFAULT_RESPONSE,
1882                },
1883                payload: Global::DefaultResponse {
1884                    command: h.command,
1885                    status: zigbee_zcl::status::SUCCESS,
1886                }
1887                .encode(),
1888            };
1889            self.send_reply(source, aps, reply);
1890        }
1891    }
1892
1893    /// Answer a device reading the host's attributes: the Time cluster, for
1894    /// devices that set their clock from the coordinator; everything else
1895    /// is unsupported.
1896    fn answer_read(&self, source: NodeId, aps: Aps, seq: u8, ids: Vec<u16>) {
1897        use zigbee_zcl::attr::time;
1898        let records = ids
1899            .into_iter()
1900            .map(|attribute| {
1901                let value = match (aps.cluster, attribute) {
1902                    (zigbee_zcl::cluster_id::TIME, time::TIME) => Some(Value::Uint(
1903                        zigbee_zcl::DataType::UtcTime,
1904                        u64::from(zcl_time_now()),
1905                    )),
1906                    (zigbee_zcl::cluster_id::TIME, time::TIME_STATUS) => Some(Value::map8(0x03)),
1907                    (zigbee_zcl::cluster_id::TIME, time::TIME_ZONE) => {
1908                        Some(Value::Int(zigbee_zcl::DataType::Int32, 0))
1909                    }
1910                    (zigbee_zcl::cluster_id::TIME, time::LOCAL_TIME) => {
1911                        Some(Value::u32(zcl_time_now()))
1912                    }
1913                    _ => None,
1914                };
1915                match value {
1916                    Some(v) => ReadRecord {
1917                        attribute,
1918                        status: zigbee_zcl::status::SUCCESS,
1919                        value: Some(v),
1920                    },
1921                    None => ReadRecord {
1922                        attribute,
1923                        status: zigbee_zcl::status::UNSUPPORTED_ATTRIBUTE,
1924                        value: None,
1925                    },
1926                }
1927            })
1928            .collect();
1929        let mut reply = Frame::global(
1930            Direction::ServerToClient,
1931            seq,
1932            foundation::id::READ_ATTRIBUTES_RESPONSE,
1933            Global::ReadAttributesResponse(records).encode(),
1934        );
1935        reply.header.disable_default_response = true;
1936        self.send_reply(source, aps, reply);
1937    }
1938
1939    fn send_reply(&self, source: NodeId, aps: Aps, frame: Frame) {
1940        let host = self.clone();
1941        let reply_aps = Aps {
1942            profile: aps.profile,
1943            cluster: aps.cluster,
1944            source_endpoint: aps.destination_endpoint,
1945            destination_endpoint: aps.source_endpoint,
1946        };
1947        tokio::spawn(async move {
1948            if let Err(e) = host
1949                .inner
1950                .adapter
1951                .send_unicast(source, reply_aps, frame.encode())
1952                .await
1953            {
1954                tracing::debug!(error = %e, "sending a reply");
1955            }
1956        });
1957    }
1958
1959    pub(crate) fn emit_event(&self, event: HostEvent) {
1960        self.emit(event);
1961    }
1962
1963    pub(crate) fn config(&self) -> &HostConfig {
1964        &self.inner.config
1965    }
1966
1967    pub(crate) fn mark_backup_wanted(&self) {
1968        self.state().backup_wanted = true;
1969    }
1970
1971    pub(crate) fn used_zone_ids(&self) -> HashSet<u8> {
1972        self.state()
1973            .devices
1974            .values()
1975            .filter_map(|d| d.ias_zone_id)
1976            .collect()
1977    }
1978}