model-railway/system-control
1
0
Fork 0
Code Issues 1 Pull Requests Releases Activity

move into firmware subfolder

Browse Source 
Signed-off-by: Peter Siegmund <developer@mars3142.org>
This commit is contained in:
Peter Siegmund
2025-08-20 10:27:03 +02:00
parent d316bb9f2c
commit 5a08c2e09d
117 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
firmware/components/insa/include/common/Common.h Normal file
View File

@@ -0,0 +1,63 @@
/**
* @file Common.h
* @brief Common definitions and types for the INSA component
* @details This header file contains shared enumerations, type definitions, and
* callback function types used throughout the INSA component system.
* It provides the foundation for button handling and event management.
* @author System Control Team
* @date 2025-06-14
*/
#pragma once
#include <functional>
/**
* @enum ButtonType
* @brief Enumeration defining the different types of buttons available in the system
* @details This enumeration represents all possible button types that can be handled
* by the system's input management. NONE represents no button pressed or
* an invalid button state, while the other values correspond to specific
* directional and action buttons.
*/
enum class ButtonType
{
NONE, ///< No button pressed or invalid button state
UP, ///< Up directional button for navigation
DOWN, ///< Down directional button for navigation
LEFT, ///< Left directional button for navigation
RIGHT, ///< Right directional button for navigation
SELECT, ///< Select/confirm button for accepting choices
BACK ///< Back/cancel button for returning to previous state
};
// Forward declaration of MenuItem to avoid circular dependency
class MenuItem;
/**
* @typedef ButtonCallback
* @brief Type alias for button event callback function
* @details This function type is used to define callback functions that handle
* button press events. The callback receives information about which
* button was pressed and any additional context data.
*
* @param MenuItem menu item for the specific action
* @param ButtonType The type of button that was pressed
*
* @note The first parameter can be used to distinguish between multiple instances
* of the same button type or to pass additional event-specific data.
*
* @example
* @code
* ButtonCallback myCallback = [](const MenuItem& item, ButtonType type) {
* if (type == ButtonType::SELECT) {
* // Handle select button press
* processSelection(item);
* }
* };
* @endcode
*/
typedef std::function<void(MenuItem, ButtonType)> ButtonCallback;
// Include MenuItem.h after the typedef to avoid circular dependency
#include "data/MenuItem.h"

194
firmware/components/insa/include/common/InactivityTracker.h Normal file
View File

