mirror of
https://github.com/daveallie/crosspoint-reader.git
synced 2026-02-04 14:47:37 +03:00
112 lines
3.4 KiB
Markdown
112 lines
3.4 KiB
Markdown
# 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/<appId>/
|
|
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/<appId>/` 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/<env>/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.
|