Enumerates shell screens. Apps use SCREEN_APP plus AppDefinition metadata.

enum Screen {
    SCREEN_HOME = 0,
    SCREEN_T9_KEYBOARD = 2,
    SCREEN_QWERTY_ZOOM_KEYBOARD = 3,
    SCREEN_MENU = 4,
    SCREEN_APP = 5,
};

Groups launcher entries into menu pages.

enum MenuCategory {
    MENU_GAMES,
    MENU_APPS,
    MENU_NETWORK,
};

Normalized outcome for app hooks and runtime button handlers.

enum class AppEventResult : uint8_t {
    Unhandled,
    Handled,
    Dirty,
    QuitRequested,
    GoHome,
    GoMenu,
    Reboot,
};

Initialization tier available to a periodic hook during a deep-sleep wake.

enum class PeriodicWakeLevel : uint8_t {
    Basic = 1,
    System = 2,
    Network = 3,
};

E-paper initialization requested independently from a periodic wake tier.

enum class PeriodicDisplayMode : uint8_t {
    None = 0,
    Partial = 1,
    Full = 2,
};

Result returned by one invocation of an app's periodic hook.

enum class PeriodicTaskAction : uint8_t {
    Complete = 0,
    RequestSystem = 1,
    RequestNetwork = 2,
    WakeDevice = 3,
    WakeApp = 4,
};

Read-only capabilities and clock state supplied to a periodic hook.

struct PeriodicTaskContext {
    int64_t localUnix = 0;
    uint16_t intervalMinutes = 0;
    PeriodicWakeLevel wakeLevel = PeriodicWakeLevel::Basic;
    PeriodicDisplayMode displayMode = PeriodicDisplayMode::None;
    bool clockSet = false;
    bool wifiPreferred = false;
    bool wifiConnected = false;
    bool lowBattery = false;
    Adafruit_GFX *display = nullptr;
};

Static schedule for the single periodic hook an app may register.

struct PeriodicTaskSchedule {
    uint16_t intervalMinutes = 0;
    PeriodicWakeLevel wakeLevel = PeriodicWakeLevel::Basic;
    PeriodicDisplayMode displayMode = PeriodicDisplayMode::None;
};

Common runtime interface used to draw apps and dispatch touch input.

class ActiveApp {
    virtual ~ActiveApp() = default;
    virtual void draw(Adafruit_GFX &gfx) = 0;
    virtual bool handleTouch(const TouchPoint &point) = 0;
    virtual bool update();
    virtual AppEventResult consumePendingEvent();
    virtual bool consumeDirtyRegion(int16_t *, int16_t *, int16_t *, int16_t *);
    virtual bool hasActiveSession() const = 0;
};

Adapts an app object with touch support to the ActiveApp runtime contract.

template <typename T, bool SupportsUpdate = false> class AppScreen : public ActiveApp {
    explicit AppScreen(T &target);
    void draw(Adafruit_GFX &gfx) override;
    bool handleTouch(const TouchPoint &point) override;
    bool update() override;
    AppEventResult consumePendingEvent() override;
    bool consumeDirtyRegion(int16_t *x, int16_t *y, int16_t *w, int16_t *h) override;
    bool hasActiveSession() const override;
};

Adapts an app object that draws itself and exposes session state, while handling input through its own app-specific path instead of ActiveApp.

template <typename T> class TouchlessAppScreen : public ActiveApp {
    explicit TouchlessAppScreen(T &target);
    void draw(Adafruit_GFX &gfx) override;
    bool handleTouch(const TouchPoint &) override;
    bool hasActiveSession() const override;
};

Pointer to a parameterless app hook such as onEnter, onExit, launch, or reset.

typedef void (*AppCallback)();

Reports whether an app should appear in the launcher, such as when the Files app is only available while an SD card is mounted.

typedef bool (*AppVisibleHandler)();

Handles a button event such as onMenu or onPowerLong and returns an AppEventResult like GoHome or Reboot.

typedef AppEventResult (*AppEventHandler)();

Receives raw touch events before higher-level app dispatch.

typedef void (*AppRawTouchHandler)(const TouchEvent &event);

Saves app-owned state into a caller-provided buffer.

typedef size_t (*AppSaveContextHandler)(uint8_t *buffer, size_t capacity);

Restores app-owned state from a previously saved buffer.

typedef void (*AppRestoreContextHandler)(const uint8_t *buffer, size_t length);

Bundles runtime callbacks for one app, including lifecycle hooks like onEnter, onExit, and onRelease, button handlers such as onMenu and onPowerLong, raw touch handling, and state save/restore.

struct AppBehavior {
    AppCallback onEnter = nullptr;
    AppCallback onExit = nullptr;
    AppEventHandler onMenu = nullptr;
    AppEventHandler onMenuDouble = nullptr;
    AppEventHandler onMenuLong = nullptr;
    AppEventHandler onPower = nullptr;
    AppEventHandler onPowerDouble = nullptr;
    AppEventHandler onPowerLong = nullptr;
    AppRawTouchHandler onRawTouch = nullptr;
    AppSaveContextHandler onSaveContext = nullptr;
    AppRestoreContextHandler onRestoreContext = nullptr;
    AppPeriodicHandler onPeriodic = nullptr;
    PeriodicTaskSchedule periodic = {};
    AppCallback onRelease = nullptr;
};

Declares one app entry together with launcher metadata, including optional icon-font rendering and visibility conditions, the per-launch reset/launch hooks that run before switchTo(), and the AppBehavior callback bundle used after the app becomes active.

struct AppDefinition {
    const char *id;
    const char *label;
    const char *icon;
    MenuCategory category;
    ActiveApp *runtime;
    AppVisibleHandler visible = nullptr;
    bool iconFont = false;
    AppCallback launch = nullptr;
    AppCallback reset = nullptr;
    AppBehavior behavior = {};
    uint32_t inactivityDeepSleepMs = 0;
};

Stores the current launcher category and page for returning to the menu.

struct MenuState {
    MenuCategory category;
    uint8_t page;
};

Runtime-facing copy of one launcher entry from the built-in and external app catalogs.

struct AppCatalogEntry {
    AppDefinition definition;
    char id[24];
    char label[16];
    char icon[2];
};

Converts bool-returning app handlers into AppEventResult values for catalog behavior callbacks.

inline AppEventResult dirtyIfHandled(bool handled);

Saves app-owned context through a concrete app instance.

template <typename T, T &App> size_t saveAppContext(uint8_t *buffer, size_t capacity);

Restores app-owned context through a concrete app instance.

template <typename T, T &App> void restoreAppContext(const uint8_t *buffer, size_t length);

Adapts a bool-returning app method to an AppEventResult callback.

template <typename T, T &App, bool (T::*Handler)()> AppEventResult dirtyIfHandledMethod();

Fluent builder for AppBehavior values used by the built-in app catalog.

struct BehaviorBuilder {
    AppBehavior behavior = {};
    BehaviorBuilder withEnter(AppCallback handler) const;
    BehaviorBuilder withExit(AppCallback handler) const;
    BehaviorBuilder withMenuBtn(AppEventHandler menu, AppEventHandler menuDouble = nullptr, AppEventHandler menuLong = nullptr) const;
    BehaviorBuilder withPowerBtn(AppEventHandler handler) const;
    BehaviorBuilder withRawTouch(AppRawTouchHandler handler) const;
    BehaviorBuilder withContext(AppSaveContextHandler save, AppRestoreContextHandler restore) const;
    BehaviorBuilder withPeriodic( AppPeriodicHandler handler, uint16_t intervalMinutes, PeriodicWakeLevel wakeLevel = PeriodicWakeLevel::Basic, PeriodicDisplayMode displayMode = PeriodicDisplayMode::None) const;
    BehaviorBuilder withRelease(AppCallback handler) const;
    AppBehavior build(const AppBehavior *behaviorOverride = nullptr) const;
};

Starts behavior composition with the runtime defaults.

inline BehaviorBuilder defaultBehavior();

Starts behavior composition with save and restore callbacks for one app instance.

template <typename T, T &App> BehaviorBuilder defaultContextBehavior();

Counts visible apps in one menu category after visibility filters are applied.

size_t appCatalogCount(MenuCategory category);

Looks up the app shown in a launcher slot and writes it into out; returns false if no app exists there.

bool tryGetVisibleAppAtIndex(MenuCategory category, size_t index, AppCatalogEntry &out);

Counts every installed app, including the SUN-button app hidden from the launcher.

size_t appCatalogAllCount();

Looks up an installed app by stable catalog order without visibility filtering.

bool tryGetAppAtIndex(size_t index, AppCatalogEntry &out);

Looks up an app by stable id across built-in and external app catalogs, even when the app is hidden from the launcher because it is the quick-access app.

bool findAppById(const char *id, AppCatalogEntry &out);

Counts built-in definitions without touching the SD-backed external catalog.

size_t builtInAppDefinitionCount();

Returns one immutable built-in definition, or nullptr when out of range.

const AppDefinition *builtInAppDefinitionAt(size_t index);

Rebuilds cached catalog state after config, storage, or external apps change.

void refreshAppCatalog();

Takes the pending .pink executable launch path from the files app.

bool takePendingPinkExecLaunchPath(char *path, size_t pathSize);

Takes the pending PocketInkJS source launch path from the files app.

bool takePendingPocketInkJSLaunchPath(char *path, size_t pathSize);

Resets all app-owned runtime state.

void resetApps();

Adafruit_GFX-backed display wrapper for full and partial e-paper updates.

class AppDisplay : public Adafruit_GFX {
    AppDisplay();
    void begin();
    void beginColdPartial();
    void beginRetainedPartial();
    void drawPixel(int16_t x, int16_t y, uint16_t color) override;
    void drawBlackPixelUnchecked(int16_t x, int16_t y);
    void drawBlackBlock2x2Unchecked(int16_t x, int16_t y);
    void flush();
    void flushPartial();
    void clear();
    void seedPartialBothImages();
    void requestFullRefresh();
    void lock();
    void unlock();
    const uint8_t *framebufferData() const;
    size_t framebufferSize() const;
};

Initializes level-2 system services shared by regular and periodic boots. Audio GPIOs become available in a powered-off state; playback activates them.

class SystemStageService {
    void initialize();
};

App-level actions needed when a periodic wake reaches a terminal state.

struct PeriodicWakeHooks {
    bool (*batteryCutoffReached)() = nullptr;
    void (*shutdownForLowBattery)() = nullptr;
    void (*prepareForPowerTransition)() = nullptr;
};

Coordinates the staged hardware initialization and dispatch for timer wakes. Scheduling and retained-state rules remain in periodic_tasks.

class PeriodicWakeService {
    PeriodicWakeService(AppDisplay &display, SystemStageService &systemStage, const PeriodicWakeHooks &hooks);
    void registerSystemTasks(uint8_t timeSyncIntervalHours = 24);
    void enterSleepClockDeepSleep();
    bool handleTimerWake();
    bool displayInitialized() const;
};

Snapshot of user-facing hardware toggles shown by status and settings UI, used by quick settings and power dialog display.

struct DeviceControlSnapshot {
    bool bluetoothOn = false;
    uint16_t cpuMhz = 240;
    uint8_t volume = 40;
    bool muted = false;
};

Initializes device-control state from persisted config and hardware defaults.

void deviceControlsBegin();

Applies persisted governor changes without replacing a quick-settings override.

void deviceControlsApplyConfig();

Raises balanced mode for a fresh touch or physical-button interaction.

void deviceControlsNoteUserActivity();

Lowers balanced mode after inactivity; Wi-Fi keeps a 160 MHz floor.