@@ -0,0 +1,194 @@
/**
* @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 <functional>
#include <stdint.h>
/**
* @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, const std::function<void()> &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; ///< 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<void()> m_onTimeout; ///< Callback function executed when timeout threshold is reached
};

223
firmware/components/insa/include/common/Menu.h Normal file
View File

@@ -0,0 +1,223 @@
/**
* @file Menu.h
* @brief Menu widget class for creating interactive menu systems
* @details This header defines the Menu class which extends the Widget base class
* to provide a comprehensive, customizable menu system supporting various
* types of interactive menu items including text buttons, selections,
* number inputs, and toggles. The menu supports navigation with directional
* input and provides visual feedback through selection highlighting and scrollbars.
* @author System Control Team
* @date 2025-06-14
*/
#pragma once
#include "Common.h"
#include "MenuOptions.h"
#include "Widget.h"
#include "data/MenuItem.h"
/**
* @class Menu
* @brief A comprehensive menu widget class for interactive user interfaces
* @details This class extends the Widget base class to provide a customizable menu system
* with support for various types of interactive menu items. It handles user input
* through directional navigation and action buttons, provides visual feedback
* through selection highlighting, and supports scrolling for long menu lists.
*
* The menu system supports four types of menu items:
* - Text buttons: Simple selectable text items
* - Selection items: Dropdown/list selection with multiple options
* - Number inputs: Numeric value adjustment controls
* - Toggle items: Boolean on/off switches
*
* @note Menu items are identified by unique IDs and can be dynamically added
* after menu creation.
*
* @see Widget
* @see MenuItem
* @see menu_options_t
*/
class Menu : public Widget
{
public:
/**
* @brief Constructs a new Menu instance with the specified configuration
* @param options Pointer to menu configuration options structure
*
* @pre options must not be nullptr and must remain valid for the menu's lifetime
* @post Menu is initialized with the provided configuration and ready for item addition
*
* @note The menu does not take ownership of the options structure and assumes
* it remains valid throughout the menu's lifetime.
*/
explicit Menu(menu_options_t *options);
/**
* @brief Destructor - Cleans up resources when menu is destroyed
* @details Properly releases any allocated resources and ensures clean shutdown
* of the menu system.
*/
~Menu() override;
/**
* @brief Adds a text-based menu item (button) to the menu
* @param id Unique identifier for this menu item (must be unique within the menu)
* @param text Display text shown on the menu item
*
* @pre id must be unique within this menu instance
* @post A new text menu item is added to the menu's item collection
*
* @note Text items act as buttons and generate selection events when activated
*/
void addText(uint8_t id, const std::string &text);
void addTextCounter(uint8_t id, const std::string &text, const uint8_t value);
/**
* @brief Adds a selection menu item (dropdown/list selection) to the menu
* @param id Unique identifier for this menu item (must be unique within the menu)
* @param text Display text/label for the selection item
* @param values Vector of all available options to choose from
* @param index Reference to current selected value (will be modified by user interaction)
*
* @pre id must be unique within this menu instance
* @pre values vector must not be empty
* @pre value must be one of the strings in the values vector
* @post A new selection menu item is added with the specified options
*
* @note The value parameter is modified directly when the user changes the selection
*/
void addSelection(uint8_t id, const std::string &text, const std::vector<std::string> &values, int index);
/**
* @brief Adds a toggle/checkbox menu item to the menu
* @param id Unique identifier for this menu item (must be unique within the menu)
* @param text Display text/label for the toggle item
* @param selected Current state of the toggle (true = on/enabled, false = off/disabled)
*
* @pre id must be unique within this menu instance
* @post A new toggle menu item is added with the specified initial state
*
* @note Toggle state can be changed through user interaction with select button
*/
void addToggle(uint8_t id, const std::string &text, bool selected);
protected:
/**
* @brief Virtual callback method for handling button press events on specific menu items
* @param item The menu item that received the button press
* @param button The type of button that was pressed
*
* @details This method can be overridden by derived classes to implement custom
* button handling logic for specific menu items. The base implementation
* is empty, allowing derived classes to selectively handle events.
*
* @note Override this method in derived classes to implement custom menu item
* interaction behavior beyond the standard navigation and value modification.
*/
virtual void onButtonPressed(const MenuItem &item, const ButtonType button)
{
// Base implementation intentionally empty - override in derived classes as needed
}
/**
* @brief Retrieves a menu item by its index position
* @param index Zero-based index of the menu item to retrieve
* @return MenuItem object at the specified index
*
* @pre index must be within valid range [0, getItemCount()-1]
* @post Returns a copy of the menu item at the specified position
*
* @throws std::out_of_range if index is invalid
*
* @note This method returns a copy of the menu item, not a reference
*/
MenuItem getItem(int index);
/**
* @brief Gets the total number of menu items in the menu
* @return Size of the menu items collection
*
* @post Returns current count of menu items (>= 0)
*
* @note This count includes all types of menu items (text, selection, toggle)
*/
[[nodiscard]] size_t getItemCount() const;
/**
* @brief Dynamically adjusts the number of menu items to the specified size
* @param size Target number of menu items the menu should contain
*
* @details If the target size is larger than current item count, new selection
* items are added using the first item's values as template. If the
* target size is smaller, excess items are removed from the end.
*
* @pre size must be > 0 and at least one menu item must exist as template
* @post Menu contains exactly 'size' number of items
*
* @note New items are created as selection items with auto-generated names
* in the format "Section X" where X is the item number
*/
void setItemSize(size_t size);
/**
* @brief Toggles the boolean state of a toggle menu item
* @param menuItem The toggle menu item whose state should be flipped
*
* @pre menuItem must be of type TOGGLE
* @post The menu item's value is switched between "true" and "false"
*
* @details Changes "true" to "false" and "false" to "true" for toggle items.
* The modified item replaces the original in the menu's item collection.
*
* @note This method directly modifies the menu's internal state
*/
void toggle(const MenuItem &menuItem);
/**
* @brief Changes the selected value of a selection menu item based on button input
* @param menuItem The selection menu item to modify
* @param button The directional button pressed (LEFT or RIGHT)
*
* @pre menuItem must be of type SELECTION with valid values array
* @post The menu item's selected index is adjusted based on button direction
*
* @details LEFT button moves to previous option (wraps to end if at beginning),
* RIGHT button moves to next option (wraps to beginning if at end).
* Other button types are ignored.
*
* @note The modified item replaces the original in the menu's item collection
*/
MenuItem switchValue(const MenuItem &menuItem, ButtonType button);
private:
MenuItem replaceItem(int index, const MenuItem &item);
void render() override;
void onButtonClicked(ButtonType button) override;
void onPressedDown();
void onPressedUp();
void onPressedLeft() const;
void onPressedRight() const;
void onPressedSelect() const;
void onPressedBack() const;
void drawScrollBar() const;
void drawSelectionBox() const;
void renderWidget(const MenuItem *item, const uint8_t *font, int x, int y) const;
// Member variables
size_t m_selected_item = 0;
std::vector<MenuItem> m_items;
menu_options_t *m_options;
};

