BUILD FOR MINIOS

Make a small app
useful on device.

MiniOS apps are WebAssembly packages that use a bounded system API. Build against the SDK, package and sign your app, then install it on a developer device.

Platform status

The app ABI and resource limits are still being validated on hardware. Check your firmware revision and the SDK before release; current acceptance status is tracked in the project documentation.

1. Set up your tools

Node.js and npm for the pinned WebAssembly and package tools.
Python 3 with pyserial for USB sideloading.
ESP-IDF 5.5.2 and MiniOS developer firmware on a Waveshare ESP32-S3-Touch-LCD-3.5B.

2. Start from an example

Use Counter or Quick Notes for private storage, Private File Shelf for app-scoped file CRUD, 2048 to see app state and a saved score, Calculator and Base Converter for numeric input, Text Counter and the text utilities for local transformations, Timer or Focus Timer for app-local timers, Unit Converter or Dice Roller for compact utilities, or Weather for bounded HTTPS requests. The text tools cover case changes, ROT13/ROT47, Caesar shifts, slug creation, filtering and whitespace cleanup. The source and SDK are in the MiniOS project repository.

Export app_init; implement app_on_event when the app needs UI, timer, or network events. Import functions from the minios module and request only the capabilities listed in your manifest. Do not call LVGL or ESP-IDF directly.

3. Build and package

From the Counter example directory, build the module and create an unsigned developer bundle:

npm ci
npm run build
npm run package -- pack --manifest manifest.json --wasm ../../fs_image/apps/com.minios.counter/app.wasm --icon ../../fs_image/apps/com.minios.counter/icon.bin --out dist/com.minios.counter.mapp --developer
npm run package -- verify --file dist/com.minios.counter.mapp --allow-developer

Developer bundles require developer firmware and explicit acceptance on the device. For release packages, sign with an Ed25519 key, verify against the configured public key, and keep the private key out of source control. Package limits and manifest rules are defined by the package format.

4. Install over USB

Connect the board over USB Serial/JTAG, install pyserial, and send the package from the example directory. Replace COM7 with your device port.

python ../../tools/mapp-sideload.py COM7 dist/com.minios.counter.mapp

Open Apps on the device and accept the staged package. Use the system Home control to close the foreground app.

5. Keep apps responsive

Design for the 320×480 portrait display and use finger-sized touch targets.
Keep callbacks short. Use system timers and asynchronous network calls; avoid busy loops and blocking operations.
Bound buffers, check return codes, and handle unavailable hardware or network services.
Declare only the capabilities your app uses. Private storage and network responses have strict quotas.
Use packaged RGB565 images prepared with the repository's image converter.

6. Publish

Build a publisher-signed .mapp, validate it with the matching public key, then use the repository publisher tool to add the package, icon, and catalog entry to the static site. The device catalog accepts at most 12 entries in its current format. See the complete developer workflow and catalog format and publisher instructions.