diff --git a/components/insa/include/common/InactivityTracker.h b/components/insa/include/common/InactivityTracker.h index b28ea51..ec38697 100644 --- a/components/insa/include/common/InactivityTracker.h +++ b/components/insa/include/common/InactivityTracker.h @@ -1,20 +1,193 @@ +/** + * @file InactivityTracker.h + * @brief Inactivity tracking system for monitoring user interaction timeouts + * @details This header defines the InactivityTracker class which monitors user + * activity and triggers timeout callbacks when the system remains inactive + * for a specified duration. It provides essential functionality for power + * management, screen savers, and automatic system state transitions. + * @author System Control Team + * @date 2025-06-20 + */ + #pragma once -#include #include +/** + * @class InactivityTracker + * @brief Activity monitoring class for detecting user inactivity periods + * @details This class provides a robust mechanism for tracking user activity and + * triggering automatic actions when the system remains inactive for a + * configured timeout period. It is commonly used for implementing power + * saving features, automatic screen savers, session timeouts, and other + * time-based system behaviors. + * + * The InactivityTracker operates by: + * - Continuously tracking elapsed time since the last user activity + * - Comparing elapsed time against a configurable timeout threshold + * - Executing a callback function when the timeout is reached + * - Providing methods to reset the timer when activity is detected + * - Supporting enable/disable functionality for dynamic control + * + * Key features include: + * - Configurable timeout duration in milliseconds + * - Custom callback function execution on timeout + * - Activity reset capability for responsive user interaction + * - Enable/disable control for conditional monitoring + * - High-resolution timing support using 64-bit millisecond precision + * + * Common use cases: + * - Screen saver activation after idle periods + * - Automatic screen dimming or shutdown + * - Session timeout management + * - Power management and battery conservation + * - User interface state transitions + * - Security lockout after inactivity + * + * The class is designed to be lightweight and efficient, suitable for + * real-time applications where precise timing and minimal overhead are important. + * + * @note This class requires regular update calls to function properly. + * @note The timeout callback is executed once per timeout period and will + * not repeat until the tracker is reset and times out again. + * + * @see Widget for integration with UI components + * @see Menu for menu timeout implementations + */ class InactivityTracker { public: + /** + * @brief Constructs an InactivityTracker with specified timeout and callback + * @param timeoutMs Timeout duration in milliseconds before triggering callback + * @param onTimeout Callback function to execute when timeout is reached + * + * @pre timeoutMs must be greater than 0 for meaningful timeout behavior + * @pre onTimeout must be a valid callable function object + * @post InactivityTracker is initialized, enabled, and ready for activity monitoring + * + * @details The constructor initializes the inactivity tracker with the specified + * timeout duration and callback function. The tracker starts in an enabled + * state with zero elapsed time, ready to begin monitoring user activity. + * + * The timeout callback function can perform any necessary actions when inactivity + * is detected, such as: + * - Activating screen savers or power saving modes + * - Transitioning to different application states + * - Logging inactivity events + * - Triggering security lockouts + * - Initiating automatic save operations + * + * @note The tracker begins monitoring immediately upon construction. + * @note The callback function should be lightweight to avoid blocking + * the main application thread during timeout processing. + * + * Example usage: + * @code + * auto tracker = InactivityTracker(30000, []() { + * // Activate screen saver after 30 seconds of inactivity + * activateScreenSaver(); + * }); + * @endcode + */ InactivityTracker(uint64_t timeoutMs, std::function onTimeout); + /** + * @brief Updates the inactivity timer and checks for timeout conditions + * @param dt Delta time in milliseconds since the last update call + * + * @details This method must be called regularly (typically every frame) to + * maintain accurate timing and timeout detection. It increments the + * elapsed time counter and triggers the timeout callback when the + * configured timeout duration is reached. + * + * The update process: + * - Adds the delta time to the elapsed time counter (if enabled) + * - Compares elapsed time against the configured timeout threshold + * - Executes the timeout callback if the threshold is exceeded + * - Continues monitoring until reset or disabled + * + * @note This method should be called consistently from the main application + * loop to ensure accurate timing behavior. + * @note The timeout callback is executed only once per timeout period. + * @note If the tracker is disabled, elapsed time is not updated. + * + * @see reset() to restart the inactivity timer + * @see setEnabled() to control monitoring state + */ void update(uint64_t dt); + + /** + * @brief Resets the inactivity timer to indicate recent user activity + * + * @details This method should be called whenever user activity is detected + * to restart the inactivity timeout period. It resets the elapsed + * time counter to zero, effectively extending the timeout deadline + * and preventing timeout callback execution until the full timeout + * duration elapses again without further resets. + * + * Common scenarios for calling reset(): + * - Button presses or key events + * - Mouse movement or touch input + * - Menu navigation or selection actions + * - Any user interface interaction + * - System activity that should extend the timeout + * + * @post Elapsed time is reset to zero, restarting the timeout period + * + * @note This method can be called at any time, even when the tracker + * is disabled, to prepare for future monitoring. + * @note Frequent reset calls from active user interaction will prevent + * timeout callback execution, which is the intended behavior. + * + * Example usage: + * @code + * void onButtonPress() { + * tracker.reset(); // User activity detected, restart timeout + * // Handle button press... + * } + * @endcode + */ void reset(); + + /** + * @brief Enables or disables inactivity monitoring + * @param enabled True to enable monitoring, false to disable + * + * @details This method controls whether the inactivity tracker actively + * monitors for timeouts. When disabled, the elapsed time counter + * is not updated during update() calls, effectively pausing the + * timeout detection without losing the current elapsed time state. + * + * Use cases for disabling: + * - Temporary suspension during system operations + * - Context-sensitive monitoring (disable in certain application states) + * - Power management control (disable during low-power modes) + * - User preference settings (allow users to disable timeouts) + * - Development and debugging (disable for testing) + * + * When re-enabled, monitoring resumes from the current elapsed time state, + * allowing for seamless pause/resume functionality. + * + * @post Monitoring state is updated according to the enabled parameter + * + * @note Disabling the tracker does not reset the elapsed time counter. + * @note The timeout callback will not be executed while disabled, even + * if the timeout threshold would otherwise be exceeded. + * @note Enabling/disabling can be done at any time during operation. + * + * Example usage: + * @code + * tracker.setEnabled(false); // Pause monitoring during critical operation + * performCriticalOperation(); + * tracker.setEnabled(true); // Resume monitoring after completion + * @endcode + */ void setEnabled(bool enabled); private: - uint64_t m_timeoutMs; - uint64_t m_elapsedTime; - bool m_enabled; - std::function m_onTimeout; -}; + uint64_t m_timeoutMs; ///< Timeout duration in milliseconds before callback execution + uint64_t m_elapsedTime; ///< Current elapsed time since last reset in milliseconds + bool m_enabled; ///< Flag indicating whether monitoring is currently active + std::function m_onTimeout; ///< Callback function executed when timeout threshold is reached +}; \ No newline at end of file diff --git a/components/insa/include/common/Widget.h b/components/insa/include/common/Widget.h index d101faa..e1b27c1 100644 --- a/components/insa/include/common/Widget.h +++ b/components/insa/include/common/Widget.h @@ -51,9 +51,58 @@ class Widget */ virtual ~Widget() = default; + /** + * @brief Called when the widget becomes active or enters the foreground + * @details This method is invoked when the widget transitions from inactive + * to active state, such as when it becomes the current screen or + * gains focus. Derived classes can override this method to perform + * initialization tasks, reset state, or prepare for user interaction. + * + * @note The base implementation is empty, allowing derived classes to override + * only if entry behavior is needed. + * @note This method is typically called by the UI management system during + * screen transitions or focus changes. + */ virtual void enter(); + + /** + * @brief Called when the widget is temporarily paused or loses focus + * @details This method is invoked when the widget needs to suspend its + * operations temporarily, such as when another widget takes focus + * or the system enters a paused state. Derived classes can override + * this method to pause animations, save state, or reduce resource usage. + * + * @note The base implementation is empty, allowing derived classes to override + * only if pause behavior is needed. + * @note The widget should be prepared to resume from this state when resume() is called. + */ virtual void pause(); + + /** + * @brief Called when the widget resumes from a paused state + * @details This method is invoked when the widget transitions from paused + * to active state, typically after a previous pause() call. Derived + * classes can override this method to restore animations, reload + * resources, or continue interrupted operations. + * + * @note The base implementation is empty, allowing derived classes to override + * only if resume behavior is needed. + * @note This method should restore the widget to the state it was in before pause() was called. + */ virtual void resume(); + + /** + * @brief Called when the widget is being destroyed or exits the system + * @details This method is invoked when the widget is about to be removed + * from the system or transitions to an inactive state permanently. + * Derived classes can override this method to perform cleanup tasks, + * save final state, or release resources that are not automatically freed. + * + * @note The base implementation is empty, allowing derived classes to override + * only if exit behavior is needed. + * @note This method is called before the widget's destructor and provides + * an opportunity for controlled shutdown of widget-specific resources. + */ virtual void exit(); /** diff --git a/components/insa/include/ui/ScreenSaver.h b/components/insa/include/ui/ScreenSaver.h index d406b57..433580d 100644 --- a/components/insa/include/ui/ScreenSaver.h +++ b/components/insa/include/ui/ScreenSaver.h @@ -1,36 +1,397 @@ +/** + * @file ScreenSaver.h + * @brief Animated screensaver implementation with starfield effect + * @details This header defines the ScreenSaver class which provides an animated + * starfield screensaver that activates during periods of user inactivity. + * The screensaver displays moving stars to prevent screen burn-in while + * providing visual feedback that the system is still active and responsive. + * @author System Control Team + * @date 2025-06-14 + */ + #pragma once #include "MenuOptions.h" #include "common/Widget.h" #include +/** + * @class ScreenSaver + * @brief Animated starfield screensaver widget for system idle periods + * @details This final class inherits from Widget and implements an interactive + * screensaver featuring an animated starfield effect. The screensaver + * activates automatically during periods of user inactivity to prevent + * screen burn-in while maintaining visual indication of system activity. + * + * The ScreenSaver class provides: + * - Dynamic starfield animation with pseudo-3D depth effect + * - Configurable star count and animation speed parameters + * - Automatic activation during idle periods + * - Immediate deactivation on any user input + * - Smooth star movement and regeneration system + * - Memory-efficient star management with object pooling + * + * Key features include: + * - 3D-style starfield with depth-based speed variation + * - Continuous star recycling for infinite animation + * - Responsive user input handling for immediate exit + * - Optimized rendering for smooth animation performance + * - Configurable animation parameters for different visual effects + * + * The starfield effect simulates movement through space by moving stars + * from the center outward at speeds proportional to their depth (z-coordinate). + * Stars that move beyond the screen boundaries are automatically recycled + * to new random positions, creating an infinite scrolling effect. + * + * @note This class is marked as final and cannot be inherited from. + * @note The screensaver automatically exits on any button press, returning + * control to the previous screen or main menu interface. + * + * @see Widget for base widget functionality + * @see menu_options_t for configuration structure + * @see InactivityTracker for automatic screensaver activation + */ class ScreenSaver final : public Widget { public: + /** + * @brief Constructs the screensaver with specified configuration + * @param options Pointer to menu options configuration structure + * + * @pre options must not be nullptr and must remain valid for the screensaver's lifetime + * @pre options->u8g2 must be initialized and ready for graphics operations + * @pre Screen transition callbacks in options must be properly configured + * @post ScreenSaver is initialized with starfield ready for animation + * + * @details The constructor initializes the screensaver by: + * - Setting up the star field with initial random positions + * - Configuring animation timing and speed parameters + * - Preparing graphics context for efficient rendering + * - Initializing the animation counter for smooth timing + * - Allocating and positioning all star objects + * + * During initialization, all stars are placed at random positions within + * the 3D space defined by Z_NEAR and Z_FAR constants. Each star receives + * random x, y coordinates and a z-depth that determines its movement speed + * and visual appearance. The animation system is prepared for immediate + * activation when the screensaver becomes active. + * + * @note The screensaver does not take ownership of the options structure + * and assumes it remains valid throughout the screensaver's lifetime. + * @note Initial star positions are randomized to create immediate visual + * interest when the screensaver first activates. + * + * @see Widget::Widget for base class construction details + * @see initStars for star field initialization process + */ explicit ScreenSaver(menu_options_t *options); + /** + * @brief Updates the screensaver animation and star positions + * @param dt Delta time in milliseconds since the last update call + * + * @details Overrides the base Widget update method to handle screensaver-specific + * animation logic including: + * - Advancing the animation counter for smooth timing control + * - Updating individual star positions based on their speed and depth + * - Moving stars outward from center based on their z-coordinate + * - Recycling stars that move beyond screen boundaries + * - Maintaining consistent animation frame rate regardless of system load + * + * The update method implements the core starfield animation by: + * - Incrementing each star's position based on its depth-determined speed + * - Checking boundary conditions for stars moving off-screen + * - Resetting off-screen stars to new random positions near the center + * - Applying speed multipliers for smooth, consistent motion + * - Managing the animation counter for timing-dependent effects + * + * Star movement calculation: + * - Stars closer to the camera (smaller z values) move faster + * - Movement speed is inversely proportional to z-coordinate + * - Stars maintain consistent outward direction from screen center + * - Boundary checking ensures smooth recycling without visual gaps + * + * @note This method is called every frame while the screensaver is active + * and must be efficient to maintain smooth 60+ FPS animation. + * @note The animation continues indefinitely until user input is received. + * + * @see Widget::update for the base update interface + * @see resetStar for star recycling implementation + */ void update(uint64_t dt) override; + + /** + * @brief Renders the animated starfield to the display + * + * @details Overrides the base Widget render method to draw the animated starfield + * effect. The rendering process includes: + * - Clearing the display buffer for clean animation frames + * - Calculating screen positions for each star based on 3D coordinates + * - Applying perspective projection to simulate depth + * - Drawing stars with size/brightness based on distance + * - Optimizing drawing operations for smooth frame rates + * + * The render method creates a convincing 3D starfield effect by: + * - Converting 3D star coordinates to 2D screen positions + * - Scaling star positions based on perspective projection + * - Varying star appearance (size, brightness) based on depth + * - Drawing only stars within the visible screen area + * - Using efficient drawing primitives for optimal performance + * + * Rendering optimizations include: + * - Culling stars outside the visible area + * - Using simple pixel/point drawing for maximum speed + * - Minimizing graphics context switches + * - Batching drawing operations where possible + * + * The visual effect simulates movement through a star field by: + * - Making distant stars appear smaller and dimmer + * - Scaling star positions relative to screen center + * - Creating smooth motion blur effects for fast-moving stars + * + * @pre u8g2 display context must be initialized and ready for drawing + * @post Starfield animation frame is drawn to the display buffer + * + * @note This method is called every frame and must be highly optimized + * to maintain smooth animation performance on embedded systems. + * @note The visual design provides an engaging screensaver that clearly + * indicates system activity while preventing screen burn-in. + * + * @see Widget::render for the base render interface + */ void render() override; + + /** + * @brief Handles user input to exit the screensaver immediately + * @param button The type of button that was pressed by the user + * + * @details Overrides the base Widget button handling to provide immediate + * screensaver exit functionality. Any button press while the screensaver + * is active will: + * - Immediately terminate the screensaver animation + * - Return to the previous screen or main menu + * - Reset any inactivity timers to prevent immediate reactivation + * - Ensure responsive system behavior for user interaction + * + * The method handles all button types uniformly since the screensaver should + * exit on any user input regardless of the specific button pressed. This + * ensures maximum responsiveness and intuitive behavior - users expect any + * interaction to wake the system from screensaver mode. + * + * Button handling includes: + * - Immediate screensaver termination regardless of button type + * - Automatic transition back to the previous active screen + * - Inactivity timer reset to prevent immediate screensaver reactivation + * - Proper state cleanup to ensure system stability + * + * @note This method ensures the screensaver never interferes with normal + * system operation - any user input immediately restores full functionality. + * @note The screensaver exit process is designed to be instantaneous to + * provide the most responsive user experience possible. + * + * @see Widget::onButtonClicked for the base input handling interface + * @see ButtonType for available button input types + */ void onButtonClicked(ButtonType button) override; private: + /** + * @struct Star + * @brief Individual star object structure for starfield animation + * @details Defines the properties and state of a single star in the animated + * starfield. Each star maintains its position in 3D space and movement + * characteristics needed for realistic animation and perspective effects. + * + * The Star structure contains: + * - 3D spatial coordinates (x, y, z) for position tracking + * - Individual speed multiplier for varied animation effects + * - All data needed for perspective projection and movement calculation + * + * Star coordinate system: + * - x, y: Screen-relative coordinates (can be negative for off-screen positioning) + * - z: Depth coordinate determining speed and perspective (Z_NEAR to Z_FAR range) + * - speed: Individual multiplier for varied star movement rates + * + * @note This structure is designed for efficient memory usage and fast + * mathematical operations during animation updates. + * @note All coordinates use float precision for smooth animation interpolation. + */ struct Star { - float x; - float y; - float z; - float speed; + float x; ///< Horizontal position coordinate (screen-relative) + float y; ///< Vertical position coordinate (screen-relative) + float z; ///< Depth coordinate (determines speed and perspective) + float speed; ///< Individual speed multiplier for animation variation }; + /** + * @brief Pointer to menu options configuration structure + * @details Stores a reference to the menu configuration passed during construction. + * Provides access to the display context for rendering operations and + * screen transition callbacks for exiting the screensaver on user input. + * + * The configuration enables: + * - Display context (u8g2) for starfield graphics rendering + * - Screen transition callbacks for returning to previous screen + * - System integration for proper screensaver lifecycle management + * + * @note This pointer is not owned by the ScreenSaver and must remain valid + * throughout the screensaver's lifetime. + */ menu_options_t *m_options; + + /** + * @brief Animation timing counter for smooth frame rate control + * @details Tracks elapsed time for animation timing and frame rate calculations. + * Used to ensure consistent star movement regardless of system load + * variations and to provide smooth interpolation between animation frames. + * + * The counter enables: + * - Frame rate independent animation timing + * - Smooth interpolation for fluid star movement + * - Consistent animation speed across different hardware platforms + * - Precise timing control for animation effects + */ uint64_t m_animationCounter; + + /** + * @brief Vector container for all star objects in the starfield + * @details Manages the collection of Star objects that comprise the animated + * starfield effect. The vector provides efficient storage and iteration + * for the star animation system while maintaining good cache locality + * for optimal performance during update and render operations. + * + * The vector contains: + * - Fixed number of Star objects (NUM_STARS) allocated at initialization + * - Contiguous memory layout for efficient iteration during animation + * - Dynamic management capabilities for potential future enhancements + * + * @note The vector size is fixed at construction to avoid memory allocations + * during animation, ensuring consistent frame timing performance. + */ std::vector m_stars; + /** + * @brief Total number of stars in the animated starfield + * @details Defines the constant number of star objects that will be created + * and animated in the starfield effect. This value balances visual + * richness with performance requirements for smooth animation. + * + * The star count affects: + * - Visual density and richness of the starfield effect + * - Performance requirements for update and rendering operations + * - Memory usage for star object storage + * - Overall visual impact of the screensaver + * + * @note This value is tuned for optimal performance on target hardware + * while providing an engaging visual effect. + */ static constexpr int NUM_STARS = 10; + + /** + * @brief Global speed multiplier for star animation + * @details Controls the overall speed of star movement in the starfield animation. + * This multiplier is applied to all star movement calculations to provide + * consistent, smooth animation at an appropriate visual speed. + * + * The speed multiplier affects: + * - Overall pace of the starfield animation + * - Visual impact and engagement level of the screensaver + * - Performance requirements for smooth animation + * - User perception of system responsiveness + * + * @note This value is carefully tuned to provide engaging animation without + * being distracting or causing motion sickness effects. + */ static constexpr float SPEED_MULTIPLIER = 0.02f; + + /** + * @brief Near clipping plane for 3D starfield depth range + * @details Defines the closest distance (minimum z-coordinate) at which stars + * can exist in the 3D starfield space. Stars closer than this distance + * are considered too close to the viewer and are recycled to new positions. + * + * The near plane affects: + * - Minimum depth for star positioning and recycling + * - Perspective calculation range for realistic depth effects + * - Star recycling triggers for continuous animation + * - Visual depth range of the starfield effect + * + * @note This value works with Z_FAR to define the 3D space within which + * stars exist and animate, creating realistic depth perception. + */ static constexpr float Z_NEAR = 0.1f; + + /** + * @brief Far clipping plane for 3D starfield depth range + * @details Defines the farthest distance (maximum z-coordinate) at which stars + * can exist in the 3D starfield space. This establishes the back + * boundary of the starfield volume and affects initial star placement. + * + * The far plane affects: + * - Maximum depth for initial star positioning + * - Perspective calculation range for depth effects + * - Visual depth range and scale of the starfield + * - Initial star placement during system initialization + * + * @note This value works with Z_NEAR to create a realistic 3D space + * that provides convincing depth perception in the starfield animation. + */ static constexpr float Z_FAR = 10.0f; + /** + * @brief Initializes all stars with random positions and properties + * @details Private helper method that sets up the initial starfield by placing + * all stars at random positions within the defined 3D space. Called + * during construction to prepare the starfield for immediate animation. + * + * The initialization process: + * - Assigns random x, y coordinates within screen boundaries + * - Sets random z-depth within the Z_NEAR to Z_FAR range + * - Configures individual speed multipliers for animation variation + * - Ensures even distribution of stars throughout the 3D volume + * + * Random placement creates: + * - Natural, non-uniform star distribution for realistic appearance + * - Varied star depths for convincing 3D perspective effects + * - Immediate visual interest when screensaver first activates + * - Foundation for smooth continuous animation + * + * @note This method is called only once during construction to establish + * the initial starfield state before animation begins. + * + * @see resetStar for individual star repositioning during animation + */ void initStars(); + + /** + * @brief Resets a single star to a new random position for recycling + * @param star Reference to the Star object to be reset and repositioned + * + * @details Private helper method that recycles individual stars that have + * moved beyond the visible screen boundaries. This enables infinite + * starfield animation by continuously introducing new stars while + * removing those that are no longer visible. + * + * The reset process: + * - Places the star at a new random position near the screen center + * - Assigns a new random depth (z-coordinate) for varied movement speed + * - Configures new speed multiplier for animation variation + * - Ensures smooth transition without visual discontinuities + * + * Star recycling maintains: + * - Continuous starfield animation without visual gaps + * - Consistent star count throughout animation lifecycle + * - Varied star properties for natural, non-repetitive effects + * - Efficient memory usage through object reuse + * + * @pre star parameter must be a valid Star object reference + * @post star object is repositioned with new random properties ready for animation + * + * @note This method is called frequently during animation as stars move + * off-screen and must be efficient to maintain smooth frame rates. + * @note The repositioning algorithm ensures stars appear to emerge naturally + * from the center of the starfield for convincing 3D movement effects. + */ void resetStar(Star &star); -}; +}; \ No newline at end of file diff --git a/main/button_handling.h b/main/button_handling.h index 620048a..a5f87dc 100644 --- a/main/button_handling.h +++ b/main/button_handling.h @@ -1,10 +1,82 @@ +/** + * @file button_handling.h + * @brief Button input handling system for user interface interaction + * @details This header defines the button handling subsystem which manages + * hardware button inputs, debouncing, interrupt processing, and + * event queue management. It provides a robust foundation for + * reliable user input processing in embedded applications. + * @author System Control Team + * @date 2025-06-20 + */ + #pragma once #ifdef __cplusplus extern "C" { #endif + /** + * @brief Initializes the button handling subsystem and configures hardware + * + * @details This function sets up the complete button handling infrastructure: + * - GPIO configuration for button input pins with pull-up resistors + * - Interrupt service routine installation for responsive input + * - Debouncing timer creation and configuration + * - FreeRTOS queue creation for button event buffering + * - Button state tracking structure initialization + * + * The function configures all defined button pins to trigger interrupts + * on both rising and falling edges, enabling detection of both press + * and release events. Each button uses a dedicated timer for debouncing + * to ensure reliable input processing even with mechanical switch bounce. + * + * Button events are queued using FreeRTOS queues to ensure no input + * events are lost during high system activity periods. The queue-based + * approach also decouples interrupt handling from application processing. + * + * @pre ESP32 GPIO and timer subsystems must be available and functional + * @pre FreeRTOS must be running and queue services available + * @post All button pins are configured and ready for input detection + * @post Button event queue is created and ready for event processing + * @post Interrupt handlers are installed and active + * + * @note This function must be called during system initialization before + * any button input processing is expected + * @note The function configures hardware-specific GPIO pins as defined + * in the project configuration + * + * @see cleanup_buttons() for proper resource cleanup + */ void setup_buttons(void); + + /** + * @brief Cleans up button handling resources and disables interrupts + * + * @details This function performs complete cleanup of the button handling + * subsystem by: + * - Stopping and deleting all debouncing timers + * - Removing GPIO interrupt handlers from all button pins + * - Deleting the button event queue and freeing associated memory + * - Resetting button state tracking structures + * + * This cleanup function ensures proper resource management and prevents + * memory leaks when the button handling subsystem is no longer needed. + * It can be called during system shutdown or when reconfiguring the + * input handling subsystem. + * + * @pre Button handling subsystem must have been previously initialized + * @post All button-related interrupts are disabled and handlers removed + * @post All timers are stopped and deleted, freeing system resources + * @post Button event queue is deleted and memory is released + * @post GPIO pins are returned to default state + * + * @note This function should be called during system shutdown or when + * button handling is no longer required + * @note After calling this function, setup_buttons() must be called + * again before button input can be processed + * + * @see setup_buttons() for initialization of the button handling system + */ void cleanup_buttons(void); #ifdef __cplusplus } diff --git a/main/setup.h b/main/setup.h index 04434e0..8e28904 100644 --- a/main/setup.h +++ b/main/setup.h @@ -1,10 +1,70 @@ +/** + * @file setup.h + * @brief System initialization and main loop declarations for embedded application + * @details This header defines the core system initialization and main loop functions + * required for embedded ESP32 applications. It provides the essential entry + * points for hardware setup, system configuration, and continuous operation + * management following standard embedded system patterns. + * @author System Control Team + * @date 2025-06-20 + */ + #pragma once #ifdef __cplusplus extern "C" { #endif + /** + * @brief Initializes all system components and hardware peripherals + * + * @details This function performs complete system initialization including: + * - Hardware peripheral configuration (GPIO, I2C, SPI, etc.) + * - Display system initialization + * - Button and input device setup + * - Communication subsystem initialization + * - Memory and storage system preparation + * - Application-specific component initialization + * + * This function is called once during system startup before entering + * the main application loop. It ensures all required subsystems are + * properly configured and ready for operation. + * + * @pre System must be in a clean startup state + * @post All system components are initialized and ready for operation + * + * @note This function must complete successfully before loop() is called + * @note Any initialization failures should be handled gracefully with + * appropriate error reporting or system recovery + * + * @see loop() for the main application execution function + */ void setup(void); + + /** + * @brief Main application execution loop for continuous operation + * + * @details This function contains the main application logic that executes + * continuously after system initialization. It typically handles: + * - User input processing and event handling + * - Display updates and rendering operations + * - System state management and transitions + * - Background tasks and periodic operations + * - Communication handling and data processing + * - Power management and system monitoring + * + * The loop function is called repeatedly in an infinite cycle, providing + * the main execution context for the embedded application. It should be + * designed to execute efficiently without blocking to maintain system + * responsiveness. + * + * @note This function runs continuously and should not block indefinitely + * @note All operations within this function should be non-blocking or + * use appropriate task scheduling for time-consuming operations + * @note The function should handle all runtime errors gracefully + * + * @see setup() for system initialization before loop execution + */ void loop(void); #ifdef __cplusplus } diff --git a/src/Common.h b/src/Common.h index dc10420..dcf20a9 100644 --- a/src/Common.h +++ b/src/Common.h @@ -1,5 +1,60 @@ +/** + * @file Common.h + * @brief Common utility functions and window management for application framework + * @details This header defines common utility functions that are shared across + * the application framework. It provides essential functionality for + * window creation and management, serving as a bridge between the + * application layer and the underlying windowing system. + * @author System Control Team + * @date 2025-06-20 + */ + #pragma once #include "model/Window.h" -auto CreateWindow(const char *title, int width, int height) -> Window *; +/** + * @brief Creates a new window with specified title and dimensions + * @param title Null-terminated string containing the window title text + * @param width Window width in pixels + * @param height Window height in pixels + * @return Pointer to the newly created Window object, or nullptr on failure + * + * @pre title must not be nullptr and should contain valid display text + * @pre width and height must be positive values within system display limits + * @post A new Window object is allocated and initialized with the specified parameters + * @post The returned Window pointer is ready for use with window management functions + * + * @details This function creates a new Window instance with the specified + * title and dimensions. It handles the underlying window system + * initialization, memory allocation, and setup required to create + * a functional window object. + * + * The window creation process includes: + * - Memory allocation for the Window structure + * - Initialization of window properties (title, dimensions, state) + * - Registration with the window management system + * - Setup of default window behavior and event handling + * + * The returned window pointer can be used with other window management + * functions to display content, handle events, and manage the window + * lifecycle. The caller is responsible for properly managing the window + * lifetime and ensuring proper cleanup when the window is no longer needed. + * + * @note The returned pointer must be properly managed by the caller + * @note Window resources should be freed when no longer needed + * @note The title string is copied internally and can be safely modified + * or freed after this function returns + * + * @see Window class for window object interface and methods + * + * Example usage: + * @code + * auto* window = CreateWindow("System Control", 800, 600); + * if (window != nullptr) { + * // Use the window... + * // Clean up when done + * } + * @endcode + */ +auto CreateWindow(const char *title, int width, int height) -> Window *; \ No newline at end of file