@geastack/core 0.1.23

package/include/platform/file_cache.h

@@ -0,0 +1,18 @@
+#pragma once
+
+namespace gea::platform::storage {
+
+// Ensure the persistent file-cache filesystem is mounted; returns true when a
+// writable root is available. Calls the registered mount provider (idempotent —
+// safe on every file op). With no provider registered it returns false, so
+// targets without persistent storage transparently fall back to no caching.
+bool ensureMounted();
+
+// Register the platform's mount provider. A target with persistent storage (e.g.
+// a microSD card) calls this at startup with its mount function. Done via
+// explicit registration rather than a weak symbol so the provider's translation
+// unit is guaranteed to be linked in (see the waveshare-p4-7 sdcard_mount.cpp,
+// wired from app_main).
+void setMountProvider(bool (*provider)());
+
+}  // namespace gea::platform::storage

package/include/power.h

@@ -0,0 +1,11 @@
+#pragma once
+
+namespace gea::platform::power {
+
+class Power {
+public:
+	static bool init();
+	static int batteryPercent();
+};
+
+}  // namespace gea::platform::power

package/include/runtime.h

@@ -0,0 +1,83 @@
+#pragma once
+
+// Optional application boot hook. An app that ships native sources can define
+// `gea_app_native_boot` to bring its own hardware up before the runtime claims
+// the display, the radios and the frame loop. It is a weak *declaration* with
+// no default definition: an app that does not provide one leaves the symbol
+// null and Runtime::run() skips the call.
+extern "C" void gea_app_native_boot(void) __attribute__((weak));
+
+// Bytes of internal, DMA-capable RAM to hold back for the display across the
+// app's native boot hook. The app hook runs FIRST, by design -- an app that owns
+// hardware needs its large contiguous internal allocations before the panel
+// takes what is left -- but an app that fills internal RAM leaves the display
+// unable to bring its bus up at all: the failure this exists for was 3,236 bytes
+// free, largest block 1,600, and "SPI bus init failed: ESP_ERR_NO_MEM" one
+// millisecond after the framebuffer landed in PSRAM. So Runtime::boot() takes a
+// reserve through gea::platform::memory::Memory before the hook and releases it
+// immediately before Display::init(), which turns an out-of-memory panel into
+// the app giving up its last few kilobytes. 0 disables the reserve, which is
+// every board that has never needed it. Declare it with `gea.defines`.
+//
+// Reserving for the WHOLE hook is the blunt version, and it is wrong for an app
+// whose hook has a mandatory phase and a greedy one. The pedal is the case: its
+// model arenas are a 213,472-byte bin-packing problem against 217,592 free, and
+// holding anything back there makes the packer fail or time out, while the
+// reverb promotion that runs straight afterwards takes 13 KB purely because it
+// is there. Such an app leaves this at 0 and calls holdDisplayReserve() itself,
+// between the two phases. See that method.
+// A board that declares neither a panel nor a canvas has nothing to render to.
+// The runtime then builds no framebuffer, no app tree and no frame loop; the
+// board's own boot hook still runs, so a headless appliance keeps everything
+// that is not the UI. Boards that say nothing keep a display, as they always
+// have.
+#ifndef GEA_EMBEDDED_NO_DISPLAY
+#define GEA_EMBEDDED_NO_DISPLAY 0
+#endif
+
+#ifndef GEA_EMBEDDED_DISPLAY_INTERNAL_RESERVE_BYTES
+#define GEA_EMBEDDED_DISPLAY_INTERNAL_RESERVE_BYTES 0
+#endif
+
+namespace gea::framework {
+
+struct RuntimeOptions {
+	int width = 0;
+	int height = 0;
+};
+
+class Runtime {
+public:
+	static void run(const RuntimeOptions &options);
+	// Runs the app's native boot hook, once. run() calls this itself, so an app
+	// never has to; a target calls it first when it wants the hook to run on a
+	// different task than the frame loop. That is not a stylistic choice: the
+	// hook is where an app initialises flash-backed things (NVS, a filesystem,
+	// its own partitions), and a task that performs a flash operation must be on
+	// an internal stack, while a frame loop that only renders can live on an
+	// external one. A target that keeps the loop on a PSRAM stack therefore runs
+	// the hook on the bring-up task and hands the loop over afterwards.
+	static void runNativeBoot();
+
+	// Bring-up only: services, storage, radios, display, the app's first mount,
+	// the frame scheduler -- everything up to but not including the event loop.
+	// It touches flash, so it must run on a task whose stack is in INTERNAL RAM;
+	// a target that runs the loop on an external stack calls this from its
+	// bring-up task and then lets run() do nothing but loop. Idempotent: run()
+	// calls it, so a target that does not care never sees a difference.
+	static bool boot(const RuntimeOptions &options);
+
+	// Hands the runtime a block of internal RAM to hold for the display and free
+	// immediately before Display::init(). For an app whose native boot hook has
+	// a phase that must not see less RAM than it actually has, followed by one
+	// that will opportunistically eat whatever is left: take the block with
+	// gea::platform::memory::Memory::reserveInternalDma() at the moment in
+	// between and pass it here. nullptr is accepted and means no reserve, so a
+	// failed reservation needs no check at the call site. Called more than once,
+	// the later block is held and the earlier one is freed at once -- the
+	// runtime holds exactly one app reserve, in addition to the one
+	// GEA_EMBEDDED_DISPLAY_INTERNAL_RESERVE_BYTES asks for.
+	static void holdDisplayReserve(void *reserve);
+};
+
+}  // namespace gea::framework

