FrameworkController Class Reference

Base class for event-driven control logic in embedded applications. More...

#include <FrameworkController.h>

Inheritance diagram for FrameworkController:

Collaboration diagram for FrameworkController:

Public Member Functions
	FrameworkController (const char *name, Router &sharedRouter, uint16_t stackSize=1024, UBaseType_t priority=tskIDLE_PRIORITY+1)
	Constructor.
void	run () override final
	Main task loop.
const char *	getName () const
	Get the name of this controller.
void	enableEventQueue (size_t depth=8)
	Enable the event queue for this controller.
QueueHandle_t	getEventQueue () const
	Get the event queue for this controller.
bool	getNextEvent (Event &event, uint32_t timeoutMs)
	Check if there are any pending events in the queue.
Public Member Functions inherited from FrameworkTask
	FrameworkTask (const char *name, uint16_t stackSize=1024, UBaseType_t priority=1)
	Constructor.
virtual	~FrameworkTask ()
	Destructor.
bool	start ()
	Starts the task via FreeRTOS.
void	suspend ()
	Suspends the task using vTaskSuspend().
void	resume ()
	Resumes the task using vTaskResume().
TaskHandle_t	getHandle () const
	Returns the FreeRTOS task handle.
const char *	getName () const
	Returns the task name.
void	notify (uint8_t index, uint32_t value=1)
	Sends a notification to this task using an index.
void	notify (Notification n, uint32_t value=1)
	Sends a notification using a framework-defined enum.
void	notifyFromISR (uint8_t index, uint32_t value=1, BaseType_t *pxHigherPriorityTaskWoken=nullptr)
	Sends a notification from an ISR (by index).
void	notifyFromISR (Notification n, uint32_t value=1, BaseType_t *pxHigherPriorityTaskWoken=nullptr)
	Sends a notification from ISR using enum identifier.
bool	waitFor (uint8_t index, TickType_t timeout=portMAX_DELAY)
	Waits for a notification (by index).
bool	waitFor (Notification n, TickType_t timeout=portMAX_DELAY)
	Waits for a notification (by enum identifier).
Notification	waitForAny (uint8_t index, uint32_t mask, TickType_t timeout=portMAX_DELAY)
	waits for any notification matching the given mask.

Protected Member Functions
virtual void	onStart ()
	Called once at task start before entering the main loop.
virtual void	initRoutes ()
	Initialize routes for this controller.
virtual void	onEvent (const Event &event)
	Called when an event is dispatched to this controller.
virtual TickType_t	getPollIntervalTicks ()
	Returns the polling interval in ticks used in run().
virtual void	poll ()
	Called during every loop iteration for non-blocking background logic.
void	runEvery (uint32_t intervalMs, const std::function< void()> &fn, const char *id)
	Run a function periodically with millisecond resolution.
Protected Member Functions inherited from FrameworkTask
uint32_t	waitFor (TickType_t timeout=portMAX_DELAY)
	Wait for any notification (default index).
bool	createQueue (size_t itemSize, size_t length)
	Creates an internal FreeRTOS queue.
bool	sendToQueue (const void *item, TickType_t timeout=0)
	Sends an item to the internal queue.
bool	receiveFromQueue (void *item, TickType_t timeout=portMAX_DELAY)
	Receives an item from the internal queue.

Protected Attributes
Router &	router
	Handles path-to-handler mapping - reference to shared Router instance.
Protected Attributes inherited from FrameworkTask
const char *	_name
uint16_t	_stackSize
UBaseType_t	_priority
TaskHandle_t	_handle = nullptr
QueueHandle_t	_queue = nullptr

Private Member Functions
void	waitAndDispatch (uint32_t timeoutMs=portMAX_DELAY)
	Waits for an event and dispatches it to onEvent() if applicable.

Private Attributes
std::unordered_map< std::string, TickType_t >	_timers
	Stores last-execution timestamps per ID.
QueueHandle_t	eventQueue_ = nullptr

Detailed Description

