Skip to main content

matter_controller/
onboarding.rs

1//! Onboarding payloads: the QR code (`MT:...`) and the manual pairing code a
2//! device carries, parsed with rs-matter's parsers.
3
4use rs_matter::pairing::qr::{CommFlowType, QrPayload};
5use rs_matter::pairing::DiscoveryCapabilities;
6use rs_matter::transport::network::mdns::CommissionableFilter;
7use serde::Serialize;
8
9use crate::Error;
10
11/// Which discriminator an onboarding payload carries.
12#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
13#[serde(rename_all = "snake_case")]
14pub enum Discriminator {
15    /// The full 12 bits, from a QR code.
16    Long(u16),
17    /// The upper 4 bits, from a manual pairing code.
18    Short(u8),
19}
20
21/// How a device can be found for commissioning, from its QR code.
22#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
23pub struct Capabilities {
24    /// Advertising over Bluetooth LE.
25    pub ble: bool,
26    /// Already on the IP network.
27    pub on_network: bool,
28    /// Running a Wi-Fi soft access point.
29    pub soft_ap: bool,
30}
31
32/// What an onboarding payload says about a device.
33#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
34pub struct Onboarding {
35    /// The setup passcode.
36    #[serde(skip)]
37    pub passcode: u32,
38    /// The discriminator.
39    pub discriminator: Discriminator,
40    /// Vendor id, if the payload has it.
41    pub vendor_id: Option<u16>,
42    /// Product id, if the payload has it.
43    pub product_id: Option<u16>,
44    /// How the device can be found; `None` for a manual code, which does not
45    /// say, so every way is tried.
46    pub capabilities: Option<Capabilities>,
47    /// Whether the device needs a custom or user-intent commissioning flow
48    /// (a button press, a vendor app) before it can be commissioned.
49    pub custom_flow: bool,
50}
51
52impl Onboarding {
53    /// Parse a QR code payload (`MT:...`) or an 11- or 21-digit manual code
54    /// (separators allowed).
55    pub fn parse(code: &str) -> Result<Self, Error> {
56        let code = code.trim();
57        if code.starts_with("MT:") {
58            let mut buf = [0u8; 256];
59            let qr = QrPayload::parse(code, &mut buf)
60                .map_err(|e| Error::Onboarding(format!("not a valid Matter QR code: {e:?}")))?;
61            let caps = qr.discovery_capabilities();
62            Ok(Self {
63                passcode: qr.passcode(),
64                discriminator: Discriminator::Long(qr.discriminator()),
65                vendor_id: Some(qr.vid()),
66                product_id: Some(qr.pid()),
67                capabilities: Some(Capabilities {
68                    ble: caps.contains(DiscoveryCapabilities::BLE),
69                    on_network: caps.contains(DiscoveryCapabilities::IP),
70                    soft_ap: caps.contains(DiscoveryCapabilities::SOFT_AP),
71                }),
72                custom_flow: !matches!(qr.comm_flow(), CommFlowType::Standard),
73            })
74        } else {
75            let manual = QrPayload::parse_pairing_code(code).map_err(|e| {
76                Error::Onboarding(format!("not a valid manual pairing code: {e:?}"))
77            })?;
78            let (vendor_id, product_id) = match manual.vid_pid() {
79                Some((v, p)) => (Some(v), Some(p)),
80                None => (None, None),
81            };
82            Ok(Self {
83                passcode: manual.passcode(),
84                discriminator: Discriminator::Short(manual.short_discriminator()),
85                vendor_id,
86                product_id,
87                capabilities: None,
88                custom_flow: !matches!(manual.comm_flow(), Some(CommFlowType::Standard) | None),
89            })
90        }
91    }
92
93    /// The mDNS filter that finds this device among commissionable nodes.
94    pub fn filter(&self) -> CommissionableFilter {
95        match self.discriminator {
96            Discriminator::Long(d) => CommissionableFilter {
97                discriminator: Some(d),
98                ..Default::default()
99            },
100            Discriminator::Short(d) => CommissionableFilter {
101                short_discriminator: Some(d),
102                ..Default::default()
103            },
104        }
105    }
106}
107
108#[cfg(test)]
109mod tests {
110    use super::*;
111
112    // The CSA's test device payloads (the C++ SDK's defaults: passcode
113    // 20202021, discriminator 3840, vendor 0xFFF1, product 0x8000).
114    #[test]
115    fn qr_code() {
116        let o = Onboarding::parse("MT:-24J0AFN00KA0648G00").unwrap();
117        assert_eq!(o.passcode, 20202021);
118        assert_eq!(o.discriminator, Discriminator::Long(3840));
119        assert_eq!(o.vendor_id, Some(0xFFF1));
120        assert!(o.capabilities.unwrap().on_network || o.capabilities.unwrap().ble);
121    }
122
123    #[test]
124    fn manual_code() {
125        let o = Onboarding::parse("3497-011-2332").unwrap();
126        assert_eq!(o.passcode, 20202021);
127        assert_eq!(o.discriminator, Discriminator::Short(15));
128        assert!(!o.custom_flow);
129        assert_eq!(o.filter().short_discriminator, Some(15));
130    }
131
132    #[test]
133    fn rejects_garbage() {
134        for code in ["", "MT:", "MT:!!!", "1234", "34970112333", "hello"] {
135            assert!(Onboarding::parse(code).is_err(), "{code}");
136        }
137    }
138}