void deviceControlsUpdate(bool wifiOn);

Selected interactive maximum, including a temporary quick-settings override.

uint16_t deviceControlsSelectedCpuMhz();

Returns the latest device-control state for display.

DeviceControlSnapshot deviceControlsSnapshot();

Restores runtime audio controls from retained RTC state.

void deviceControlsRestoreAudio(uint8_t volume, bool muteState);

Toggles the Bluetooth preference and hardware state when supported.

void toggleBluetooth();

Advances the runtime CPU maximum without persisting the selection.

void cycleCpuFrequency();

Returns source volume scaled by the current output volume and mute state.

uint8_t deviceEffectiveOutputVolumePercent(uint8_t sourceVolumePercent);

Returns current output volume, using a minimum audible gain while muted.

uint8_t deviceEffectiveAlarmVolumePercent(uint8_t sourceVolumePercent);

Decreases runtime output volume by one UI step.

void volumeDown();

Increases runtime output volume by one UI step.

void volumeUp();

Toggles mute while preserving the configured volume level.

void toggleMute();

Releases transient holds before entering a low-power or shutdown path.

void releasePowerHolds();

Keeps the hardware power latch asserted while firmware is running.

void keepPowerLatchOn();

Restores GPIO defaults expected immediately after wake.

void prepareWakePowerDefaults();

Disables wireless peripherals before sleep or shutdown.

void disableWirelessForSleep();

Reboots the device through the platform reset path.

void rebootDevice();

Powers the device down after preparing peripherals for shutdown.

void powerOffDevice();

Powers down through the shortest path for emergency button holds.

void emergencyPowerOffDevice();

Enters deep sleep, optionally keeping e-paper powered for display retention.

void enterDeepSleep(uint64_t timerWakeupUs = 0, bool keepEpdPowerOn = false);

Reports whether the current boot was caused by a deep-sleep timer wake.

bool deepSleepWokeFromTimer();

Platform reset reason used by the retained wake trace.

int16_t deviceResetReason();

Platform wakeup cause used by the retained wake trace.

int16_t deviceWakeupCause();

Adds one active hold that prevents inactivity-triggered sleep.

void lockscreenGuardAcquire();

Releases one inactivity-sleep hold.

void lockscreenGuardRelease();

Resets the inactivity timer after user activity or foreground work.

void inactivitySleepKeepAwake();

Returns true when sleep is blocked by holds or recent keep-awake activity.

bool inactivitySleepBlocked(uint32_t graceMs = 0);

RAII helper that keeps the lockscreen awake for the lifetime of a scope.

class LockscreenGuard {
    LockscreenGuard();
    ~LockscreenGuard();
    LockscreenGuard(const LockscreenGuard &) = delete;
    LockscreenGuard &operator=(const LockscreenGuard &) = delete;
};

Allocates only from PSRAM on ESP32, with no internal-memory fallback.

inline void *allocate(size_t bytes);

Prefers PSRAM, then permits any 8-bit-capable heap as a fallback.

inline void *allocateOrDefault(size_t bytes);

Prefers PSRAM, then explicitly falls back to internal 8-bit memory.

inline void *allocateOrInternal(size_t bytes);

Prefers low-latency internal memory and uses PSRAM only when necessary.

inline void *allocateInternalOrPsram(size_t bytes);

Resizes a block preferring PSRAM, then the default 8-bit heap.

inline void *reallocateOrDefault(void *memory, size_t bytes);

Resizes a block in PSRAM without changing the allocation policy.

inline void *reallocate(void *memory, size_t bytes);

Releases memory returned by any allocator in this namespace.

inline void release(void *memory);

Maximum stored length for a single string config value, including terminator.

static const uint16_t CONFIG_VALUE_MAX = 96;

Number of Wi-Fi network slots persisted for automatic reconnect.

static const uint8_t CONFIG_WIFI_SAVED_MAX = 3;

Largest supported inactivity timeout for the uint8_t setting, in minutes.

static const uint8_t CONFIG_LOCKSCREEN_INACTIVITY_MAX_MINUTES = UINT8_MAX;

Supported periodic-task interval range in whole minutes.

static const uint16_t CONFIG_PERIODIC_INTERVAL_MIN_MINUTES = 1;

static const uint16_t CONFIG_PERIODIC_INTERVAL_MAX_MINUTES = 24U * 60U;

Fixed hardware policy for low-power periodic wakes.

static const uint16_t PERIODIC_TASK_CPU_MHZ = 80;

static const uint16_t PERIODIC_WIFI_CPU_MHZ = 160;

static const uint8_t PERIODIC_LOW_BATTERY_PERCENT = 15;

static_assert(PERIODIC_LOW_BATTERY_PERCENT < 20, "Periodic low-battery threshold must stay below 20%");

CPU frequency policy stored in system config.

enum ConfigCpuGovernor : uint8_t {
    CONFIG_CPU_FIXED,
    CONFIG_CPU_BALANCED,
};

User-selected clock display format.

enum ConfigTimeFormat : uint8_t {
    CONFIG_TIME_24H,
    CONFIG_TIME_12H,
};

User-selected date display format.

enum ConfigDateFormat : uint8_t {
    CONFIG_DATE_ISO,
    CONFIG_DATE_MDY,
    CONFIG_DATE_DMY,
    CONFIG_DATE_DMY_DOT,
    CONFIG_DATE_WEEKDAY,
};

Network protocol used to set the local clock.

enum ConfigTimeSyncProtocol : uint8_t {
    CONFIG_TIME_SYNC_HTTPS,
    CONFIG_TIME_SYNC_NTP,
};

Persisted Wi-Fi credentials for one remembered network.

struct ConfigWifiSavedNetwork {
    char ssid[33];
    char password[64];
    char bssid[18];
};

Complete persisted system configuration loaded at boot.

struct SystemConfig {
    struct { char ssid[64]; char password[64]; char displayName[24]; bool autoConnect; uint8_t autoOffMinutes; ConfigWifiSavedNetwork saved[CONFIG_WIFI_SAVED_MAX]; } wifi;
    struct { char sunBtnApp[32]; char widgets[CONFIG_VALUE_MAX]; } home;
    char layout[16];
    struct { char topIcon[2]; bool showDate; uint8_t inactivityMinutes; } lockscreen;
    struct { uint16_t mhz; ConfigCpuGovernor governor; } cpu;
    struct { ConfigTimeFormat timeFormat; ConfigDateFormat dateFormat; ConfigTimeSyncProtocol syncProtocol; uint8_t syncIntervalHours; int32_t lastUtcOffsetSeconds; char timezone[32]; char syncServer[96]; } time;
    struct { float temperatureOffsetC; char unit[2]; } sensors;
    struct { uint16_t minIntervalMinutes; bool disableOnLowBattery; } periodic;
};

Initializes config storage and loads the active configuration.

void configBegin();

Replaces active configuration with built-in defaults.

void configLoadDefaults();

Reloads config from persistent storage.

void configReload();

Returns the active read-only system configuration.

const SystemConfig &currentSystemConfig();

Parses a whole-minute inactivity timeout in the supported 0–255 range.

bool configParseLockscreenInactivityMinutes(const char *value, uint8_t &out);

Parses UTC, auto, or a fixed UTC offset such as UTC+02:30.

bool configParseUtcOffset(const char *value, int32_t &out);

Returns the configured fixed offset, or the last network-provided offset when timezone is automatic.

int32_t configEffectiveUtcOffset();

Persists the latest trusted network UTC offset for automatic timezone use.

bool configRememberUtcOffset(int32_t offsetSeconds);

Reads a raw config value by key into out.

bool configGet(const char *key, char *out, size_t outSize);

Writes a raw config value by key.

bool configSet(const char *key, const char *value);

Removes a raw config value by key.

bool configRemove(const char *key);

Reads a raw string value from the config file scoped to a single app id. Does not validate the value or apply an app setting default; use appConfigGet for schema-aware reads with validation and defaults.

bool configGetForApp(const char *appId, const char *key, char *out, size_t outSize);

Writes a raw string value to the config file scoped to a single app id. Does not validate the value against an AppConfigSetting schema; use appConfigSet for schema-aware writes.

bool configSetForApp(const char *appId, const char *key, const char *value);

Maximum bytes reserved in RTC memory for app-owned suspend state.

static const size_t RTC_CONTEXT_APP_CAPACITY = 4096;

Maximum stored app id length in RTC navigation context, including terminator.

static const size_t RTC_CONTEXT_APP_ID_SIZE = 24;

Navigation state preserved across deep sleep.

struct RtcNavigationContext {
    Screen screen;
    MenuCategory menuCategory;
    uint8_t menuPage;
    bool hasActiveApp;
    char appId[RTC_CONTEXT_APP_ID_SIZE];
};

System-level state preserved across deep sleep.

struct RtcSystemContext {
    bool clockSet;
    int64_t clockLocalUnix;
    int32_t clockUtcOffsetSeconds;
    bool wifiOn;
    uint8_t volume;
    bool muted;
};

App-owned state blob preserved across deep sleep.

struct RtcAppContext {
    uint16_t appDataLength;
    uint8_t appData[RTC_CONTEXT_APP_CAPACITY];
};

Full RTC context payload saved before deep sleep.

struct RtcContextSnapshot {
    RtcNavigationContext navigation;
    RtcSystemContext system;
    RtcAppContext app;
};

Bit-packed writer used to keep RTC snapshots small and versionable.

class RtcBitWriter {
    RtcBitWriter(uint8_t *buffer, size_t capacity);
    bool writeBits(uint32_t value, uint8_t bitCount);
    bool ok() const;
    size_t bytesWritten() const;
};

Bit-packed reader matching RtcBitWriter encoding.

class RtcBitReader {
    RtcBitReader(const uint8_t *buffer, size_t length);
    bool readBits(uint8_t bitCount, uint32_t &value);
    bool ok() const;
};

Saves a complete RTC snapshot for restoration after deep sleep.

bool rtcContextSave(const RtcContextSnapshot &snapshot);

Loads a previously saved RTC snapshot.

bool rtcContextLoad(RtcContextSnapshot &snapshot);

Clears any saved RTC snapshot.

void rtcContextClear();

Minimal clock context used by periodic sleep/wake clock updates.

struct SleepClockSnapshot {
    bool active;
    bool clockSet;
    bool timeEstimated;
    int64_t localUnix;
    int32_t utcOffsetSeconds;
    uint16_t wakeIntervalSeconds;
    bool previousFrameValid;
    ConfigTimeFormat timeFormat;
};

Starts periodic sleep clock mode with the current clock state.

void sleepClockContextStart(bool clockSet, bool timeEstimated, int64_t localUnix, int32_t utcOffsetSeconds, uint16_t wakeIntervalSeconds, ConfigTimeFormat timeFormat);

Loads periodic sleep clock state after wake.

bool sleepClockContextLoad(SleepClockSnapshot &snapshot);

Updates periodic sleep clock state before returning to sleep.

void sleepClockContextUpdate(bool clockSet, bool timeEstimated, int64_t localUnix, int32_t utcOffsetSeconds, uint16_t wakeIntervalSeconds, ConfigTimeFormat timeFormat, bool previousFrameValid = true);

Clears periodic sleep clock state.

void sleepClockContextClear();

Runtime policy copied from system config and retained for level-1 wakes.

struct PeriodicWakePolicy {
    uint16_t minIntervalMinutes = 1;
    uint8_t timeSyncIntervalHours = 24;
    bool disableOnLowBattery = true;
};

Small POD summary retained across deep sleep; no runtime pointers are kept.

