// APP STRUCTURE

Badge Apps

Apps live under /apps, use standard MicroPython modules, and can be single-file experiments or folders with a main.py entry point.

Single File

Put hello.py directly in /apps for quick tests and small demos. Badge functions are available globally.

Use /apps/my_app/main.py for games or tools that need helper modules, assets, or save data.

Dev builds list folders with main.py. Production menu entries are registered in native firmware.

// MULTI-FILE PATTERN

Insert the app directory into sys.path, import your module, then call a single entry function.

# /apps/my_app/main.py
import sys

sys.path.insert(0, "/apps/my_app")

from game import run

run()

// MICROPYTHON

The badge includes standard MicroPython modules plus the badge-specific hardware API.

sys, os, time, errno, gc, and micropython.

json, struct, array, binascii, collections, and io.

math, cmath, and random for games, animations, and UI behavior.

badge exposes OLED, matrix, buttons, joystick, IMU, haptics, IR, mouse, and identity calls.

// FILES

/apps/
|-- hello.py
|-- my_app/
|   |-- main.py
|   |-- game.py
|   `-- save.json
/lib/
|-- badge_ui.py
/tests/

// SAVE DATA

Apps have filesystem access through open() and os. Store per-app state beside the app that owns it.

import json

state = {"score": 42}

with open("/apps/my_app/save.json", "w") as f:
    f.write(json.dumps(state))