matter-kit 0.3.0

Matter (CSA smart-home standard) protocol implementation in Rust: no_std, no-alloc, executor-agnostic
Documentation
// Generated by `cargo xtask` from the CSA data model 1.6. Do not edit.
//
// Commissioner Control โ€” cluster 0x0751.
//
// Regenerate with `cargo xtask clusters --dm <checkout>/data_model/1.6`; `cargo xtask check`
// is the CI gate that keeps this file honest. The XML itself is not vendored here โ€” it
// carries the CSA's own copyright notice and is not redistributable.

//! Commissioner Control (cluster `0x0751`, revision 1).
//!
//! 5 identifiers, 0 feature bits, and the specification's own conformance for
//! every element. `CLUSTER` is the whole table.

#![allow(unused_imports)]

use crate::dm::conformance::{Clause, Condition, Conform, Conformance};
use crate::dm::meta::{EventPriority, Reporting};
use crate::dm::spec::{Attribute, Cluster, Command, Event, Feature};
use crate::dm::{Access, AccessQualities, AttributeQualities, Privilege};
use crate::error::Result;
use crate::im::{AttributeId, ClusterId, CommandId, EventId};
use crate::tlv::{
    ContainerKind, Element, FromTlv, Nullable, Tag, TlvList, TlvReader, TlvWriter, ToTlv, Value,
};

/// The cluster id.
pub const ID: ClusterId = 0x0751;

/// The highest revision the specification's history defines โ€” what `ClusterRevision`
/// must report (Core ยง7.13.1).
pub const REVISION: u16 = 1;

/// The PICS code, which a certification declaration names the cluster by.
pub const PICS: &str = "CCTRL";

/// This cluster defines no features, so its `FeatureMap` is always zero.
pub const FEATURES: &[Feature] = &[];

/// The attribute ids.
pub mod attribute {
    use crate::im::AttributeId;

    /// `SupportedDeviceCategories`.
    pub const SUPPORTED_DEVICE_CATEGORIES: AttributeId = 0x00;
}

/// The command ids.
pub mod command {
    use crate::im::CommandId;

    /// `RequestCommissioningApproval`.
    pub const REQUEST_COMMISSIONING_APPROVAL: CommandId = 0x00;
    /// `CommissionNode`.
    pub const COMMISSION_NODE: CommandId = 0x01;
    /// `ReverseOpenCommissioningWindow`.
    pub const REVERSE_OPEN_COMMISSIONING_WINDOW: CommandId = 0x02;
}

/// The event ids.
pub mod event {
    use crate::im::EventId;

    /// `CommissioningRequestResult`.
    pub const COMMISSIONING_REQUEST_RESULT: EventId = 0x00;
}

bitflags::bitflags! {
    /// `SupportedDeviceCategoryBitmap`.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct SupportedDeviceCategoryBitmap: u8 {
        /// Aggregators which support Fabric Synchronization may be commissioned.
        const FABRIC_SYNCHRONIZATION = 1 << 0;
    }
}

impl ToTlv for SupportedDeviceCategoryBitmap {
    fn to_tlv(&self, w: &mut TlvWriter<'_>, tag: Tag) -> Result<()> {
        self.bits().to_tlv(w, tag)
    }
}

impl<'a> FromTlv<'a> for SupportedDeviceCategoryBitmap {
    fn from_tlv(reader: &mut TlvReader<'a>, element: &Element<'a>) -> Result<Self> {
        let bits = <u8 as FromTlv<'a>>::from_tlv(reader, element)?;
        Self::from_bits(bits).ok_or(crate::Error::new(crate::ErrorCode::TlvOutOfRange))
    }
}

/// The fields of `RequestCommissioningApproval` (command `0x00`).
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct RequestCommissioningApprovalFields<'a> {
    /// `RequestID`, field 0.
    pub request_id: u64,
    /// `VendorID`, field 1.
    pub vendor_id: crate::msg::VendorId,
    /// `ProductID`, field 2.
    pub product_id: u16,
    /// `Label`, field 3.
    pub label: Option<&'a str>,
}

impl<'a> ToTlv for RequestCommissioningApprovalFields<'a> {
    fn to_tlv(&self, w: &mut TlvWriter<'_>, tag: Tag) -> Result<()> {
        w.start_structure(tag)?;
        self.request_id.to_tlv(w, Tag::Context(0))?;
        self.vendor_id.to_tlv(w, Tag::Context(1))?;
        self.product_id.to_tlv(w, Tag::Context(2))?;
        if let Some(value) = &self.label {
            value.to_tlv(w, Tag::Context(3))?;
        }
        w.end_container()
    }
}