struct PeriodicRetainedSnapshot {
    PeriodicWakePolicy policy;
    int64_t lastDispatchMinute = -1;
    int64_t pinkNextDueMinute = -1;
    uint32_t pendingWakeAppHash = 0;
    bool wifiPreferred = false;
    bool pinkRegistered = false;
};

One OS-owned task registration. The registry is rebuilt early on every boot.

struct PeriodicSystemTaskDefinition {
    const char *id = nullptr;
    PeriodicTaskSchedule schedule;
    AppPeriodicHandler onPeriodic = nullptr;
};

Compact aggregate retained for profiling without storing task-name strings.

struct PeriodicTaskStats {
    uint16_t idHash = 0;
    uint16_t totalDuration10Ms = 0;
    uint16_t runCount = 0;
};

Start sample used to attribute elapsed time to one hook.

struct PeriodicTaskMeasurement {
    uint32_t startedAtMs = 0;
    bool shouldRun = true;
};

Normalizes a requested cadence against the OS policy and 1-minute/1-day limits.

uint16_t periodicEffectiveIntervalMinutes(uint16_t requestedMinutes, uint16_t policyMinimumMinutes);

Uses epoch-aligned whole-minute buckets so schedules do not drift across sleep.

bool periodicTaskDueAtMinute(int64_t localMinute, uint16_t intervalMinutes);

Reports whether an aligned due minute falls in (previousMinute, currentMinute].

bool periodicTaskDueBetweenMinutes(int64_t previousMinute, int64_t currentMinute, uint16_t intervalMinutes);

Returns the first aligned minute strictly after currentMinute.

int64_t periodicNextDueMinute(int64_t currentMinute, uint16_t intervalMinutes);

Builds the low-power wake policy from the active system configuration.

PeriodicWakePolicy periodicPolicyFromConfig(const SystemConfig &config);

Clears the boot-local OS task registry before system services repopulate it.

void periodicSystemTasksReset();

Registers one static-lifetime OS task; duplicate ids replace their pointer.

bool periodicSystemTaskRegister(const PeriodicSystemTaskDefinition &task);

Starts/finishes compact profiling around a periodic callback.

PeriodicTaskMeasurement periodicTaskMeasurementStart(const char *taskId);

void periodicTaskMeasurementFinish(const char *taskId, const PeriodicTaskMeasurement &measurement);

Enumerates retained profiling aggregates for diagnostics UIs/tools.

size_t periodicTaskStatsCount();

bool periodicTaskStatsAt(size_t index, PeriodicTaskStats &out);

Saves current policy and external-task summary immediately before deep sleep.

void periodicRetainedPrepareForSleep(const PeriodicWakePolicy &policy, bool wifiPreferred, bool pinkRegistered, int64_t pinkNextDueMinute);

Loads a validated retained snapshot after a timer wake.

bool periodicRetainedLoad(PeriodicRetainedSnapshot &snapshot);

Refreshes policy and external-task summary after level-2 config/SD init.

void periodicRetainedUpdate(const PeriodicWakePolicy &policy, bool pinkRegistered, int64_t pinkNextDueMinute);

Atomically claims one minute for dispatch and rejects duplicate timer wakes.

bool periodicRetainedClaimDispatchMinute(int64_t localMinute);

Persists a WakeApp outcome before later tasks can crash the same wake.

void periodicRetainedRememberWakeApp(const char *appId);

Resolves and clears a retained WakeApp target after the app catalog is ready.

bool periodicRetainedTakeWakeApp(char *appId, size_t appIdSize);

One timer-wake dispatch over all statically registered built-in hooks.

class PeriodicWakeSession {
    PeriodicWakeSession(int64_t localUnix, int64_t previousDispatchMinute, bool clockSet, const PeriodicWakePolicy &policy, bool wifiPreferred, bool lowBattery);
    PeriodicWakeLevel nextWakeLevel() const;
    PeriodicDisplayMode displayModeFor(PeriodicWakeLevel level) const;
    void dispatch(PeriodicWakeLevel level, Adafruit_GFX *display, bool wifiConnected);
    PeriodicDisplayMode takeDisplayUpdate();
    bool hasPendingTasks() const;
    bool shouldWakeDevice() const;
    const char *wakeAppId() const;
    int64_t localMinute() const;
};

Last known SD-card mount and capacity state.

struct SdStorageSnapshot {
    bool mounted = false;
    uint32_t totalGb = 0;
    uint32_t freeGb = 0;
};

Initializes SD storage support.

void sdStorageBegin();

Unmounts SD storage and releases related resources.

void sdStorageEnd();

Marks SD storage state stale so the next update probes the card.

void sdStorageRequestRefresh();

Refreshes mount and capacity state; returns true when the snapshot changed.

bool sdStorageUpdate();

Returns true when SD storage is currently mounted.

bool sdStorageMounted();

Returns the last cached SD storage snapshot.

const SdStorageSnapshot &currentSdStorageSnapshot();

Storage and editor representation for one app-owned setting.

enum class AppConfigType : uint8_t {
    Bool, Int, Float, String, OneOf,
};

One labelled value for an AppConfigType::OneOf setting.

struct AppConfigOption {
    const char *label;
    const char *value;
};

Read-only metadata that an app registers with the Settings app. Definitions should be const so they remain in flash. Values themselves are persisted lazily in /cfg/app-<id>.cfg and are never cached here.

struct AppConfigSetting {
    const char *key;
    const char *label;
    AppConfigType type;
    const char *defaultValue;
    const AppConfigOption *options;
    uint8_t optionCount;
    uint8_t inputCapacity;
};

Settings metadata registered by one built-in app.

struct AppConfigRegistration {
    const char *appId;
    const char *label;
    const AppConfigSetting *settings;
    uint8_t settingCount;
};

Clears registrations before built-in apps register their static schemas.

void appConfigRegistryReset();

Adds one static schema. Duplicate registrations are ignored.

bool appConfigRegister(const AppConfigRegistration &registration);

Returns the number of registered app schemas.

uint8_t appConfigRegistrationCount();

Returns a registered schema by index, or nullptr when out of range.

const AppConfigRegistration *appConfigRegistrationAt(uint8_t index);

Reads an app value, falling back to the registered default when absent or invalid. No per-app values are retained in RAM.

bool appConfigGet(const AppConfigRegistration &registration, const AppConfigSetting &setting, char *out, size_t outSize);

Reads a registered boolean as a native value, including its default.

bool appConfigGetBool(const AppConfigRegistration &registration, const AppConfigSetting &setting);

Validates and persists an app value through the existing app-scoped config.

bool appConfigSet(const AppConfigRegistration &registration, const AppConfigSetting &setting, const char *value);

Hooks from the sketch runtime into ShellController. These keep platform-level behaviors, such as power transitions and home data refresh, outside the controller while still allowing the shell to coordinate them from button and quick-settings flows.

struct ShellControllerHooks {
    void *context = nullptr;
    void (*refreshHome)(void *context) = nullptr;
    void (*noteUserActivity)(void *context) = nullptr;
    void (*prepareForPowerTransition)(void *context) = nullptr;
    void (*enterSleepClockDeepSleep)(void *context) = nullptr;
    void (*renderPowerOffScreen)(void *context) = nullptr;
};

Main coordinator for the firmware shell. The sketch owns hardware services, then calls this controller for button events, touch dispatch, active app updates, retained context, and redraws. This keeps screen routing and app lifecycle in one place.

class ShellController {
    ShellController(AppDisplay &display, TouchInput &touch, TextInputController &textInput);
    void setHooks(const ShellControllerHooks &hooks);
    Screen currentScreen() const;
    bool shouldRedrawForBatteryRefresh() const;
    unsigned long inactivityDeepSleepMs(unsigned long defaultMs) const;
    void markDirty();
    void clampMenu();
    void switchTo(Screen next, ActiveApp *nextApp = nullptr, const AppDefinition *nextDefinition = nullptr);
    void handleMenuButton();
    void handleMenuDoubleButton();
    void handleMenuLongButton();
    void handlePowerSingleButton();
    void handlePowerDoubleButton();
    void handlePowerLongButton();
    bool dispatchTouch();
    bool updateActiveApp();
    bool handlePendingFilesPinkLaunch();
    bool wakeAppById(const char *id);
    void handleCatalogChanged();
    void refreshHomeMinuteIfNeeded();
    void renderIfDirty();
    void saveRetainedContextForSleep();
    void restoreRetainedContextAfterSleep();
};

Shell-owned side effect invoked by quick settings without coupling to globals.

typedef void (*QuickSettingsCallback)(void *context);

Capability table for actions that QuickSettingsController can request. The controller owns dialog state and hit testing; the shell provides these callbacks for operations that affect power, retained context, or rendering.

struct QuickSettingsActions {
    void *context = nullptr;
    QuickSettingsCallback renderPowerOff = nullptr;
    QuickSettingsCallback prepareForPowerTransition = nullptr;
    QuickSettingsCallback saveRetainedContext = nullptr;
    QuickSettingsCallback enterSleepClock = nullptr;
    QuickSettingsCallback captureScreenshot = nullptr;
};

Small state machine for the power/quick-settings dialog. ShellController opens this on long power press, asks it for a render snapshot, and forwards touches here so page navigation and device actions stay together.

class QuickSettingsController {
    void open(PowerDialogPage page = PowerDialogPage::Power);
    void close();
    bool isOpen() const;
    PowerDialogSnapshot snapshot() const;
    PowerDialogAction handleTouch(const TouchPoint &point);
    void runAction(PowerDialogAction action, const QuickSettingsActions &actions) const;
};

Restore hooks that let retained context code resume shell state safely. The context module persists only small identifiers. ShellController supplies these callbacks so restore can relaunch apps or switch screens without owning the full controller.

struct ShellContextRestoreActions {
    void *context = nullptr;
    void (*launchApp)(void *context, const AppDefinition &app) = nullptr;
    void (*switchTo)(void *context, Screen screen) = nullptr;
    const AppDefinition *(*activeDefinition)(void *context) = nullptr;
};

Collapses transient screens into the screen value that should survive sleep.

Screen shellContextScreenForSave(Screen screen, bool textInputScreen, const AppDefinition *activeDefinition);

Persists the current shell/app/menu position into RTC-retained state.

void shellContextSaveForSleep(Screen screen, bool textInputScreen, const AppDefinition *activeDefinition, const MenuState &menuState);

Replays retained shell state after wake; returns true when a restore happened.

bool shellContextRestoreAfterSleep(MenuState &menuState, const ShellContextRestoreActions &actions);

Callback signature for a recognized hardware-button gesture.

typedef void (*ShellButtonCallback)();

Shell actions assigned to each gesture on the menu and power buttons.

struct ShellButtonHandlers {
    ShellButtonCallback onMenu = nullptr;
    ShellButtonCallback onMenuDouble = nullptr;
    ShellButtonCallback onMenuLong = nullptr;
    ShellButtonCallback onPower = nullptr;
    ShellButtonCallback onPowerDouble = nullptr;
    ShellButtonCallback onPowerLong = nullptr;
};

Configures button timing, callbacks, and the background GPIO polling task.

void shellButtonsBegin(const ShellButtonHandlers &handlers);

Delivers all queued gestures on the caller's thread; returns true on activity.

bool shellButtonsDispatch();

Provides the status-bar glyph for the shared Wi-Fi state.

char wifiStatusIcon();

Reports whether the shell intends Wi-Fi to be enabled, even while connecting.

bool wifiIsOn();

Reports whether the shared Wi-Fi client currently has a network connection.

bool wifiIsConnected();

