App Class Reference

#include <app.h>

Inheritance diagram for App:

Collaboration diagram for App:

Public Types
enum class	UserNotification : uint8_t { Heartbeat = 0 }

Public Member Functions
	App (int port)
void	initRoutes () override
	Define the application's HTTP routes.
void	onStart () override
	Called once at task start before entering the main loop.
void	poll () override
	Called during every loop iteration for non-blocking background logic.
void	onEvent (const Event &e) override
	Called when an event is dispatched to this controller.
Public Member Functions inherited from FrameworkApp
	FrameworkApp (int port, const char *name="AppTask", uint16_t stackSize=2048, UBaseType_t priority=tskIDLE_PRIORITY+1)
	Constructor.
virtual	~FrameworkApp ()=default
	Virtual destructor.
virtual void	start ()
	Initializes the application and its framework services.
void	onStart () override
	Starts the Framework Manager.
Public Member Functions inherited from FrameworkController
	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.

Private Attributes
PicoModel	pico

Additional Inherited Members
Protected Member Functions inherited from FrameworkController
virtual TickType_t	getPollIntervalTicks ()
	Returns the polling interval in ticks used in run().
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 inherited from FrameworkApp
Router	router
	Router instance for handling HTTP routes.
HttpServer	server
	Embedded HTTP server instance.
FrameworkManager	manager
	Responsible for launching system services and networking.
Protected Attributes inherited from FrameworkController
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

Detailed Description

Definition at line 22 of file app.h.

Member Enumeration Documentation

UserNotification

enum class App::UserNotification : uint8_t

strong

Enumerator
Heartbeat

Definition at line 33 of file app.h.

                                : uint8_t { // user-defined notifications
        Heartbeat = 0
    };

Constructor & Destructor Documentation

App()

App::App

(

int

port

)

Definition at line 27 of file app.cpp.

                 : FrameworkApp(port, "AppTask", 1024, 3)
{
    
 
}

Member Function Documentation

initRoutes()

void App::initRoutes ( )

overridevirtual

You must implement this method in your subclass. Define your routes here using router.addRoute(...). This centralizes route logic and ensures all endpoints are registered before the server runs.

Example:

router.addRoute("GET", "/", [](HttpRequest& req, HttpResponse& res, const std::vector<std::string>&) {
    res.send("Hello from root!");
});

Or bind member functions:

router.addRoute("GET", "/status",
    std::bind(&MyApp::handleStatus, this, _1, _2, _3));

Reimplemented from FrameworkApp.

Definition at line 33 of file app.cpp.

{
    // This method is called by the base class to initialize HTTP routes.
    // You can add your application's routes here.
    // All FrameWorkController instances will have their initRoutes called
    // when the application starts, so you can add routes in your controllers.
    // See the GpioController and DashboardController classes for examples.
    // Add a simple route for testing
    router.addRoute("GET", "/", [](HttpRequest &req, HttpResponse &res, const auto &)
                    { res.send(DashboardView()); });
    router.addRoute("GET", "/hello", [](HttpRequest &req, HttpResponse &res, const auto &)
                    { res.send("Welcome to PicoFramework!"); });
    // Return the contents of the directory
    router.addRoute("GET", "/ls(.*)", [](HttpRequest &req, HttpResponse &res, const auto &match) {
            std::vector<FileInfo> files;
            AppContext::get<StorageManager>()->listDirectory(match.ordered[0], files);
            res.json(files);                  
    });                
}

References Router::addRoute(), AppContext::getTypeKey(), HttpResponse::json(), FrameworkApp::router, and HttpResponse::send().

Here is the call graph for this function:

onEvent()

void App::onEvent ( const Event &  event )

overridevirtual

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 FrameworkController.

Definition at line 108 of file app.cpp.

