diff --git a/src/hardware/clock.rs b/src/hardware/clock.rs index fafdeaa3..0f275d21 100644 --- a/src/hardware/clock.rs +++ b/src/hardware/clock.rs @@ -1,3 +1,9 @@ +//! Booster system clock setup and management routines. +//! +//! # Copyright +//! Copyright (C) 2020 QUARTIQ GmbH - All Rights Reserved +//! Unauthorized usage, editing, or copying is strictly prohibited. +//! Proprietary and confidential. use minimq::embedded_time::{ clock::{Clock, Error}, fraction::Fraction, @@ -6,10 +12,23 @@ use minimq::embedded_time::{ use core::convert::TryInto; +/// The SystemTimer is the main timekeeping mechanism for the device. +/// +/// # Note +/// At current configurations, the timer overflows every 2^32 10KHz ticks, which corresponds to +/// approximately just shy of every 5 days. #[derive(Copy, Clone, Debug, Default)] pub struct SystemTimer {} impl SystemTimer { + /// Initialize the SystemTimer for use in time keeping. + /// + /// # Note + /// The system timer is always configured for 10KHz. + /// + /// # Args + /// * `regs` - The TIM2 register block. + /// * `clocks` - The configured RCC clocks. pub fn initialize(regs: stm32f4xx_hal::stm32::TIM2, clocks: &stm32f4xx_hal::rcc::Clocks) { // Reset and enable the timer in the RCC. let rcc = unsafe { &*stm32f4xx_hal::stm32::RCC::ptr() }; @@ -49,6 +68,9 @@ impl Clock for SystemTimer { let regs = unsafe { &*stm32f4xx_hal::stm32::TIM2::ptr() }; // The TIM2 peripheral is a 32-bit counter. + // Note: We silently ignore overflows of the CNT register because `embedded-time` will + // automatically handle overflowed tick counts as long as the space between them is less + // than ~2.5 days. Ok(Instant::new(regs.cnt.read().bits())) } } diff --git a/src/net/mod.rs b/src/net/mod.rs index 15ccdcb8..c555efcb 100644 --- a/src/net/mod.rs +++ b/src/net/mod.rs @@ -1,3 +1,9 @@ +//! Booster network management definitions +//! +//! # Copyright +//! Copyright (C) 2020 QUARTIQ GmbH - All Rights Reserved +//! Unauthorized usage, editing, or copying is strictly prohibited. +//! Proprietary and confidential. use crate::hardware::NetworkStack; use crate::delay::AsmDelay; @@ -7,10 +13,15 @@ mod shared; mod telemetry; use mqtt_control::ControlState; - use shared::NetworkManager; + type NetworkStackProxy = shared::NetworkStackProxy<'static, NetworkStack>; +/// Container structure for holding all network devices. +/// +/// # Note +/// All devices accessing the shared stack must be contained within a single structure to prevent +/// potential pre-emption when using the `shared` network stack. pub struct NetworkDevices { pub controller: mqtt_control::ControlState, pub telemetry: telemetry::TelemetryClient, @@ -21,6 +32,13 @@ pub struct NetworkDevices { } impl NetworkDevices { + /// Construct all of Booster's Network devices. + /// + /// # Args + /// * `broker` - The broker IP address for MQTT. + /// * `stack` - The network stack to use for communications. + /// * `identifier` - The unique identifier of this device. + /// * `delay` - A delay mechanism. pub fn new( broker: minimq::embedded_nal::IpAddr, stack: NetworkStack, @@ -38,6 +56,11 @@ impl NetworkDevices { } } + /// Process the network stack. + /// + /// # Note + /// This function must be called periodically to handle ingress/egress of packets and update + /// state management. pub fn process(&mut self) -> bool { self.telemetry.process(); diff --git a/src/net/shared.rs b/src/net/shared.rs index aa7bff38..fb46f2e2 100644 --- a/src/net/shared.rs +++ b/src/net/shared.rs @@ -1,3 +1,13 @@ +//! Booster shared network stack management +//! +//! # Note +//! Portions of this file are taken from the +//! [`smoltcp-nal`](https://github.com/quartiq/smoltcp-nal/blob/main/src/shared.rs) +//! +//! # Copyright +//! Copyright (C) 2020 QUARTIQ GmbH - All Rights Reserved +//! Unauthorized usage, editing, or copying is strictly prohibited. +//! Proprietary and confidential. use minimq::embedded_nal; use shared_bus::{AtomicCheckMutex, BusMutex}; diff --git a/src/net/telemetry.rs b/src/net/telemetry.rs index 69cc3685..89f399b4 100644 --- a/src/net/telemetry.rs +++ b/src/net/telemetry.rs @@ -1,16 +1,28 @@ +//! Booster telemetry client management +//! +//! # Copyright +//! Copyright (C) 2020 QUARTIQ GmbH - All Rights Reserved +//! Unauthorized usage, editing, or copying is strictly prohibited. +//! Proprietary and confidential. use super::NetworkStackProxy; use crate::hardware::{clock::SystemTimer, Channel}; - use core::fmt::Write; use heapless::String; use serde::Serialize; +/// Telemetry reporting MQTT client. pub struct TelemetryClient { mqtt: minimq::Minimq, prefix: String<128>, } impl TelemetryClient { + /// Construct the telemetry client. + /// + /// # Args + /// * `broker` - The Booster MQTT broker IP address. + /// * `stack` - A reference to the shared network stack. + /// * `identifier` - The unique Booster ID. pub fn new( broker: minimq::embedded_nal::IpAddr, stack: NetworkStackProxy, @@ -28,6 +40,11 @@ impl TelemetryClient { } } + /// Publish telemetry for a specific channel. + /// + /// # Args + /// * `channel` - The channel that telemetry is being reported for. + /// * `telemetry` - The associated telemetry of the channel to report. pub fn report_telemetry(&mut self, channel: Channel, telemetry: &impl Serialize) { let mut topic: String<64> = String::new(); write!(&mut topic, "{}/ch{}", self.prefix, channel as u8).unwrap(); @@ -47,10 +64,10 @@ impl TelemetryClient { .unwrap(); } - // Update the telemetry client. - // - // # Note - // This must be called periodically to advance the MQTT state machine. + /// Update the telemetry client. + /// + /// # Note + /// This must be called periodically to advance the MQTT state machine. pub fn process(&mut self) { self.mqtt .poll(|_client, _topic, _message, _properties| {})