package/include/services/app_runner.h

@@ -0,0 +1,10 @@
+#pragma once
+
+namespace gea::framework::services {
+
+class AppRunner {
+public:
+	static bool initApplication(int width, int height);
+};
+
+}  // namespace gea::framework::services

package/include/services/app_state.h

@@ -0,0 +1,14 @@
+#pragma once
+
+namespace gea::framework::services {
+
+class AppState {
+public:
+	static bool init();
+	static void lock();
+	static void unlock();
+	static const char *currentAppId();
+	static void afterAppInit();
+};
+
+}  // namespace gea::framework::services

package/include/services/battery_service.h

@@ -0,0 +1,12 @@
+#pragma once
+
+namespace gea::framework::services {
+
+class BatteryService {
+public:
+	static void update();
+	static void start();
+	static void poll(int nowMs);
+};
+
+}  // namespace gea::framework::services

package/include/services/bluetooth_service.h

@@ -0,0 +1,13 @@
+#pragma once
+
+namespace gea::framework::services {
+
+class BluetoothService {
+public:
+	static void preinitForApp();
+	static void notifyConnected();
+	static void notifyDisconnected();
+	static void notifyBound();
+};
+
+}  // namespace gea::framework::services

package/include/services/diagnostics.h

@@ -0,0 +1,76 @@
+#pragma once
+
+#include <cstdarg>
+#include <cstdint>
+#include <cstddef>
+
+namespace gea::framework::services {
+
+class DiagnosticsFrame {
+public:
+	virtual ~DiagnosticsFrame() = default;
+	virtual bool empty() const = 0;
+	virtual unsigned char *payload() = 0;
+	virtual int payloadCapacity() const = 0;
+	virtual bool queue(int channel, int type, const unsigned char *payload, int payload_len) = 0;
+};
+
+class DiagnosticsOutput {
+public:
+	virtual ~DiagnosticsOutput() = default;
+	virtual int write(const unsigned char *data, int len, int *err_out) = 0;
+};
+
+enum class DiagnosticsSendStatus {
+	Idle,
+	Sent,
+	Backpressure,
+	Closed,
+};
+
+class DiagnosticsConnection {
+public:
+	DiagnosticsConnection();
+	~DiagnosticsConnection();
+	DiagnosticsConnection(const DiagnosticsConnection &) = delete;
+	DiagnosticsConnection &operator=(const DiagnosticsConnection &) = delete;
+
+	void reset();
+	bool hasPendingOutput() const;
+	bool wantsImmediatePoll(std::int64_t now_us) const;
+	int pollIntervalMs() const;
+	int backpressureDelayMs() const;
+	void handleIncoming(const char *data, int len);
+	DiagnosticsSendStatus flush(DiagnosticsOutput &output, std::int64_t now_us, int *err_out);
+	void prepareNextFrame(std::int64_t now_us);
+
+private:
+	class Impl;
+	Impl *impl_;
+};
+
+class DiagnosticsServer {
+public:
+	static bool begin();
+	static int port();
+	static void start();
+	static void print(const char *fmt, ...);
+	static int vprint(const char *fmt, std::va_list args);
+};
+
+class HeapProbe {
+public:
+	static void log(const char *stage);
+};
+
+class StackProbe {
+public:
+	static void logCurrentTask(const char *stage);
+};
+
+class HeapTaskSummary {
+public:
+	static void log(const char *stage);
+};
+
+}  // namespace gea::framework::services

