Universe 2025 Badge Development

Help develop, flash, and debug applications for the Universe 2025 (Tufty) Badge and its MonaOS launcher system.

Important: MonaOS & API

The Universe 2025 Badge uses:

• MonaOS: Built-in app launcher that auto-discovers apps in /system/apps/ directory
• badgeware Module: Custom API with screen, brushes, shapes, io, Image, PixelFont
• Display: 160x120 framebuffer (pixel-doubled to 320x240)
• App Structure: Apps are directories containing __init__.py, icon.png, and optional assets/
• Entry Point: Apps must implement update() function called every frame

When developing MonaOS apps:

1. Use the badgeware module API
2. Create app as directory with __init__.py and icon.png
3. Install to /system/apps/my_app/ directory
4. HOME button exits to menu automatically
5. Default menu shows 6 apps - enable pagination for more

Board Specifications

• Processor: RP2350 dual-core ARM Cortex-M33 @ 200MHz
• Memory: 512KB SRAM, 16MB QSPI XiP flash
• Display: 320x240 full-color IPS (160x120 framebuffer pixel-doubled)
• Connectivity: 2.4GHz WiFi, Bluetooth 5
• Power: USB-C charging, 1000mAh rechargeable battery (up to 8 hours runtime)
• Special Features: IR receiver/transmitter, 4-zone LED backlight
• Buttons: 5 front-facing (A, B, C, UP, DOWN) + HOME button
• Expansion: 4 GPIO pins, Qw/ST and SWD ports
• Primary Language: MicroPython with badgeware module + MonaOS

Development Setup

1. Install toolchain

For MicroPython development:

# Install Thonny IDE (recommended for beginners)
brew install --cask thonny

# Or install command-line tools
pip install esptool adafruit-ampy mpremote

For C++ development:

# Install Pico SDK
git clone https://github.com/raspberrypi/pico-sdk.git
export PICO_SDK_PATH=/path/to/pico-sdk

2. Connect to the badge

# List connected devices
ls /dev/tty.usb*

# Connect via serial (MicroPython REPL)
screen /dev/tty.usbmodem* 115200
# Exit screen: Ctrl+A then K

3. Flash firmware

# Put badge in bootloader mode (hold BOOT button, press RESET)

# Flash MicroPython firmware
esptool.py --port /dev/tty.usbmodem* write_flash 0x0 firmware.uf2

Common Development Tasks

Test app temporarily (doesn't save)

mpremote connect /dev/tty.usbmodem* run my_app/__init__.py

Install MonaOS app using USB Mass Storage Mode

⚠️ CRITICAL: /system/apps/ is READ-ONLY via mpremote. You MUST use USB Mass Storage Mode to install apps.

# Step 1: Enter Mass Storage Mode
# - Press RESET button TWICE quickly (double-click)
# - Badge appears as "BADGER" drive

# Step 2: Copy app to badge
# macOS/Linux:
cp -r my_app /Volumes/BADGER/apps/

# Windows:
xcopy my_app D:\apps\my_app\ /E /I

# Step 3: Exit Mass Storage Mode
# - Eject BADGER drive safely
diskutil eject /Volumes/BADGER  # macOS
# - Press RESET once to reboot

# Your app now appears in MonaOS launcher!

File System Mapping:

• /Volumes/BADGER/apps/ → /system/apps/ on badge
• /Volumes/BADGER/assets/ → /system/assets/ on badge

List MonaOS apps (read-only view)

mpremote connect /dev/tty.usbmodem* ls /system/apps

⚠️ Note: Install the paginated menu for unlimited apps (default shows 6):

• Download: https://raw.githubusercontent.com/badger/home/refs/heads/main/badge/apps/menu/__init__.py
• Replace /Volumes/BADGER/apps/menu/__init__.py in Mass Storage Mode

List files in writable storage

mpremote connect /dev/tty.usbmodem* ls /storage

Download file from badge

mpremote connect /dev/tty.usbmodem* cp :/system/apps/my_app/__init__.py local_backup.py

Project Structure

MonaOS app structure on your computer:

my_app/               # MonaOS app directory
├── __init__.py       # Entry point with update() function (required)
├── icon.png          # 24x24 PNG icon for launcher (required)
├── assets/           # Optional: app resources (auto-added to path)
│   ├── sprites.png
│   ├── font.ppf
│   └── data.json
└── README.md         # Optional: app documentation

Multiple apps in development:

badge-project/
├── my_app/           # First MonaOS app
│   ├── __init__.py
│   └── icon.png
├── game_app/         # Second MonaOS app
│   ├── __init__.py
│   ├── icon.png
│   └── assets/
│       └── sprites.png
├── requirements.txt  # Python tools
└── deploy.sh         # Deployment script

Debugging

Check badge logs

# In REPL
import sys
sys.print_exception(e)  # Print full exception traceback

Test display

from badgeware import screen, display, brushes

# Clear with black
screen.brush = brushes.color(0, 0, 0)
screen.clear()

# White text
screen.brush = brushes.color(255, 255, 255)
screen.text("Hello Badge!", 10, 10, 2)
display.update()

Test WiFi

import network
wlan = network.WLAN(network.STA_IF)
wlan.active(True)
wlan.connect('SSID', 'password')
print(wlan.isconnected())
print(wlan.ifconfig())  # IP address info

Power Management

import machine
import badgeware

# Check battery level
battery = badgeware.get_battery_level()
print(f"Battery: {battery}%")

# Check if USB connected
usb = badgeware.get_usb_connected()
print(f"USB: {usb}")

# Light sleep (for delays)
machine.lightsleep(1000)  # Sleep 1 second

# Deep sleep (wake on button press - saves significant power)
machine.deepsleep()

Tips for MonaOS Apps

• MonaOS apps use update() function called every frame
• Optimize update() - it runs continuously
• Use io.ticks for animations instead of time.time()
• Minimize allocations in update() to reduce GC pauses
• Use try/except blocks to prevent crashes
• Test with USB power first, then battery
• Apps automatically return to menu when HOME button pressed

Common Issues

Badge not detected: Check USB cable, try different port, press RESET button

Out of memory: Reduce allocations in update(), use generators, call gc.collect(), free variables with del

Display not updating: MonaOS automatically updates after update() returns - no manual update needed

App not in menu: Check uploaded to /system/apps/my_app/, verify icon.png exists, may need pagination: https://badger.github.io/hack/menu-pagination/

WiFi connection fails: Check credentials, verify 2.4GHz band, restart badge

Resources

Official Badge Resources

• Getting Started: https://badger.github.io/get-started/ - Overview and setup
• About Badge: https://badger.github.io/about-badge/ - Hardware specifications
• Hacks: https://badger.github.io/hacks/ - Beginner to advanced customization tutorials
• Apps: https://badger.github.io/apps/ - Loadable MonaOS apps (Commits, Snake)
• Source Code: https://github.com/badger/home/tree/main/badgerware - Official MonaOS app code and API docs

API Documentation

• badgeware modules: https://github.com/badger/home/tree/main/badgerware - shapes, brushes, io, Image, PixelFont, Matrix

Development Resources

• MicroPython docs: https://docs.micropython.org/
• WiFi/Network: https://docs.micropython.org/en/latest/rp2/quickref.html#wlan
• Community: Badger GitHub discussions