EventBus

Thread-safe inter-task messaging

#include <EventBus.h>

Public Member Functions

void initialize ()
 
bool sendToUI (const Event &event, TickType_t timeout=0)
 
bool receiveFromMain (Event &event, TickType_t timeout=0)
 
bool sendToMain (const Event &event, TickType_t timeout=0)
 
bool receiveFromUI (Event &event, TickType_t timeout=0)
 
uint32_t getUIQueueCount () const
 
uint32_t getMainQueueCount () const
 
bool isInitialized () const
 
uint32_t getQueueCapacity () const
 
bool isUIQueueFull () const
 
bool isMainQueueFull () const
 
void logStatus () const
 
void getQueueStats (uint32_t &uiCount, uint32_t &mainCount, bool &uiFull, bool &mainFull) const
 

Static Public Member Functions

static EventBus & instance ()
 

Detailed Description

EventBus - Centralized Event Communication Hub

Manages thread-safe event distribution between system tasks using FreeRTOS queues. Implements singleton pattern to ensure single communication channel and resource sharing.

Design Principles:

  • Singleton for global accessibility and resource management
  • Separate queues for each direction to prevent deadlocks
  • Copy semantics for events to ensure thread safety
  • Configurable timeouts for responsive vs. reliable communication
  • Comprehensive monitoring for system health and debugging

Memory Usage:

  • 2 queues × 10 events × ~264 bytes = ~5.3KB RAM
  • Fixed allocation prevents heap fragmentation
  • Predictable memory footprint for system planning

Member Function Documentation

◆ getMainQueueCount()

uint32_t CloudMouse::EventBus::getMainQueueCount ( ) const

Get number of pending events in Main queue (UI→Core) Useful for monitoring queue depth and system load

Returns
Number of events waiting to be processed by Core task

◆ getQueueCapacity()

uint32_t CloudMouse::EventBus::getQueueCapacity ( ) const
inline

Get maximum queue capacity Returns configured queue size for capacity planning

Returns
Maximum number of events each queue can hold

◆ getQueueStats()

void CloudMouse::EventBus::getQueueStats ( uint32_t &  uiCount,
uint32_t &  mainCount,
bool &  uiFull,
bool &  mainFull 
) const
inline

Get detailed queue statistics Advanced diagnostics for performance analysis

Parameters
uiCountOutput parameter for UI queue depth
mainCountOutput parameter for Main queue depth
uiFullOutput parameter for UI queue full status
mainFullOutput parameter for Main queue full status

◆ getUIQueueCount()

uint32_t CloudMouse::EventBus::getUIQueueCount ( ) const

Get number of pending events in UI queue (Core→UI) Useful for monitoring queue depth and system load

Returns
Number of events waiting to be processed by UI task

◆ initialize()

void CloudMouse::EventBus::initialize ( )

Initialize EventBus queues and prepare for communication Creates FreeRTOS queues and validates successful allocation Must be called once during system initialization before any event operations

Note
Idempotent - safe to call multiple times
Not thread-safe - call only from main initialization thread

UI → Core Queue Creation Handles events flowing from UI task to Core task Examples: user input, configuration changes, UI requests

Core → UI Queue Creation
Handles events flowing from Core task to UI task Examples: display updates, status changes, error notifications

◆ instance()

static EventBus& CloudMouse::EventBus::instance ( )
inlinestatic

Get singleton EventBus instance Thread-safe lazy initialization with automatic cleanup

Returns
Reference to global EventBus instance

◆ isInitialized()

bool CloudMouse::EventBus::isInitialized ( ) const
inline

Check if EventBus is properly initialized Validates that both queues are created and operational

Returns
true if EventBus is ready for event operations

◆ isMainQueueFull()

bool CloudMouse::EventBus::isMainQueueFull ( ) const
inline

Check if Main queue is full Useful for implementing backpressure or alternative handling

Returns
true if Main queue cannot accept more events

◆ isUIQueueFull()

bool CloudMouse::EventBus::isUIQueueFull ( ) const
inline

Check if UI queue is full Useful for implementing backpressure or alternative handling

Returns
true if UI queue cannot accept more events

◆ logStatus()

void CloudMouse::EventBus::logStatus ( ) const

Log current queue status to Serial Debugging utility for system health monitoring Output format: "[EventBus] UI Queue: X, Main Queue: Y"

◆ receiveFromMain()

bool CloudMouse::EventBus::receiveFromMain ( Event &  event,
TickType_t  timeout = 0 
)

Receive event from Core task in UI task Retrieves next pending event from Core→UI queue

Parameters
eventReference to store received event data
timeoutMaximum wait time if queue is empty (FreeRTOS ticks) 0 = non-blocking (default) portMAX_DELAY = block until event available pdMS_TO_TICKS(ms) = wait up to specified milliseconds
Returns
true if event received successfully, false if queue empty or timeout

Usage Examples:

  • receiveFromMain(event) // Check for event, don't wait
  • receiveFromMain(event, pdMS_TO_TICKS(50)) // Wait up to 50ms
  • receiveFromMain(event, portMAX_DELAY) // Wait until event arrives

◆ receiveFromUI()

bool CloudMouse::EventBus::receiveFromUI ( Event &  event,
TickType_t  timeout = 0 
)

Receive event from UI task in Core task Retrieves next pending event from UI→Core queue

Parameters
eventReference to store received event data
timeoutMaximum wait time if queue is empty (FreeRTOS ticks)
Returns
true if event received successfully, false if queue empty or timeout

Common Use Cases:

  • Processing user input in main application logic
  • Handling configuration updates from UI
  • Responding to UI requests for data or actions

◆ sendToMain()

bool CloudMouse::EventBus::sendToMain ( const Event &  event,
TickType_t  timeout = 0 
)

Send event from UI task to Core task Queues event for Core task processing with optional timeout

Parameters
eventEvent to send (copied into queue)
timeoutMaximum wait time if queue is full (FreeRTOS ticks)
Returns
true if event queued successfully, false if queue full or timeout

Common Use Cases:

  • User input events (encoder clicks, button presses)
  • Configuration changes from UI
  • Requests for data updates or system actions

◆ sendToUI()

bool CloudMouse::EventBus::sendToUI ( const Event &  event,
TickType_t  timeout = 0 
)

Send event from Core task to UI task Queues event for UI task processing with optional timeout

Parameters
eventEvent to send (copied into queue)
timeoutMaximum wait time if queue is full (FreeRTOS ticks) 0 = non-blocking (default) portMAX_DELAY = block indefinitely pdMS_TO_TICKS(ms) = wait up to specified milliseconds
Returns
true if event queued successfully, false if queue full or timeout

Usage Examples:

  • sendToUI(Event(EventType::DISPLAY_UPDATE)) // Non-blocking
  • sendToUI(event, pdMS_TO_TICKS(100)) // Wait up to 100ms
  • sendToUI(event, portMAX_DELAY) // Block until space available