Reports whether a station association attempt is still in progress.

bool wifiConnectionInProgress();

Enables Wi-Fi from shell UI such as quick settings.

void wifiTurnOn();

Disables Wi-Fi and lets shell UI reflect the power-saving state.

void wifiTurnOff();

Toggles Wi-Fi from the quick-settings device page.

void wifiToggle();

Advances the Wi-Fi service; the shell redraws when the visible state changes.

bool wifiUpdate();

Reapplies retained Wi-Fi preference after boot or deep-sleep wake.

void restoreWifiOn(bool enabled);

Home-screen density profile loaded from shell configuration.

enum ShellLayoutMode : uint8_t {
    SHELL_LAYOUT_DEFAULT,
    SHELL_LAYOUT_ULTRA_LARGE,
};

Display unit for temperature values shown on shell surfaces.

enum ShellTemperatureUnit : uint8_t {
    SHELL_TEMP_CELSIUS,
    SHELL_TEMP_FAHRENHEIT,
};

Bitmask for optional home widgets so low-memory config can stay compact.

enum ShellWidget : uint16_t {
    SHELL_WIDGET_TEMP = 1U << 0,
    SHELL_WIDGET_HUM = 1U << 1,
    SHELL_WIDGET_CPU_TEMP = 1U << 2,
    SHELL_WIDGET_SD = 1U << 3,
    SHELL_WIDGET_BATTERY = 1U << 4,
    SHELL_WIDGET_NOTIFICATIONS = 1U << 5,
    SHELL_WIDGET_LOGO_TEXT = 1U << 6,
    SHELL_WIDGET_BUTTON_HELP = 1U << 7,
    SHELL_WIDGET_WALLPAPER = 1U << 8,
    SHELL_WIDGET_WEATHER = 1U << 9,
};

User-configurable presentation state for the home screen. This separates persistent layout choices from live sensor/app data so render functions can stay deterministic and easy to test.

struct ShellLayoutConfig {
    ShellLayoutMode layout = SHELL_LAYOUT_DEFAULT;
    ShellTemperatureUnit temperatureUnit = SHELL_TEMP_CELSIUS;
    uint16_t homeWidgets = 0;
};

Live data passed into shell renderers for one frame. Pointers are non-owning; callers keep sensor/storage snapshots in their service modules and pass the current view here.

struct ShellData {
    StatusBarSnapshot status;
    const BatterySnapshot *battery;
    const EnvironmentSnapshot *environment;
    const SdStorageSnapshot *sd;
};

Reloads both home and lockscreen presentation config after settings changes.

void shellLayoutConfigReload();

Shares the active presentation config with shell render paths.

const ShellLayoutConfig &shellLayoutConfig();

Checks a home-widget bit against the active layout config.

bool shellHomeWidgetEnabled(uint16_t widget);

Renders the home surface from a live ShellData snapshot.

void drawHomeScreen(AppDisplay &display, const ShellData &data);

Walks categories backward for button navigation.

MenuCategory previousMenuCategory(MenuCategory category);

Walks categories forward for button navigation.

MenuCategory nextMenuCategory(MenuCategory category);

Provides the short category label used by the app menu.

const char *menuCategoryTitle(MenuCategory category);

Keeps menu state valid after app catalog or category contents change.

void clampMenuState(MenuState &state);

Applies one backward menu step with category-aware wrapping.

void moveMenuPrevious(MenuState &state);

Applies one forward menu step with category-aware wrapping.

void moveMenuNext(MenuState &state);

Renders the category app menu and optional pressed-slot feedback.

void drawAppMenu(AppDisplay &display, const MenuState &state, int8_t pressedSlot = -1);

Converts a touch into menu movement or an app selection.

bool hitTestAppMenu(const TouchPoint &point, MenuState &state, AppCatalogEntry &selected, bool &stateChanged, int8_t *hitSlot = nullptr);

Overlays the app quit confirmation dialog.

void drawQuitDialog(AppDisplay &display, const StatusBarSnapshot &status);

Hit-tests the quit confirmation action.

bool quitDialogHitYes(const TouchPoint &point);

Hit-tests the quit cancel action.

bool quitDialogHitNo(const TouchPoint &point);

Semantic actions emitted by the power/quick-settings dialog.

enum class PowerDialogAction : uint8_t {
    None,
    PreviousPage,
    NextPage,
    Reboot,
    PowerOff,
    DeepSleep,
    WifiToggle,
    BluetoothToggle,
    CpuCycle,
    VolumeDown,
    VolumeMute,
    VolumeUp,
    Screenshot,
};

Paged groups in the power/quick-settings dialog.

enum class PowerDialogPage : uint8_t {
    Power,
    Device,
    Volume,
    Screen,
};

Live device state displayed by the power/quick-settings dialog.

struct PowerDialogSnapshot {
    PowerDialogPage page = PowerDialogPage::Power;
    bool wifiOn = false;
    bool wifiConnected = false;
    bool bluetoothOn = false;
    uint16_t cpuMhz = 240;
    uint8_t volume = 60;
    bool muted = false;
};

Renders the power/quick-settings dialog from the supplied snapshot.

void drawPowerDialog(AppDisplay &display, const StatusBarSnapshot &status, const PowerDialogSnapshot &snapshot, PowerDialogAction pressed = PowerDialogAction::None);

Converts a dialog touch into a semantic quick-settings action.

PowerDialogAction powerDialogHitAction(const TouchPoint &point, PowerDialogPage page);

Draws the final user-visible frame before powering off.

void drawPowerOffScreen(AppDisplay &display);

Draws the battery-protection screen used before forced sleep/shutdown.

void drawLowBatteryScreen(AppDisplay &display);

User-configurable presentation state for the lockscreen/sleep clock.

struct LockscreenLayoutConfig {
    char topIcon = 'S';
    bool showDate = true;
};

Reloads lockscreen presentation config after settings changes.

void lockscreenLayoutConfigReload();

Returns the active lockscreen configuration.

const LockscreenLayoutConfig &lockscreenLayoutConfig();

Draws the simple deep-sleep transition frame.

void drawLockscreenSleepScreen(AppDisplay &display);

Draws the low-power lockscreen clock frame.

void drawLockscreenClockScreen(AppDisplay &display, const char *timeText, const char *dateText, bool timeEstimated = false);

Result of exporting the current display buffer to the SD card.

enum class ScreenshotResult : uint8_t {
    Saved,
    NoSdCard,
    NoFramebuffer,
    WriteFailed,
};

Writes the current one-bit framebuffer as a BMP under /screenshots. The caller must keep the display framebuffer stable for the duration.

ScreenshotResult saveFramebufferScreenshot(const AppDisplay &display);

Provides a short UI-safe message for an unsuccessful screenshot export.

const char *screenshotResultMessage(ScreenshotResult result);

Data needed to render the top status bar for shell and app screens. The status bar does not query services directly; callers provide one compact snapshot so app rendering remains predictable and cheap.

struct StatusBarSnapshot {
    const char *dateText;
    const char *timeText;
    const BatterySnapshot *battery;
    char wifiIcon;
    bool usbConnected;
};

Draws date/time, battery, and connectivity indicators into the display.

void drawStatusBar(AppDisplay &display, const StatusBarSnapshot &status);

Shared controller for the firmware text-entry modes. Apps switch to these screens instead of owning keyboard widgets directly. The controller keeps the current draft text and routes draw/touch behavior to the selected keyboard implementation.

class TextInputController {
    bool isScreen(Screen screen) const;
    bool toggleCaps(Screen screen);
    Screen nextMode(Screen screen) const;
    void draw(AppDisplay &display, Screen screen);
    bool handleTouch(Screen screen, const TouchPoint &point);
};

static const unsigned long UI_PRESS_FEEDBACK_MS = 180;

static const uint8_t UI_TOUCH_ASSIST_PX = 2;

Small helper for pressed feedback in screens without a full component. Screens store an integer control id, call press() from hit testing, and call update() from their loop to know when to redraw the released state.

struct UiPressFeedback {
    int8_t id = -1;
    unsigned long until = 0;
    void clear();
    void press(int8_t nextId, unsigned long durationMs = UI_PRESS_FEEDBACK_MS);
    bool isPressed(int8_t queryId) const;
    bool update();
};

Hit-tests a standard rectangular control using TouchButton semantics.

inline bool uiContains(const UiRect &rect, const TouchPoint &point);

Hit-tests a small visual control with extra invisible touch padding.

inline bool uiTouchContains(const UiRect &rect, const TouchPoint &point, uint8_t touchPadding = UI_TOUCH_ASSIST_PX);

Draws the common compact monochrome text button used across shell screens.

inline void uiDrawButton(Adafruit_GFX &gfx, const UiRect &rect, const char *label, bool pressed = false, uint8_t textSize = 1);

Draws an icon-only control without a border, retaining pressed feedback.

inline void uiDrawBorderlessIconButton(Adafruit_GFX &gfx, const UiRect &rect, char icon, bool pressed = false);

Integer rectangle used by touchable UI controls.

struct UiRect {
    int16_t x;
    int16_t y;
    int16_t w;
    int16_t h;
};

Built-in shape kinds for touch button rendering and hit testing.

enum class TouchButtonShapeType : uint8_t {
    Rectangle,
    RoundedRectangle,
    Circle,
    Custom,
};

Custom touch-button hit-test callback.

typedef bool (*TouchButtonHitTest)(const UiRect &bounds, const TouchPoint &point, void *context);

Custom touch-button painter callback.

typedef void (*TouchButtonPainter)(Adafruit_GFX &gfx, const UiRect &bounds, bool pressed, void *context);

Shape configuration for a touch button.

struct TouchButtonShape {
    TouchButtonShapeType type = TouchButtonShapeType::Rectangle;
    uint8_t radius = 0;
    TouchButtonHitTest hitTest = nullptr;
    TouchButtonPainter painter = nullptr;
    void *context = nullptr;
    static TouchButtonShape rectangle();
    static TouchButtonShape rounded(uint8_t radius);
    static TouchButtonShape circle();
    static TouchButtonShape custom(TouchButtonHitTest hitTest, TouchButtonPainter painter = nullptr, void *context = nullptr);
};

Icon placement relative to text.

enum class TouchButtonIconPlacement : uint8_t {
    None,
    Only,
    AboveText,
    Left,
    Right,
};

Alignment value used for button text positioning.

enum class TouchButtonAlign : uint8_t {
    Start,
    Center,
    End,
};

Text and icon content for a touch button.

struct TouchButtonContent {
    const char *text = nullptr;
    const char *icon = nullptr;
    TouchButtonIconPlacement iconPlacement = TouchButtonIconPlacement::None;
    bool iconUsesIconFont = true;
    uint8_t iconTextSize = 1;
    TouchButtonAlign textX = TouchButtonAlign::Center;
    TouchButtonAlign textY = TouchButtonAlign::Center;
    uint8_t textSize = 1;
    int8_t textOffsetX = 0;
    int8_t textOffsetY = 0;
    int8_t iconOffsetX = 0;
    int8_t iconOffsetY = 0;
};

Drawing and hit-test style for a touch button.

struct TouchButtonStyle {
    uint8_t color = 1;
    uint8_t backgroundColor = 0;
    uint8_t pressedColor = 0;
    uint8_t pressedBackgroundColor = 1;
    uint8_t padding = 4;
    uint8_t touchPadding = 0;
    bool drawOutline = true;
    bool fillPressed = true;
};

Reusable touchable button primitive for e-paper UI controls.

