Codebase Architecture

This document provides a high-level overview of the PictoStick source code structure.

Directory Structure

  • src/: Contains all the C++ source code for the firmware. * main.cpp: The main entry point of the application. Handles initialization and the main loop. * ui*.cpp: Source files related to the user interface, built with the LVGL library. * system.cpp: Manages system-level functions like time, battery, and WiFi. * fs_helpers.cpp: Helper functions for interacting with the SPIFFS filesystem. * PSpref.cpp: Manages persistent storage of settings in NVS (Non-Volatile Storage).

  • include/: Contains all the header files (.h) corresponding to the source files in src/.

  • data/: Contains all files that will be uploaded to the device’s filesystem (SPIFFS). * picto/: The library of all available PNG picto images. * index.html, style.css: The web interface for managing activities. * data_*.json: The JSON files where the weekly activity schedules are stored.

  • lib/: This directory is managed by PlatformIO and contains all the external libraries the project depends on.

  • platformio.ini: The main configuration file for PlatformIO. It defines the board, framework, libraries, and build flags.

Core Components

Main Loop

The main.cpp file contains the setup() and loop() functions, which are standard in the Arduino framework.

  • setup(): Initializes hardware (display, buttons), filesystems, WiFi, and the user interface. It determines which mode the device should boot into (Normal, WiFi Config, Web Admin).

  • loop(): The main application loop. It primarily calls the LVGL task handler (lv_timer_handler()) which manages all UI rendering and interaction. It also handles button presses and power management.

User Interface (LVGL)

The user interface is built using the LVGL (Light and Versatile Graphics Library).

  • uimain.cpp is responsible for creating and managing the main screen, including the picto display, labels, and progress dots.

  • uisetup.cpp handles the on-device setup menu.

  • uiconfig.cpp manages the WiFi and Web Admin mode screens.

Data Flow

The activity schedules are stored as JSON files in the data/ directory.

  • When in Web Administration mode, the web server (ESPAsyncWebServer) serves the index.html and style.css files.

  • The web interface fetches the data_*.json files to display the current schedules.

  • When the caretaker saves the configuration, the web interface sends the new schedule data back to the device, which overwrites the corresponding data_*.json files on the filesystem.

  • In normal mode, the device reads the appropriate data_*.json file for the current day to load and display the activities.

Power Management

To conserve battery, the device makes use of several strategies:

  • Light Sleep: The ESP32 enters a light sleep mode when the screen is off.

  • WiFi Off: WiFi is only enabled when actively needed (initial time sync, web admin mode) and is turned off otherwise.

  • Screen Timeout: The screen backlight is turned off after a short period of inactivity.