Skip to main content

zwave_host/
interview.rs

1//! The interview: everything the host learns about a node after inclusion
2//! (and resumes after a restart).
3
4use crate::controller::{Controller, Inbound, TxSecurity};
5use crate::node::{InterviewStage, Manufacturer};
6use crate::{Error, Event, NodeId};
7use std::time::Duration;
8use tracing::{debug, info, warn};
9use zwave_cc::{
10    association, basic, battery, binary_sensor, binary_switch, manufacturer_specific, meter,
11    multi_channel, multilevel_sensor, multilevel_switch, notification, security, security_2,
12    version, wake_up, zwave_plus_info, Command,
13};
14use zwave_security::s2::KeyId;
15use zwave_security::SecurityClass;
16use zwave_serial::{DataFrame, FunctionId as F};
17
18/// Interview attempts before giving up until the next restart or wake-up.
19const MAX_ATTEMPTS: u32 = 5;
20
21impl Controller {
22    /// Starts (or resumes) a node's interview in the background, unless one is running.
23    pub fn spawn_interview(&self, node: NodeId) {
24        if !self.inner.interviews.lock().expect("lock").insert(node) {
25            return;
26        }
27        let c = self.clone();
28        tokio::spawn(async move {
29            let mut attempt = 0;
30            loop {
31                attempt += 1;
32                match c.interview(node).await {
33                    Ok(()) => {
34                        info!(node, "interview complete");
35                        c.emit(Event::InterviewCompleted { node });
36                        break;
37                    }
38                    Err(Error::UnknownNode(_)) => break,
39                    Err(e) => {
40                        warn!(node, attempt, "interview failed: {e}");
41                        c.emit(Event::InterviewFailed {
42                            node,
43                            reason: e.to_string(),
44                        });
45                        if attempt >= MAX_ATTEMPTS {
46                            break;
47                        }
48                        tokio::time::sleep(Duration::from_secs(10 * u64::from(attempt))).await;
49                    }
50                }
51            }
52            c.inner.interviews.lock().expect("lock").remove(&node);
53        });
54    }
55
56    /// Re-runs a node's interview from the start.
57    pub fn reinterview(&self, node: NodeId) -> Result<(), Error> {
58        self.update_node(node, |r| {
59            r.stage = InterviewStage::ProtocolInfo;
60            r.secure_ccs_known = false;
61        })?;
62        self.spawn_interview(node);
63        Ok(())
64    }
65
66    fn stage(&self, node: NodeId) -> Result<InterviewStage, Error> {
67        self.with_node(node, |r| r.stage)
68            .ok_or(Error::UnknownNode(node))
69    }
70
71    fn reach(&self, node: NodeId, stage: InterviewStage) -> Result<(), Error> {
72        self.update_node(node, |r| {
73            if r.stage < stage {
74                r.stage = stage;
75            }
76        })?;
77        self.emit(Event::InterviewStage { node, stage });
78        Ok(())
79    }
80
81    async fn interview(&self, node: NodeId) -> Result<(), Error> {
82        if self.stage(node)? < InterviewStage::ProtocolInfo {
83            self.fetch_protocol_info(node).await?;
84            self.reach(node, InterviewStage::ProtocolInfo)?;
85        }
86        if self.stage(node)? < InterviewStage::NodeInfo {
87            self.request_node_info(node).await?;
88            self.reach(node, InterviewStage::NodeInfo)?;
89        }
90        if self.stage(node)? < InterviewStage::Security {
91            self.interview_security(node).await?;
92            self.reach(node, InterviewStage::Security)?;
93        }
94        if self.stage(node)? < InterviewStage::Identity {
95            self.interview_identity(node).await;
96            self.reach(node, InterviewStage::Identity)?;
97        }
98        if self.stage(node)? < InterviewStage::Versions {
99            self.interview_versions(node).await;
100            self.reach(node, InterviewStage::Versions)?;
101        }
102        if self.stage(node)? < InterviewStage::Endpoints {
103            self.interview_endpoints(node).await;
104            self.reach(node, InterviewStage::Endpoints)?;
105        }
106        if self.stage(node)? < InterviewStage::CommandClasses {
107            let eps: Vec<u8> = self
108                .with_node(node, |r| r.endpoints.keys().copied().collect())
109                .unwrap_or_default();
110            for ep in eps {
111                self.interview_endpoint(node, ep).await;
112            }
113            self.configure_wake_up(node).await;
114            self.configure_lifeline(node).await;
115            self.reach(node, InterviewStage::CommandClasses)?;
116        }
117        if let Err(e) = self.refresh_neighbors(node).await {
118            debug!(node, "neighbors: {e}");
119        }
120        self.reach(node, InterviewStage::Complete)?;
121        Ok(())
122    }
123
124    async fn request_node_info(&self, node: NodeId) -> Result<(), Error> {
125        let _a = self.activity(node);
126        self.wait_awake(node).await;
127        let (_g, rx) = self.wait_for(node, false, |i| {
128            matches!(i, Inbound::NodeInfo(_) | Inbound::NodeInfoFailed)
129        });
130        let r = self
131            .inner
132            .api
133            .request(
134                DataFrame::request(F::REQUEST_NODE_INFO, self.node_payload(node)),
135                Duration::from_secs(2),
136            )
137            .await?;
138        if r.payload.first() != Some(&1) {
139            return Err(Error::Controller("Request Node Info refused".into()));
140        }
141        match tokio::time::timeout(self.inner.cfg.request_timeout * 2, rx).await {
142            Ok(Ok(Inbound::NodeInfo(info))) => {
143                self.update_node(node, |r| {
144                    for cc in info.supported {
145                        r.root_mut().ccs.entry(cc).or_default();
146                    }
147                })?;
148                Ok(())
149            }
150            Ok(_) => Err(Error::Timeout(node)),
151            Err(_) => Err(Error::Timeout(node)),
152        }
153    }
154
155    async fn interview_security(&self, node: NodeId) -> Result<(), Error> {
156        let Some((s2, s0)) = self.with_node(node, |r| (r.highest_s2(), r.s0_only())) else {
157            return Err(Error::UnknownNode(node));
158        };
159        let _a = self.activity(node);
160        self.wait_awake(node).await;
161        let secure: Option<Vec<u16>> = if let Some(class) = s2 {
162            let (c, _) = self
163                .request_secured(
164                    node,
165                    Command::from(security_2::CommandsSupportedGet {}).encode(),
166                    TxSecurity::S2(KeyId::Class(class)),
167                    self.inner.cfg.request_timeout,
168                    |c, _| {
169                        matches!(
170                            c,
171                            Command::Security2(security_2::Command::CommandsSupportedReport(_))
172                        )
173                    },
174                )
175                .await?;
176            let Command::Security2(security_2::Command::CommandsSupportedReport(r)) = c else {
177                unreachable!()
178            };
179            Some(r.command_classes)
180        } else if s0 {
181            let (c, _) = self
182                .request_secured(
183                    node,
184                    Command::from(security::CommandsSupportedGet {}).encode(),
185                    TxSecurity::S0 { temp: false },
186                    self.inner.cfg.request_timeout,
187                    |c, _| {
188                        matches!(
189                            c,
190                            Command::Security(security::Command::CommandsSupportedReport(_))
191                        )
192                    },
193                )
194                .await?;
195            let Command::Security(security::Command::CommandsSupportedReport(r)) = c else {
196                unreachable!()
197            };
198            Some(r.command_classes)
199        } else {
200            None
201        };
202        self.update_node(node, |r| {
203            if let Some(list) = &secure {
204                for cc in list {
205                    r.root_mut().ccs.entry(*cc).or_default().secure = true;
206                }
207            }
208            r.secure_ccs_known = true;
209        })
210    }
211
212    async fn interview_identity(&self, node: NodeId) {
213        let supports = |cc| {
214            self.with_node(node, |r| r.root().supports(cc))
215                .unwrap_or(false)
216        };
217        if supports(manufacturer_specific::ID) {
218            let r = self
219                .req(node, 0, manufacturer_specific::Get {}, |c| match c {
220                    Command::ManufacturerSpecific(manufacturer_specific::Command::Report(r)) => {
221                        Some(r.clone())
222                    }
223                    _ => None,
224                })
225                .await;
226            match r {
227                Ok(m) => {
228                    let _ = self.update_node(node, |r| {
229                        r.manufacturer = Some(Manufacturer {
230                            manufacturer_id: m.manufacturer_id,
231                            product_type: m.product_type,
232                            product_id: m.product_id,
233                        })
234                    });
235                }
236                Err(e) => warn!(node, "manufacturer: {e}"),
237            }
238        }
239        if supports(zwave_plus_info::ID) {
240            let r = self
241                .req(node, 0, zwave_plus_info::Get {}, |c| match c {
242                    Command::ZwavePlusInfo(zwave_plus_info::Command::Report(r)) => Some(r.clone()),
243                    _ => None,
244                })
245                .await;
246            match r {
247                Ok(z) => {
248                    let _ = self.update_node(node, |r| {
249                        r.zwave_plus =
250                            Some((z.role_type, z.node_type, z.installer_icon, z.user_icon))
251                    });
252                }
253                Err(e) => warn!(node, "Z-Wave Plus info: {e}"),
254            }
255        }
256    }
257
258    async fn interview_versions(&self, node: NodeId) {
259        let Some(ccs) = self.with_node(node, |r| r.root().ccs.keys().copied().collect::<Vec<_>>())
260        else {
261            return;
262        };
263        if !ccs.contains(&version::ID) {
264            return;
265        }
266        let r = self
267            .req(node, 0, version::Get {}, |c| match c {
268                Command::Version(version::Command::Report(r)) => Some(r.clone()),
269                _ => None,
270            })
271            .await;
272        if let Ok(v) = &r {
273            let _ = self.update_node(node, |r| {
274                r.firmware = Some(format!("{}.{}", v.firmware_version, v.firmware_sub_version))
275            });
276        }
277        for cc in ccs.into_iter().filter(|&c| c <= 0xff) {
278            let r = self
279                .req(
280                    node,
281                    0,
282                    version::CommandClassGet {
283                        requested_cc: cc as u8,
284                    },
285                    move |c| match c {
286                        Command::Version(version::Command::CommandClassReport(r))
287                            if u16::from(r.requested_cc) == cc =>
288                        {
289                            Some(r.version)
290                        }
291                        _ => None,
292                    },
293                )
294                .await;
295            match r {
296                Ok(v) => {
297                    let _ = self.update_node(node, |r| {
298                        if v == 0 {
299                            // Version 0: not actually supported.
300                            r.root_mut().ccs.remove(&cc);
301                        } else if let Some(s) = r.root_mut().ccs.get_mut(&cc) {
302                            s.version = v;
303                        }
304                    });
305                }
306                Err(e) => debug!(node, cc, "version: {e}"),
307            }
308        }
309    }
310
311    async fn interview_endpoints(&self, node: NodeId) {
312        if !self
313            .with_node(node, |r| r.root().supports(multi_channel::ID))
314            .unwrap_or(false)
315        {
316            return;
317        }
318        let r = self
319            .req(node, 0, multi_channel::EndPointGet {}, |c| match c {
320                Command::MultiChannel(multi_channel::Command::EndPointReport(r)) => {
321                    Some(r.individual_end_points)
322                }
323                _ => None,
324            })
325            .await;
326        let Ok(count) = r else { return };
327        for ep in 1..=count.min(127) {
328            let r = self
329                .req(
330                    node,
331                    0,
332                    multi_channel::CapabilityGet { end_point: ep },
333                    move |c| match c {
334                        Command::MultiChannel(multi_channel::Command::CapabilityReport(r))
335                            if r.end_point == ep =>
336                        {
337                            Some(r.clone())
338                        }
339                        _ => None,
340                    },
341                )
342                .await;
343            match r {
344                Ok(cap) => {
345                    let _ = self.update_node(node, |r| {
346                        let versions: Vec<(u16, crate::node::CcSupport)> =
347                            r.root().ccs.iter().map(|(k, v)| (*k, *v)).collect();
348                        let e = r.endpoints.entry(ep).or_default();
349                        e.generic = cap.generic;
350                        e.specific = cap.specific;
351                        for cc in cap.command_classes {
352                            let root = versions
353                                .iter()
354                                .find(|(k, _)| *k == cc)
355                                .map(|(_, v)| *v)
356                                .unwrap_or_default();
357                            e.ccs.insert(cc, root);
358                        }
359                    });
360                }
361                Err(e) => warn!(node, ep, "endpoint capability: {e}"),
362            }
363        }
364    }
365
366    async fn interview_endpoint(&self, node: NodeId, ep: u8) {
367        let Some(e) = self
368            .with_node(node, |r| r.endpoints.get(&ep).cloned())
369            .flatten()
370        else {
371            return;
372        };
373        let has = |cc| e.supports(cc);
374        if has(multilevel_sensor::ID) {
375            if e.version(multilevel_sensor::ID) >= 5 {
376                let types = self
377                    .req(
378                        node,
379                        ep,
380                        multilevel_sensor::SupportedSensorGet {},
381                        |c| match c {
382                            Command::MultilevelSensor(
383                                multilevel_sensor::Command::SupportedSensorReport(r),
384                            ) => Some(r.sensor_types.clone()),
385                            _ => None,
386                        },
387                    )
388                    .await
389                    .unwrap_or_default();
390                for t in types.into_iter().filter_map(|t| u8::try_from(t).ok()) {
391                    let scales = self
392                        .req(
393                            node,
394                            ep,
395                            multilevel_sensor::SupportedScaleGet { sensor_type: t },
396                            move |c| match c {
397                                Command::MultilevelSensor(
398                                    multilevel_sensor::Command::SupportedScaleReport(r),
399                                ) if r.sensor_type == t => Some(r.scales),
400                                _ => None,
401                            },
402                        )
403                        .await
404                        .unwrap_or(1);
405                    let list: Vec<u8> = (0..4).filter(|b| scales & (1 << b) != 0).collect();
406                    let first = list.first().copied().unwrap_or(0);
407                    let _ = self.update_node(node, |r| {
408                        r.endpoints
409                            .entry(ep)
410                            .or_default()
411                            .caps
412                            .sensors
413                            .insert(t, list.clone());
414                    });
415                    let _ = self
416                        .req(node, ep, multilevel_sensor::Get { sensor_type: Some(t), scale: Some(first) }, move |c| {
417                            matches!(c, Command::MultilevelSensor(multilevel_sensor::Command::Report(r)) if r.sensor_type == t).then_some(())
418                        })
419                        .await;
420                }
421            } else {
422                let r = self
423                    .req(
424                        node,
425                        ep,
426                        multilevel_sensor::Get {
427                            sensor_type: None,
428                            scale: None,
429                        },
430                        |c| match c {
431                            Command::MultilevelSensor(multilevel_sensor::Command::Report(r)) => {
432                                Some((r.sensor_type, r.value.scale))
433                            }
434                            _ => None,
435                        },
436                    )
437                    .await;
438                if let Ok((t, s)) = r {
439                    let _ = self.update_node(node, |r| {
440                        r.endpoints
441                            .entry(ep)
442                            .or_default()
443                            .caps
444                            .sensors
445                            .insert(t, vec![s]);
446                    });
447                }
448            }
449        }
450        if has(meter::ID) {
451            let v = e.version(meter::ID);
452            let scales: Vec<u8> = if v >= 2 {
453                match self
454                    .req(node, ep, meter::SupportedGet {}, |c| match c {
455                        Command::Meter(meter::Command::SupportedReport(r)) => Some(r.clone()),
456                        _ => None,
457                    })
458                    .await
459                {
460                    Ok(s) => {
461                        let list: Vec<u8> = (0..7).filter(|b| s.scales & (1 << b) != 0).collect();
462                        let _ = self.update_node(node, |r| {
463                            r.endpoints.entry(ep).or_default().caps.meter =
464                                Some((s.meter_type, list.clone()))
465                        });
466                        list
467                    }
468                    Err(_) => vec![],
469                }
470            } else {
471                vec![0]
472            };
473            for s in scales {
474                let get = if v >= 2 {
475                    meter::Get {
476                        rate_type: Some(if v >= 4 { 1 } else { 0 }),
477                        scale: Some(s),
478                        scale2: None,
479                    }
480                } else {
481                    meter::Get::default()
482                };
483                let _ = self
484                    .req(node, ep, get, |c| {
485                        matches!(c, Command::Meter(meter::Command::Report(_))).then_some(())
486                    })
487                    .await;
488            }
489        }
490        if has(notification::ID) && e.version(notification::ID) >= 3 {
491            let types = self
492                .req(node, ep, notification::SupportedGet {}, |c| match c {
493                    Command::Notification(notification::Command::SupportedReport(r)) => {
494                        Some(r.types.clone())
495                    }
496                    _ => None,
497                })
498                .await
499                .unwrap_or_default();
500            for t in types
501                .into_iter()
502                .filter_map(|t| u8::try_from(t).ok())
503                .filter(|&t| t > 0)
504            {
505                let events = self
506                    .req(
507                        node,
508                        ep,
509                        notification::EventSupportedGet {
510                            notification_type: t,
511                        },
512                        move |c| match c {
513                            Command::Notification(notification::Command::EventSupportedReport(
514                                r,
515                            )) if r.notification_type == t => Some(r.events.clone()),
516                            _ => None,
517                        },
518                    )
519                    .await
520                    .unwrap_or_default();
521                let events: Vec<u8> = events
522                    .into_iter()
523                    .filter_map(|e| u8::try_from(e).ok())
524                    .collect();
525                let _ = self.update_node(node, |r| {
526                    r.endpoints
527                        .entry(ep)
528                        .or_default()
529                        .caps
530                        .notifications
531                        .insert(t, events.clone());
532                });
533            }
534        }
535        if has(binary_sensor::ID) {
536            let types: Vec<u8> = if e.version(binary_sensor::ID) >= 2 {
537                self.req(node, ep, binary_sensor::SupportedGet {}, |c| match c {
538                    Command::BinarySensor(binary_sensor::Command::SupportedReport(r)) => {
539                        Some(r.sensor_types.clone())
540                    }
541                    _ => None,
542                })
543                .await
544                .unwrap_or_default()
545                .into_iter()
546                .filter_map(|t| u8::try_from(t).ok())
547                .filter(|&t| t > 0)
548                .collect()
549            } else {
550                vec![]
551            };
552            let _ = self.update_node(node, |r| {
553                r.endpoints.entry(ep).or_default().caps.binary_sensors = types.clone()
554            });
555            if types.is_empty() {
556                let _ = self
557                    .req(node, ep, binary_sensor::Get { sensor_type: None }, |c| {
558                        matches!(c, Command::BinarySensor(binary_sensor::Command::Report(_)))
559                            .then_some(())
560                    })
561                    .await;
562            }
563            for t in types {
564                let _ = self
565                    .req(
566                        node,
567                        ep,
568                        binary_sensor::Get {
569                            sensor_type: Some(t),
570                        },
571                        |c| {
572                            matches!(c, Command::BinarySensor(binary_sensor::Command::Report(_)))
573                                .then_some(())
574                        },
575                    )
576                    .await;
577            }
578        }
579        if has(multilevel_switch::ID) {
580            if e.version(multilevel_switch::ID) >= 3 {
581                if let Ok(t) = self
582                    .req(node, ep, multilevel_switch::SupportedGet {}, |c| match c {
583                        Command::MultilevelSwitch(multilevel_switch::Command::SupportedReport(
584                            r,
585                        )) => Some(r.primary_switch_type),
586                        _ => None,
587                    })
588                    .await
589                {
590                    let _ = self.update_node(node, |r| {
591                        r.endpoints.entry(ep).or_default().caps.switch_type = Some(t)
592                    });
593                }
594            }
595            let _ = self
596                .req(node, ep, multilevel_switch::Get {}, |c| {
597                    matches!(
598                        c,
599                        Command::MultilevelSwitch(multilevel_switch::Command::Report(_))
600                    )
601                    .then_some(())
602                })
603                .await;
604        }
605        if has(binary_switch::ID) {
606            let _ = self
607                .req(node, ep, binary_switch::Get {}, |c| {
608                    matches!(c, Command::BinarySwitch(binary_switch::Command::Report(_)))
609                        .then_some(())
610                })
611                .await;
612        }
613        let actuator_or_sensor = [
614            binary_switch::ID,
615            multilevel_switch::ID,
616            multilevel_sensor::ID,
617            binary_sensor::ID,
618            notification::ID,
619            meter::ID,
620        ]
621        .iter()
622        .any(|&c| has(c));
623        if has(basic::ID) && !actuator_or_sensor {
624            let _ = self
625                .req(node, ep, basic::Get {}, |c| {
626                    matches!(c, Command::Basic(basic::Command::Report(_))).then_some(())
627                })
628                .await;
629        }
630        if ep == 0 && has(battery::ID) {
631            let _ = self
632                .req(node, 0, battery::Get {}, |c| {
633                    matches!(c, Command::Battery(battery::Command::Report(_))).then_some(())
634                })
635                .await;
636        }
637    }
638
639    async fn configure_wake_up(&self, node: NodeId) {
640        let Some((has, v)) = self.with_node(node, |r| {
641            (
642                r.root().supports(wake_up::ID),
643                r.root().version(wake_up::ID),
644            )
645        }) else {
646            return;
647        };
648        if !has {
649            return;
650        }
651        let mut want = self.inner.cfg.wake_up_interval;
652        if v >= 2 {
653            if let Ok(c) = self
654                .req(node, 0, wake_up::IntervalCapabilitiesGet {}, |c| match c {
655                    Command::WakeUp(wake_up::Command::IntervalCapabilitiesReport(r)) => {
656                        Some(r.clone())
657                    }
658                    _ => None,
659                })
660                .await
661            {
662                want = want.clamp(c.minimum, c.maximum.max(c.minimum));
663                if let Some(steps) = (want - c.minimum).checked_div(c.step) {
664                    want = c.minimum + steps * c.step;
665                }
666            }
667        }
668        let own = self.info().node_id as u8;
669        if let Err(e) = self
670            .send(
671                node,
672                0,
673                &wake_up::IntervalSet {
674                    seconds: want,
675                    node_id: own,
676                }
677                .into(),
678            )
679            .await
680        {
681            warn!(node, "wake-up interval: {e}");
682            return;
683        }
684        if let Ok(r) = self
685            .req(node, 0, wake_up::IntervalGet {}, |c| match c {
686                Command::WakeUp(wake_up::Command::IntervalReport(r)) => Some(r.clone()),
687                _ => None,
688            })
689            .await
690        {
691            let _ = self.update_node(node, |rec| rec.wake_up_interval = Some(r.seconds));
692        }
693    }
694
695    async fn configure_lifeline(&self, node: NodeId) {
696        if !self
697            .with_node(node, |r| r.root().supports(association::ID))
698            .unwrap_or(false)
699        {
700            return;
701        }
702        let groups = self
703            .req(node, 0, association::GroupingsGet {}, |c| match c {
704                Command::Association(association::Command::GroupingsReport(r)) => Some(r.groups),
705                _ => None,
706            })
707            .await
708            .unwrap_or(0);
709        if groups == 0 {
710            return;
711        }
712        let own = self.info().node_id as u8;
713        if let Err(e) = self
714            .send(
715                node,
716                0,
717                &association::Set {
718                    group: 1,
719                    nodes: vec![own],
720                }
721                .into(),
722            )
723            .await
724        {
725            warn!(node, "lifeline: {e}");
726        }
727    }
728
729    /// The classes a node was granted, for callers that need them.
730    pub fn security_classes(&self, node: NodeId) -> Vec<SecurityClass> {
731        self.with_node(node, |r| r.security.clone())
732            .unwrap_or_default()
733    }
734}