106
firmware/components/insa/include/common/ScrollBar.h Normal file
View File

@@ -0,0 +1,106 @@
/**
* @file ScrollBar.h
* @brief Vertical scrollbar widget for indicating scroll position in long content
* @details This header defines the ScrollBar class which provides a visual scrollbar
* widget for indicating the current position within scrollable content.
* The scrollbar displays a thumb that moves proportionally to represent
* the current scroll position and visible area relative to the total content.
* @author System Control Team
* @date 2025-06-14
*/
#pragma once
#include "MenuOptions.h"
#include "Widget.h"
/**
* @class ScrollBar
* @brief A vertical scrollbar widget that represents scroll position and range
* @details This final class inherits from Widget and provides visual feedback for
* scrollable content. It displays a vertical track with a movable thumb
* that indicates the current position within a scrollable range. The thumb
* size is proportional to the visible area relative to the total content,
* and its position reflects the current scroll offset.
*
* The scrollbar automatically calculates thumb dimensions and position based on
* the provided scroll values (current, minimum, maximum). It is designed to be
* used alongside scrollable content like menus or lists to provide visual
* feedback about scroll state.
*
* @note This class is marked as final and cannot be inherited from.
*
* @see Widget
* @see menu_options_t
*/
class ScrollBar final : public Widget
{
public:
/**
* @brief Constructs a ScrollBar with specified position and dimensions
* @param options Pointer to menu options configuration structure
* @param x X coordinate position of the scrollbar on screen
* @param y Y coordinate position of the scrollbar on screen
* @param width Width of the scrollbar in pixels
* @param height Height of the scrollbar in pixels
*
* @pre options must not be nullptr and must remain valid for the scrollbar's lifetime
* @pre width and height must be greater than 0
* @pre x and y must be valid screen coordinates
* @post ScrollBar is initialized with the specified geometry and ready for use
*
* @note The scrollbar does not take ownership of the options structure and
* assumes it remains valid throughout the scrollbar's lifetime.
*/
ScrollBar(const menu_options_t *options, size_t x, size_t y, size_t width, size_t height);
/**
* @brief Renders the scrollbar to the screen
* @details Overrides the base Widget render method to draw the scrollbar track
* and thumb. The appearance is determined by the current scroll state
* and the menu options configuration.
*
* @pre u8g2 display context must be initialized and ready for drawing
* @post Scrollbar's visual representation is drawn to the display buffer
*
* @note This method is called during each frame's render cycle. The scrollbar
* track and thumb are drawn based on the current scroll values set by refresh().
*/
void render() override;
/**
* @brief Updates the scrollbar state with new scroll values
* @param value Current scroll position value (must be between min and max)
* @param max Maximum scroll value (total content size)
* @param min Minimum scroll value (default: 0, typically the start of content)
*
* @pre value must be between min and max (inclusive)
* @pre max must be greater than or equal to min
* @post Scrollbar thumb position and size are recalculated based on new values
*
* @details This method recalculates the thumb's height and vertical position
* based on the provided scroll range and current position. The thumb
* height represents the proportion of visible content to total content,
* while its position represents the current scroll offset within the range.
*
* @note Call this method whenever the scroll state changes to keep the
* scrollbar visualization synchronized with the actual content position.
*/
void refresh(size_t value, size_t max, size_t min = 0);
private:
// Position and dimensions
size_t m_x; ///< X coordinate of the scrollbar's left edge
size_t m_y; ///< Y coordinate of the scrollbar's top edge
size_t m_width; ///< Width of the scrollbar track in pixels
size_t m_height; ///< Height of the scrollbar track in pixels
// Scroll state values
size_t m_value; ///< Current scroll position within the range [m_min, m_max]
size_t m_max; ///< Maximum scroll value representing the end of content
size_t m_min; ///< Minimum scroll value representing the start of content
// Calculated thumb properties (updated by refresh())
size_t m_thumbHeight; ///< Calculated height of the scroll thumb in pixels
size_t m_thumbY; ///< Calculated Y position of the scroll thumb relative to track
};