{
    // This method is called when an event is posted to the App's event queue.
    // It is called by the FrameworkController base class when an event is received.
    // You can handle different types of events here based on the notification kind.
    // For example, you can handle GPIO change events or user-defined events.
    // You subscribe for events in the onStart() method (for example), so this will be called
    // when an event is posted to the App's event queue. The Eventmanager operates as a true
    // publish-subscribe system, so you can post events from anywhere in the application
    // and they will be delivered to ALL subscribers that have registered for that event type.
 
    if (e.notification.kind == NotificationKind::System)
    {
        switch (e.notification.system)
        {
            case SystemNotification::GpioChange:
            {
                printf("[App] GpioChange received\n");
                printf("[App] Pin = %u, Edge = 0x%X\n", e.gpioEvent.pin, e.gpioEvent.edge);
 
                const GpioEvent &data = e.gpioEvent;
                printf("[App] GPIO changed - pin %u: %s\n",
                       data.pin,
                       (data.edge & GPIO_IRQ_EDGE_RISE) ? "rising" : (data.edge & GPIO_IRQ_EDGE_FALL) ? "falling" : "unknown");
                break;
            }
 
            case SystemNotification::NetworkReady:
                std::cout << "[App] Network ready. Starting services..." << std::endl;
                pico.onNetworkReady(); // Notify the PicoModel that the network is ready
                printf("[App] Network ready. Starting HTTP server...\n");
                server.start();
                break;    
 
            case SystemNotification::TimeValid: {
                std::cout << "[App] Time is valid." << std::endl;
                // at this point local time may equal UTC time or it may be the local time zone
                // depending on whether the local timezone has been acquired (async)
                // This example turns on that example, it is off by default
                std::string localTime = AppContext::get<TimeManager>()->formatTimeWithZone();
                printf("[App] UTC time: %s\n", localTime.c_str());
                break;
            }
            
            case SystemNotification::LocalTimeValid: {
                // This event is sent when the local time zone has been acquired
                // It will not occur if the DETECT_LOCAL_TIMEZONE flag is not set
                // in framework_user_config.h
                std::cout << "[App] Local Time is valid." << std::endl;
                std::string localTime = AppContext::get<TimeManager>()->formatTimeWithZone();
                printf("[App] Local time: %s\n", localTime.c_str());
                break;
            }
 
            case SystemNotification::TimeSync:
            std::cout << "[App] SNTP Time Sync event." << std::endl;
            // No need to do anything here, the time is valid - these occur every hour
            // SNTP time sync events are sent every hour by default
            // You can change the interval in framework_user_config.h
            // by setting the SNTP_SYNC_INTERVAL to a different value
            break;
 
            case SystemNotification::TimeInvalid:
                std::cout << "[App] Time is invalid. Running in degraded mode." << std::endl;
                // handle degraded state if needed
                break;
 
            default:
                break;
        }
    }
 
    if (e.notification.kind == NotificationKind::User &&
        e.notification.user_code == static_cast<uint8_t>(UserNotification::Heartbeat))
    {
        printf("[App] Heartbeat user event received\n");
    }
}

References GpioEvent::edge, AppContext::getTypeKey(), GpioChange, Event::gpioEvent, Heartbeat, Notification::kind, LocalTimeValid, NetworkReady, Event::notification, PicoModel::onNetworkReady(), pico, GpioEvent::pin, FrameworkApp::server, HttpServer::start(), System, Notification::system, TimeInvalid, TimeSync, TimeValid, User, and Notification::user_code.

Here is the call graph for this function:

onStart()

void App::onStart ( )

overridevirtual

Called once at task start before entering the main loop.

Override this to initialize controller state.

Override this to initialize controller state.

Reimplemented from FrameworkController.

Definition at line 53 of file app.cpp.

