onlyn00bs-badge

display.h (11812B)

---

 #pragma once
 #include "peers.h"
 #include "encounters.h"
 #include "points.h"
 #include "points_history.h"
 
 // ─────────────────────────────────────────────────────────────────────────
 //  Display abstraction. The board-independent core calls these; the concrete
 //  implementation is chosen at build time via a -D flag in platformio.ini:
 //
 //    BADGE_DISPLAY_SERIAL  → display_serial.cpp   (works on ANY ESP32 today;
 //                                                  renders to the serial monitor)
 //    BADGE_DISPLAY_EINK    → display_eink.cpp     (LilyGo T5 4.7")
 //
 //  Swapping screens = swapping one .cpp file. The protocol never changes.
 // ─────────────────────────────────────────────────────────────────────────
 
 void display_init();
 
 // Power the panel down before deep sleep. The SSD1309 draws ~10-20 mA and keeps drawing
 // with the SoC asleep — without this the sleep saves almost nothing. One-way by design:
 // waking is a full restart through display_init(), so there is no matching _wake().
 void display_sleep();
 
 // Boot splash / one-line status.
 void display_boot(const char* line);
 
 // Animated boot splash, shown once at power-on before the mode screen. OLED
 // animates (style = one of BOOT_SPLASH_* in config.h); serial prints a static
 // ASCII banner; e-ink draws a static logo. Blocks ~1–1.5s (boot only).
 void display_boot_splash(int style);
 
 // Logo card, shown once at boot immediately AFTER display_boot_splash() and before the
 // disclaimer — so it plays whichever splash style the user picked, rather than replacing
 // one. The OLED blits the baked bitmaps from logos.h as full-screen frames, sharing the
 // BOOT_LOGO_TOTAL_MS budget between them; serial prints a one-line credit. Blocking
 // (boot only), ~4.9s on the OLED.
 void display_boot_logos();
 
 // A light-hearted heat + LiPo-safety disclaimer, shown once at boot right after the
 // splash. A static full-screen text card; blocking (boot only) — the caller holds it
 // on screen (DISCLAIMER_HOLD_MS × BOOT_TIMING_SCALE) then continues the boot sequence.
 void display_disclaimer();
 
 // Provisioning mode: tell the user to connect over BLE, show the device name and the
 // 3-char pairing `code` they must enter in the web app to unlock provisioning.
 void display_provisioning(const char* device_name, const char* code);
 
 // Whoami: a read-only identity screen — the badge's handle (username) + eFuse MAC.
 void display_whoami(const char* handle, const char* mac);
 
 // Home view — the at-a-glance default/initial screen: the user's handle, pet face,
 // total points, battery %, and wall-clock time. `clock_str` is preformatted by the
 // caller ("HH:MM", or "--:--" when the clock is unsynced/stale) so the backends stay
 // clock-agnostic; `batt_low` flags the warning threshold for an inline marker.
 // `disk_pct` is LittleFS % USED (same polarity as the STORAGE view), printed as a second
 // header readout beside the battery — as text; the disk glyph itself is static, unlike the
 // battery's proportional one. The caller supplies it from its cached figures — usedBytes()
 // must never be walked from a live redraw.
 // `radio_on` is the Badge Settings → Stealth switch (inverted: stealth ON = radio off).
 // When it's false the badge is NOT broadcasting, and HOME says so with an inverse STEALTH
 // chip along the bottom: a silent badge with no on-screen tell is indistinguishable from a
 // broken one, and this is the default view.
 void display_home(const char* handle, const char* pet_face, uint32_t points,
                   uint8_t batt_pct, bool batt_low, uint8_t disk_pct, const char* clock_str,
                   bool radio_on);
 
 // The finder list renders this many peers per screen (one "page"); main.cpp uses it for
 // the page count + wrap math, the OLED backend for its row slice. Fixed by the 64px panel.
 #define FINDER_PAGE_ROWS 5
 
 // Finder mode: render the sorted peer list (closest first). The OLED header is a
 // static "// finder" title (matching the other view headers); each peer row shows
 // that peer's handle. `my_handle` is used only by the serial backend's diagnostic
 // line. show_rssi toggles the OLED right column: false = peer's pet face, true =
 // dBm. `mult` is the active group points-multiplier (1 = none; 2/3 show an
 // indicator chip in the header — see POINTS_X2_PEERS / POINTS_X3_PEERS). `page` is the
 // 0-based page of the list (FINDER_PAGE_ROWS per screen); the OLED renders that slice
 // and shows "p/P" in the header when P>1. The serial backend lists all peers, ignoring it.
 void display_peers(const char* my_handle, const Peer* peers, int n, bool show_rssi,
                    uint8_t mult, int page);
 
 // Report mode: the "social graph of your con" — aggregated friend stats.
 void display_report(const char* my_handle, const Report& r);
 
 // Points mode: gamified proximity score. `points` is 1 per full minute spent
 // with crew close enough to clear the RSSI gate; `prox_seconds` is the
 // underlying tally (its sub-minute remainder drives a live countdown to the
 // next point). `peers_now` is the current in-range crew count; `earning` is
 // whether the tally is accruing right now (≥1 crew AND within the RSSI gate AND not
 // stealthed) — so the view can distinguish "no crew" from "crew here but too far".
 // `stealth` says WHY it's paused when that's the reason: stealth stops scoring, and crew
 // can be in range and in-gate at the time, so "too far" would be an outright lie. Check
 // it before the distance case.
 // `hist`/`hist_n` are the timestamped points-over-time samples (oldest→newest)
 // for the line graph on this view; `hist_n` may be 0 (nothing sampled yet).
 // `mult` is the active group multiplier (1/2/3): ≥2 shows the indicator chip and
 // scales the "+1 pt in Ns" countdown (the tally ticks ×mult per wall second).
 void display_points(const char* my_handle, uint32_t points,
                     uint32_t prox_seconds, int peers_now, bool earning,
                     const PointSample* hist, int hist_n,
                     uint32_t graph_span_s, const char* window_label, bool anchor_newest,
                     uint8_t mult, bool stealth);
 
 // Best-friends mode: the top crew by close-time shared with you, most first.
 // `top[i].seconds / 60` is the minutes you spent near friend i; `total_points`
 // is your whole score. Each friend is ≤ the total, but they overlap (a group
 // minute credits everyone), so they don't sum to it. `n` is how many are in
 // `top` (may be < 3 early on, 0 before you've scored anything).
 void display_friends(const char* my_handle, const PointFriend* top, int n,
                      uint32_t total_points);
 
 // Battery mode: coarse LiPo fuel gauge for "charge tonight?" decisions. `mv` is
 // the divider-corrected battery voltage in millivolts, `pct` the 0..100 charge
 // estimate (linear on voltage — slightly pessimistic mid-range, the safe way),
 // `low` flags that we're at/below the warning threshold.
 void display_battery(const char* my_handle, uint16_t mv, uint8_t pct, bool low);
 
 // STORAGE readout — the BATTERY view's single-tap alternate. `used`/`total` are LittleFS
 // bytes, cached by the caller (usedBytes() walks the filesystem, so it must not be re-read
 // on every live redraw). Reports USED, per disk convention — the bar fills as the disk
 // fills, the opposite polarity to the battery face it otherwise mirrors — with the
 // remaining space shown alongside as a free-bytes figure. `full` is the caller's
 // disk-guard verdict (same >=90% trip that trims the log), drawn as a warning.
 void display_storage(const char* my_handle, size_t used, size_t total, bool full);
 
 // Pet selection screen — the badge companion: name header + a big ASCII face (no
 // stats readout). `face` is the current state-face (idle / reaction / lonely /
 // low-batt), already resolved by the caller. Tap swaps the pet.
 void display_pet(const char* name, const char* face);
 
 // Settings MENU — currently the boot-splash picker. `splash_sel` is
 // 0..BOOT_SPLASH_COUNT-1 (radar / terminal / glitch / matrix).
 void display_menu(int splash_sel);
 
 // Transient reaction pop-up: a big pet face + a reason line (line1), with an
 // optional detail line (line2 — pass nullptr for a single-line toast). Briefly
 // overlays the current view when an event fires off the PET view (cooldown by caller).
 void display_pet_popup(const char* face, const char* line1, const char* line2,
                        uint16_t hold_ms);
 
 // NON-BLOCKING toast — same look as display_pet_popup (big face + 1–2 lines) but it
 // draws and returns immediately (no hold/delay). The caller owns its lifetime: it
 // stays on screen until the caller redraws (dismissed by a button press / timeout in
 // the main loop). Used for reminder alerts, which must not freeze beaconing/scoring.
 void display_toast(const char* face, const char* line1, const char* line2);
 
 // OPTIONS menus. `screen` selects which one to draw: ROOT (Back · User Settings ·
 // Badge Settings), USER (Back · Pet · Finder View · Reminders), BADGE (Back · Display ·
 // Stealth · Developer Options · Power), DISPLAY (Back · Splash), DEVOPTS (Back · Whoami ·
 // Debug · Provisioning Mode), REMIND (Back · Global · Shower), or POWER (Back · Reboot ·
 // Deep sleep). A cursor list with Back first (the default row). OptView carries the
 // dynamic row values; each screen reads only the fields it renders — beats a positional
 // const char* per row as the tree grows.
 // NOTE: BADGE is at 5 rows, which is the renderer's hard cap (`rows[5]` + the y0/dy
 // ladder). A sixth row there needs the array and the ladder widened first — which is why
 // POWER exists as a sub-menu: it holds Reboot + Deep sleep in the slot Reboot alone used
 // to occupy, instead of growing BADGE past the cap.
 enum OptMenu { OPTM_ROOT = 0, OPTM_USER, OPTM_BADGE, OPTM_DISPLAY, OPTM_DEVOPTS, OPTM_REMIND,
                OPTM_POWER };
 struct OptView {
   const char* pet;             // USER    — active pet name
   const char* splash;          // DISPLAY — boot-splash style name
   const char* bright;          // DISPLAY — "LOW"/"MED"/"HIGH"
   const char* test_state;      // DEVOPTS — "ON"/"OFF"
   const char* finder_mode;     // USER    — "pet"/"dBm"
   const char* remind_global;   // REMIND  — "ON"/"OFF"
   const char* remind_shower;   // REMIND  — "ON"/"OFF"
   // BADGE — "ON"/"OFF" for STEALTH, which is the INVERSE of the internal g_radio_on:
   // stealth ON = not broadcasting. The caller does the inversion; don't re-flip it here.
   const char* stealth;
 };
 void display_options_menu(int screen, int cursor, const OptView& v);
 
 // Factory-reset confirmation. Its own screen rather than a row in DEVOPTS because the
 // menu's activate gesture is a double-tap: one fumbled press on a bare "Factory Reset" row
 // would wipe someone's whole con with no way back. Spells out what goes, and `cursor` 0 is
 // Cancel — the default landing row, so the destructive option is never the one under the
 // cursor when you arrive. 1 = confirm.
 void display_reset_confirm(int cursor);
 
 // Screen brightness. `level` indexes the SCREEN_BRIGHT_* table (0=LOW, 1=MED, 2=HIGH);
 // out-of-range falls back to SCREEN_BRIGHT_DEFAULT. The OLED backend maps it to the
 // panel's contrast register; serial has no panel and no-ops. Must be called AFTER the
 // display is up (display_init() claims the I2C bus) — and, for the saved pick, after
 // NVS is open, which is later than display_init() in setup().
 void display_set_brightness(uint8_t level);