class TouchButton {
    TouchButton(const UiRect &bounds, TouchButtonShape shape = TouchButtonShape::rectangle());
    TouchButton(const UiRect &bounds, const TouchButtonContent &content, TouchButtonShape shape = TouchButtonShape::rectangle(), const TouchButtonStyle &style = TouchButtonStyle());
    bool contains(const TouchPoint &point) const;
    void draw(Adafruit_GFX &gfx, bool pressed = false) const;
    const UiRect &bounds() const;
};

Actions emitted by keyboard hit testing.

enum KeyboardAction {
    KEY_NONE,
    KEY_CHAR,
    KEY_BACKSPACE,
    KEY_SPACE,
    KEY_SHIFT,
    KEY_NAV,
    KEY_OK,
};

Keyboard hit-test result.

struct KeyboardEvent {
    KeyboardAction action;
    char value;
};

Shared contract for keyboard components backed by external text state.

class KeyboardComponent {
    virtual ~KeyboardComponent() = default;
    virtual void draw(Adafruit_GFX &gfx, const String &text) = 0;
    virtual void draw(Adafruit_GFX &gfx, const String &text, int maxLength) = 0;
    virtual KeyboardEvent hitTest(const TouchPoint &point) = 0;
    virtual KeyboardEvent hitTest(const TouchPoint &point, int currentLength, int maxLength) = 0;
    virtual void toggleCaps() = 0;
};

Draws and hit-tests a phone-style T9 keyboard.

class T9KeyboardComponent {
    enum class Layout : uint8_t { Text, Numbers, Numeric };
    void draw(Adafruit_GFX &gfx, const String &text);
    void draw(Adafruit_GFX &gfx, const String &text, int maxLength);
    void draw(Adafruit_GFX &gfx, const char *text, int maxLength);
    KeyboardEvent hitTest(const TouchPoint &point, String &text);
    KeyboardEvent hitTest(const TouchPoint &point, String &text, int maxLength);
    KeyboardEvent hitTest(const TouchPoint &point, char *text, int capacity);
    void setLayout(Layout nextLayout);
    bool update();
    void toggleCaps();
};

Draws and hit-tests a paged zoomed QWERTY keyboard.

class QwertyZoomKeyboardComponent : public KeyboardComponent {
    void draw(Adafruit_GFX &gfx, const String &text) override;
    void draw(Adafruit_GFX &gfx, const String &text, int maxLength) override;
    KeyboardEvent hitTest(const TouchPoint &point) override;
    KeyboardEvent hitTest(const TouchPoint &point, int currentLength, int maxLength) override;
    void toggleCaps() override;
};

Touch navigation behavior for compact list controls.

enum class UiListNavMode : uint8_t {
    Scroll,
    Select,
    Split,
};

Result action from list hit testing.

enum class UiListTouchAction : uint8_t {
    None,
    Scroll,
    Select,
};

List hit-test result.

struct UiListTouchResult {
    UiListTouchAction action = UiListTouchAction::None;
    uint16_t index = 0;
};

Returns the largest valid scroll offset for a list.

inline uint16_t uiListMaxOffset(uint16_t itemCount, uint8_t visibleCount);

Clamps a list scroll offset in place.

inline void uiListClampOffset(uint16_t &offset, uint16_t itemCount, uint8_t visibleCount);

Scrolls a list offset by a signed row delta.

inline bool uiListScrollBy(uint16_t &offset, uint16_t itemCount, uint8_t visibleCount, int8_t delta);

Maps a touch point to scroll or select behavior for a simple list.

inline UiListTouchResult uiListHandleTouch(const TouchPoint &point, uint16_t itemCount, uint8_t visibleCount, int16_t listY, int16_t rowHeight, int16_t listHeight, int16_t splitX, UiListNavMode mode, uint16_t &offset);

Calendar date selected by the date picker.

struct DatePickerDate {
    int year = 1970;
    int month = 1;
    int day = 1;
};

Clock time selected by the time picker.

struct TimePickerTime {
    uint8_t hour = 0;
    uint8_t minute = 0;
};

Draws and edits a small date picker with optional time selection.

class DateTimePickerComponent {
    void reset(const DatePickerDate &date);
    void setToday(const DatePickerDate &date, bool available);
    void setTime(const TimePickerTime &time);
    void setTimePickerEnabled(bool enabled);
    void setMondayFirst(bool enabled);
    void draw(Adafruit_GFX &gfx);
    bool handleTouch(const TouchPoint &point);
    bool dateAtPoint(const TouchPoint &point, DatePickerDate &out) const;
    bool update();
    DatePickerDate selectedDate() const;
    TimePickerTime selectedTime() const;
    bool timePickerEnabled() const;
    static int daysInMonth(int year, int month);
    static int weekdayForDate(int year, int month, int day);
    static DatePickerDate dateFromUnixDays(int days);
    static const char *monthName(int month);
    static const char *weekdayName(int weekday);
};

Touch actions emitted by the audio player component.

enum class AudioPlayerAction : uint8_t {
    None,
    TogglePlayPause,
    VolumeDown,
    VolumeUp,
    Seek,
};

Result of hit-testing the audio player component.

struct AudioPlayerEvent {
    AudioPlayerAction action = AudioPlayerAction::None;
    uint16_t seekPermille = 0;
};

Render state for the audio player component.

struct AudioPlayerState {
    const char *title = nullptr;
    const char *subtitle = nullptr;
    const char *detail = nullptr;
    bool playing = false;
    AudioPlayerAction pressedAction = AudioPlayerAction::None;
    uint8_t volumePercent = 80;
    bool muted = false;
    uint32_t positionMs = 0;
    uint32_t durationMs = 0;
};

Draws and hit-tests the compact/fullscreen audio playback controls.

class AudioPlayerComponent {
    void draw(Adafruit_GFX &gfx, const AudioPlayerState &state, bool fullscreen) const;
    AudioPlayerEvent hitTest(const TouchPoint &point, bool fullscreen, uint32_t durationMs) const;
};

Describes a font already compiled into the firmware.

struct SystemFontInfo {
    const char *name = nullptr;
    uint8_t nominalSize = 0;
};

Returns the number of fonts in the firmware-wide registry.

size_t systemFontCount();

Copies metadata for one registry entry; returns false out of range.

bool systemFontInfo(size_t index, SystemFontInfo &out);

Looks up a stable font name, returning -1 when it is unknown.

int systemFontIndex(const char *name);

Applies a registry font by index to a GFX drawing surface.

bool systemFontApply(Adafruit_GFX &gfx, size_t index);

Applies a registry font by name to a GFX drawing surface.

bool systemFontApply(Adafruit_GFX &gfx, const char *name);

Initializes the board I2C bus shared by touch, RTC, and sensors.

bool sharedI2cBegin();

Returns the initialized shared bus, or nullptr before successful setup.

i2c_master_bus_handle_t sharedI2cBusHandle();

Raw sample reported by the FT6336 touch controller.

struct TouchControllerSample {
    uint8_t count = 0;
    uint16_t x = 0;
    uint16_t y = 0;
};

Low-level FT6336 access on the board's shared I2C bus.

class TouchController {
    bool begin();
    bool read(TouchControllerSample &sample);
};

Raw readings produced by the board's ambient and chip sensors.

struct EnvironmentSensorReadings {
    bool ambientTemperatureValid = false;
    bool ambientHumidityValid = false;
    bool chipTemperatureValid = false;
    float ambientTemperatureC = 0.0f;
    float ambientHumidityPct = 0.0f;
    float chipTemperatureC = 0.0f;
};

Low-level access to the SHTC3 and ESP32 internal temperature sensor.

class EnvironmentSensors {
    void begin();
    void read(EnvironmentSensorReadings &readings);
};

Releases GPIO and RTC holds left by a sleep transition.

void powerHardwareReleaseHolds();

Applies safe board GPIO levels immediately after wake.

void powerHardwarePrepareWakeDefaults();

Keeps the board power latch asserted.

void powerHardwareKeepLatchOn();

Restarts through the platform reset mechanism.

void powerHardwareReboot();

Drops power rails and waits for a power-button wake.

void powerHardwareOff();

Enters deep sleep with the configured wake timer and panel power state.

void powerHardwareEnterDeepSleep(uint64_t timerWakeupUs, bool keepEpdPowerOn);

Reports whether deep sleep ended because of the timer.

bool powerHardwareWokeFromTimer();

Returns the platform reset reason as a stable diagnostic integer.

int16_t powerHardwareResetReason();

Returns the platform wakeup cause as a stable diagnostic integer.

int16_t powerHardwareWakeupCause();

Raw SD-card capacity reported by the board storage driver.

struct SdCardCapacity {
    uint64_t totalBytes = 0;
    uint64_t usedBytes = 0;
};

Mounts the board SD card in one-bit SD_MMC mode.

bool sdCardMount();

Unmounts the board SD card.

void sdCardUnmount();

Reports whether hardware still exposes a mounted card.

bool sdCardPresent();

Reads raw card capacity counters.

SdCardCapacity sdCardCapacity();

Debounces one hardware button and emits single-click, double-click, long-press, and activity callbacks.

class HwButton {
    HwButton(uint8_t pin, bool activeLow = true);
    void begin();
    void update();
    void attachSingleClick(std::function<void()> callback);
    void attachDoubleClick(std::function<void()> callback);
    void attachLongPressStart(std::function<void()> callback);
    void attachHold(std::function<void()> callback, uint16_t ms);
    void attachActivity(std::function<void()> callback);
    void setLongPressMs(uint16_t ms);
    void setDoubleClickMs(uint16_t ms);
};

Owns one e-paper controller, its SPI attachment, and its framebuffer.

class epaper_driver_display {
    epaper_driver_display(int width, int height, custom_lcd_spi_t _lcd_spi_data);
    ~epaper_driver_display();
    void EPD_Init();
    void EPD_InitColdPartial();
    void EPD_ReattachPartial();
    void EPD_Clear();
    void EPD_Display();
    [[deprecated("EPD_DisplayRegion is not hardware-safe; use EPD_DisplayPart/full-buffer partial refresh")]] void EPD_DisplayRegion(int16_t x, int16_t y, int16_t w, int16_t h);
    void EPD_LoadPartBaseImage();
    void EPD_LoadPartBothImages();
    void EPD_DisplayPartBaseImage();
    void EPD_Init_Partial();
    void EPD_DisplayPart();
    void EPD_DrawColorPixel(uint16_t x, uint16_t y, uint8_t color);
    void EPD_DrawBlackPixelUnchecked(uint16_t x, uint16_t y);
    void EPD_DrawBlackBlock2x2Unchecked(uint16_t x, uint16_t y);
    const uint8_t *framebufferData() const;
    int framebufferSize() const;
};

Minimal access for reading and writing the battery-backed PCF85063.

class Pcf85063Clock {
    void begin();
    bool readLocalUnix(int64_t &localUnix);
    bool writeFromUnix(int64_t unixTime, int32_t utcOffsetSeconds);
};

Returns true when the device sees a USB host connection.

bool usbConnected();

Voltage treated as 0 percent when estimating battery state of charge.

constexpr float BATTERY_EMPTY_VOLTAGE = 2.80f;

Voltage treated as 100 percent when estimating battery state of charge.

constexpr float BATTERY_FULL_VOLTAGE = 3.95f;

One voltage-to-percentage point in the battery state-of-charge curve.

struct BatterySocPoint {
    float voltage;
    int percentage;
};

Hardware and calibration settings used by BatteryMonitor.

struct BatteryMonitorConfig {
    int adcPin;
    int controlPin;
    int sampleCount;
    int adcMaxReading;
    float adcReferenceVoltage;
    float dividerScale;
    const BatterySocPoint *socCurve;
    size_t socCurveLength;
};

