Flipdot-display/src/esp32/app.h

#pragma once

// The objects of the clock firmware and the actions the web UI and Home Assistant use.
// main.cpp only decides the order of things at boot and in loop().

#include "BROSE9323.h"
#include "display/frames.h"
#include "display/status_screen.h"
#include "logic/display_controller.h"
#include "logic/icon_format.h"
#include "logic/local_time.h"
#include "logic/loop_stats.h"
#include "logic/page.h"
#include "logic/page_schedule.h"
#include "logic/settings.h"
#include "nano_link/nano_link.h"
#include "nano_link/nano_monitor.h"

extern NanoLink nano;
extern BROSE9323 display;
extern FlipdotFrames frames;
extern StatusScreen status;
extern DisplayController controller;
extern LoopStats loopStats;
extern NanoMonitor nanoMonitor;

// Settings: loaded at boot, changed in the web UI
const Settings &appSettings();
void appLoadSettings();
// Validates, stores and applies. Returns nullptr or an error message. Sets
// restart_needed when the change only works after a restart (Home Assistant MQTT).
const char *appSaveSettings(const Settings &settings, bool &restart_needed);

// Slow mode (Home Assistant switch and dropdown): stored and used right away. minutes: one
// of SLOW_MODE_MINUTES. Return nullptr or an error message.
void appSetSlowMode(bool enabled);
const char *appSetSlowModeMinutes(int minutes);

// The chosen page (settings): a dynamic page or a bitmap. With a schedule it is shown until
// the next block starts (a manual pick), without one all the time.
const char *appSelectPage(const char *name);

// The schedule and trigger rules (validated, stored, used right away)
const char *appSaveSchedule(const PageSchedule &schedule);
const PageSchedule &appSchedule();
// Ends a manual pick: the schedule decides again
void appBackToSchedule();
// The page or bitmap shown now, and why (e.g. "schedule", "chosen, until 17:00")
const char *appShownPage();
void appShowStatus(char *out, size_t size);
// Decides the shown page (rules, schedule, chosen page); call every loop() before the
// display controller
void appPageLoop(bool time_valid, const LocalTime &time);
// Left on the dots when the display switches off: OFF_PAGE_BLANK or a bitmap name
const char *appSelectOffPage(const char *name);

// Bitmaps, icons, dynamic pages and fonts: stored, and the display redrawn when it shows
// them. Bitmaps, icons and pages share one namespace; what a page uses can't be deleted.
// All return nullptr or an error message.
const char *appSaveBitmap(const char *name, const uint8_t *bitmap);
const char *appDeleteBitmap(const char *name);
const char *appSaveIcon(const char *name, const Icon &icon);
const char *appDeleteIcon(const char *name);
// A bitmap becomes an icon (cut to its dots from the top left, so pages look the same) and
// the other way around; not for bitmaps that are shown on their own
const char *appBitmapToIcon(const char *name);
const char *appIconToBitmap(const char *name);
// Once: the uploaded bitmaps that only pages use become icons. Call from loop(); returns at
// once when it is done.
void appMigrateIcons();
// Once per boot, after the firmware was marked good (the old firmware can't read the new
// formats): settings and schedule read in an older layout are stored again, and pages in an
// older format are rewritten. Call from loop(); returns at once when it is done.
void appMigrateData();
// Records still in an older format (-1 until appMigrateData() checked the pages)
int appOldDataLeft();
const char *appSavePage(const char *name, const DynamicPage &page);
const char *appDeletePage(const char *name);
const char *appSaveFont(const char *name, const uint8_t *data, size_t size);
const char *appDeleteFont(const char *name);

// The stopwatch of the dynamic pages (web UI and Home Assistant); redraws the display
enum class StopwatchAction
{
	Start,
	Stop,
	Reset,
};
void appStopwatch(StopwatchAction action);

// Live mode of the web UI
void appShowLive(const uint8_t *bitmap);
void appStopLive();

// The local time; false until it is synced over NTP
bool appLocalTime(LocalTime &time);

// Restart the ESP32 after `delay_ms` (so a web response can still be sent)
void appRestartLater(uint32_t delay_ms);
void appLoop();