impl<'a> FromTlv<'a> for RequestCommissioningApprovalFields<'a> {
    fn from_tlv(reader: &mut TlvReader<'a>, element: &Element<'a>) -> Result<Self> {
        if element.value.container() != Some(ContainerKind::Structure) {
            return Err(crate::Error::new(crate::ErrorCode::TlvWrongType));
        }
        let mut request_id = None;
        let mut vendor_id = None;
        let mut product_id = None;
        let mut label = None;
        loop {
            let Some(field) = reader.next_element()? else {
                return Err(crate::Error::new(crate::ErrorCode::TlvTruncated));
            };
            if field.value == Value::EndOfContainer {
                break;
            }
            match field.tag.context() {
                Some(0) => request_id = Some(<u64>::from_tlv(reader, &field)?),
                Some(1) => vendor_id = Some(<crate::msg::VendorId>::from_tlv(reader, &field)?),
                Some(2) => product_id = Some(<u16>::from_tlv(reader, &field)?),
                Some(3) => label = Some(<&'a str>::from_tlv(reader, &field)?),
                // A field this revision does not define. ยง7.19.2: a receiver
                // ignores what it does not know rather than refusing the whole
                // structure, which is what lets a newer peer talk to an older one.
                _ => reader.skip_value(&field)?,
            }
        }
        Ok(Self {
            request_id: request_id.ok_or(crate::Error::new(crate::ErrorCode::TlvNotFound))?,
            vendor_id: vendor_id.ok_or(crate::Error::new(crate::ErrorCode::TlvNotFound))?,
            product_id: product_id.ok_or(crate::Error::new(crate::ErrorCode::TlvNotFound))?,
            label,
        })
    }
}

/// The fields of `CommissionNode` (command `0x01`).
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct CommissionNodeFields {
    /// `RequestID`, field 0.
    pub request_id: u64,
    /// `ResponseTimeoutSeconds`, field 1.
    pub response_timeout_seconds: u16,
}

impl ToTlv for CommissionNodeFields {
    fn to_tlv(&self, w: &mut TlvWriter<'_>, tag: Tag) -> Result<()> {
        w.start_structure(tag)?;
        self.request_id.to_tlv(w, Tag::Context(0))?;
        self.response_timeout_seconds.to_tlv(w, Tag::Context(1))?;
        w.end_container()
    }
}

impl<'a> FromTlv<'a> for CommissionNodeFields {
    fn from_tlv(reader: &mut TlvReader<'a>, element: &Element<'a>) -> Result<Self> {
        if element.value.container() != Some(ContainerKind::Structure) {
            return Err(crate::Error::new(crate::ErrorCode::TlvWrongType));
        }
        let mut request_id = None;
        let mut response_timeout_seconds = None;
        loop {
            let Some(field) = reader.next_element()? else {
                return Err(crate::Error::new(crate::ErrorCode::TlvTruncated));
            };
            if field.value == Value::EndOfContainer {
                break;
            }
            match field.tag.context() {
                Some(0) => request_id = Some(<u64>::from_tlv(reader, &field)?),
                Some(1) => response_timeout_seconds = Some(<u16>::from_tlv(reader, &field)?),
                // A field this revision does not define. ยง7.19.2: a receiver
                // ignores what it does not know rather than refusing the whole
                // structure, which is what lets a newer peer talk to an older one.
                _ => reader.skip_value(&field)?,
            }
        }
        Ok(Self {
            request_id: request_id.ok_or(crate::Error::new(crate::ErrorCode::TlvNotFound))?,
            response_timeout_seconds: response_timeout_seconds
                .ok_or(crate::Error::new(crate::ErrorCode::TlvNotFound))?,
        })
    }
}

/// The fields of `ReverseOpenCommissioningWindow` (command `0x02`).
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct ReverseOpenCommissioningWindowFields<'a> {
    /// `CommissioningTimeout`, field 0.
    pub commissioning_timeout: u16,
    /// `PAKEPasscodeVerifier`, field 1.
    pub pake_passcode_verifier: &'a [u8],
    /// `Discriminator`, field 2.
    pub discriminator: u16,
    /// `Iterations`, field 3.
    pub iterations: u32,
    /// `Salt`, field 4.
    pub salt: &'a [u8],
}