Cached battery reading exposed to UI and power policy.

struct BatterySnapshot {
    bool valid;
    float voltage;
    int percentage;
};

Samples battery voltage and exposes a cached percentage estimate.

class BatteryMonitor {
    void begin();
    void refresh();
    void configure(const BatteryMonitorConfig &config);
    const BatterySnapshot &snapshot() const;
};

Cached temperature and humidity readings from onboard sensors.

struct EnvironmentSnapshot {
    bool ambientTemperatureValid;
    bool ambientHumidityValid;
    bool chipTemperatureValid;
    float ambientTemperatureC;
    float ambientHumidityPct;
    float chipTemperatureC;
};

Polls environmental sensors and caches values for UI display.

class EnvironmentMonitor {
    void begin();
    void refresh();
    const EnvironmentSnapshot &snapshot() const;
};

One sampled touch coordinate in display space.

struct TouchPoint {
    uint16_t x;
    uint16_t y;
};

Type of touch transitions reported by the controller.

enum TouchEventType {
    TOUCH_EVENT_DOWN,
    TOUCH_EVENT_MOVE,
    TOUCH_EVENT_UP,
};

Packs one touch event with its type and coordinates.

struct TouchEvent {
    TouchEventType type;
    TouchPoint point;
};

Reads debounced touch points and higher-level touch events from the panel.

class TouchInput {
    void begin();
    bool read(TouchPoint &point);
    bool readEvent(TouchEvent &event);
};

Monotonic-millis backed local clock used after network or RTC time sync.

class DeviceClock {
    void set(int64_t unixTime, int32_t utcOffsetSeconds);
    bool isSet() const;
    bool isEstimated() const;
    bool snapshotLocalUnix(int64_t &localUnix) const;
    bool snapshotLocalUnixMillis(int64_t &localUnix, uint16_t &millisIntoSecond) const;
    bool snapshotUnixMillis(int64_t &unixTime, uint16_t &millisIntoSecond) const;
    void restoreLocalUnix(int64_t localUnix, int32_t utcOffsetSeconds, bool estimated = false);
    int32_t utcOffsetSeconds() const;
    int64_t localMinuteIndex() const;
    void formatTime(char *out, size_t outSize) const;
    void formatTime(char *out, size_t outSize, ConfigTimeFormat format) const;
    void formatDate(char *out, size_t outSize) const;
};

Coarse Wi-Fi state used by compact status indicators.

enum WifiDisplayState {
    WIFI_DISPLAY_OFF,
    WIFI_DISPLAY_ON,
    WIFI_DISPLAY_CONNECTED,
};

Owns station-mode Wi-Fi lifecycle, remembered networks, and time sync updates.

class WifiManager {
    enum ConnectionState : uint8_t { STATE_IDLE, STATE_CONNECTING, STATE_CONNECTED, STATE_FAILED };
    void reset();
    bool update();
    bool startSta();
    void connect();
    void connectTo(const char *ssid, const char *password);
    void disconnect();
    void toggle();
    void restoreOn(bool enabled);
    bool isOn() const;
    bool isConnected() const;
    bool isConnecting() const;
    bool hasActiveSession() const;
    WifiDisplayState displayState() const;
    ConnectionState connectionState() const;
    bool preferredMatches(const char *ssid) const;
    void saveNetworkSlot(uint8_t slot, const char *ssid, const char *password, const char *bssid);
    void savePreferred(const char *ssid, const char *password);
    void clearPreferredIfMatches(const char *ssid);
    const char *statusText() const;
    const char *datetimeText() const;
    void setStatus(const char *status);
};

Network time synchronizer that updates DeviceClock and exposes UI status text.

class TimeSyncService {
    void reset();
    bool update(bool wifiConnected);
    bool hasActiveSession() const;
    const char *statusText() const;
    const char *datetimeText() const;
    void setStatus(const char *value);
};

Pull-based PCM source consumed by AudioPlaybackRenderer.

struct AudioPlaybackStream {
    void *user = nullptr;
    size_t (*fillPcm16)(void *user, int16_t *stereoFrames, size_t frameCount) = nullptr;
};

Runtime audio playback settings.

struct AudioPlaybackConfig {
    uint32_t sampleRate = 16000;
    size_t chunkFrames = 512;
    uint8_t volumePercent = 80;
    bool playWhenMutedAtMinimumVolume = false;
};

Streams signed 16-bit stereo PCM to the codec and I2S output path.

class AudioPlaybackRenderer {
    static void stopActive();
    bool begin(const AudioPlaybackStream &stream, const AudioPlaybackConfig &config, char *error, int errorSize);
    bool pump(char *error, int errorSize);
    void stop();
    void setVolumePercent(uint8_t percent);
    uint8_t volumePercent() const;
    bool active() const;
    bool finished() const;
    uint32_t sampleRate() const;
    uint16_t lastPeak() const;
    uint32_t chunksWritten() const;
};

Owned PCM recording buffer returned by AudioCapture.

struct AudioCaptureResult {
    uint8_t *data = nullptr;
    size_t length = 0;
    uint32_t sampleRate = 16000;
    bool wav = false;
};

Captures microphone audio as signed 16-bit PCM.

class AudioCapture {
    bool beginPcm16(AudioCaptureResult &out, uint32_t maxDurationMs, char *error, int errorSize);
    bool beginWav(AudioCaptureResult &out, uint32_t maxDurationMs, char *error, int errorSize);
    bool pumpPcm16(AudioCaptureResult &out, char *error, int errorSize);
    void finishPcm16(AudioCaptureResult &out);
    bool recordPcm16(AudioCaptureResult &out, uint32_t durationMs, char *error, int errorSize);
    bool recordWav(AudioCaptureResult &out, uint32_t durationMs, char *error, int errorSize);
    void release(AudioCaptureResult &result);
};

Initializes GPIOs that control codec and speaker power.

void audioPowerBegin();

Enables shared audio power rails.

void audioPowerOn();

Disables shared audio power rails.

void audioPowerOff();

Enables the speaker amplifier.

void audioSpeakerAmpOn();

Disables the speaker amplifier.

void audioSpeakerAmpOff();

Returns true when audio power rails are enabled.

bool audioPowerIsOn();

Formats accepted by Audio's memory-backed constructor. WAV, MP3, and AAC/M4A decoding are extended-edition codecs. MIDI uses the existing headless parser/synth shared with the MIDI file viewer.

enum class AudioCodec : uint8_t {
    Auto,
    Wav,
    Mp3,
    Aac,
    Midi,
    Pcm16Mono16k,
};

UI-independent, independently preloadable audio source. Multiple Audio objects may remain preloaded at once. The device has one physical codec output, so play() hands output ownership to the newest caller while preserving every other object's decoded/preloaded state.

class Audio {
    struct State;
    explicit Audio(const char *path, const char *providerId = "sd");
    Audio(const uint8_t *bytes, size_t length, AudioCodec codec);
    ~Audio();
    Audio(const Audio &) = delete;
    Audio &operator=(const Audio &) = delete;
    static bool codecAvailable(AudioCodec codec);
    bool preload();
    bool play();
    bool update();
    void stop();
    void release();
    bool loaded() const;
    bool playing() const;
    bool finished() const;
    uint32_t positionMs() const;
    uint32_t durationMs() const;
    uint32_t sampleRate() const;
    uint8_t channels() const;
    const char *error() const;
};

Size of a canonical PCM RIFF/WAVE header.

constexpr size_t kPcmHeaderSize = 44;

Writes a mono/stereo PCM header in front of already captured sample bytes. The destination must have room for kPcmHeaderSize bytes.

bool writePcmHeader(uint8_t *header, size_t headerSize, uint32_t sampleRate, uint16_t channels, uint16_t bitsPerSample, size_t pcmByteCount);

Magic value that marks a binary as a .pink executable.

static const uint32_t PINK_EXECUTABLE_MAGIC = 0x4b4e4950UL;

ABI version emitted by the current .pink build tooling.

static const uint16_t PINK_EXECUTABLE_ABI_VERSION = 12;

Oldest .pink ABI version the current firmware still accepts.

static const uint16_t PINK_EXECUTABLE_MIN_ABI_VERSION = 7;

static const uint16_t PINK_EXECUTABLE_HEADER_SIZE = 28;

static const size_t PINK_EXECUTABLE_MAX_IMAGE_BYTES = 64U * 1024U;

Events that the firmware can deliver to an external .pink app.

enum PinkEventType : uint8_t {
    PINK_EVENT_START = 1,
    PINK_EVENT_STOP = 2,
    PINK_EVENT_DRAW = 3,
    PINK_EVENT_TOUCH = 4,
    PINK_EVENT_UPDATE = 5,
    PINK_EVENT_TOUCH_DOWN = 6,
    PINK_EVENT_TOUCH_MOVE = 7,
    PINK_EVENT_TOUCH_UP = 8,
    PINK_EVENT_MENU_BUTTON = 9,
    PINK_EVENT_MENU_DOUBLE = 10,
    PINK_EVENT_MENU_LONG = 11,
    PINK_EVENT_POWER_BUTTON = 12,
    PINK_EVENT_POWER_DOUBLE = 13,
    PINK_EVENT_POWER_LONG = 14,
    PINK_EVENT_SAVE_STATE = 15,
    PINK_EVENT_RESTORE_STATE = 16,
    PINK_EVENT_PERIODIC = 17,
};

Fonts exposed by the firmware drawing host.

enum PinkFont : uint8_t {
    PINK_FONT_DEFAULT = 0,
    PINK_FONT_ICON_8 = 1,
    PINK_FONT_ICON_12 = 2,
};

enum PinkApiStatus : int8_t {
    PINK_API_ERROR = -1,
    PINK_API_DENIED = -2,
    PINK_API_UNSUPPORTED = -3,
    PINK_API_PENDING = 0,
    PINK_API_OK = 1,
    PINK_API_END = 2,
};

enum PinkFeature : uint32_t {
    PINK_FEATURE_READ_FILES = 1U << 0U,
    PINK_FEATURE_WRITE_FILES = 1U << 1U,
    PINK_FEATURE_DELETE_FILES = 1U << 2U,
    PINK_FEATURE_AUDIO_CAPTURE = 1U << 3U,
    PINK_FEATURE_GPIO = 1U << 4U,
    PINK_FEATURE_SENSORS = 1U << 5U,
    PINK_FEATURE_WIFI_SCAN = 1U << 6U,
};

enum PinkPeriodicWakeLevel : uint8_t {
    PINK_PERIODIC_SYSTEM = 2,
    PINK_PERIODIC_NETWORK = 3,
};

enum PinkPeriodicDisplayMode : uint8_t {
    PINK_PERIODIC_DISPLAY_NONE = 0,
    PINK_PERIODIC_DISPLAY_PARTIAL = 1,
    PINK_PERIODIC_DISPLAY_FULL = 2,
};

enum PinkPeriodicAction : uint8_t {
    PINK_PERIODIC_COMPLETE = 0,
    PINK_PERIODIC_WAKE_DEVICE = 3,
    PINK_PERIODIC_WAKE_APP = 4,
};

struct PinkImageTransform {
    float a = 1.0f;
    float b = 0.0f;
    float c = 0.0f;
    float d = 1.0f;
    float tx = 0.0f;
    float ty = 0.0f;
};

struct PinkSensorSnapshot {
    uint8_t temperatureValid = 0;
    uint8_t humidityValid = 0;
    uint8_t cpuTemperatureValid = 0;
    uint8_t reserved = 0;
    float temperatureC = 0.0f;
    float humidityPct = 0.0f;
    float cpuTemperatureC = 0.0f;
};