FrameworkController builds on FrameworkTask to offer structured hooks:

• onStart() – called once at task start
• onEvent() – called when an event is received
• poll() – called periodically for background work

It also includes a utility runEvery() to call a function at regular intervals.

Definition at line 53 of file FrameworkController.h.

Constructor & Destructor Documentation

FrameworkController()

FrameworkController::FrameworkController	(	const char *	name,
		Router &	sharedRouter,
		uint16_t	stackSize = 1024,
		UBaseType_t	priority = tskIDLE_PRIORITY + 1
	)

Parameters

name	Task name.
stackSize	Stack size in words.
priority	Task priority (default is one above idle).

Constructor for framework controllers.

Parameters

name	Task name.
sharedRouter	Reference to the shared Router instance.
stackSize	Task stack size (in words).
priority	Task priority.

Definition at line 39 of file FrameworkController.cpp.

    : FrameworkTask(name, stackSize, priority),
      router(sharedRouter) {}

Member Function Documentation

enableEventQueue()

void FrameworkController::enableEventQueue ( size_t  depth = 8 )

inline

Creates a FreeRTOS queue to hold events if it doesn't already exist. The queue depth can be specified, defaulting to 8.

Parameters

depth

Maximum number of events in the queue.

Definition at line 152 of file FrameworkController.h.

                                            {
        if (!eventQueue_) {
            eventQueue_ = xQueueCreate(depth, sizeof(Event));
        }
    }

References eventQueue_.

Referenced by run().

Here is the caller graph for this function:

getEventQueue()

QueueHandle_t FrameworkController::getEventQueue ( ) const

inline

Returns the FreeRTOS queue handle used to hold events. This queue is used to post events from other tasks or ISRs.

Definition at line 163 of file FrameworkController.h.

                                        {
        return eventQueue_;
    }

References eventQueue_.

getName()

const char * FrameworkController::getName ( ) const

inline

Returns

Controller name.

Definition at line 89 of file FrameworkController.h.

{ return FrameworkTask::getName(); }

References FrameworkTask::getName().

Here is the call graph for this function:

getNextEvent()

bool FrameworkController::getNextEvent ( Event &  event, uint32_t  timeoutMs  )

inline

Parameters

controller

Pointer to the controller to check.

Returns

True if there are pending events, false otherwise.

Definition at line 172 of file FrameworkController.h.

                                                        {
        return eventQueue_ && xQueueReceive(eventQueue_, &event, pdMS_TO_TICKS(timeoutMs)) == pdTRUE;
    }

References eventQueue_.

Referenced by waitAndDispatch().

Here is the caller graph for this function:

getPollIntervalTicks()

virtual TickType_t FrameworkController::getPollIntervalTicks ( )

inlineprotectedvirtual

Override this in subclasses if different polling frequency is needed.

Definition at line 119 of file FrameworkController.h.

                                              {
        return pdMS_TO_TICKS(100); // Default: 100ms
    }

Referenced by run().

Here is the caller graph for this function:

initRoutes()

void FrameworkController::initRoutes ( )

protectedvirtual

@bcopydoc FrameworkController::initRoutes

Override to define HTTP routes or other event handlers. This is called once at task start.

Reimplemented in FrameworkApp, App, DashboardController, and GpioController.

Definition at line 64 of file FrameworkController.cpp.

{
    // Default implementation does nothing
    // Override in derived classes to set up routes
}

Referenced by run().

Here is the caller graph for this function:

onEvent()

void FrameworkController::onEvent ( const Event &  event )

protectedvirtual

Called when an event is dispatched to this controller.

Override to implement your event-driven logic.

Override to implement your event-driven logic.

Reimplemented from FrameworkTask.

Reimplemented in App, and FrameworkManager.

Definition at line 71 of file FrameworkController.cpp.

{
    // Default: do nothing
}

Referenced by waitAndDispatch().

Here is the caller graph for this function:

onStart()

void FrameworkController::onStart ( )

protectedvirtual

Called once at task start before entering the main loop.

