Skip to content
Free-InkPublic

About

A tiny RISC-V sandboxed runtime for e-ink devices. Run micro-binaries without flashing.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

17 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

dessen

Run sandboxed apps inside e-paper reader firmware — tiny RISC-V binaries launched from the SD card, no reflashing.

Dessen lets a CrossPoint / FreeInk e-paper reader run small apps without flashing new firmware. An app is a tiny RISC-V binary that the firmware runs inside a ~1.3 KB interpreter, sandboxed so it can only touch the screen, buttons, and the capabilities the firmware hands it — never the flash, the radio, or anything else. Apps draw through the reader's own renderer and fonts, so they look native and work across every board; they launch straight from the SD card alongside the existing plugins. The whole app-facing API is a thin, generated projection of the FreeInk SDK, so games, tools, and utilities ship as self-contained files instead of firmware forks.

Status: pre-release / experimental. The app ABI is still changing freely. Firmware and apps must be built from the same version. Not yet in anyone's hands.

Why

A reader's firmware is a single image you flash to the chip. Adding a feature means forking and reflashing. Dessen turns "an app" into a file on the SD card: write it, drop it in /plugins/, launch it from the menu. The firmware stays one build; the apps are independent.

It is not a VM that emulates an ESP32, a browser-script plugin, or a Lua engine. It is a small virtual CPU (RISC-V RV32IM) with a sandbox, plus a set of system calls that map onto the FreeInk SDK.

Demo apps

App What it shows
hello The minimum: draw, refresh, wait for a button
dice Polyhedral dice roller (d4–d100), touch + buttons, hardware random
lightsout A touch/button grid puzzle with generated solvable levels
sudoku On-device puzzle generation with a unique solution

Quick start