struct PinkWifiNetwork {
    char ssid[33] = {};
    int32_t rssi = -127;
};

Shared event payload exchanged between the firmware and a .pink app.

struct PinkEvent {
    uint8_t type = 0;
    uint8_t handled = 0;
    uint8_t dirty = 0;
    uint8_t reserved = 0;
    uint16_t x = 0;
    uint16_t y = 0;
    uint8_t *data = nullptr;
    size_t dataLength = 0;
    size_t dataCapacity = 0;
    size_t eventSize = 0;
    uint32_t featureFlags = 0;
    int64_t periodicLocalUnix = 0;
    uint16_t periodicIntervalMinutes = 0;
    uint8_t periodicWakeLevel = 0;
    uint8_t periodicDisplayMode = 0;
    uint8_t periodicAction = 0;
    uint8_t periodicReserved[3] = {};
};

Function table and runtime context passed to a .pink app instance.

struct PinkHost {
    uint16_t abiVersion;
    uint16_t screenWidth;
    uint16_t screenHeight;
    uint16_t reserved;
    const char *appId;
    const char *appPath;
    uint8_t *memory;
    size_t memorySize;
    uint32_t (*millis)();
    void (*delayMs)(uint32_t ms);
    void (*log)(const char *message);
    bool (*networkConnected)();
    void (*keepAwake)();
    void (*deepSleepPreventAcquire)();
    void (*deepSleepPreventRelease)();
    void (*setFont)(uint8_t font);
    void (*setTextSize)(uint8_t size);
    void (*setTextColor)(uint16_t color);
    void (*setCursor)(int16_t x, int16_t y);
    void (*print)(const char *text);
    void (*drawPixel)(int16_t x, int16_t y, uint16_t color);
    void (*drawLine)(int16_t x0, int16_t y0, int16_t x1, int16_t y1, uint16_t color);
    void (*drawRect)(int16_t x, int16_t y, int16_t w, int16_t h, uint16_t color);
    void (*fillRect)(int16_t x, int16_t y, int16_t w, int16_t h, uint16_t color);
    void (*fillScreen)(uint16_t color);
    void *(*psramAlloc)(size_t bytes);
    void (*psramFree)(void *ptr);
    bool (*configGet)(const char *key, char *out, size_t outSize);
    bool (*configSet)(const char *key, const char *value);
    size_t hostSize;
    uint32_t featureFlags;
    uint32_t reserved2;
    int8_t (*drawImagePath)(const char *path, int16_t x, int16_t y, int16_t w, int16_t h, uint8_t dither, bool scaleToFit, const PinkImageTransform *transform);
    int8_t (*drawImageBuffer)(const uint8_t *data, size_t size, const char *format, int16_t x, int16_t y, int16_t w, int16_t h, uint8_t dither, bool scaleToFit, const PinkImageTransform *transform);
    int8_t (*fileRead)(const char *path, size_t offset, uint8_t *out, size_t capacity, size_t *outRead, size_t *outFileSize);
    int8_t (*fileWrite)(const char *path, const uint8_t *data, size_t size, bool append);
    int8_t (*filePicker)(const char *initialPath, const char *extensionFilter, char *outPath, size_t outSize);
    bool (*openApp)(const char *appId);
    int8_t (*gpioConfigure)(uint8_t pin, uint8_t mode);
    int8_t (*gpioRead)(uint8_t pin, int *value);
    int8_t (*gpioWrite)(uint8_t pin, bool high);
    bool (*sensorSnapshot)(PinkSensorSnapshot *out, bool refresh);
    int8_t (*wifiScan)();
    size_t (*wifiNetworkCount)();
    bool (*wifiNetworkAt)(size_t index, PinkWifiNetwork *out);
    size_t (*fontCount)();
    bool (*fontInfo)(size_t index, char *name, size_t nameSize, uint8_t *nominalSize);
    bool (*setFontByName)(const char *name);
    void *reservedAbi9Capture[5];
    int32_t (*audioLoadPath)(const char *path);
    bool (*audioFormatSupported)(const char *format);
    int32_t (*audioLoadBuffer)(const uint8_t *data, size_t size, const char *format);
    int8_t (*audioPlay)(uint32_t handle);
    int8_t (*audioStop)(uint32_t handle);
    int8_t (*audioUpdate)(uint32_t handle);
    void (*audioRelease)(uint32_t handle);
    void *reservedAbi9DatePicker[4];
    bool (*drawQr)(const char *text, int16_t x, int16_t y, int16_t size, uint16_t color);
    void *reservedAbi9Keyboard[6];
    int8_t (*fileDelete)(const char *path);
    int8_t (*audioCaptureWav)(uint32_t maxDurationMs, const uint8_t **data, size_t *size);
    int8_t (*getDateInput)(int initialYear, int initialMonth, int initialDay, int *year, int *month, int *day);
    int8_t (*getKeyboardInput)(const char *initialText, uint8_t layout, size_t maxLength, char *out, size_t outSize);
    int8_t (*audioCapturePcm16)(uint32_t maxDurationMs, const uint8_t **data, size_t *size);
    int8_t (*drawVectorPath)(const char *path, int16_t x, int16_t y, int16_t w, int16_t h, const PinkImageTransform *transform);
    int8_t (*drawVectorString)(const char *svg, size_t size, int16_t x, int16_t y, int16_t w, int16_t h, const PinkImageTransform *transform);
};

Returns the runtime adapter used when a .pink app is active.

ActiveApp *pinkExecutableRuntime();

Re-scans storage for available .pink apps.

void pinkExecutableRefreshApps();

Counts visible .pink apps in one launcher category.

size_t pinkExecutableCount(MenuCategory category);

Copies one visible .pink app definition into caller-provided buffers.

bool pinkExecutableDefinitionAt(MenuCategory category, size_t index, AppDefinition *out, char *id, size_t idSize, char *label, size_t labelSize, char *icon, size_t iconSize);

Launches a discovered .pink app by stable id.

bool pinkExecutableLaunchById(const char *id);

Launches a .pink executable at an explicit filesystem path.

bool pinkExecutableLaunchPath(const char *path, AppDefinition *out, char *id, size_t idSize, char *label, size_t labelSize, char *icon, size_t iconSize);

Stops the active .pink app and releases its loaded image.

void pinkExecutableStop();

Summary of installed .pink hooks due in one wake window.

struct PinkPeriodicPlan {
    bool anyRegistered = false;
    bool dueAtSystem = false;
    bool dueAtNetwork = false;
    int64_t nextDueMinute = -1;
    PeriodicDisplayMode systemDisplayMode = PeriodicDisplayMode::None;
    PeriodicDisplayMode networkDisplayMode = PeriodicDisplayMode::None;
};

Combined outcome of the due .pink hooks invoked at one wake tier.

struct PinkPeriodicRunResult {
    bool wakeDevice = false;
    bool displayUpdated = false;
    char wakeAppId[24] = {};
};

Re-scans installed artifacts and plans their valid static schedules.

PinkPeriodicPlan pinkPeriodicPlan(int64_t localMinute, int64_t previousMinute, uint16_t minIntervalMinutes);

Invokes the due hooks at one initialized tier using the last plan's scan.

PinkPeriodicRunResult pinkRunDuePeriodic( int64_t localUnix, int64_t previousMinute, uint16_t minIntervalMinutes, PeriodicWakeLevel wakeLevel, Adafruit_GFX *display);

Shared result contract used by PinkApp's C ABI and PocketInkJS's adapters.

enum class AppApiStatus : int8_t {
    Error = -1,
    Denied = -2,
    Unsupported = -3,
    Pending = 0,
    Ok = 1,
};

Portable GPIO modes exposed to external apps rather than Arduino constants.

enum class AppApiGpioMode : uint8_t {
    Input = 0,
    InputPullup = 1,
    Output = 2,
};

Bounded Wi-Fi scan entry copied out of the platform network stack.

struct AppApiWifiNetwork {
    char ssid[33] = {};
    int32_t rssi = -127;
};

Callback used to consume transient directory entries during enumeration.

using AppApiDirectoryEntryHandler = bool (*)(const char *name, bool directory, uint32_t size, void *context);

Starts or resumes capability state for the active external app. Permissions live only for this session and are discarded by appApiEndSession().

bool appApiBeginSession(const char *appId);

Releases permissions, modal state, media, capture, and configured GPIO.

void appApiEndSession();

Checks whether the active capability session belongs to an app id.

bool appApiSessionMatches(const char *appId);

Performs deferred hardware work from the shell/main core.

bool appApiUpdateOnMainCore();

Shell-owned overlay hooks for permission prompts and the file picker.

bool appApiOverlayActive();

void appApiDrawOverlay(Adafruit_GFX &gfx);

bool appApiHandleOverlayTouch(const TouchPoint &point);

bool appApiHandleOverlayMenuButton();

bool appApiHandleOverlayPowerButton();

Reads an arbitrary chunk. outRead may be zero with End when offset is at or beyond EOF. Passing a null output is allowed only when capacity is zero and can be used to query the file size.

AppApiStatus appApiReadFile(const char *path, size_t offset, uint8_t *out, size_t capacity, size_t *outRead, size_t *outFileSize);

Enumerates one directory synchronously. The callback may return false to stop early; names are valid only for the duration of the callback.

AppApiStatus appApiListDirectory(const char *path, AppApiDirectoryEntryHandler handler, void *context);

Writes or appends one chunk after a once-per-session, once-per-path prompt.

AppApiStatus appApiWriteFile(const char *path, const uint8_t *data, size_t size, bool append);

Deletes one file after a once-per-session, once-per-path prompt.

AppApiStatus appApiDeleteFile(const char *path);

Opens the full-screen file picker. Repeating the request polls its state; appApiTakePickedFile consumes a completed selection.

AppApiStatus appApiRequestFilePicker(const char *initialPath, const char *extensionFilter);

AppApiStatus appApiTakePickedFile(char *out, size_t outSize);

One-call modal input APIs. The first call opens system UI; subsequent calls return Pending until the user accepts or cancels. Sandbox code never draws or hit-tests the system widgets.

AppApiStatus appApiGetKeyboardInput(const char *initialText, uint8_t layout, size_t maxLength, char *out, size_t outSize);

AppApiStatus appApiGetDateInput(const DatePickerDate &initial, DatePickerDate &out);

Queues a stable catalog id for the shell to launch after the current app callback returns.

bool appApiRequestOpenApp(const char *appId);

bool appApiTakeOpenAppRequest(char *out, size_t outSize);

Configures an allow-listed expansion GPIO after session permission.

AppApiStatus appApiGpioConfigure(uint8_t pin, AppApiGpioMode mode);

Reads an allow-listed GPIO previously configured by this session.

AppApiStatus appApiGpioRead(uint8_t pin, int *value);

Writes an allow-listed output GPIO previously configured by this session.

AppApiStatus appApiGpioWrite(uint8_t pin, bool high);

Returns the cached environment snapshot and optionally requests a refresh.

EnvironmentSnapshot appApiSensorSnapshot(bool refresh);

Starts a confirmed scan and exposes a bounded snapshot after completion.

AppApiStatus appApiWifiScan();

Returns the number of entries in the completed bounded scan snapshot.

size_t appApiWifiNetworkCount();

Copies one completed scan entry; returns false when out of range.

bool appApiWifiNetworkAt(size_t index, AppApiWifiNetwork &out);

Simplified capture operation. The system pumps recording while Pending and returns a session-owned WAV buffer at End.