impl<'a> ToTlv for ReverseOpenCommissioningWindowFields<'a> {
    fn to_tlv(&self, w: &mut TlvWriter<'_>, tag: Tag) -> Result<()> {
        w.start_structure(tag)?;
        self.commissioning_timeout.to_tlv(w, Tag::Context(0))?;
        self.pake_passcode_verifier.to_tlv(w, Tag::Context(1))?;
        self.discriminator.to_tlv(w, Tag::Context(2))?;
        self.iterations.to_tlv(w, Tag::Context(3))?;
        self.salt.to_tlv(w, Tag::Context(4))?;
        w.end_container()
    }
}

impl<'a> FromTlv<'a> for ReverseOpenCommissioningWindowFields<'a> {
    fn from_tlv(reader: &mut TlvReader<'a>, element: &Element<'a>) -> Result<Self> {
        if element.value.container() != Some(ContainerKind::Structure) {
            return Err(crate::Error::new(crate::ErrorCode::TlvWrongType));
        }
        let mut commissioning_timeout = None;
        let mut pake_passcode_verifier = None;
        let mut discriminator = None;
        let mut iterations = None;
        let mut salt = None;
        loop {
            let Some(field) = reader.next_element()? else {
                return Err(crate::Error::new(crate::ErrorCode::TlvTruncated));
            };
            if field.value == Value::EndOfContainer {
                break;
            }
            match field.tag.context() {
                Some(0) => commissioning_timeout = Some(<u16>::from_tlv(reader, &field)?),
                Some(1) => pake_passcode_verifier = Some(<&'a [u8]>::from_tlv(reader, &field)?),
                Some(2) => discriminator = Some(<u16>::from_tlv(reader, &field)?),
                Some(3) => iterations = Some(<u32>::from_tlv(reader, &field)?),
                Some(4) => salt = Some(<&'a [u8]>::from_tlv(reader, &field)?),
                // A field this revision does not define. ยง7.19.2: a receiver
                // ignores what it does not know rather than refusing the whole
                // structure, which is what lets a newer peer talk to an older one.
                _ => reader.skip_value(&field)?,
            }
        }
        Ok(Self {
            commissioning_timeout: commissioning_timeout
                .ok_or(crate::Error::new(crate::ErrorCode::TlvNotFound))?,
            pake_passcode_verifier: pake_passcode_verifier
                .ok_or(crate::Error::new(crate::ErrorCode::TlvNotFound))?,
            discriminator: discriminator.ok_or(crate::Error::new(crate::ErrorCode::TlvNotFound))?,
            iterations: iterations.ok_or(crate::Error::new(crate::ErrorCode::TlvNotFound))?,
            salt: salt.ok_or(crate::Error::new(crate::ErrorCode::TlvNotFound))?,
        })
    }
}

/// Every attribute the specification defines, with its conformance.
pub const ATTRIBUTES: &[Attribute] = &[Attribute {
    id: 0x0000,
    name: "SupportedDeviceCategories",
    kind: "SupportedDeviceCategoryBitmap",
    access: Access::read_only(Privilege::Manage),
    qualities: AttributeQualities::empty(),
    reporting: Reporting::OnChange,
    conform: Conform::MANDATORY,
}];

/// Every command, with its conformance.
pub const COMMANDS: &[Command] = &[
    Command {
        id: 0x00,
        name: "RequestCommissioningApproval",
        to_server: true,
        response: None,
        access: Access::invoke(Privilege::Manage),
        conform: Conform::MANDATORY,
    },
    Command {
        id: 0x01,
        name: "CommissionNode",
        to_server: true,
        response: Some(0x02),
        access: Access::invoke(Privilege::Manage),
        conform: Conform::MANDATORY,
    },
    Command {
        id: 0x02,
        name: "ReverseOpenCommissioningWindow",
        to_server: false,
        response: None,
        access: Access::invoke(Privilege::Operate),
        conform: Conform::MANDATORY,
    },
];

/// Every event, with its conformance.
pub const EVENTS: &[Event] = &[Event {
    id: 0x00,
    name: "CommissioningRequestResult",
    priority: EventPriority::Info,
    access: Access::read_only(Privilege::Manage).with_qualities(AccessQualities::FABRIC_SENSITIVE),
    conform: Conform::MANDATORY,
}];

/// The whole cluster, as the specification defines it.
pub const CLUSTER: Cluster = Cluster {
    id: ID,
    name: "Commissioner Control",
    revision: REVISION,
    pics: "CCTRL",
    derived_from: None,
    features: FEATURES,
    attributes: ATTRIBUTES,
    commands: COMMANDS,
    events: EVENTS,
};