package/include/services/diagnostics_platform.h

@@ -0,0 +1,54 @@
+#pragma once
+
+#include "services/diagnostics.h"
+
+#include <cstdarg>
+#include <cstdint>
+
+namespace gea::framework::services {
+
+enum DiagnosticsWaitEvent {
+	kDiagnosticsWaitNone = 0,
+	kDiagnosticsWaitListenerReadable = 1 << 0,
+	kDiagnosticsWaitPeerReadable = 1 << 1,
+	kDiagnosticsWaitPeerWritable = 1 << 2,
+};
+
+constexpr int kDiagnosticsIoWouldBlock = -2;
+
+class DiagnosticsPeer : public DiagnosticsOutput {
+public:
+	~DiagnosticsPeer() override = default;
+	virtual int read(char *data, int len, int *err_out) = 0;
+	virtual void close(const char *reason, int err) = 0;
+};
+
+class DiagnosticsListener {
+public:
+	virtual ~DiagnosticsListener() = default;
+	virtual bool listen(int port) = 0;
+	virtual DiagnosticsPeer *accept() = 0;
+	virtual int wait(DiagnosticsPeer *peer, bool wait_for_peer_write, int timeout_ms, int *err_out) = 0;
+};
+
+using DiagnosticsVPrintSink = int (*)(const char *, std::va_list);
+
+class DiagnosticsPlatform {
+public:
+	virtual ~DiagnosticsPlatform() = default;
+	virtual DiagnosticsListener &listener() = 0;
+	virtual void installLogSink(DiagnosticsVPrintSink sink) = 0;
+	virtual void startTask(void (*entry)(void *), void *context) = 0;
+	virtual std::int64_t nowUs() = 0;
+	virtual void sleepMs(int ms) = 0;
+	virtual void logInfo(const char *fmt, ...) = 0;
+	virtual void logWarn(const char *fmt, ...) = 0;
+	virtual void logError(const char *fmt, ...) = 0;
+	virtual void logHeapProbe(const char *stage) = 0;
+	virtual void logCurrentTaskStackProbe(const char *stage) { (void)stage; }
+	virtual void logHeapTaskSummary(const char *stage) { (void)stage; }
+};
+
+DiagnosticsPlatform &diagnosticsPlatform();
+
+}  // namespace gea::framework::services

package/include/services/frame_scheduler.h