AppApiStatus appApiCaptureWav(uint32_t maxDurationMs, const uint8_t **data, size_t *size);

AppApiStatus appApiCapturePcm16(uint32_t maxDurationMs, const uint8_t **data, size_t *size);

Preloads independently replayable audio. MIDI is always available; other codecs follow the firmware edition's headless Audio implementation.

bool appApiAudioFormatSupported(const char *format);

Preloads an audio path and returns a session handle, or a negative error.

int32_t appApiAudioLoadPath(const char *path);

Preloads copied audio bytes and returns a session handle, or a negative error.

int32_t appApiAudioLoadBuffer(const uint8_t *data, size_t size, const char *format);

Starts the selected preloaded source from its beginning.

AppApiStatus appApiAudioPlay(uint32_t handle);

Stops the selected source while retaining its preload state.

AppApiStatus appApiAudioStop(uint32_t handle);

Polls playback and reports End after a source finishes naturally.

AppApiStatus appApiAudioUpdate(uint32_t handle);

Releases one session audio handle and its owned resources.

void appApiAudioRelease(uint32_t handle);

Asynchronous mailbox between an app task and main-core microphone hardware.

class AudioCaptureService {
    enum class Format : uint8_t { Pcm16, Wav };
    ServiceResult request(Format format, uint32_t maxDurationMs, const uint8_t **data, size_t *size);
    void updateOnMainCore();
    void release();
};

Result of loading a source into the bounded session handle table.

struct AudioHandleResult {
    ServiceResult result;
    int32_t handle = -1;
};

Owns the bounded set of audio sources preloaded by one external app session.

class AudioService {
    explicit AudioService(FileService &files);
    bool formatSupported(const char *format) const;
    AudioHandleResult loadPath(const char *path);
    AudioHandleResult loadBuffer(const uint8_t *data, size_t size, const char *format);
    ServiceResult play(uint32_t handle);
    ServiceResult stop(uint32_t handle);
    ServiceResult update(uint32_t handle);
    void release(uint32_t handle);
    void releaseAll();
};

Validates and permissions external-app operations on the active file provider.

class FileService {
    explicit FileService(PermissionService &permissions);
    ServiceResult read(const char *path, size_t offset, uint8_t *out, size_t capacity, size_t *outRead, size_t *outFileSize);
    ServiceResult list(const char *path, AppApiDirectoryEntryHandler handler, void *context);
    ServiceResult write(const char *path, const uint8_t *data, size_t size, bool append);
    ServiceResult remove(const char *path);
    ServiceResult openRead(const char *path, File &out);
    const char *providerId() const;
};

State machine for all system UI that may temporarily cover an external app.

class ModalService {
    ModalService(PermissionService &permissions, const char *appId);
    bool update();
    bool active();
    void draw(Adafruit_GFX &gfx);
    bool handleTouch(const TouchPoint &point);
    bool handleMenuButton();
    bool handlePowerButton();
    ServiceResult requestFilePicker(const char *initialPath, const char *extensionFilter);
    ServiceResult takePickedFile(char *out, size_t outSize);
    ServiceResult keyboardInput(const char *initialText, uint8_t layout, size_t maxLength, char *out, size_t outSize);
    ServiceResult dateInput(const DatePickerDate &initial, DatePickerDate &out);
    void release();
};

Capability classes that require explicit user consent.

enum class PermissionKind : uint8_t {
    FileWrite, FileDelete, Gpio, WifiScan,
};

Stored or pending answer to one capability request.

enum class PermissionDecision : int8_t {
    Denied = -1, Pending = 0, Granted = 1,
};

Session-local permission records plus the currently unresolved user prompt.

class PermissionService {
    ServiceResult request(PermissionKind kind, const char *resource);
    bool promptActive() const;
    void drawPrompt(Adafruit_GFX &gfx, const char *appId) const;
    bool handlePromptTouch(const TouchPoint &point);
    void release();
};

Lifecycle outcome of an internal app service operation.

enum class ServiceState : uint8_t {
    Ok, Pending, End, Failed,
};

Structured failure reason retained before conversion to the public ABI.

enum class ServiceError : uint8_t {
    None,
    InvalidArgument,
    Denied,
    Unsupported,
    Busy,
    OutOfMemory,
    NotFound,
    Io,
    Hardware,
};

State, error category, and optional static detail for one service call.

struct ServiceResult {
    ServiceState state = ServiceState::Ok;
    ServiceError error = ServiceError::None;
    const char *detail = nullptr;
    static ServiceResult ok();
    static ServiceResult pending();
    static ServiceResult end();
    static ServiceResult fail(ServiceError error, const char *detail);
};

Maximum app identifier size, including the terminating null byte.

constexpr size_t kAppIdCapacity = 24;

Maximum service path size, including the terminating null byte.

constexpr size_t kPathCapacity = 288;

Copies null-terminated text without truncation or unterminated output.

bool copyText(char *out, size_t outSize, const char *text);

Accepts only absolute, normalized paths that cannot escape app storage rules.

bool safePath(const char *path);

Returns the ActiveApp adapter used for a JavaScript file launched by Files.

ActiveApp *PocketInkJSAppRuntime();

Loads and evaluates the current contents of a .js file from SD storage. Re-launching the path is the hot-reload boundary: no old VM state survives.

bool PocketInkJSAppLaunchPath(const char *path, AppDefinition *out, char *id, size_t idSize, char *label, size_t labelSize, char *icon, size_t iconSize);

Stops callbacks and releases all source/runtime PSRAM owned by PocketInkJS.

void PocketInkJSAppStop();

Compact NaN-boxed JavaScript value; only Runtime should interpret its bits.

struct Value {
    uint64_t bits = 0;
};

Public type categories returned by Runtime::typeOf().

enum class ValueType : uint8_t {
    Undefined,
    Null,
    Boolean,
    Number,
    String,
    Object,
    Array,
    Set,
    Promise,
    Function,
};

Non-owning UTF-8 byte span into runtime-managed string storage.

struct StringView {
    const char *data = nullptr;
    size_t size = 0;
};

Stable numeric script error code used where retaining messages is too costly.

enum class ErrorCode : uint8_t {

};

Observable lifecycle of a JavaScript promise.

enum class PromiseState : uint8_t {
    Pending, Fulfilled, Rejected,
};

Fixed capacity limits and optional platform hooks for one Runtime instance.

struct Options {
    uint16_t maxBindings = 160;
    uint16_t maxNatives = 48;
    uint16_t maxTemporaryRoots = 48;
    uint16_t maxHostRoots = 32;
    uint16_t maxGcWork = 256;
    uint8_t maxCallDepth = 12;
    uint8_t maxCallArguments = 16;
    uint8_t maxParseDepth = 32;
    uint32_t maxSteps = 120000;
    int64_t (*nowMilliseconds)(void *userData) = nullptr;
    void *nowUserData = nullptr;
    JsonParseFunction jsonParse = nullptr;
    void *jsonUserData = nullptr;
    AwaitPendingFunction awaitPending = nullptr;
    void *awaitUserData = nullptr;
};

Last script failure with location and a bounded source excerpt.

struct Error {
    char message[96] = {};
    char sourceLine[160] = {};
    uint32_t line = 0;
    uint32_t column = 0;
    uint16_t sourceColumn = 0;
};

Outcome and resulting value from evaluation or a function call.

struct RunResult {
    bool ok = false;
    Value value = {};
};

Current and peak use of the caller-owned runtime workspace.

struct MemoryStats {
    size_t workspaceBytes = 0;
    size_t metadataBytes = 0;
    size_t heapBytes = 0;
    size_t heapUsedBytes = 0;
    size_t heapFreeBytes = 0;
    size_t peakHeapUsedBytes = 0;
    size_t bindingCount = 0;
};

C callback facade for temporary memory borrowed from a runtime workspace.

struct ScratchAllocator {
    void *context = nullptr;
    void *(*allocate)(void *context, size_t bytes, size_t alignment) = nullptr;
    void (*release)(void *context, void *memory) = nullptr;
    size_t (*available)(void *context) = nullptr;
};

Allocation-bounded JavaScript VM operating entirely in caller-owned memory.

class Runtime {
    class ScratchLease { public: ScratchLease() = default; ScratchLease(const ScratchLease &) = delete; ScratchLease &operator=(const ScratchLease &) = delete; ScratchLease(ScratchLease &&) = delete; ScratchLease &operator=(ScratchLease &&) = delete; ~ScratchLease(); void *allocate(size_t bytes, size_t alignment = alignof(std::max_align_t)); void release(void *memory); size_t available() const; ScratchAllocator allocator(); explicit operator bool() const { return runtime_ != nullptr; } private: friend class Runtime; explicit ScratchLease(Runtime *runtime) : runtime_(runtime) {} static void *allocateCallback(void *context, size_t bytes, size_t alignment); static void releaseCallback(void *context, void *memory); static size_t availableCallback(void *context); Runtime *runtime_ = nullptr; uint32_t firstBlock_ = 0; };
    Runtime(void *workspace, size_t workspaceBytes, const Options &options = Options;
    Runtime(const Runtime &) = delete;
    Runtime &operator=(const Runtime &) = delete;
    bool ready() const;
    const Error &error() const;
    Value undefined() const;
    Value null() const;
    Value boolean(bool value) const;
    Value number(double value) const;
    ValueType typeOf(Value value) const;
    bool isCallable(Value value) const;
    bool isTruthy(Value value) const;
    bool isUndefined(Value value) const;
    bool isString(Value value) const;
    bool isNumber(Value value) const;
    double toNumber(Value value) const;
    bool toBoolean(Value value) const;
    StringView stringView(Value value) const;
    size_t format(Value value, char *out, size_t outSize) const;
    Value makeString(const char *text, size_t length);
    Value makeString(const char *text);
    Value makeStringBuffer(size_t length, char **data);
    Value makeObject();
    Value makeArray(size_t reserve = 0);
    Value makeSet();
    Value makePromise();
    Value rejectCurrentError();
    bool arrayPush(Value array, Value value);
    size_t arrayLength(Value array) const;
    Value arrayAt(Value array, size_t index) const;
    bool arraySet(Value array, size_t index, Value value);
    bool objectSet(Value object, const char *key, Value value);
    bool objectSet(Value object, const char *key, size_t keyLength, Value value);
    Value objectGet(Value object, const char *key) const;
    Value objectGet(Value object, const char *key, size_t keyLength) const;
    size_t objectPropertyCount(Value object) const;
    bool objectPropertyAt(Value object, size_t index, Value *key, Value *value) const;
    bool bind(const char *path, NativeFunction function, void *userData = nullptr);
    bool bindMethod(const char *path, NativeMethodFunction function, void *userData = nullptr);
    bool set(const char *path, Value value, bool constant = true);
    Value get(const char *name) const;
    RunResult eval(const char *source, size_t length);
    RunResult eval(const char *source);
    RunResult call(const char *name, const Value *args = nullptr, size_t argc = 0);
    RunResult call(Value function, const Value *args = nullptr, size_t argc = 0);
    RunResult callIfFunction(const char *name, const Value *args, size_t argc, bool *called);
    void collectGarbage();
    RootHandle retain(Value value);
    void release(RootHandle handle);
    Value retained(RootHandle handle) const;
    PromiseState promiseState(Value promise) const;
    Value promiseResult(Value promise) const;
    bool settlePromise(Value promise, Value result, bool rejected = false);
    Value parseJsonPromise(Value text);
    RunResult drainJobs(size_t maximum = 8);
    MemoryStats memoryStats() const;
    ScratchLease leaseScratch();
    Value fail(const char *message);
    Value fail(ErrorCode code);
};