From b03c08454c32e39e3da225e8903403656437af10 Mon Sep 17 00:00:00 2001 From: Daniel Date: Tue, 3 Feb 2026 00:02:53 -0800 Subject: [PATCH] docs: document extensions and app upload workflow --- docs/app-architecture.md | 76 ++++++++++++++++++++++++ docs/apps.md | 111 ++++++++++++++++++++++++++++++++++++ docs/webserver-endpoints.md | 63 ++++++++++++++++++++ docs/webserver.md | 2 + 4 files changed, 252 insertions(+) create mode 100644 docs/app-architecture.md create mode 100644 docs/apps.md diff --git a/docs/app-architecture.md b/docs/app-architecture.md new file mode 100644 index 00000000..d35de577 --- /dev/null +++ b/docs/app-architecture.md @@ -0,0 +1,76 @@ +# App / Extension Architecture + +This document explains how CrossPoint apps (aka extensions) work today, and how we can evolve toward an on-device app store. + +## Current Model: Partition-based apps + +CrossPoint runs as the main firmware, and apps are installed by flashing a standalone firmware image into the device's *other* OTA partition. + +### Components + +- **Apps directory** (SD): `/.crosspoint/apps//` + - `app.json`: manifest (name/version/author/minFirmware...) + - `app.bin`: firmware image for the app (ESP32-C3) +- **Launcher UI** (device): Home → Apps + - lists apps discovered on SD + - installs/launches apps by flashing `app.bin` +- **AppLoader**: SD scan + OTA flashing +- **File Transfer Web UI**: developer workflow for uploading apps without removing SD + +### End-to-end flow + +```text +Developer builds app firmware -> app.bin + | + | (WiFi) upload via File Transfer /apps (developer page) + v +SD card: /.crosspoint/apps//{app.bin, app.json} + | + | (device UI) Home -> Apps -> select app -> Install + v +AppLoader flashes app.bin to next OTA partition, sets boot partition, reboots + | + v +Device boots into the app firmware +``` + +### Why this aligns with extension requests + +This keeps out-of-scope features (games/puzzles, experimental tools) out of the core reader firmware while still allowing the community to build and run them. + +This is directly aligned with: +- Discussion #257: "extension/plugin support" requests +- Discussion #575: chess interest + feedback that games should not live in the core firmware + +## Future: On-device app store (proposed) + +The current system requires getting `app.bin` onto the SD card. +An on-device app store would automate that step by downloading releases and assets over WiFi. + +### Proposed pieces + +1) **Registry** + +- `apps.json` listing available apps with metadata and download URLs. +- Maintainer choice: + - separate repo (recommended) `crosspoint-reader/app-registry` + - or keep `apps.json` in the firmware repo + +2) **Release assets** + +- Required: `app.bin` +- Optional: `assets.zip` (unpacks to `/.crosspoint//...`) +- Optional: `app.json` (manifest) if authors prefer to author it directly + +3) **Device-side store UX** (follow-up work) + +- Fetch registry over HTTPS +- Download `app.bin` + optional `assets.zip` to SD +- Unpack assets to expected paths +- Surface install/update actions via Home → Apps + +### Why assets.zip matters + +Many apps need more than a binary (sprites, fonts, puzzle packs). +For production UX, users should not have to manually place these files. +Bundling assets as a separate downloadable archive keeps the app firmware small while enabling a 1-click install experience. diff --git a/docs/apps.md b/docs/apps.md new file mode 100644 index 00000000..fca66f07 --- /dev/null +++ b/docs/apps.md @@ -0,0 +1,111 @@ +# Apps (Extensions) and Developer Workflow + +CrossPoint supports **apps/extensions** that live on the SD card and are installed by flashing their firmware image into the device's unused OTA partition. + +This is intentionally designed so out-of-scope apps (games, puzzles, etc.) do **not** need to be included in the core reader firmware. + +## What is an "app"? + +An app is a **standalone firmware binary** (ESP32-C3) with a small manifest. + +SD card layout: + +``` +/.crosspoint/apps// + app.bin # app firmware image (ESP32-C3; starts with magic byte 0xE9) + app.json # manifest (name, version, ...) +``` + +The CrossPoint launcher discovers apps by scanning `/.crosspoint/apps/*/app.json`. + +## Installing an app (on device) + +1. Home → Apps +2. Select the app +3. Press Launch/Install + +CrossPoint will flash `app.bin` to the OTA partition and reboot. + +## Fast iteration: upload apps over WiFi (no SD card removal) + +Use the File Transfer feature: + +1. On device: Home → File Transfer +2. Connect to WiFi (STA) or create a hotspot (AP) +3. From your computer/phone browser, open the URL shown on the device +4. Open **Apps (Developer)** +5. Fill in: + - App ID (e.g. `chess-puzzles` or `org.example.myapp`) + - Name + - Version + - Optional: author, description, minFirmware +6. Upload your app binary (`app.bin`) +7. On device: Home → Apps → select app → Install + +Notes: +- This page is upload-only. Installing always happens on device. +- The Apps (Developer) page writes to `/.crosspoint/apps//` and generates `app.json`. + +## Building apps with the community SDK + +Recommended SDK: `https://github.com/open-x4-epaper/community-sdk` + +Typical setup (in your app repo): + +1. Add the SDK as a submodule: + ```bash + git submodule add https://github.com/open-x4-epaper/community-sdk.git open-x4-sdk + ``` +2. In `platformio.ini`, add SDK libs as `lib_deps` (symlink form), for example: + ```ini + lib_deps = + BatteryMonitor=symlink://open-x4-sdk/libs/hardware/BatteryMonitor + EInkDisplay=symlink://open-x4-sdk/libs/display/EInkDisplay + SDCardManager=symlink://open-x4-sdk/libs/hardware/SDCardManager + InputManager=symlink://open-x4-sdk/libs/hardware/InputManager + ``` +3. Build with PlatformIO: + ```bash + pio run + ``` +4. The firmware binary will usually be: + - `.pio/build//firmware.bin` + +For CrossPoint app uploads: +- Rename/copy your output to `app.bin`, then upload via the Apps (Developer) page. + +## Example: Hello World app + +This repo includes a minimal Hello World app that can be built as a standalone firmware image and installed via the Apps menu. + +Build: + +```bash +.venv/bin/pio run -e hello-world +``` + +Upload the output: + +- File: `.pio/build/hello-world/firmware.bin` +- Upload via: File Transfer → Apps (Developer) +- Suggested App ID: `hello-world` + +Then install on device: + +Home → Apps → Hello World → Install + +## Distribution (proposed) + +Apps should live in their own repositories and publish binaries via GitHub Releases. + +For safety/auditability, registry listings should reference a public source repository (e.g. GitHub URL) so maintainers and users can review the code that produced the release. + +Release assets: +- Required: `app.bin` +- Optional: `app.json` + +Registry location (maintainer choice): +1. Separate repo (recommended): `crosspoint-reader/app-registry` containing `apps.json` +2. Or keep `apps.json` in the main firmware repo + +The on-device store UI can be built later on top of this ecosystem. diff --git a/docs/webserver-endpoints.md b/docs/webserver-endpoints.md index 0abe9df4..05e0412c 100644 --- a/docs/webserver-endpoints.md +++ b/docs/webserver-endpoints.md @@ -7,9 +7,11 @@ This document describes all HTTP and WebSocket endpoints available on the CrossP - [HTTP Endpoints](#http-endpoints) - [GET `/` - Home Page](#get----home-page) - [GET `/files` - File Browser Page](#get-files---file-browser-page) + - [GET `/apps` - Apps (Developer) Page](#get-apps---apps-developer-page) - [GET `/api/status` - Device Status](#get-apistatus---device-status) - [GET `/api/files` - List Files](#get-apifiles---list-files) - [POST `/upload` - Upload File](#post-upload---upload-file) + - [POST `/upload-app` - Upload App (Developer)](#post-upload-app---upload-app-developer) - [POST `/mkdir` - Create Folder](#post-mkdir---create-folder) - [POST `/delete` - Delete File or Folder](#post-delete---delete-file-or-folder) - [WebSocket Endpoint](#websocket-endpoint) @@ -57,6 +59,22 @@ curl http://crosspoint.local/files --- +### GET `/apps` - Apps (Developer) Page + +Serves the Apps (Developer) HTML interface. + +This is a developer-oriented page for uploading app binaries to the SD card under `/.crosspoint/apps/`. +Installing/running apps still happens on the device: Home → Apps. + +**Request:** +```bash +curl http://crosspoint.local/apps +``` + +**Response:** HTML page (200 OK) + +--- + ### GET `/api/status` - Device Status Returns JSON with device status information. @@ -170,6 +188,51 @@ File uploaded successfully: mybook.epub --- +### POST `/upload-app` - Upload App (Developer) + +Uploads an app binary to the SD card under `/.crosspoint/apps//` and creates/updates `app.json`. + +**Important:** this endpoint does not install the app. Install on device via Home → Apps. + +**Request:** +```bash +curl -X POST \ + -F "file=@app.bin" \ + "http://crosspoint.local/upload-app?appId=chess-puzzles&name=Chess%20Puzzles&version=0.1.0" +``` + +**Query Parameters:** + +| Parameter | Required | Description | +|---------------|----------|-------------| +| `appId` | Yes | App identifier; allowed chars: `[A-Za-z0-9._-]`, max 64, no slashes | +| `name` | Yes | Display name | +| `version` | Yes | Version string | +| `author` | No | Author string | +| `description` | No | Short description | +| `minFirmware` | No | Minimum CrossPoint firmware version required | + +**Response (200 OK):** +``` +App uploaded. Install on device: Home -> Apps -> v +``` + +**Error Responses:** + +| Status | Body | Cause | +|--------|--------------------------------------------|-------| +| 400 | `Missing required fields: appId, name, version` | Missing query parameters | +| 400 | `Invalid appId` | appId failed validation | +| 500 | `SD card not ready` | SD not mounted/ready | +| 500 | `Failed to create app.bin.tmp` | File create failed (disk full / FS error) | +| 500 | `Invalid firmware image (bad magic byte)` | Uploaded file is not an ESP32 image | + +**Notes:** +- Upload uses a temp file (`app.bin.tmp`) and finalizes to `app.bin` on success. +- Partial uploads are cleaned up on abort/failure. + +--- + ### POST `/mkdir` - Create Folder Creates a new folder on the SD card. diff --git a/docs/webserver.md b/docs/webserver.md index 355bac41..86bef296 100644 --- a/docs/webserver.md +++ b/docs/webserver.md @@ -10,6 +10,7 @@ CrossPoint Reader includes a built-in web server that allows you to: - Browse and manage files on your device's SD card - Create folders to organize your ebooks - Delete files and folders +- (Developer) Upload app binaries for installation via the on-device Apps menu ## Prerequisites @@ -118,6 +119,7 @@ The home page displays: Navigation links: - **Home** - Returns to the status page +- **Apps (Developer)** - Upload app binaries to `/.crosspoint/apps//` (install on device) - **File Manager** - Access file management features