Write apps for paper.

Built-in apps are compiled into the firmware image — shipping one means reflashing. Dynamic apps are position-independent Xtensa ELF binaries (-fPIC -shared) the firmware — the “kernel” — loads at runtime from the app store.

An app never links M5GFX, the network stack, or a JSON parser. Everything it does on the device it does by calling one function table, the PepApi, passed in at launch. That is what keeps binaries tiny (the reference Zepto app is 21.5 KB) and makes the whole surface one versioned contract. There is no symbol-table linking: an app resolves only its own entry point plus a small allowlist of libc/libgcc routines.

One translation unit includes PepApi.h and exports a single entry point. The kernel calls it once per open and the app returns a descriptor of callbacks (in static storage):

const PepAppModule *pep_app_main(const PepApi *api);

typedef struct PepAppModule {
  uint32_t abi_version;    // PEP_ABI_VERSION you compiled against
  const char *name;        // title shown in the app header
  void (*on_open)(void);   // fresh open — draw your first page
  void (*tick)(void);      // every kernel loop while foreground
  void (*on_close)(void);  // about to unload — free nothing
  bool requires_network;   // true → kernel gates open on WiFi
} PepAppModule;

• on_open — initialize state, draw the first frame (or set a dirty flag and draw in tick). Also runs on wake with the app foregrounded.
• tick — read input, pump network, redraw on change. Must not block for long.
• on_close — the loader reclaims the whole image; you free nothing.

Only one dynamic app is resident at a time. Opening loads it; closing frees the entire image, so an app’s memory budget is per-open, never cumulative.

Input is polled once per loop by the kernel; your tick reads a snapshot with api->touch() (clicked is a tap edge, x/y the point). Never spin your own input loop. Swipes are OS gestures the kernel handles.

e-ink cannot repaint per primitive, so every draw call sits inside one batching pair, and pairs never nest:

Keep a dirty flag and, in tick, do if (dirty) { draw(); dirty = 0; } where draw() opens a page, paints the whole frame, and closes it.

PepApi.h is the entire device-facing surface. Colors are RGB565 (PEP_BLACK/WHITE/DARKGRAY/LIGHTGRAY); fonts are PEP_FONT_R9/R12/B12/B18/B24; datums are PEP_DATUM_TOP_LEFT/…/BOTTOM_LEFT.

Each app folder carries an app.json the publisher reads:

{ "name": "Hello", "icon": "H", "net": false, "abiMajor": 1 }

• name — launcher / store title. icon — one or two chars drawn as the glyph.
• net — becomes requires_network (true gates opening on WiFi).
• abiMajor — must equal the kernel’s PEP_ABI_MAJOR, or the device refuses the app.

Apps live in the top-level apps/ directory, one folder per reverse-DNS id.

sdk/tools/build-app.sh   apps/com.vendor.app all        # esp32 + esp32s3
scripts/publish-app.sh   apps/com.vendor.app 1.0.0 "release notes"

The build compiles -Os -fPIC -shared -nostdlib -e pep_app_main with dead-code elimination, strips, and runs pep-lint — which fails the build if the ELF is not a relocatable Xtensa ET_DYN, is missing its entry point, imports a symbol outside the allowlist, or uses an unsupported relocation. Publish uploads both targets plus a manifest to the store; devices install it over the air from the Store app.

ABI versioning is append-only within a major. New fields go at the end of the struct (minor bump); an older app never reads past what it knows, so it keeps working. Any reorder/removal is a major bump, and the kernel refuses a mismatched major.

The same ELF runs three ways, chosen by the firmware, not the app:

On the classic M5Paper it is compiled code that is capped, not data. The System app’s Exec heap line shows the live budget and the largest .text loadable now. Keep .text well under it and the app runs on every backend — the reference Zepto app is ~11.5 KB.

apps/com.pep.hello — the minimal app (a tap counter); exercises text, storage, and the draw/input/lifecycle surface.

apps/com.pephone.zepto — the reference real-world app: eleven views over MQTT + JSON + keyboard + QR, fixed-size arrays throughout, a 21.5 KB ELF. Read it as the template for any bridge-backed app.

Full details, including the complete PepApi field list, live in docs/APP_SPEC.md.