From b16e4f9d5da8f30c0a81bf73b9db513741b05475 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Benjamin=20Stu=CC=88rmer?= Date: Tue, 22 Oct 2024 06:40:52 +0200 Subject: [PATCH] add more docs --- src/aps/apsde.rs | 78 ---------------------------------- src/aps/apsde/mod.rs | 89 +++++++++++++++++++++++++++++++++++++++ src/aps/apsme/basemgt.rs | 67 ++++++++++++++++++++--------- src/aps/apsme/groupmgt.rs | 9 ++-- src/aps/apsme/mod.rs | 33 ++++++++------- src/aps/mod.rs | 8 +++- src/lib.rs | 5 +++ 7 files changed, 167 insertions(+), 122 deletions(-) delete mode 100644 src/aps/apsde.rs create mode 100644 src/aps/apsde/mod.rs diff --git a/src/aps/apsde.rs b/src/aps/apsde.rs deleted file mode 100644 index fe3e9ab..0000000 --- a/src/aps/apsde.rs +++ /dev/null @@ -1,78 +0,0 @@ -#![allow(dead_code)] -use crate::aps::types; - -// 2.2.4.1 -// Application support sub-layer data entity – service access point -// -// Interface between the NWK (Network) layer and the APL (Application) layer -// through a general set of services for use by both the ZDO (device object) and the application. -pub(crate) trait ApsdeSap { - fn data_request(request: ApsdeSapRequest) -> ApsdeSapConfirm; -} - - - -type DstAddrMode = u8; -// 2.2.4.1.1 -pub(crate) struct ApsdeSapRequest { - dst_addr_mode: DstAddrMode, - dst_address: u8, - dst_endpoint: u8, - profile_id: u16, - cluster_id: u16, - src_endpoint: types::SrcEndpoint, - asdulength: u8, - asdu: u8, - tx_options: bitmaps::Bitmap<8>, - use_alias: bool, - alias_src_addr: u16, - alias_seq_number: u8, - radius_counter: u8 -} - -enum ApsdeSapConfirmStatus { - Success, - NoShortAddress, - NoBoundDevice, - SecurityFail, - NoAck, - AsduTooLong -} -// 2.2.4.1.2 -pub(crate) struct ApsdeSapConfirm { - dst_addr_mode: DstAddrMode, - dst_address: u8, - dst_endpoint: u8, - src_endpoint: types::SrcEndpoint, - status: ApsdeSapConfirmStatus, - tx_time: u8, -} - -enum ApsdeSapIndicationStatus { - Success, - DefragUnsupported, - DefragDeferred -} -enum SecurityStatus { - Unsecured, - SecuredNwkKey, - SecuredLinkKey -} - -// 2.2.4.1.3 -struct ApsdeSapIndication { - dst_addr_mode: DstAddrMode, - dst_address: u8, - dst_endpoint: u8, - src_addr_mode: u8, - src_address: u64, - src_endpoint: types::SrcEndpoint, - profile_id: u16, - cluster_id: u16, - asdulength: u8, - status: ApsdeSapIndicationStatus, - security_status: SecurityStatus, - link_quality: u8, - rx_time: u8, -} - diff --git a/src/aps/apsde/mod.rs b/src/aps/apsde/mod.rs new file mode 100644 index 0000000..7ea5cb8 --- /dev/null +++ b/src/aps/apsde/mod.rs @@ -0,0 +1,89 @@ +#![allow(dead_code)] +use crate::aps::types; + + +/// Application support sub-layer data entity – service access point +/// +/// 2.2.4.1.1 +/// +/// Interface between the NWK (Network) layer and the APL (Application) layer +/// through a general set of services for use by both the ZDO (device object) and the application. +pub trait ApsdeSap { + /// Requests the transfer of a NHLE PDU from a local NHLE to one or more peer NHLE entities + fn data_request(&self, request: ApsdeSapRequest) -> ApsdeSapConfirm; +} + + +type DstAddrMode = u8; +// 2.2.4.1.1 +pub struct ApsdeSapRequest { + dst_addr_mode: DstAddrMode, + dst_address: u8, + dst_endpoint: u8, + profile_id: u16, + cluster_id: u16, + src_endpoint: types::SrcEndpoint, + asdulength: u8, + asdu: u8, + tx_options: bitmaps::Bitmap<8>, + use_alias: bool, + alias_src_addr: u16, + alias_seq_number: u8, + radius_counter: u8 +} + + +/// The status of the corresponding request. +pub enum ApsdeSapConfirmStatus { + /// indicating that the request to transmit was successful + Success, + /// No corresponding 16-bit NKW address found + NoShortAddress, + /// No binding table entries found with the respectively SrcEndpoint and ClusterId parameter + NoBoundDevice, + /// the security processing failed + SecurityFail, + /// one or more APS acknowledgements were not correctly received + NoAck, + /// ASDU to be transmitted is larger than will fit in a single frame and fragmentation is not possible + AsduTooLong +} +// 2.2.4.1.2 +pub struct ApsdeSapConfirm { + pub dst_addr_mode: DstAddrMode, + pub dst_address: u8, + pub dst_endpoint: u8, + pub src_endpoint: types::SrcEndpoint, + pub status: ApsdeSapConfirmStatus, + pub tx_time: u8, +} + +pub enum ApsdeSapIndicationStatus { + Success, + DefragUnsupported, + DefragDeferred +} + +pub enum SecurityStatus { + Unsecured, + SecuredNwkKey, + SecuredLinkKey +} + +// 2.2.4.1.3 +pub struct ApsdeSapIndication { + dst_addr_mode: DstAddrMode, + dst_address: u8, + dst_endpoint: u8, + src_addr_mode: u8, + src_address: u64, + src_endpoint: types::SrcEndpoint, + profile_id: u16, + cluster_id: u16, + asdulength: u8, + status: ApsdeSapIndicationStatus, + security_status: SecurityStatus, + link_quality: u8, + rx_time: u8, +} + diff --git a/src/aps/apsme/basemgt.rs b/src/aps/apsme/basemgt.rs index ca029a6..d69545d 100644 --- a/src/aps/apsme/basemgt.rs +++ b/src/aps/apsme/basemgt.rs @@ -1,3 +1,4 @@ +#![allow(dead_code)] //! //! 2.2.4.4 Information Base Maintenance //! This set of primitives defines how the next higher layer of a device can read and write attributes in the AIB @@ -5,8 +6,8 @@ use crate::aps::types; type DstAddrMode = u8; -// 2.2.4.3.1 APSME-BIND.request -pub(crate) struct ApsmeBindRequest { +/// 2.2.4.3.1 - APSME-BIND.request +pub struct ApsmeBindRequest { src_address: u64, src_endpoint: types::SrcEndpoint, cluster_id: u16, @@ -15,15 +16,15 @@ pub(crate) struct ApsmeBindRequest { dst_endpoint: u8, } -enum ApsmeBindRequestStatus { +pub enum ApsmeBindRequestStatus { Success, IllegalRequest, TableFull, NotSupported } -// 2.2.4.3.2 APSME-BIND.confirm -pub(crate) struct ApsmeBindConfirm { +/// 2.2.4.3.2 - APSME-BIND.confirm +pub struct ApsmeBindConfirm { status: ApsmeBindRequestStatus, src_address: u64, src_endpoint: types::SrcEndpoint, @@ -33,8 +34,8 @@ pub(crate) struct ApsmeBindConfirm { dst_endpoint: u8, } -// 2.2.4.3.3 APSME-UNBIND.request -struct ApsmeUnbindRequest { +/// 2.2.4.3.3 - APSME-UNBIND.request +pub struct ApsmeUnbindRequest { src_address: u64, src_endpoint: types::SrcEndpoint, cluster_id: u16, @@ -43,13 +44,13 @@ struct ApsmeUnbindRequest { dst_endpoint: u8, } -enum ApsmeUnbindRequestStatus { +pub enum ApsmeUnbindRequestStatus { Success, IllegalRequest, InvalidBinding } -// 2.2.4.3.4 APSME-UNBIND.confirm -struct ApsmeUnbindConfirm { +/// 2.2.4.3.4 - APSME-UNBIND.confirm +pub struct ApsmeUnbindConfirm { status: ApsmeUnbindRequestStatus, src_address: u64, src_endpoint: types::SrcEndpoint, @@ -59,7 +60,7 @@ struct ApsmeUnbindConfirm { dst_endpoint: u8, } -pub(crate) enum AIBAttribute { +pub enum AIBAttribute { IapsBindingTable = 0xc1, ApsDesignatedCoordinator = 0xc2, ApsChannelMaskList = 0xc3, @@ -75,35 +76,61 @@ pub(crate) enum AIBAttribute { ApsParentAnnounceTimer = 0xce, } -// 2.2.4.4.1 APSME-GET.request -struct ApsmeGetRequest { +/// 2.2.4.4.1 - APSME-GET.request +pub struct ApsmeGetRequest { attribute: AIBAttribute } -pub(crate) struct AIBAttributeValue { +pub struct AIBAttributeValue { } - -struct ApsmeGetConfirm { +/// 2.2.4.4.2 - APSME-GET.confirm +pub struct ApsmeGetConfirm { status: u8, attribute: AIBAttribute, attribute_length: u8, attribute_value: AIBAttributeValue, } -// 2.2.4.4.3 APSME-SET.request -struct ApsmeSetRequest { +/// 2.2.4.4.3 - APSME-SET.request +pub struct ApsmeSetRequest { attribute: AIBAttribute, attribute_length: u8, attribute_value: AIBAttributeValue, } -// 2.2.4.4.4 APSME-SET.confirm -struct ApsmeSetConfirm { +/// 2.2.4.4.4 - APSME-SET.confirm +pub struct ApsmeSetConfirm { status: u8, attribute: AIBAttribute, attribute_length: u8, attribute_value: AIBAttributeValue, } +/// 2.2.4.5.1 - APSME-ADD-GROUP.request +pub struct ApsmeAddGroupRequest { + +} + +/// 2.2.4.5.2 - APSME-ADD-GROUP.confirm +pub struct ApsmeAddGroupConfirm { +} + +/// 2.2.4.5.3 - APSME-REMOVE-GROUP.request +pub struct ApsmeRemoveGroupRequest { + +} +/// 2.2.4.5.3 - APSME-REMOVE-GROUP.request +pub struct ApsmeRemoveGroupConfirm { + +} + +/// 2.2.4.5.5 - APSME-REMOVE-ALL-GROUPS.request +pub struct ApsmeRemoveAllGroupsRequest { + +} +/// 2.2.4.5.6 - APSME-REMOVE-ALL-GROUPs.request +pub struct ApsmeRemoveAllGroupsConfirm { + +} diff --git a/src/aps/apsme/groupmgt.rs b/src/aps/apsme/groupmgt.rs index bc1b271..0ecb76a 100644 --- a/src/aps/apsme/groupmgt.rs +++ b/src/aps/apsme/groupmgt.rs @@ -1,13 +1,10 @@ -//! -//! 2.2.4.5 Group Management //! This set of primitives allows the next higher layer to manage group membership for endpoints on the current device by adding and removing entries in the group table //! +//! 2.2.4.5 Group Management type DstAddrMode = u8; -// 2.2.4.3.1 APSME-BIND.request -struct ApsmeAddrGroupRequest { +/// 2.2.4.3.1 - APSME-BIND.request +pub struct ApsmeAddrGroupRequest { group_address: u16, endpoint: u8, } - - diff --git a/src/aps/apsme/mod.rs b/src/aps/apsme/mod.rs index 799058e..f3e7d9f 100644 --- a/src/aps/apsme/mod.rs +++ b/src/aps/apsme/mod.rs @@ -1,28 +1,29 @@ +#![allow(dead_code)] + use basemgt::{AIBAttribute, AIBAttributeValue, ApsmeBindConfirm, ApsmeBindRequest}; -pub(crate) mod basemgt; -pub(crate) mod groupmgt; +pub mod basemgt; +pub mod groupmgt; -// 2.2.4.2 -// Application support sub-layer management service = service access point -// -// supports the transport of management commands between the NHLE and the APSME -pub(crate) trait ApsmeSap { - // 2.2.4.3.1 - // request to bind two devices together, or to bind a device to a group +/// Application support sub-layer management service = service access point +/// +/// 2.2.4.2 +/// +/// supports the transport of management commands between the NHLE and the APSME +pub trait ApsmeSap { + /// 2.2.4.3.1 - request to bind two devices together, or to bind a device to a group fn bind_request(request: ApsmeBindRequest) -> ApsmeBindConfirm; - // 2.2.4.3.3 - // request to unbind two devices, or to unbind a device from a group + /// 2.2.4.3.3 - request to unbind two devices, or to unbind a device from a group fn unbind_request(); - // 2.2.4.4.1 + /// 2.2.4.4.1 fn get(attribute: AIBAttribute) -> AIBAttributeValue; - // 2.2.4.4.3 + /// 2.2.4.4.3 fn set(); - // 2.2.4.5.1 + /// 2.2.4.5.1 fn add_group(); - // 2.2.4.5.1 + /// 2.2.4.5.1 fn remove_group(); - // 2.2.4.5.5 + /// 2.2.4.5.5 fn remove_all_groups(); } diff --git a/src/aps/mod.rs b/src/aps/mod.rs index 50327b4..8ba77cb 100644 --- a/src/aps/mod.rs +++ b/src/aps/mod.rs @@ -1,6 +1,10 @@ pub(crate) mod types; pub(crate) mod error; -pub(crate) mod apsde; -pub(crate) mod apsme; +/// The APS data entity provides the data transmission service between two or more application entities located on the same network. +pub mod apsde; + +/// The APS management entity provides a variety of services to application objects including security services and binding of devices. +/// It also maintains a database of managed objects, known as the APS information base (AIB). +pub mod apsme; diff --git a/src/lib.rs b/src/lib.rs index 03c3ae2..f845b23 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -4,3 +4,8 @@ //! #![no_std] +/// This aps (application support sub-layer) module provides an interface between the `nwk` +/// (Network layer) and the `apl` (Application layer) through a general set of services that are +/// used by both the `zdo` (Zigbee device object) and the application objects. +pub mod aps; +