Override this to initialize controller state.

Override this to initialize controller state.

Reimplemented in FrameworkManager, FrameworkApp, and App.

Definition at line 57 of file FrameworkController.cpp.

{
    // can safely be overridden in derived classes
    // Default implementation does nothing
}

Referenced by FrameworkApp::onStart(), and run().

Here is the caller graph for this function:

poll()

void FrameworkController::poll ( )

protectedvirtual

Called during every loop iteration for non-blocking background logic.

Runs after waitAndDispatch() — useful for polling sensors or internal FSMs.

Runs after waitAndDispatch() — useful for polling sensors or internal FSMs.

Reimplemented in FrameworkManager, and App.

Definition at line 77 of file FrameworkController.cpp.

{
    // Default no-op
}

Referenced by run().

Here is the caller graph for this function:

run()

void FrameworkController::run ( )

finaloverridevirtual

Main task loop.

Calls onStart() once, then enters a loop that:

• Waits for an event (or timeout)
• Dispatches it to onEvent()
• Calls poll() to perform non-blocking logic

Calls onStart() once, then enters a loop that:

• Waits for an event (or timeout)
• Dispatches it to onEvent()
• Calls poll() to perform non-blocking logic

Implements FrameworkTask.

Definition at line 44 of file FrameworkController.cpp.

{
    enableEventQueue();  // MUST be here to initialize queue before use
    initRoutes();        // Call initRoutes() to set up routes
    onStart();           // Call onStart() to initialize controller state
    while (true)
    {
        waitAndDispatch(getPollIntervalTicks()); // Wait for notifications or timeout
        poll();               // Call user logic
    }
}

References enableEventQueue(), getPollIntervalTicks(), initRoutes(), onStart(), poll(), and waitAndDispatch().

Here is the call graph for this function:

runEvery()

void FrameworkController::runEvery ( uint32_t  intervalMs, const std::function< void()> &  fn, const char *  id  )

protected

Run a function periodically with millisecond resolution.

Parameters

intervalMs	Time interval in milliseconds.
fn	Function to run.
id	Unique ID for this timed function (used to track last execution).

Parameters

intervalMs	Time interval in milliseconds.
fn	Function to run.
id	Unique ID for this timed function (used to track last execution).

Definition at line 93 of file FrameworkController.cpp.

{
    TickType_t now = xTaskGetTickCount();
    TickType_t &last = _timers[std::string(id)];
 
    if ((now - last) >= pdMS_TO_TICKS(intervalMs))
    {
        fn();
        last = now;
    }
}

References _timers.

Referenced by App::poll().

Here is the caller graph for this function:

waitAndDispatch()

void FrameworkController::waitAndDispatch ( uint32_t  timeoutMs = portMAX_DELAY )

private

Waits for an event and dispatches it to onEvent() if applicable.

If the event is targeted at this controller (or has no target), it will be passed to onEvent().

Parameters

timeoutMs

Maximum time to wait for an event in milliseconds.

If the event is targeted at this controller (or has no target), it will be passed to onEvent().

Parameters

timeoutMs

Maximum time to wait for an event in milliseconds.

Definition at line 83 of file FrameworkController.cpp.

{
    Event event;
    if (getNextEvent(event, timeoutMs))
    {
        onEvent(event);
    }
}

References getNextEvent(), and onEvent().

Referenced by run().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

_timers

std::unordered_map<std::string, TickType_t> FrameworkController::_timers

private

Definition at line 178 of file FrameworkController.h.

Referenced by runEvery().

eventQueue_

QueueHandle_t FrameworkController::eventQueue_ = nullptr

private

Definition at line 180 of file FrameworkController.h.

Referenced by enableEventQueue(), getEventQueue(), and getNextEvent().

router

Router& FrameworkController::router

protected

Definition at line 139 of file FrameworkController.h.

Referenced by DashboardController::initRoutes(), and GpioController::initRoutes().

---

The documentation for this class was generated from the following files:

• FrameworkController.h
• FrameworkController.cpp