{
    // Call the base class to ensure the framework starts correctly.
    FrameworkApp::onStart();  
    
    pico.onStart(); // Initialize the PicoModel, which handles GPIO and other hardware interactions
 
    // These are two controllers derived from FrameworkController that add event support to the FrameworkTask base class.
    // They are started here to ensure they are ready to handle events and HTTP requests.
    std::cout << "[App] Initializing application..." << std::endl;
 
    static GpioController gpioController(router, pico);
    gpioController.start();
    static DashboardController dashboardController(router, pico);
    dashboardController.start();
 
    // Here we are setting up event handlers - we get the EventManager and GpioEventManager from the AppContext.
    EventManager* eventManager = AppContext::get<EventManager>();
    GpioEventManager* gpioEventManager = AppContext::get<GpioEventManager>();
 
    // Subscribe to GPIO change events
    // This will call onEvent() in this App class when a GPIO change event occurs.
    // Note: The GpioEventManager will call the gpio_event_handler() function when a GPIO interrupt occurs.
    // The gpio_event_handler() will then post an Event to the EventManager, which posts to the FRameworkController event queue.
    // FrameworkController has a waitAndDispatch function that polls the queue and will call onEvent() in this App class.
    // Events can be SystemNotification or UserNotification types, which are defined in enum class UserNotification (see the App.h file).
    eventManager->subscribe(eventMask(SystemNotification::GpioChange), this);
    gpioEventManager->enableInterrupt(16, GPIO_IRQ_EDGE_RISE | GPIO_IRQ_EDGE_FALL); 
    gpioEventManager->enableInterrupt(17, GPIO_IRQ_EDGE_RISE | GPIO_IRQ_EDGE_FALL); 
 
    eventManager->subscribe(eventMask(UserNotification::Heartbeat), this);
 
    std::cout << "[App] Waiting for network..." << std::endl;
    // Wait for the network to be ready before starting services
    // This is a blocking call that waits for the NetworkReady notification
    // You could use a non-blocking wait if you want to do other work in the meantime
    // waitfor is provided by the FrameworkTask base class and has a timeout parameter, unused here
    // The underlying imlementation uses FreeRTOS notifications
    //waitFor(SystemNotification::NetworkReady);
 
    //std::cout << "[App] Network ready. Starting services..." << std::endl;
    // Now that the network is ready, we can start services that depend on it
    // For example, you might want to start an HTTP server or other network services here
    //server.start();
    eventManager->subscribe(
        eventMask(
            SystemNotification::NetworkReady,
            SystemNotification::TimeValid,
            SystemNotification::TimeSync,
            SystemNotification::TimeInvalid,
            SystemNotification::LocalTimeValid
        ),
        this);
}

References GpioEventManager::enableInterrupt(), eventMask(), AppContext::getTypeKey(), GpioChange, Heartbeat, LocalTimeValid, NetworkReady, PicoModel::onStart(), FrameworkApp::onStart(), pico, FrameworkApp::router, FrameworkTask::start(), EventManager::subscribe(), TimeInvalid, TimeSync, and TimeValid.

Here is the call graph for this function:

poll()

void App::poll ( )

overridevirtual

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 from FrameworkController.

Definition at line 188 of file app.cpp.

{
    static int count = 0;
    if (count == 0) {
        printf("[App] Starting main polling loop...\n");
    }
    count++;
    vTaskDelay(pdMS_TO_TICKS(100)); // Yield to other tasks
    // This function is called continuously (non-blocking) from the App task.
    // Use RUN_EVERY to do periodic background work:
 
    runEvery(15000, [&]()
             { 
            printf("[App] Running main polling loop...\n"); 
            Event userEvt(static_cast<uint8_t>(UserNotification::Heartbeat));
            AppContext::get<EventManager>()->postEvent(userEvt);
            // this yield is not essential, but without yielding you can miss events
            vTaskDelay(pdMS_TO_TICKS(1)); }, "logLoop"); // <-- Unique ID for this timer (enables it to be cancelled)
}

References AppContext::getTypeKey(), Heartbeat, and FrameworkController::runEvery().

Here is the call graph for this function:

Member Data Documentation

pico

PicoModel App::pico

private

Definition at line 38 of file app.h.

Referenced by onEvent(), and onStart().

---

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

• app.h
• app.cpp