@@ -0,0 +1,71 @@
+#pragma once
+
+#include "event.h"
+
+namespace gea::framework::services {
+
+class EventQueue {
+public:
+	constexpr EventQueue() = default;
+	explicit constexpr EventQueue(void *native) : native_(native) {}
+
+	explicit constexpr operator bool() const { return native_ != nullptr; }
+	constexpr void *nativeHandle() const { return native_; }
+
+private:
+	void *native_ = nullptr;
+};
+
+class FrameScheduler {
+public:
+	using FrameCallback = void (*)(int timestamp_ms, void *context);
+
+	struct FrameCallbacks {
+		FrameCallback frame = nullptr;
+		void *context = nullptr;
+	};
+
+#ifndef GEA_EMBEDDED_DEFAULT_FRAME_INTERVAL_US
+#define GEA_EMBEDDED_DEFAULT_FRAME_INTERVAL_US 16667
+#endif
+
+	static constexpr int kDefaultFrameIntervalUs = GEA_EMBEDDED_DEFAULT_FRAME_INTERVAL_US;
+	static constexpr int kDefaultFrameIntervalMs = 16;
+	static constexpr int kMinFrameIntervalMs = 1;
+	static constexpr int kMaxFrameIntervalMs = 1000;
+	static constexpr int kFrameIntervalUs = kDefaultFrameIntervalUs;
+	static constexpr int kFrameIntervalMs = kDefaultFrameIntervalMs;
+	static constexpr int kWatchdogMs = 2000;
+	static constexpr int kEventQueueDepth = 32;
+
+	static EventQueue createEventQueue();
+	static EventQueue eventQueue();
+	static bool sendEvent(const gea::framework::events::Event &event, int wait_ms = 0);
+	static bool receiveEvent(gea::framework::events::Event *event);
+	static void start(EventQueue queue);
+	static void runFrame(const FrameCallbacks &callbacks);
+	// Graceful-overrun catch-up (see runFrame): takeCatchUpRequest() returns+clears
+	// whether the last frame overran the budget; drainFramesAndCheckInput() discards
+	// the timer's redundant queued frames and returns true if real input is waiting,
+	// so the catch-up loop yields to input but not to its own frame posts.
+	static bool takeCatchUpRequest();
+	static bool drainFramesAndCheckInput();
+	// TE-vsync single-clock pacing: when the active display has TE-sync enabled, the
+	// panel's TE edge is the ONE frame clock. The TE ISR (teEdgeIsr → notifyVsyncFromISR)
+	// becomes the sole frame producer; the scheduler's own timer stops posting frames
+	// (it stays only as a dead-TE watchdog), and the runtime loop suppresses its
+	// timer/touch frame posts + back-to-back catch-up. This eliminates the second clock
+	// (scheduler timer) that raced the TE → unstable 30-44fps pan. No effect on non-vsync
+	// apps. setVsyncDriven() is called from the display backend's setVSync().
+	static void setVsyncDriven(bool driven);
+	static bool vsyncDriven();
+	// Post exactly one (coalesced) frame from the panel TE edge ISR. ISR-safe.
+	static void notifyVsyncFromISR();
+	static void setFrameIntervalMs(int interval_ms);
+	static int frameIntervalMs();
+	static void setFrameRate(double fps);
+	static double frameRate();
+	static int nowMs();
+};
+
+}  // namespace gea::framework::services

package/include/services/mirror.h

@@ -0,0 +1,49 @@
+#pragma once
+
+#include "services/diagnostics.h"
+
+#include <cstdint>
+
+namespace gea::framework::services {
+
+class MirrorService {
+public:
+	static int beginSnapshot();
+	static int beginDiff();
+	static int nextRecord(unsigned char *dst, int capacity);
+	static void clearDirty();
+};
+
+class MirrorTransport {
+public:
+	~MirrorTransport();
+
+	static int pollIntervalMs();
+
+	bool enabled() const;
+	bool suppressesLogForwarding() const;
+	void reset();
+	bool handleCommand(char command);
+	bool ready(std::int64_t now) const;
+	void syncCurrentApp();
+	bool ensureBuffer(DiagnosticsFrame &pending);
+	void beginIfDue(std::int64_t now, DiagnosticsFrame &pending);
+	void appendBatch(std::int64_t now, DiagnosticsFrame &pending);
+
+private:
+	void enable();
+	void disable();
+	void endMessage(std::int64_t now);
+	void releaseBuffer();
+
+	bool enabled_ = false;
+	bool forceSnapshot_ = true;
+	bool messageActive_ = false;
+	unsigned char *buffer_ = nullptr;
+	int cap_ = 0;
+	int heldLen_ = 0;
+	std::int64_t nextAt_ = 0;
+	char appId_[64] = "";
+};
+
+}  // namespace gea::framework::services

package/include/services/network_services.h

@@ -0,0 +1,25 @@
+#pragma once
+
+namespace gea::framework::services {
+
+struct NetworkServicesOptions {
+	// Device control and screenshots use the USB command channel. Keep the
+	// separate TCP diagnostics server opt-in so its 6 KiB task does not compete
+	// with WiFi OTA on RAM-constrained boards.
+	bool diagnosticsEnabled = false;
+	bool otaEnabled = true;
+};
+
+class NetworkServices {
+public:
+	// Records the requested service options. If early boot already connected
+	// WiFi, starts the servers immediately and returns true. Otherwise the
+	// platform WiFi bring-up calls startDeferredServers() after lazy connection.
+	static bool start(const NetworkServicesOptions &options);
+
+	// Starts diagnostics/OTA per the options recorded by start(). Called by the
+	// platform WiFi driver once the radio is up and connected.
+	static void startDeferredServers();
+};
+
+}  // namespace gea::framework::services

