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

Folder App

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

Menu Entry

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

// MULTI-FILE PATTERN

Keep `main.py` Thin

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

Available Modules

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

System

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

Data

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

Math

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

Hardware

badge, machine, network, select, socket, _espnow, and uctypes cover badge APIs, WiFi scans, TCP/UDP, timers, WDT, and pulse measurement.

TLS/WebREPL, Bluetooth, and _thread are intentionally held behind firmware build flags until they are fully validated on badge hardware. ESP-NOW is exposed as the low-level _espnow module while the public wrapper is pending.

// FILES

Filesystem Pattern

/apps/
|-- hello.py
|-- diagnostics/
|   `-- api_test.py
|-- my_app/
|   |-- main.py
|   |-- game.py
|   `-- save.json
/docs/
|-- API_REFERENCE.md
|-- MicroPythonDeveloperGuide.md
/lib/
|-- badge_ui.py
/micropython_tests/

After writing a new app folder over serial, return to the Apps menu or run rescan_apps() from the REPL so the native app registry refreshes.

// COMMUNITY CONTRIBUTIONS

Community Apps

Community Apps install over WiFi from the Community Apps tile on the badge home menu. They stay out of the factory home menu until someone chooses to install them. To submit or share an app, add it to the public registry and open a pull request.

Tardigotchi by aask42: Hatch and care for a tiny tardigrade.

Durable Snake by Alexandre Roman: Snake game with three retries.

Starfield Nametag by Alexandre Roman: Animated starfield with a personalized nametag.

Want to share an app? Add a folder under community_apps/, include main.py plus community.json for the registry listing, add a README and any license or third-party asset notices, add optional __title__ and __description__ metadata for the installed app menu, and open a pull request. The release workflow generates the downloadable registry file.

// SAVE DATA

Use Normal Files

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