Xteink-X4-crosspoint-reader/docs/apps.md

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:

   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:

   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:

   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:

.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.