diff --git a/satrs/src/pus/action.rs b/satrs/src/pus/action.rs index 88e146f..155ddca 100644 --- a/satrs/src/pus/action.rs +++ b/satrs/src/pus/action.rs @@ -8,6 +8,21 @@ use super::verification::{TcStateAccepted, VerificationReporterWithSender, Verif #[cfg_attr(doc_cfg, doc(cfg(feature = "std")))] pub use std_mod::*; +/// This trait is an abstraction for the conversion of a PUS service 8 action telecommand into +/// an [ActionRequest]. +/// +/// Having a dedicated trait for this allows maximum flexiblity and tailoring of the standard. +/// The only requirement is that a valid [TargetId] and an [ActionRequest] are returned by the +/// core conversion function. +/// +/// The user should take care of performing the error handling as well. Some of the following +/// aspects might be relevant: +/// +/// - Checking the validity of the APID, service ID, subservice ID. +/// - Checking the validity of the user data. +/// +/// A [VerificationReporterWithSender] instance is passed to the user to also allow handling +/// of the verification process as part of the PUS standard requirements. pub trait PusActionToRequestConverter { type Error; fn convert( @@ -19,6 +34,8 @@ pub trait PusActionToRequestConverter { ) -> Result<(TargetId, ActionRequest), Self::Error>; } +/// This trait is an abstraction for the routing of PUS service 8 action requests to a dedicated +/// recipient using the generic [TargetId]. pub trait PusActionRequestRouter { type Error; fn route( @@ -39,6 +56,16 @@ pub mod std_mod { use super::*; + /// This is a high-level handler for the PUS service 8 action service. + /// + /// It performs the following handling steps: + /// + /// 1. Retrieve the next TC packet from the [PusServiceHelper]. The [EcssTcInMemConverter] + /// allows to configure the used telecommand memory backend. + /// 2. Convert the TC to a targeted action request using the provided + /// [PusActionToRequestConverter]. + /// 3. Route the action request using the provided [PusActionRequestRouter]. + /// 4. Handle all routing errors using the provided [PusRoutingErrorHandler]. pub struct PusService8ActionHandler< TcInMemConverter: EcssTcInMemConverter, RequestConverter: PusActionToRequestConverter, @@ -78,6 +105,7 @@ pub mod std_mod { } } + /// Core function to poll the next TC packet and try to handle it. pub fn handle_one_tc(&mut self) -> Result { let possible_packet = self.service_helper.retrieve_and_accept_next_packet()?; if possible_packet.is_none() {