168
firmware/components/insa/include/common/Widget.h Normal file
View File

@@ -0,0 +1,168 @@
/**
* @file Widget.h
* @brief Base widget class for UI components in the INSA system
* @details This header defines the Widget base class that serves as the foundation
* for all UI components in the system. It provides a standardized interface
* for rendering, updating, and handling user input using the u8g2 graphics library.
* @author System Control Team
* @date 2025-06-14
*/
#pragma once
#include "u8g2.h"
#include "common/Common.h"
/**
* @class Widget
* @brief Base class for UI widgets that can be rendered and interact with user input
* @details This abstract base class provides a common interface for all widgets in the system.
* It manages the u8g2 display context and defines the core methods that all widgets
* must implement or can override. The class follows the template method pattern,
* allowing derived classes to customize behavior while maintaining a consistent
* interface for the UI system.
*
* @note All widgets should inherit from this class to ensure compatibility with
* the UI management system.
*
* @see u8g2_t
* @see ButtonType
*/
class Widget
{
public:
/**
* @brief Constructs a widget with the given u8g2 display context
* @param u8g2 Pointer to the u8g2 display context used for rendering operations
*
* @pre u8g2 must not be nullptr
* @post Widget is initialized with the provided display context
*
* @note The widget does not take ownership of the u8g2 context and assumes
* it remains valid for the lifetime of the widget.
*/
explicit Widget(u8g2_t *u8g2);
/**
* @brief Virtual destructor to ensure proper cleanup of derived classes
* @details Ensures that derived class destructors are called correctly when
* a widget is destroyed through a base class pointer.
*/
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();
/**
* @brief Updates the widget's internal state based on elapsed time
* @param dt Delta time in milliseconds since the last update call
*
* @details This method is called once per frame by the UI system to handle
* animations, timers, state transitions, or other time-dependent behavior.
* The base implementation is empty, allowing derived classes to override
* only if time-based updates are needed.
*
* @note Override this method in derived classes to implement time-based behavior
* such as animations, blinking effects, or timeout handling.
*/
virtual void update(uint64_t dt);
/**
* @brief Renders the widget to the display
* @details This method should be overridden by derived classes to implement
* their specific rendering logic using the u8g2 display context.
* The base implementation is empty, requiring derived classes to
* provide their own rendering code.
*
* @pre u8g2 context must be initialized and ready for drawing operations
* @post Widget's visual representation is drawn to the display buffer
*
* @note This method is called during the rendering phase of each frame.
* Derived classes should use the u8g2 member variable to perform
* drawing operations.
*/
virtual void render();
/**
* @brief Handles button press events
* @param button The type of button that was pressed
*
* @details This method is called when a button press event occurs and allows
* the widget to respond to user input. The base implementation is empty,
* allowing derived classes to override only if input handling is needed.
*
* @note Override this method in derived classes to implement button-specific
* behavior such as navigation, selection, or state changes.
*
* @see ButtonType for available button types
*/
virtual void onButtonClicked(ButtonType button);
protected:
/**
* @brief Pointer to the u8g2 display context used for rendering operations
* @details This member provides access to the u8g2 graphics library functions
* for drawing text, shapes, bitmaps, and other UI elements. It is
* initialized during construction and remains valid for the widget's lifetime.
*
* @note This member is protected to allow derived classes direct access while
* preventing external modification. Derived classes should use this
* context for all rendering operations.
*
* @warning Do not modify or delete this pointer. The widget does not own
* the u8g2 context and assumes it is managed externally.
*/
u8g2_t *u8g2;
};