tildagon-cli

A command-line utility for managing a Tildagon (Electromagnetic Field event badge) over USB.

Table of Contents

• Background
• Install
• Usage
• License

Background

tildagon.py wraps mpremote to run MicroPython commands on the badge over USB serial. It can manage apps, WiFi credentials, and settings without needing to interact with the badge UI. I wanted to be able to do things like adding and removing apps in bulk at the CLI, so I made this. Built on Linux, but should be fine on other OSes - assuming things like port are specified in a platform-specific manner.

Install

Requirements: Python 3.13+

From PyPI (recommended - installs the tildagon command plus mpremote automatically):

uv tool install tildagon-cli

pipx install tildagon-cli or pip install tildagon-cli work the same way if you don't use uv.

Run without installing: uv run accepts a URL directly, so the script can be run with no local checkout and no separate mpremote install - dependencies (click, rich, mpremote) are declared inline and handled automatically by uv:

uv run https://codeberg.org/andypiper/tildagon-cli/raw/branch/main/tildagon.py -- --help

Local checkout without uv run:

chmod +x tildagon.py
ln -s "$(pwd)/tildagon.py" ~/.local/bin/tildagon

(this form still needs mpremote installed separately: pip install mpremote.)

Shell completion (zsh):

_TILDAGON_COMPLETE=zsh_source tildagon > ~/.zfunc/_tildagon

Add to ~/.zshrc if not already present:

fpath+=~/.zfunc
autoload -Uz compinit && compinit

Usage

uv run tildagon.py [--port /dev/ttyACM0] <command>

On Linux, the device is often /dev/ttyACM0 (default). Override with --port / -p.

Every command accepts -h as well as --help, e.g. tildagon apps install --help.

Commands

info

Show firmware version, MicroPython version, frontboard type, and attached hexpansions.

uv run tildagon.py info

battery

Show battery level and charge state.

uv run tildagon.py battery

df

Show flash filesystem usage on the badge.

uv run tildagon.py df

Wraps mpremote df. If Avail (KB) is negative and Use% is over 100%, the badge's flash is full — that shows up as apps crashing on OSError: 28 (ENOSPC) whenever they try to write settings or cache files. Free space with apps uninstall.

name

Get or set the badge display name.

uv run tildagon.py name get
uv run tildagon.py name set "Jonty"

wifi

Read or update WiFi credentials.

uv run tildagon.py wifi get
uv run tildagon.py wifi set <ssid> <password>

autoexec

Get, set, or clear the app that launches automatically at startup instead of the default launcher.

uv run tildagon.py autoexec get
uv run tildagon.py autoexec set "Settings"
uv run tildagon.py autoexec clear

autoexec set writes /autoexec.bat with the exact app name as shown in the launcher menu. Requires firmware >= 2.0.0-alpha7.

dev

Get, enable, or disable developer mode.

uv run tildagon.py dev get
uv run tildagon.py dev enable
uv run tildagon.py dev disable

Developer mode adds a handful of debug apps to the launcher menu (BoopSpinner, Menu demo, Text demo, Inhibit LEDs, ESPNow ping), and unlocks manual editing of a hexpansion's unique ID in the Hexpansions app. Developer mode can be toggled on the badge itself by pressing confirm 5 times on the "Software version" line in Settings; there is no in-UI way to turn it back off, so use dev disable.

apps

List, install, or uninstall badge apps from local directories.

uv run tildagon.py apps list
uv run tildagon.py apps install path/to/myapp [path/to/another]
uv run tildagon.py apps uninstall <directory> [<directory> ...]
uv run tildagon.py apps uninstall

apps list shows the display name alongside the directory name (needed for uninstall). App metadata is read from tildagon.toml or tildagon.json (the app store writes the latter, and removes any tildagon.toml from installed apps). Installing reboots the badge automatically. Run apps uninstall with no arguments to pick apps to remove from a numbered list instead of copying directory names by hand.

store

Search and install apps from the Tildagon App Store.

uv run tildagon.py store search [query] [--category Games,Apps] [--author x] [--license MIT] [--service github] [--capability neopixels] [--requires nmea] [--supports x] [--limit 10]
uv run tildagon.py store install [<code> ...] [--category Games,Apps] [--author x] [--license MIT] [--service github] [--capability neopixels] [--requires nmea] [--supports x] [--limit 10]
uv run tildagon.py store url <code> [<code> ...] [--open]
uv run tildagon.py store src <code> [<code> ...] [--open]
uv run tildagon.py store failures

store url prints the app store page for one or more codes (from store search); store src prints the app's source homepage instead (from its manifest, usually a GitHub/Codeberg repo). Both accept --open/-o to open the URL(s) directly in your browser. store search and store install take the same filters (comma-separated, matched against the store API) and sort newest first, so store search --limit 10 shows the 10 most recently released apps (the table title shows "N of TOTAL" when a limit truncates the match count). --capability filters on apps that require or support a given capability; --requires/--supports narrow to just one side. Short names like neopixels expand to the full capability registry URL automatically. Run store install with no codes (optionally filtered) to browse a numbered list and pick apps interactively instead of looking up codes first; multiple codes are resolved in a single store request. store failures lists submissions that failed to publish, with the validation reason — useful when an expected app isn't showing up.

settings

Show all badge settings (passwords redacted by default), or get/set/clear a single key.

uv run tildagon.py settings
uv run tildagon.py settings --raw
uv run tildagon.py settings get <key>
uv run tildagon.py settings set <key> <value>
uv run tildagon.py settings clear <key>

monitor

Open the badge REPL for debugging. Useful for seeing tracebacks from crashing apps.

uv run tildagon.py monitor

Ctrl-C interrupts the running app, Ctrl-D soft-resets while staying connected, Ctrl-] exits.

reboop / reboot

Reset the badge.

uv run tildagon.py reboop

poweroff

Disconnect the badge's battery. Prompts for confirmation unless --yes/-y is given.

uv run tildagon.py poweroff
uv run tildagon.py poweroff --yes

It can't fully power off while connected, it actually powers off once unplugged from USB (same as the on-badge power-off screen).

backup / restore

Copy the entire badge filesystem to a local directory, or restore one back.

uv run tildagon.py backup [dest]
uv run tildagon.py restore <src>

backup defaults to a timestamped tildagon-backup-YYYYMMDD-HHMMSS directory if dest is omitted. Useful before reflashing. restore copies each top-level item in src back onto the badge individually, merging into the current filesystem and overwriting same-named files - it does not wipe anything first, so stale files from a factory reset in between won't be removed. Prompts for confirmation unless --yes/-y is given, and reboots the badge afterwards.

License

MIT © Andy Piper