package/include/services/ota.h

@@ -0,0 +1,32 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+
+namespace gea::framework::services {
+
+class OtaServer {
+public:
+	enum class Result : std::uint8_t {
+		Ok = 0,
+		InvalidSize = 1,
+		NoPartition = 2,
+		BeginFailed = 3,
+		WriteFailed = 4,
+		SizeMismatch = 5,
+		ValidationFailed = 6,
+		BootSelectionFailed = 7,
+		NotStarted = 8,
+	};
+
+	static bool start();
+	static Result beginImage(std::size_t imageSize);
+	static Result writeImage(const std::uint8_t *data, std::size_t length);
+	static Result finishImage();
+	static void abortImage();
+	static std::size_t receivedBytes();
+	static std::size_t expectedBytes();
+	static void rebootSoon();
+};
+
+}  // namespace gea::framework::services

package/include/services/runtime_log.h

@@ -0,0 +1,11 @@
+#pragma once
+
+namespace gea::framework::services {
+
+class RuntimeLog {
+public:
+	static void printRuntimeBanner();
+	static void appStarted(bool networkReady);
+};
+
+}  // namespace gea::framework::services

package/include/services/storage_service.h

@@ -0,0 +1,26 @@
+#pragma once
+
+#include <string>
+
+namespace gea::framework::services {
+
+class StorageService {
+public:
+	static bool init();
+
+	// Persistent key/value strings (NVS "gea" namespace on esp32). getString
+	// fills buf and returns true iff the key exists; setString persists + commits.
+	// Used for device settings such as the default launch app (read at boot).
+	static bool getString(const char *key, char *buf, unsigned capacity);
+	static bool setString(const char *key, const char *value);
+
+	// Whole-store blob persistence for the app-facing `localStorage` (see
+	// gea::host::StorageFacade). The facade keeps the live key/value set in RAM
+	// and serializes it to one opaque, binary-safe blob; loadKv restores it at
+	// boot (empty `out` if none stored), saveKv persists it (an empty blob clears
+	// the slot). Backed by an NVS blob on esp32, RAM elsewhere.
+	static bool loadKv(std::string &out);
+	static void saveKv(const std::string &blob);
+};
+
+}  // namespace gea::framework::services

package/include/touch.h

@@ -0,0 +1,38 @@
+#pragma once
+
+namespace gea::platform::touch {
+
+enum class Phase {
+	Down = 1,
+	Move = 2,
+	Up = 3,
+};
+
+class Touchscreen {
+public:
+	using Observer = void (*)(Phase phase, bool touching, int x, int y);
+	// Multi-finger variant: same event plus a 0-based finger index (0 = primary).
+	// Controllers that support simultaneous touches (e.g. the GT911) report every
+	// finger through this. Single-touch controllers leave it unimplemented; the
+	// weak default in touch_runtime.cpp is a no-op, so those targets keep using
+	// the single Observer with no code change.
+	using PointerObserver = void (*)(Phase phase, bool touching, int x, int y, int pointerId);
+
+	static void setObserver(Observer observer);
+	// Optional: register a multi-finger observer. Default (weak) no-op.
+	static void setPointerObserver(PointerObserver observer);
+	static bool init();
+	// Optional event-loop polling hook. Controllers backed by interrupts or their
+	// own driver task use the weak no-op implementation.
+	static void poll(int nowMs);
+	static int read(int *x, int *y);
+	static int readCached(int *x, int *y);
+	static void consumeLatestMove(int *x, int *y);
+	// Inject a synthetic touch event through the same path as the hardware
+	// reader: updates the latest-move cache (so consumeLatestMove returns these
+	// coords) and notifies the observer. Used by the debug FIFO so injected
+	// drags behave exactly like a real finger.
+	static void injectEvent(Phase phase, bool touching, int x, int y);
+};
+
+}  // namespace gea::platform::touch