use core::cell::RefCell;
use core::marker::PhantomData;
use crate::config::Config;
use crate::crypto::{SYMMETRIC_KEY_LENGTH_BYTES, SymmetricKey, ct_eq};
use crate::dm::spec::{Conforming, Optional};
use crate::dm::{Privilege, Resolved, ResolvedCommand};
use crate::im::{
AttributeId, ClusterHandler, ClusterId, CommandId, InteractionContext, Status, StatusIb,
};
use crate::msg::{FabricIndex, NodeId};
use crate::tlv::{ContainerKind, Tag, TlvReader, TlvWriter, Value};
use super::Cluster;
pub const ID: ClusterId = 0x0046;
pub const REVISION: u16 = 3;
pub const IDLE_MODE_DURATION: AttributeId = 0x0000;
pub const ACTIVE_MODE_DURATION: AttributeId = 0x0001;
pub const ACTIVE_MODE_THRESHOLD: AttributeId = 0x0002;
pub const REGISTERED_CLIENTS: AttributeId = 0x0003;
pub const ICD_COUNTER: AttributeId = 0x0004;
pub const CLIENTS_SUPPORTED_PER_FABRIC: AttributeId = 0x0005;
pub const USER_ACTIVE_MODE_TRIGGER_HINT: AttributeId = 0x0006;
pub const USER_ACTIVE_MODE_TRIGGER_INSTRUCTION: AttributeId = 0x0007;
pub const OPERATING_MODE: AttributeId = 0x0008;
pub const MAXIMUM_CHECK_IN_BACKOFF: AttributeId = 0x0009;
pub const REGISTER_CLIENT: CommandId = 0x00;
pub const REGISTER_CLIENT_RESPONSE: CommandId = 0x01;
pub const UNREGISTER_CLIENT: CommandId = 0x02;
pub const STAY_ACTIVE_REQUEST: CommandId = 0x03;
pub const STAY_ACTIVE_RESPONSE: CommandId = 0x04;
pub const FABRIC_INDEX_FIELD: u8 = 254;
pub const IDLE_MODE_DURATION_MAX: u32 = 64_800;
bitflags::bitflags! {
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub struct UserActiveModeTrigger: u32 {
const POWER_CYCLE = 1 << 0;
const SETTINGS_MENU = 1 << 1;
const CUSTOM_INSTRUCTION = 1 << 2;
const DEVICE_MANUAL = 1 << 3;
const ACTUATE_SENSOR = 1 << 4;
const ACTUATE_SENSOR_SECONDS = 1 << 5;
const ACTUATE_SENSOR_TIMES = 1 << 6;
const ACTUATE_SENSOR_LIGHTS_BLINK = 1 << 7;
const RESET_BUTTON = 1 << 8;
const RESET_BUTTON_LIGHTS_BLINK = 1 << 9;
const RESET_BUTTON_SECONDS = 1 << 10;
const RESET_BUTTON_TIMES = 1 << 11;
const SETUP_BUTTON = 1 << 12;
const SETUP_BUTTON_SECONDS = 1 << 13;
const SETUP_BUTTON_LIGHTS_BLINK = 1 << 14;
const SETUP_BUTTON_TIMES = 1 << 15;
const APP_DEFINED_BUTTON = 1 << 16;
}
}
impl UserActiveModeTrigger {
pub const REQUIRE_INSTRUCTION: Self = Self::from_bits_truncate(
Self::CUSTOM_INSTRUCTION.bits()
| Self::ACTUATE_SENSOR_SECONDS.bits()
| Self::ACTUATE_SENSOR_TIMES.bits()
| Self::RESET_BUTTON_SECONDS.bits()
| Self::RESET_BUTTON_TIMES.bits()
| Self::SETUP_BUTTON_SECONDS.bits()
| Self::SETUP_BUTTON_TIMES.bits()
| Self::APP_DEFINED_BUTTON.bits(),
);
#[must_use]
pub const fn needs_instruction(self) -> bool {
self.intersects(Self::REQUIRE_INSTRUCTION)
}
}
bitflags::bitflags! {
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub struct Feature: u32 {
const CHECK_IN_PROTOCOL_SUPPORT = 1 << 0;
const USER_ACTIVE_MODE_TRIGGER = 1 << 1;
const LONG_IDLE_TIME_SUPPORT = 1 << 2;
const DYNAMIC_SIT_LIT_SUPPORT = 1 << 3;
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
#[repr(u8)]
pub enum ClientType {
#[default]
Permanent = 0,
Ephemeral = 1,
}
impl ClientType {
pub const fn from_value(value: u64) -> Result<Self, Status> {
match value {
0 => Ok(Self::Permanent),
1 => Ok(Self::Ephemeral),
_ => Err(Status::ConstraintError),
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
#[repr(u8)]
pub enum OperatingMode {
#[default]
Sit = 0,
Lit = 1,
}
#[derive(Debug, Clone)]
pub struct Registration {
pub check_in_node_id: NodeId,
pub monitored_subject: u64,
pub client_type: ClientType,
pub fabric_index: FabricIndex,
key: SymmetricKey,
}
const CAT_PREFIX: u64 = 0xFFFF_FFFD_0000_0000;
const CAT_MASK: u64 = 0xFFFF_FFFF_0000_0000;
impl Registration {
#[must_use]
pub const fn new(
check_in_node_id: NodeId,
monitored_subject: u64,
client_type: ClientType,
fabric_index: FabricIndex,
key: SymmetricKey,
) -> Self {
Self {
check_in_node_id,
monitored_subject,
client_type,
fabric_index,
key,
}
}
#[must_use]
pub const fn key(&self) -> &SymmetricKey {
&self.key
}
#[must_use]
#[expect(
clippy::cast_possible_truncation,
reason = "§9.16.5.2's monitored subject is matched against a CAT, which is 32 bits (§6.5.6.3)"
)]
pub fn matches_subscriber(&self, node: NodeId, cats: &[u32]) -> bool {
if self.monitored_subject & CAT_MASK != CAT_PREFIX {
return self.monitored_subject == node.0;
}
let wanted = self.monitored_subject as u32;
let (wanted_tag, wanted_version) = (wanted >> 16, wanted & 0xFFFF);
cats.iter().any(|&cat| {
let (tag, version) = (cat >> 16, cat & 0xFFFF);
tag == wanted_tag && version >= wanted_version
})
}
fn encode(&self, w: &mut TlvWriter<'_>) -> crate::error::Result<()> {
w.start_structure(Tag::Anonymous)?;
w.unsigned(Tag::Context(1), self.check_in_node_id.0)?;
w.unsigned(Tag::Context(2), self.monitored_subject)?;
w.unsigned(Tag::Context(4), self.client_type as u64)?;
w.unsigned(
Tag::Context(FABRIC_INDEX_FIELD),
u64::from(self.fabric_index.0),
)?;
w.end_container()
}
}
#[derive(Debug, Clone)]
struct RegisterFields {
check_in_node_id: NodeId,
monitored_subject: u64,
key: SymmetricKey,
verification_key: Option<SymmetricKey>,
client_type: ClientType,
}
fn key_field(bytes: &[u8]) -> Result<SymmetricKey, Status> {
if bytes.len() != SYMMETRIC_KEY_LENGTH_BYTES {
return Err(Status::ConstraintError);
}
SymmetricKey::from_slice(bytes).map_err(|_| Status::ConstraintError)
}
fn decode_register(fields: &[u8]) -> Result<RegisterFields, Status> {
let mut reader = TlvReader::new_in(fields, ContainerKind::Structure);
let element = reader
.next_element()
.map_err(|_| Status::InvalidAction)?
.ok_or(Status::InvalidAction)?;
if element.value.container() != Some(ContainerKind::Structure) {
return Err(Status::InvalidAction);
}
let mut check_in_node_id = None;
let mut monitored_subject = None;
let mut key = None;
let mut verification_key = None;
let mut client_type = None;
loop {
let Some(field) = reader.next_element().map_err(|_| Status::InvalidAction)? else {
return Err(Status::InvalidAction);
};
if field.value == Value::EndOfContainer {
break;
}
match field.tag.context() {
Some(0) => {
check_in_node_id = Some(NodeId(
field.unsigned().map_err(|_| Status::ConstraintError)?,
));
}
Some(1) => {
monitored_subject = Some(field.unsigned().map_err(|_| Status::ConstraintError)?);
}
Some(2) => {
key = Some(key_field(
field.octets().map_err(|_| Status::ConstraintError)?,
)?);
}
Some(3) => {
verification_key = Some(key_field(
field.octets().map_err(|_| Status::ConstraintError)?,
)?);
}
Some(4) => {
client_type = Some(ClientType::from_value(
field.unsigned().map_err(|_| Status::ConstraintError)?,
)?);
}
_ => {
reader
.skip_value(&field)
.map_err(|_| Status::InvalidAction)?;
}
}
}
let (Some(check_in_node_id), Some(monitored_subject), Some(key), Some(client_type)) =
(check_in_node_id, monitored_subject, key, client_type)
else {
return Err(Status::InvalidCommand);
};
Ok(RegisterFields {
check_in_node_id,
monitored_subject,
key,
verification_key,
client_type,
})
}
fn decode_unregister(fields: &[u8]) -> Result<(NodeId, Option<SymmetricKey>), Status> {
let mut reader = TlvReader::new_in(fields, ContainerKind::Structure);
let element = reader
.next_element()
.map_err(|_| Status::InvalidAction)?
.ok_or(Status::InvalidAction)?;
if element.value.container() != Some(ContainerKind::Structure) {
return Err(Status::InvalidAction);
}
let mut node = None;
let mut verification_key = None;
loop {
let Some(field) = reader.next_element().map_err(|_| Status::InvalidAction)? else {
return Err(Status::InvalidAction);
};
if field.value == Value::EndOfContainer {
break;
}
match field.tag.context() {
Some(0) => {
node = Some(NodeId(
field.unsigned().map_err(|_| Status::ConstraintError)?,
))
}
Some(1) => {
verification_key = Some(key_field(
field.octets().map_err(|_| Status::ConstraintError)?,
)?);
}
_ => {
reader
.skip_value(&field)
.map_err(|_| Status::InvalidAction)?;
}
}
}
node.map(|n| (n, verification_key))
.ok_or(Status::InvalidCommand)
}
fn decode_stay_active(fields: &[u8]) -> Result<u32, Status> {
let mut reader = TlvReader::new_in(fields, ContainerKind::Structure);
let element = reader
.next_element()
.map_err(|_| Status::InvalidAction)?
.ok_or(Status::InvalidAction)?;
if element.value.container() != Some(ContainerKind::Structure) {
return Err(Status::InvalidAction);
}
let mut duration = None;
loop {
let Some(field) = reader.next_element().map_err(|_| Status::InvalidAction)? else {
return Err(Status::InvalidAction);
};
if field.value == Value::EndOfContainer {
break;
}
if field.tag.context() == Some(0) {
duration = Some(
u32::try_from(field.unsigned().map_err(|_| Status::ConstraintError)?)
.map_err(|_| Status::ConstraintError)?,
);
} else {
reader
.skip_value(&field)
.map_err(|_| Status::InvalidAction)?;
}
}
duration.ok_or(Status::InvalidCommand)
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Timings {
pub idle_mode_duration: u32,
pub active_mode_duration: u32,
pub active_mode_threshold: u16,
pub maximum_check_in_backoff: u32,
}
impl Default for Timings {
fn default() -> Self {
Self {
idle_mode_duration: 1,
active_mode_duration: 300,
active_mode_threshold: 300,
maximum_check_in_backoff: 1,
}
}
}
impl Timings {
#[must_use]
pub const fn is_valid(&self) -> bool {
if self.idle_mode_duration == 0 || self.idle_mode_duration > IDLE_MODE_DURATION_MAX {
return false;
}
if self.maximum_check_in_backoff < self.idle_mode_duration
|| self.maximum_check_in_backoff > IDLE_MODE_DURATION_MAX
{
return false;
}
self.idle_mode_duration.saturating_mul(1000) >= self.active_mode_duration
}
}
pub fn conforming(
features: Feature,
optional: &Optional<'_>,
) -> crate::error::Result<Conforming<12, 4, 2, 0>> {
Conforming::new(
&crate::clusters::generated::icd_management::CLUSTER,
features.bits(),
optional,
)
}
pub trait StayActive {
fn promise(&self, requested: u32) -> u32;
}
#[derive(Debug, Clone, Copy, Default)]
pub struct GrantRequested;
impl StayActive for GrantRequested {
fn promise(&self, requested: u32) -> u32 {
requested
}
}
#[derive(Debug)]
pub struct IcdManagement<'a, C: Config, const N: usize = 5, A: StayActive = GrantRequested> {
clients: RefCell<heapless::Vec<Registration, N>>,
counter: RefCell<u32>,
timings: Timings,
features: Feature,
operating_mode: RefCell<OperatingMode>,
trigger_hint: UserActiveModeTrigger,
trigger_instruction: &'a str,
stay_active: A,
_config: PhantomData<C>,
}
impl<'a, C: Config, const N: usize> IcdManagement<'a, C, N, GrantRequested> {
#[must_use]
pub const fn new(features: Feature, timings: Timings) -> Self {
Self::with_stay_active(features, timings, GrantRequested)
}
}
impl<'a, C: Config, const N: usize, A: StayActive> IcdManagement<'a, C, N, A> {
pub const CHECK: () = {
let () = crate::config::AssertValid::<C>::CHECK;
assert!(
N >= C::ICD_CLIENTS_PER_FABRIC * C::FABRICS,
"IcdManagement: §9.16.6.6 promises ICD_CLIENTS_PER_FABRIC registrations to every \
fabric, so the table must hold FABRICS × that many"
);
};
#[must_use]
pub const fn with_stay_active(features: Feature, timings: Timings, stay_active: A) -> Self {
let () = Self::CHECK;
Self {
clients: RefCell::new(heapless::Vec::new()),
counter: RefCell::new(0),
timings,
features,
operating_mode: RefCell::new(OperatingMode::Sit),
trigger_hint: UserActiveModeTrigger::empty(),
trigger_instruction: "",
stay_active,
_config: PhantomData,
}
}
pub fn with_trigger(
mut self,
hint: UserActiveModeTrigger,
instruction: &'a str,
) -> crate::error::Result<Self> {
if instruction.len() > 128 {
crate::error::bail!(InvalidArgument)
}
if hint.needs_instruction() && instruction.is_empty() {
crate::error::bail!(InvalidArgument)
}
self.trigger_hint = hint;
self.trigger_instruction = instruction;
Ok(self)
}
#[must_use]
pub const fn timings(&self) -> Timings {
self.timings
}
#[must_use]
pub fn operating_mode(&self) -> OperatingMode {
*self.operating_mode.borrow()
}
pub fn set_operating_mode(&self, mode: OperatingMode) -> Result<(), Status> {
if !self.features.contains(Feature::LONG_IDLE_TIME_SUPPORT) {
return Err(Status::UnsupportedAttribute);
}
if mode == OperatingMode::Lit
&& !self.features.contains(Feature::DYNAMIC_SIT_LIT_SUPPORT)
&& !self.clients.borrow().is_empty()
{
return Err(Status::InvalidInState);
}
*self.operating_mode.borrow_mut() = mode;
Ok(())
}
#[must_use]
pub fn counter(&self) -> u32 {
*self.counter.borrow()
}
pub fn next_check_in_counter(&self) -> u32 {
let mut counter = self.counter.borrow_mut();
*counter = counter.wrapping_add(1);
*counter
}
pub fn restore_counter(&self, value: u32) {
*self.counter.borrow_mut() = value;
}
pub fn randomize_counter(&self, randomness: u32) {
*self.counter.borrow_mut() = crate::msg::initial_counter(randomness);
}
#[must_use]
pub fn clients(&self) -> core::cell::Ref<'_, heapless::Vec<Registration, N>> {
self.clients.borrow()
}
#[must_use]
pub fn len_of_fabric(&self, fabric: FabricIndex) -> usize {
self.clients
.borrow()
.iter()
.filter(|c| c.fabric_index == fabric)
.count()
}
pub fn remove_fabric(&self, fabric: FabricIndex) {
self.clients
.borrow_mut()
.retain(|c| c.fabric_index != fabric);
}
fn register(
&self,
fields: RegisterFields,
fabric: FabricIndex,
administrator: bool,
) -> Result<(), StatusIb> {
let mut clients = self.clients.borrow_mut();
let existing = clients.iter().position(|c| {
c.fabric_index == fabric && c.check_in_node_id == fields.check_in_node_id
});
match existing {
Some(position) => {
let Some(entry) = clients.get_mut(position) else {
return Err(Status::Failure.into());
};
if !administrator {
let Some(verification) = fields.verification_key else {
return Err(Status::Failure.into());
};
if !ct_eq(verification.as_bytes(), entry.key.as_bytes()) {
return Err(Status::Failure.into());
}
}
entry.monitored_subject = fields.monitored_subject;
entry.client_type = fields.client_type;
entry.key = fields.key;
Ok(())
}
None => {
let used = clients.iter().filter(|c| c.fabric_index == fabric).count();
if used >= C::ICD_CLIENTS_PER_FABRIC {
return Err(Status::ResourceExhausted.into());
}
clients
.push(Registration::new(
fields.check_in_node_id,
fields.monitored_subject,
fields.client_type,
fabric,
fields.key,
))
.map_err(|_| StatusIb::from(Status::ResourceExhausted))
}
}
}
fn unregister(
&self,
node: NodeId,
verification_key: Option<SymmetricKey>,
fabric: FabricIndex,
administrator: bool,
) -> Result<(), StatusIb> {
let mut clients = self.clients.borrow_mut();
let Some(position) = clients
.iter()
.position(|c| c.fabric_index == fabric && c.check_in_node_id == node)
else {
return Err(Status::NotFound.into());
};
if !administrator {
let Some(entry) = clients.get(position) else {
return Err(Status::Failure.into());
};
let Some(verification) = verification_key else {
return Err(Status::Failure.into());
};
if !ct_eq(verification.as_bytes(), entry.key.as_bytes()) {
return Err(Status::Failure.into());
}
}
clients.remove(position);
Ok(())
}
fn visible(ctx: &InteractionContext<'_>, index: FabricIndex) -> bool {
!ctx.fabric_filtered || ctx.fabric_index == Some(index)
}
fn is_administrator(ctx: &InteractionContext<'_>) -> bool {
ctx.privilege
.is_some_and(|p| p.grants(Privilege::Administer))
}
}
impl<C: Config, const N: usize, A: StayActive> ClusterHandler for IcdManagement<'_, C, N, A> {
fn on_lifecycle(&self, event: crate::im::Lifecycle) {
if let crate::im::Lifecycle::FabricRemoved(fabric) = event {
self.remove_fabric(fabric);
}
}
fn read(
&self,
resolved: &Resolved<'_>,
ctx: &InteractionContext<'_>,
w: &mut TlvWriter<'_>,
tag: Tag,
) -> Result<(), Status> {
let full = |r: crate::error::Result<()>| r.map_err(|_| Status::ResourceExhausted);
match resolved.attribute {
IDLE_MODE_DURATION => full(w.unsigned(tag, u64::from(self.timings.idle_mode_duration))),
ACTIVE_MODE_DURATION => {
full(w.unsigned(tag, u64::from(self.timings.active_mode_duration)))
}
ACTIVE_MODE_THRESHOLD => {
full(w.unsigned(tag, u64::from(self.timings.active_mode_threshold)))
}
REGISTERED_CLIENTS => {
if !self.features.contains(Feature::CHECK_IN_PROTOCOL_SUPPORT) {
return Err(Status::UnsupportedAttribute);
}
let clients = self.clients.borrow();
full(w.start_array(tag))?;
for client in clients
.iter()
.filter(|c| Self::visible(ctx, c.fabric_index))
{
full(client.encode(w))?;
}
full(w.end_container())
}
ICD_COUNTER => {
if !self.features.contains(Feature::CHECK_IN_PROTOCOL_SUPPORT) {
return Err(Status::UnsupportedAttribute);
}
full(w.unsigned(tag, u64::from(self.counter())))
}
CLIENTS_SUPPORTED_PER_FABRIC => {
if !self.features.contains(Feature::CHECK_IN_PROTOCOL_SUPPORT) {
return Err(Status::UnsupportedAttribute);
}
full(w.unsigned(tag, C::ICD_CLIENTS_PER_FABRIC as u64))
}
USER_ACTIVE_MODE_TRIGGER_HINT => {
if !self.features.contains(Feature::USER_ACTIVE_MODE_TRIGGER) {
return Err(Status::UnsupportedAttribute);
}
full(w.unsigned(tag, u64::from(self.trigger_hint.bits())))
}
USER_ACTIVE_MODE_TRIGGER_INSTRUCTION => {
if !self.features.contains(Feature::USER_ACTIVE_MODE_TRIGGER) {
return Err(Status::UnsupportedAttribute);
}
full(w.utf8(tag, self.trigger_instruction))
}
OPERATING_MODE => {
if !self.features.contains(Feature::LONG_IDLE_TIME_SUPPORT) {
return Err(Status::UnsupportedAttribute);
}
full(w.unsigned(tag, self.operating_mode() as u64))
}
MAXIMUM_CHECK_IN_BACKOFF => {
if !self.features.contains(Feature::CHECK_IN_PROTOCOL_SUPPORT) {
return Err(Status::UnsupportedAttribute);
}
full(w.unsigned(tag, u64::from(self.timings.maximum_check_in_backoff)))
}
_ => Err(Status::UnsupportedAttribute),
}
}
fn invoke(
&self,
resolved: &ResolvedCommand<'_>,
fields: Option<&[u8]>,
ctx: &InteractionContext<'_>,
w: &mut TlvWriter<'_>,
tag: Tag,
) -> Result<Option<CommandId>, StatusIb> {
let full = |r: crate::error::Result<()>| r.map_err(|_| StatusIb::from(Status::Failure));
match resolved.command.id {
REGISTER_CLIENT => {
if !self.features.contains(Feature::CHECK_IN_PROTOCOL_SUPPORT) {
return Err(Status::UnsupportedCommand.into());
}
let Some(fabric) = ctx.fabric_index else {
return Err(Status::UnsupportedAccess.into());
};
let fields =
decode_register(fields.ok_or(StatusIb::from(Status::InvalidCommand))?)?;
self.register(fields, fabric, Self::is_administrator(ctx))?;
full(w.start_structure(tag))?;
full(w.unsigned(Tag::Context(0), u64::from(self.counter())))?;
full(w.end_container())?;
Ok(Some(REGISTER_CLIENT_RESPONSE))
}
UNREGISTER_CLIENT => {
if !self.features.contains(Feature::CHECK_IN_PROTOCOL_SUPPORT) {
return Err(Status::UnsupportedCommand.into());
}
let Some(fabric) = ctx.fabric_index else {
return Err(Status::UnsupportedAccess.into());
};
let (node, verification_key) =
decode_unregister(fields.ok_or(StatusIb::from(Status::InvalidCommand))?)?;
self.unregister(node, verification_key, fabric, Self::is_administrator(ctx))?;
Ok(None)
}
STAY_ACTIVE_REQUEST => {
if !self.features.contains(Feature::LONG_IDLE_TIME_SUPPORT) {
return Err(Status::UnsupportedCommand.into());
}
let requested =
decode_stay_active(fields.ok_or(StatusIb::from(Status::InvalidCommand))?)?;
let promised = self.stay_active.promise(requested);
full(w.start_structure(tag))?;
full(w.unsigned(Tag::Context(0), u64::from(promised)))?;
full(w.end_container())?;
Ok(Some(STAY_ACTIVE_RESPONSE))
}
_ => Err(Status::UnsupportedCommand.into()),
}
}
}
impl<C: Config, const N: usize, A: StayActive> Cluster for IcdManagement<'_, C, N, A> {
const ID: ClusterId = ID;
}