Needs a RISC-V GCC (PlatformIO's toolchain-riscv32-esp works), a C++17 host compiler, and a freeink-sdk checkout next to this repo.

make test                      # build the VM + apps, run the suite
build/dessen build/dice.bin    # run an app on the desktop (keys c/b/p/n = events)
make sd                        # stage build/sd/plugins/<app>/ for an SD card

To run on a device, copy a staged build/sd/plugins/<app>/ folder into /plugins/ on the reader's SD card, enable Settings → Connectivity → Plugins, and open it from Home → Plugins. (The firmware must be a CrossPoint build with dessen support enabled — see Running on a device.)

Write an app

Full walkthrough in docs/writing-apps.md. The shape:

#include "dessen.h"

int main(void) {
  int w = dsn_screen_width(), h = dsn_screen_height();
  dsn_clear();
  dsn_text_box(0, h / 2 - 20, w, 40, "Hello", 5, DSN_FONT_TITLE, DSN_ALIGN_CENTER, 1, 0);
  dsn_refresh();
  return dsn_wait_event();   // sleep until a tap or button, then exit
}

Apps are event-driven (draw → refresh → wait_event), get semantic events (CONFIRM/BACK/PREV/NEXT/TAP) so one binary works on touch and button boards, and draw inside the device's safe area so nothing lands under a bezel.

How it works

app.c ──(RISC-V GCC)──▶ app.bin ──┐
                                  │  loaded from the SD card
   abi/freeink.api ──(gen_api.py)─┤
        │                         ▼
        ├─▶ sdk/*.h   (app side)  ┌─────────────────────────────┐
        └─▶ dispatch  (host side) │ firmware                    │
                                  │  ┌────────────┐   ┌────────┐│
                                  │  │ dessen VM  │──▶│ binding││──▶ FreeInk SDK
                                  │  │ (RV32IM)   │◀──│ (calls)││    (draw, input, …)
                                  │  └────────────┘   └────────┘│
                                  └─────────────────────────────┘
  • The VM (vm/) is a portable RV32IM interpreter. It bounds-checks every memory access, so an app can never reach outside its own block.
  • The call list (abi/freeink.api) is the single source of truth. tools/gen_api.py turns it into both the app-side wrappers and the firmware-side dispatch, so exposing a new capability is one line.
  • The binding (freeink/) maps each call onto FreeInk SDK types, sanitizing every untrusted app value before it reaches the renderer.
  • Apps carry their own logic; the firmware provides the device. The app API is a projection of the SDK, not a reimplementation.

Flash cost on an ESP32-C3 (-Os): ~1.3 KB interpreter + ~5.7 KB binding ≈ 7 KB (the binding at ~2.8 KB for drawing alone, the rest for the full capability set — storage, crypto, network, board sensors, text input). The crypto/network/storage work is not in that number: it reuses firmware code that is already there. Zero when the firmware build doesn't enable it.

Alternatives we evaluated

The question was how to run user-supplied "apps" on a reader without reflashing. Flash cost was the deciding factor, because CrossPoint's rule is that an unused feature must cost nothing, and the firmware image already fills most of its slot. The figures below are engine code size (text+data) compiled for the ESP32-C3 at -Os and measured directly (see Method), not quoted.

Approach App is Engine flash Authoring Why not
dessen (this repo) compiled RV32IM .bin ~7 KB (1.3 KB VM + 5.7 KB binding) needs a compiler (a tool can hide it) — chosen
Lua 5.4 .lua text file ~119 KB¹ (141 KB full) edit on the SD card, no toolchain 30× the flash; GC on a 380 KB heap
MicroQuickJS .js text file ~109 KB² edit on the SD card; same language as plugin.js 27× the flash; heavier RAM
QuickJS (full) .js text file ~377 KB full modern JS won't fit the headroom
JerryScript .js text file ~565 KB⁴ edit on the SD card largest of the lot; even reduced profiles stay in the hundreds of KB
wasm3 (WASM) .wasm from C/Rust/Zig ~74 KB needs a compiler and a wasm toolchain 18× the flash, still needs a compiler
Berry .be text file ~70 KB core³ (129 KB full) edit on the SD card 17×+ the flash
Chain-load whole firmware .bins a full firmware image ~0 engine build a whole firmware per app reflash per launch; MBs per app; partition/bootloader work; no sandbox
Emulate an ESP32 in the ESP32 an unmodified firmware .bin n/a — infeasible: RAM, closed radio blobs, ~20–50× slowdown
Extend device.json (declarative) a JSON manifest ~0 edit on the SD card can't compute anything (no games, tools, logic)

Every scripting-engine row would also need the same ~5.7 KB capability binding on top, plus its own interpreter heap in RAM; the compiled-bin approach needs only the binding. The one thing the scripting engines win is authoring — editing a text file straight on the card, no compiler — which is what a host-side authoring tool is meant to close for dessen.

¹ Lua core+parser+useful stdlibs, dropping io/os/debug/package. ² mquickjs + dtoa + libm + cutils (Bellard's own figure is ~100 KB ROM). ³ Berry core without the optional *lib modules, which are needed for a usable embed. ⁴ JerryScript default profile, all 200 core TUs; it is configurable downward but stays large.

Method: each engine's C sources were compiled with riscv32-esp-elf-gcc -march=rv32imc_zicsr_zifencei -mabi=ilp32 -Os -ffunction-sections -fdata-sections and summed with size (text+data). These are code size only, before link-time garbage collection, and exclude the C library each engine pulls in. dessen's own number is reproduced by make size.

Repo layout

vm/            the RV32IM interpreter
sdk/           what an app links: dessen.h, generated headers, crt0.S, app.ld
abi/freeink.api  the call list (source of truth); gen_api.py generates from it
freeink/       the host binding onto FreeInk SDK types
apps/          demo + test apps (.c) and their menu manifests (.json)
host/          desktop runner + a recording draw target for tests
tools/         gen_api.py (codegen), sync_check.py (SDK drift report)
docs/          writing-apps.md
AGENTS.md      guide for building apps / capabilities with an AI assistant

The firmware side (the activity that runs an app, the plugin-menu hook) lives in the CrossPoint repo, behind -DCROSSPOINT_DESSEN_APPS.

Why "dessen"

Named after Jason Dessen, the physicist at the center of Blake Crouch's Dark Matter. He builds a chamber — the Box — that holds a person in quantum superposition: inside it you are every version of yourself at once, in the box and not in the box, and nothing is real until a choice collapses it into a single world.

A dessen app lives the same way. The .bin on the SD card is both an app and not an app — inert bytes until the firmware opens the box and runs it. It executes inside the firmware yet was never flashed into it; it is present on the device yet separable from it; it is, at rest, a superposition of every app the reader could become. Launching one is the observation that collapses it: of all the versions waiting in /plugins/, this is the one the device is, right now, until you leave and it returns to being just a file.

And the sandbox is the Box itself — a sealed space where an app runs in its own world, able to see out through narrow windows (the system calls) but never to reach out and touch the world that contains it. Whatever happens in there stays in there. Close the lid and the device is exactly as it was.

"Are you happy with your life?" — the question that opens the Box. Every app is a different answer.

Contributing

make test must pass. New capabilities are added to abi/freeink.api (one line) and must sanitize all app input — see AGENTS.md for the rules and recipes. make sync reports FreeInk SDK surface not yet exposed.

About

A tiny RISC-V sandboxed runtime for e-ink devices. Run micro-binaries without flashing.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages