Complete Badger 2350 Badge development environment with skills, commands, and examples

GitHub stars
8

Install

/plugin install badger-2350-dev@badger-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add johnlindquist/badger-2350-plugin.

Contents

Discovered from source

Skills 8

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

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

API Documentation

Development Resources

Universe 2025 Badge App Creator

Create well-structured MicroPython applications for the Universe 2025 (Tufty) Badge with MonaOS integration, display graphics, button handling, and proper app architecture.

Important: MonaOS App Structure

Critical: MonaOS apps follow a specific structure. Each app is a directory in /system/apps/ containing:

/system/apps/my_app/
├── icon.png          # 24x24 PNG icon
├── __init__.py       # Entry point with update() function
└── assets/           # Optional: app assets (auto-added to path)
    └── ...

Required Functions

Your __init__.py must implement:

update() - Required, called every frame by MonaOS:

def update():
    # Called every frame
    # Draw your UI, handle input, update state
    pass

init() - Optional, called once when app launches:

def init():
    # Initialize app state, load resources
    pass

on_exit() - Optional, called when HOME button pressed:

def on_exit():
    # Save state, cleanup resources
    pass

MonaOS App Template

# __init__.py - MonaOS app template
from badgeware import screen, brushes, shapes, io, PixelFont, Image

# App state
app_state = {
    "counter": 0,
    "color": (255, 255, 255)
}

def init():
    """Called once when app launches"""
    # Load font
    screen.font = PixelFont.load("nope.ppf")

    # Load saved state if exists
    try:
        with open("/storage/myapp_state.txt", "r") as f:
            app_state["counter"] = int(f.read())
    except:
        pass

    print("App initialized!")

def update():
    """Called every frame by MonaOS"""
    # Clear screen
    screen.brush = brushes.color(20, 40, 60)
    screen.clear()

    # Draw UI
    screen.brush = brushes.color(255, 255, 255)
    screen.text("My App", 10, 10)
    screen.text(f"Count: {app_state['counter']}", 10, 30)

    # Handle buttons (checked every frame)
    if io.BUTTON_A in io.pressed:
        app_state["counter"] += 1

    if io.BUTTON_B in io.pressed:
        app_state["counter"] = 0

    # HOME button exits automatically

def on_exit():
    """Called when returning to MonaOS menu"""
    # Save state
    with open("/storage/myapp_state.txt", "w") as f:
        f.write(str(app_state["counter"]))

    print("App exiting!")

Display API (badgeware)

Import Modules

from badgeware import screen, brushes, shapes, Image, PixelFont, Matrix, io

Screen Drawing (160x120 framebuffer)

The screen is a 160×120 RGB framebuffer that MonaOS automatically pixel-doubles to 320×240.

Basic Drawing:

# Set brush color (RGB 0-255)
screen.brush = brushes.color(r, g, b)

# Clear screen
screen.clear()

# Draw text
screen.text("Hello", x, y)

# Draw shapes
screen.draw(shapes.rectangle(x, y, width, height))
screen.draw(shapes.circle(x, y, radius))
screen.draw(shapes.line(x1, y1, x2, y2))
screen.draw(shapes.arc(x, y, radius, start_angle, end_angle))
screen.draw(shapes.pie(x, y, radius, start_angle, end_angle))

Antialiasing (smooth edges):

screen.antialias = Image.X4  # Enable 4x antialiasing
screen.antialias = Image.NONE  # Disable

No Manual Update Needed: MonaOS automatically updates the display after each update() call.

Shapes Module

Full documentation: https://github.com/badger/home/blob/main/badgerware/shapes.md

Available Shapes:

from badgeware import shapes

# Rectangle
shapes.rectangle(x, y, width, height)

# Circle
shapes.circle(x, y, radius)

# Line
shapes.line(x1, y1, x2, y2)

# Arc (portion of circle outline)
shapes.arc(x, y, radius, start_angle, end_angle)

# Pie (filled circle segment)
shapes.pie(x, y, radius, start_angle, end_angle)

# Rounded rectangle
shapes.rounded_rectangle(x, y, width, height, radius)

# Regular polygon (pentagon, hexagon, etc.)
shapes.regular_polygon(x, y, sides, radius)

# Squircle (smooth rectangle-circle hybrid)
shapes.squircle(x, y, width, height)

Transformations:

from badgeware import Matrix

# Create shape
rect = shapes.rectangle(-1, -1, 2, 2)

# Apply transformation
rect.transform = Matrix() \
    .translate(80, 60) \  # Move to center
    .scale(20, 20) \      # Scale up
    .rotate(io.ticks / 100)  # Animated rotation

screen.draw(rect)

Brushes Module

Full documentation: https://github.com/badger/home/blob/main/badgerware/brushes.md

Solid Colors:

from badgeware import brushes

# RGB color (0-255 per channel)
screen.brush = brushes.color(r, g, b)

# Examples
screen.brush = brushes.color(255, 0, 0)     # Red
screen.brush = brushes.color(0, 255, 0)     # Green
screen.brush = brushes.color(0, 0, 255)     # Blue
screen.brush = brushes.color(255, 255, 255) # White
screen.brush = brushes.color(0, 0, 0)       # Black

Fonts

Full documentation: https://github.com/badger/home/blob/main/PixelFont.md

30 Licensed Pixel Fonts Included:

from badgeware import PixelFont

# Load font
screen.font = PixelFont.load("nope.ppf")

# Draw text with loaded font
screen.text("Styled text", x, y)

# Measure text width
width = screen.font.measure("text to measure")

# Reset to default font
screen.font = None

Images & Sprites

Full documentation: https://github.com/badger/home/blob/main/badgerware/Image.md

Loading Images:

from badgeware import Image

# Load PNG image
img = Image.load("sprite.png")

# Blit to screen
screen.blit(img, x, y)

# Scaled blit
screen.scale_blit(img, x, y, width, height)

Sprite Sheets:

# Using SpriteSheet helper (from examples)
from lib import SpriteSheet

# Load sprite sheet (7 columns, 1 row)
sprites = SpriteSheet("assets/mona-sprites.png", 7, 1)

# Blit specific sprite (column 0, row 0)
screen.blit(sprites.sprite(0, 0), x, y)

# Scaled sprite
screen.scale_blit(sprites.sprite(3, 0), x, y, 30, 30)

Button Handling (io module)

Full documentation: https://github.com/badger/home/blob/main/badgerware/io.md

Button Constants

from badgeware import io

# Available buttons
io.BUTTON_A       # Left button
io.BUTTON_B       # Middle button
io.BUTTON_C       # Right button
io.BUTTON_UP      # Up button
io.BUTTON_DOWN    # Down button
io.BUTTON_HOME    # HOME button (exits to MonaOS)

Button States

Check button states within your update() function:

def update():
    # Button just pressed this frame
    if io.BUTTON_A in io.pressed:
        print("A was just pressed")

    # Button just released this frame
    if io.BUTTON_B in io.released:
        print("B was just released")

    # Button currently held down
    if io.BUTTON_C in io.held:
        print("C is being held")

    # Button state changed this frame (pressed or released)
    if io.BUTTON_UP in io.changed:
        print("UP state changed")

No Debouncing Needed: The io module handles button debouncing automatically.

Menu Navigation Example

menu_items = ["Option 1", "Option 2", "Option 3", "Option 4"]
selected = 0

def update():
    global selected

    # Clear screen
    screen.brush = brushes.color(20, 40, 60)
    screen.clear()

    # Draw title
    screen.brush = brushes.color(255, 255, 255)
    screen.text("Menu", 10, 5)

    # Draw menu items
    y = 30
    for i, item in enumerate(menu_items):
        if i == selected:
            # Highlight selected item
            screen.brush = brushes.color(255, 255, 0)
            screen.text("> " + item, 10, y)
        else:
            screen.brush = brushes.color(200, 200, 200)
            screen.text("  " + item, 10, y)
        y += 20

    # Handle navigation
    if io.BUTTON_UP in io.pressed:
        selected = (selected - 1) % len(menu_items)

    if io.BUTTON_DOWN in io.pressed:
        selected = (selected + 1) % len(menu_items)

    if io.BUTTON_A in io.pressed:
        print(f"Selected: {menu_items[selected]}")

Animation & Timing

Using io.ticks

from badgeware import io
import math

def update():
    # io.ticks increments every frame
    # Use for smooth animations

    # Oscillating value
    y = (math.sin(io.ticks / 100) * 30) + 60

    # Rotating shape
    angle = io.ticks / 50
    rect = shapes.rectangle(-1, -1, 2, 2)
    rect.transform = Matrix().translate(80, 60).rotate(angle)
    screen.draw(rect)

    # Pulsing size
    scale = (math.sin(io.ticks / 60) * 10) + 20
    circle = shapes.circle(80, 60, scale)
    screen.draw(circle)

State Management

Persistent Storage

Store app data in the writable LittleFS partition at /storage/:

import json

CONFIG_FILE = "/storage/myapp_config.json"

def save_config(data):
    """Save configuration to persistent storage"""
    try:
        with open(CONFIG_FILE, "w") as f:
            json.dump(data, f)
        print("Config saved!")
    except Exception as e:
        print(f"Save failed: {e}")

def load_config():
    """Load configuration from persistent storage"""
    try:
        with open(CONFIG_FILE, "r") as f:
            return json.load(f)
    except:
        # Return defaults if file doesn't exist
        return {
            "name": "Badge User",
            "theme": "light",
            "counter": 0
        }

# Usage in app
config = {}

def init():
    global config
    config = load_config()
    print(f"Loaded: {config}")

def on_exit():
    save_config(config)

State Machine Pattern

class AppState:
    MENU = 0
    GAME = 1
    SETTINGS = 2
    GAME_OVER = 3

state = AppState.MENU
game_data = {"score": 0, "level": 1}

def update():
    global state

    if state == AppState.MENU:
        draw_menu()
        if io.BUTTON_A in io.pressed:
            state = AppState.GAME

    elif state == AppState.GAME:
        update_game()
        draw_game()
        if game_data["score"] < 0:
            state = AppState.GAME_OVER

    elif state == AppState.SETTINGS:
        draw_settings()
        if io.BUTTON_B in io.pressed:
            state = AppState.MENU

    elif state == AppState.GAME_OVER:
        draw_game_over()
        if io.BUTTON_A in io.pressed:
            state = AppState.MENU
            game_data = {"score": 0, "level": 1}

def draw_menu():
    screen.brush = brushes.color(0, 0, 0)
    screen.clear()
    screen.brush = brushes.color(255, 255, 255)
    screen.text("MAIN MENU", 40, 50)
    screen.text("Press A to start", 30, 70)

def update_game():
    # Game logic
    game_data["score"] += 1

def draw_game():
    screen.brush = brushes.color(0, 0, 0)
    screen.clear()
    screen.brush = brushes.color(255, 255, 255)
    screen.text(f"Score: {game_data['score']}", 10, 10)

def draw_settings():
    # Settings UI
    pass

def draw_game_over():
    screen.brush = brushes.color(0, 0, 0)
    screen.clear()
    screen.brush = brushes.color(255, 0, 0)
    screen.text("GAME OVER", 40, 50)
    screen.text(f"Score: {game_data['score']}", 40, 70)

WiFi Integration

Use standard MicroPython network module:

import network
import time

def connect_wifi(ssid, password):
    """Connect to WiFi network"""
    wlan = network.WLAN(network.STA_IF)
    wlan.active(True)

    if wlan.isconnected():
        print("Already connected:", wlan.ifconfig()[0])
        return True

    print(f"Connecting to {ssid}...")
    wlan.connect(ssid, password)

    # Wait for connection (with timeout)
    timeout = 10
    while not wlan.isconnected() and timeout > 0:
        time.sleep(1)
        timeout -= 1

    if wlan.isconnected():
        print("Connected:", wlan.ifconfig()[0])
        return True
    else:
        print("Connection failed")
        return False

def fetch_data(url):
    """Fetch data from URL"""
    try:
        import urequests
        response = urequests.get(url)
        data = response.json()
        response.close()
        return data
    except Exception as e:
        print(f"Error fetching data: {e}")
        return None

# Usage in app
def init():
    if connect_wifi("MyWiFi", "password123"):
        data = fetch_data("https://api.example.com/data")
        if data:
            print("Got data:", data)

Full WiFi docs: https://docs.micropython.org/en/latest/rp2/quickref.html#wlan

Performance Optimization

Reduce Draw Calls

# Bad - many individual draws
def update():
    for i in range(100):
        screen.draw(shapes.rectangle(i, i, 2, 2))

# Better - batch or optimize
def update():
    # Draw fewer, larger shapes
    screen.draw(shapes.rectangle(0, 0, 100, 100))

Cache Computed Values

# Cache expensive calculations
_cached_sprites = None

def get_sprites():
    global _cached_sprites
    if _cached_sprites is None:
        _cached_sprites = SpriteSheet("sprites.png", 8, 8)
    return _cached_sprites

def update():
    sprites = get_sprites()  # Fast after first call
    screen.blit(sprites.sprite(0, 0), 10, 10)

Minimize Memory Allocation

# Bad - creates new lists every frame
def update():
    items = [1, 2, 3, 4, 5]  # Don't do this in update()
    for item in items:
        process(item)

# Good - create once, reuse
items = [1, 2, 3, 4, 5]  # Module level

def update():
    for item in items:  # Reuse existing list
        process(item)

Project Structure Best Practices

Simple App (Single File)

my_app/
├── icon.png
└── __init__.py

Complex App (Multiple Files)

my_app/
├── icon.png
├── __init__.py      # Entry point
└── assets/
    ├── sprites.png
    ├── font.ppf
    └── config.json

Access assets using relative paths (assets/ is auto-added to sys.path):

# In __init__.py
from badgeware import Image

# Load from assets/
sprite = Image.load("assets/sprites.png")

# Or if assets/ in path:
sprite = Image.load("sprites.png")

Error Handling

def update():
    """Update with error handling"""
    try:
        # Your update code
        draw_ui()
        handle_input()
    except Exception as e:
        # Show error on screen
        screen.brush = brushes.color(255, 0, 0)
        screen.clear()
        screen.brush = brushes.color(255, 255, 255)
        screen.text("Error:", 10, 10)
        screen.text(str(e)[:30], 10, 30)

        # Log to console for debugging
        import sys
        sys.print_exception(e)

Testing & Debugging

Test Locally

# Run app temporarily without installing
mpremote run my_app/__init__.py

REPL Debugging

# Connect to REPL
mpremote

# Test imports
>>> from badgeware import screen, brushes
>>> screen.brush = brushes.color(255, 0, 0)
>>> screen.clear()

Print Debugging

def update():
    # Print statements appear in REPL/serial console
    print(f"State: {state}, Counter: {counter}")

    # Draw debug info on screen
    screen.text(f"Debug: {value}", 0, 110)

Official Examples

Study official examples: https://github.com/badger/home/tree/main/badge/apps

Key examples:

  • Commits Game: Sprite animations, collision detection
  • Snake Game: Grid-based movement, state management
  • Menu System: Navigation, app launching

Official API Documentation

Complete Example App

# __init__.py - Complete counter app with persistence
from badgeware import screen, brushes, shapes, io, PixelFont
import json

# State
counter = 0
high_score = 0

def init():
    """Load saved state"""
    global counter, high_score

    screen.font = PixelFont.load("nope.ppf")

    try:
        with open("/storage/counter_state.json", "r") as f:
            data = json.load(f)
            counter = data.get("counter", 0)
            high_score = data.get("high_score", 0)
    except:
        pass

    print(f"Counter initialized: {counter}, High: {high_score}")

def update():
    """Update every frame"""
    global counter, high_score

    # Clear screen
    screen.brush = brushes.color(20, 40, 60)
    screen.clear()

    # Draw title
    screen.brush = brushes.color(255, 255, 255)
    screen.text("COUNTER APP", 30, 10)

    # Draw counter (large)
    screen.text(f"{counter}", 60, 40, scale=3)

    # Draw high score
    screen.text(f"High: {high_score}", 40, 80)

    # Draw instructions
    screen.text("A: +1  B: Reset", 20, 105)

    # Handle buttons
    if io.BUTTON_A in io.pressed:
        counter += 1
        if counter > high_score:
            high_score = counter

    if io.BUTTON_B in io.pressed:
        counter = 0

def on_exit():
    """Save state before exit"""
    try:
        with open("/storage/counter_state.json", "w") as f:
            json.dump({
                "counter": counter,
                "high_score": high_score
            }, f)
        print("State saved!")
    except Exception as e:
        print(f"Save failed: {e}")

Next Steps

  • See Official Hacks: https://badger.github.io/hacks/
  • Explore Badge Hardware: Use badger-hardware skill
  • WiFi & Bluetooth: See MicroPython docs
  • Deploy Your App: Use badger-deploy skill

Happy coding! 🦡

Universe 2025 Badge Deployment and File Management

Efficient workflows for deploying applications to MonaOS, managing files, and organizing projects on the Universe 2025 (Tufty) Badge.

Deploying to MonaOS

MonaOS apps are directories in /system/apps/, not single files. Each app directory must contain:

  • __init__.py - Entry point with update() function
  • icon.png - 24x24 PNG icon for the launcher
  • assets/ - Optional directory for app resources

⚠️ CRITICAL: USB Mass Storage Mode Required

The /system/apps/ directory is READ-ONLY via mpremote. You MUST use USB Mass Storage Mode to install, update, or delete apps.

# Step 1: Enter USB Mass Storage Mode
# - Connect badge via USB-C
# - Press RESET button TWICE quickly (double-click)
# - Badge appears as "BADGER" drive at /Volumes/BADGER (macOS)

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

# Or manually via Finder:
# - Open BADGER drive
# - Navigate to apps/ folder
# - Drag my_app folder into apps/

# Step 3: Exit Mass Storage Mode
diskutil eject /Volumes/BADGER  # Or eject via Finder
# Press RESET button once to reboot into MonaOS

# Your app will now appear in the MonaOS launcher!

File System Mapping:

  • /Volumes/BADGER/apps/ → /system/apps/ on badge (MonaOS apps)
  • /Volumes/BADGER/assets/ → /system/assets/ on badge (system resources)
  • /Volumes/BADGER/main.py → /system/main.py on badge (boot script)

⚠️ Important: Install the paginated menu to show unlimited apps (default shows only 6):

File Transfer Methods

Using mpremote for Development (NOT for installing apps)

⚠️ IMPORTANT: You CANNOT use mpremote to install apps to /system/apps/ because it's read-only. Use Mass Storage Mode for apps.

mpremote is useful for:

  • Testing: Running code temporarily without saving
  • App Data: Copying files to /storage/ (writable partition)
  • Development: Quick iteration and debugging
# Run app temporarily (doesn't save to badge)
mpremote run my_app/__init__.py

# Copy app data to writable storage
mpremote cp data.txt :/storage/data.txt

# Create directory in writable storage
mpremote mkdir :/storage/mydata

# Copy from badge to computer
mpremote cp :/storage/data.txt local_backup.txt

# List files on badge
mpremote ls              # Root directory
mpremote ls /system/apps # MonaOS apps (read-only)
mpremote ls /storage     # Writable storage

# Remove file from storage (NOT /system/)
mpremote rm :/storage/data.txt

# Remove directory from storage (NOT /system/)
mpremote rm -rf :/storage/mydata

What you CANNOT do with mpremote:

  • ❌ Install apps to /system/apps/ (read-only)
  • ❌ Modify /system/apps/menu/ (read-only)
  • ❌ Edit files in /system/ (read-only)
  • ✅ Use USB Mass Storage Mode instead for these operations

Using ampy

# Install ampy
pip install adafruit-ampy

# Set port (or use --port flag)
export AMPY_PORT=/dev/tty.usbmodem*

# Upload file
ampy put main.py
ampy put config.py /lib/config.py

# Upload directory
ampy put lib/

# Download file
ampy get main.py

# List files
ampy ls
ampy ls /lib

# Remove file
ampy rm old_file.py

Using rshell

# Install rshell
pip install rshell

# Connect
rshell --port /dev/tty.usbmodem*

# Commands in rshell
/your/computer> boards               # List connected boards
/your/computer> connect serial /dev/tty.usbmodem*
/your/computer> cp main.py /pyboard/
/your/computer> cp -r lib /pyboard/
/your/computer> ls /pyboard
/your/computer> cat /pyboard/main.py
/your/computer> rm /pyboard/old.py

Manual File Sync via REPL

# In REPL - create/edit file directly
f = open('config.py', 'w')
f.write('''
CONFIG = {
    'wifi_ssid': 'MyNetwork',
    'wifi_password': 'password123',
    'version': '1.0.0'
}
''')
f.close()

Project Organization

MonaOS App Structure

Each MonaOS app is a directory with this structure:

my_app/                  # Your 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
│   └── config.json
└── README.md            # Optional: app documentation

Local Development Structure

Your development directory on your computer:

badge-project/
├── my_app/              # MonaOS app directory
│   ├── __init__.py      # App entry point
│   ├── icon.png         # 24x24 icon
│   └── assets/          # App assets
│       └── sprites.png
├── another_app/         # Another MonaOS app
│   ├── __init__.py
│   └── icon.png
├── requirements.txt     # Python dependencies for development
├── venv/                # Virtual environment
└── deploy.sh            # Deployment script

Deploy Script for MonaOS Apps

⚠️ IMPORTANT: Since /system/apps/ is read-only via mpremote, this script uses USB Mass Storage Mode.

Create deploy.sh:

#!/bin/bash
# deploy.sh - Deploy MonaOS app to badge via USB Mass Storage Mode

if [ -z "$1" ]; then
    echo "Usage: ./deploy.sh <app_name>"
    echo "Example: ./deploy.sh my_app"
    exit 1
fi

APP_NAME=$1
BADGE_MOUNT="/Volumes/BADGER"

if [ ! -d "$APP_NAME" ]; then
    echo "Error: App directory '$APP_NAME' not found"
    exit 1
fi

# Check if badge is in Mass Storage Mode
if [ ! -d "$BADGE_MOUNT" ]; then
    echo "⚠️  Badge not found in Mass Storage Mode"
    echo ""
    echo "Please enter Mass Storage Mode:"
    echo "  1. Connect badge via USB-C"
    echo "  2. Press RESET button TWICE quickly"
    echo "  3. Wait for BADGER drive to appear"
    echo "  4. Run this script again"
    exit 1
fi

echo "Deploying $APP_NAME to MonaOS..."

# Verify required files exist
if [ ! -f "$APP_NAME/__init__.py" ]; then
    echo "Error: __init__.py not found in $APP_NAME/"
    exit 1
fi

if [ ! -f "$APP_NAME/icon.png" ]; then
    echo "Warning: icon.png not found (required for launcher display)"
fi

# Remove old version if it exists
if [ -d "$BADGE_MOUNT/apps/$APP_NAME" ]; then
    echo "Removing old version..."
    rm -rf "$BADGE_MOUNT/apps/$APP_NAME"
fi

# Copy app to badge
echo "Copying app to badge..."
cp -r "$APP_NAME" "$BADGE_MOUNT/apps/"

echo "✓ Deployment complete!"
echo ""
echo "Next steps:"
echo "  1. Eject BADGER drive: diskutil eject /Volumes/BADGER"
echo "  2. Press RESET once on badge to reboot"
echo "  3. Your app will appear in MonaOS launcher"
echo ""
echo "Note: Install paginated menu for unlimited apps:"
echo "https://raw.githubusercontent.com/badger/home/refs/heads/main/badge/apps/menu/__init__.py"

Make executable: chmod +x deploy.sh

Usage:

./deploy.sh my_app

Deployment Workflows

Development Workflow

Quick iteration during development:

# 1. Edit code locally
vim my_app/__init__.py

# 2. Test app temporarily (doesn't save to badge)
mpremote run my_app/__init__.py

# 3. Deploy to MonaOS launcher (use Mass Storage Mode)
# - Press RESET twice on badge
# - Copy updated files: cp -r my_app /Volumes/BADGER/apps/
# - Eject and press RESET once

# 4. Verify deployment
mpremote ls /system/apps/my_app

# 5. Launch from badge
# Use physical buttons to navigate MonaOS menu and select your app

Production Deployment

Full deployment with verification:

#!/bin/bash
# production-deploy.sh

set -e  # Exit on error

BADGE_PORT="/dev/tty.usbmodem*"

echo "Starting production deployment..."

# Backup existing files
echo "Creating backup..."
mpremote connect $BADGE_PORT cp :main.py :main.py.backup
mpremote connect $BADGE_PORT cp :config.py :config.py.backup

# Deploy new files
echo "Deploying new version..."
mpremote connect $BADGE_PORT cp main.py :main.py
mpremote connect $BADGE_PORT cp config.py :config.py
mpremote connect $BADGE_PORT cp -r lib/ :/lib/

# Verify deployment
echo "Verifying deployment..."
mpremote connect $BADGE_PORT exec "
import sys
print('MicroPython version:', sys.version)

# Import and verify main module
try:
    import main
    print('✓ main.py imports successfully')
except Exception as e:
    print('✗ Error importing main.py:', e)
    sys.exit(1)
"

# Restart with new code
echo "Restarting badge..."
mpremote connect $BADGE_PORT exec "import machine; machine.soft_reset()"

echo "Production deployment complete!"

Staged Deployment

Test on one badge before deploying to multiple:

#!/bin/bash
# staged-deploy.sh

# Stage 1: Deploy to test badge
echo "Stage 1: Deploying to test badge..."
./deploy.sh --port /dev/tty.usbmodem1

# Stage 2: Run automated tests
echo "Stage 2: Running tests..."
python test_suite.py --badge /dev/tty.usbmodem1

# Stage 3: Deploy to production badges
echo "Stage 3: Deploying to all badges..."
for port in /dev/tty.usbmodem*; do
    echo "Deploying to $port..."
    ./deploy.sh --port $port
done

echo "Staged deployment complete!"

File Management

Sync Local and Badge Files

# sync.py - Sync files between computer and badge
import os
import subprocess
import hashlib

def get_local_files(path='.'):
    """Get list of local .py files"""
    files = []
    for root, dirs, filenames in os.walk(path):
        # Skip test directories
        if 'test' in root:
            continue
        for filename in filenames:
            if filename.endswith('.py'):
                filepath = os.path.join(root, filename)
                files.append(filepath)
    return files

def sync_to_badge(port='/dev/tty.usbmodem*'):
    """Sync all Python files to badge"""
    files = get_local_files()

    print(f"Syncing {len(files)} files to badge...")
    for filepath in files:
        # Determine badge path
        if filepath.startswith('./lib/'):
            badge_path = f":/{filepath[2:]}"
        elif filepath.startswith('./'):
            badge_path = f":/{filepath[2:]}"
        else:
            badge_path = f":/{filepath}"

        # Upload file
        cmd = f"mpremote connect {port} cp {filepath} {badge_path}"
        print(f"  {filepath} -> {badge_path}")
        subprocess.run(cmd, shell=True, check=True)

    print("Sync complete!")

if __name__ == '__main__':
    sync_to_badge()

Clean Up Badge Files

# cleanup.py - Remove unused files from badge

def cleanup_badge():
    """Remove temporary and cache files from badge"""
    import os

    # Files to remove
    patterns = [
        '.pyc',      # Compiled Python
        '.backup',   # Backup files
        '.tmp',      # Temporary files
        'debug_',    # Debug files
    ]

    removed = []

    for path in ['/', '/lib']:
        try:
            files = os.listdir(path)
            for file in files:
                # Check if file matches cleanup pattern
                if any(file.endswith(p) or file.startswith(p) for p in patterns):
                    filepath = f"{path}/{file}".replace('//', '/')
                    os.remove(filepath)
                    removed.append(filepath)
        except:
            pass

    print(f"Cleanup complete! Removed {len(removed)} files:")
    for f in removed:
        print(f"  {f}")

# Run on badge via mpremote:
# mpremote exec "$(cat cleanup.py)"

List Badge Files

# list_files.sh - Comprehensive file listing

echo "Files on badge:"
echo "==============="

echo -e "\nRoot directory:"
mpremote ls

echo -e "\n/lib directory:"
mpremote ls /lib 2>/dev/null || echo "  (not found)"

echo -e "\n/assets directory:"
mpremote ls /assets 2>/dev/null || echo "  (not found)"

echo -e "\n/data directory:"
mpremote ls /data 2>/dev/null || echo "  (not found)"

Backup and Restore

Backup Badge to Computer

#!/bin/bash
# backup.sh - Backup all files from badge

BACKUP_DIR="backup_$(date +%Y%m%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"

echo "Backing up badge to $BACKUP_DIR..."

# Backup root Python files
for file in $(mpremote ls | grep '.py'); do
    echo "  Backing up $file..."
    mpremote cp ":$file" "$BACKUP_DIR/$file"
done

# Backup lib directory
mkdir -p "$BACKUP_DIR/lib"
for file in $(mpremote ls /lib 2>/dev/null | grep '.py'); do
    echo "  Backing up /lib/$file..."
    mpremote cp ":/lib/$file" "$BACKUP_DIR/lib/$file"
done

echo "Backup complete: $BACKUP_DIR"

Restore Badge from Backup

#!/bin/bash
# restore.sh - Restore files to badge from backup

if [ -z "$1" ]; then
    echo "Usage: ./restore.sh <backup_directory>"
    exit 1
fi

BACKUP_DIR=$1

echo "Restoring from $BACKUP_DIR..."

# Restore root files
for file in "$BACKUP_DIR"/*.py; do
    if [ -f "$file" ]; then
        filename=$(basename "$file")
        echo "  Restoring $filename..."
        mpremote cp "$file" ":$filename"
    fi
done

# Restore lib directory
if [ -d "$BACKUP_DIR/lib" ]; then
    mpremote mkdir /lib 2>/dev/null || true
    for file in "$BACKUP_DIR/lib"/*.py; do
        if [ -f "$file" ]; then
            filename=$(basename "$file")
            echo "  Restoring /lib/$filename..."
            mpremote cp "$file" ":/lib/$filename"
        fi
    done
fi

echo "Restore complete!"

Version Management

Version File

Create version.py on badge:

# version.py
VERSION = '1.2.3'
BUILD_DATE = '2024-01-15'
COMMIT = 'abc123f'

def show():
    print(f"Version: {VERSION}")
    print(f"Build: {BUILD_DATE}")
    print(f"Commit: {COMMIT}")

Auto-generate Version

#!/bin/bash
# generate_version.sh - Auto-generate version file

VERSION=$(git describe --tags --always)
BUILD_DATE=$(date +%Y-%m-%d)
COMMIT=$(git rev-parse --short HEAD)

cat > version.py <<EOF
# Auto-generated version file
VERSION = '$VERSION'
BUILD_DATE = '$BUILD_DATE'
COMMIT = '$COMMIT'
EOF

echo "Generated version.py: $VERSION ($BUILD_DATE)"

Add to deploy script:

# Generate version before deploy
./generate_version.sh
mpremote cp version.py :version.py

Multi-Badge Deployment

Deploy to Multiple Badges

#!/bin/bash
# multi-deploy.sh - Deploy to multiple connected badges

echo "Scanning for connected badges..."
BADGES=$(ls /dev/tty.usbmodem* 2>/dev/null)

if [ -z "$BADGES" ]; then
    echo "No badges found!"
    exit 1
fi

echo "Found badges:"
echo "$BADGES"
echo

read -p "Deploy to all? (y/n) " -n 1 -r
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
    exit 0
fi

for PORT in $BADGES; do
    echo "================================"
    echo "Deploying to $PORT..."
    echo "================================"

    mpremote connect $PORT cp main.py :main.py
    mpremote connect $PORT cp config.py :config.py
    mpremote connect $PORT cp -r lib/ :/lib/

    echo "✓ Deployed to $PORT"
    echo
done

echo "All badges updated!"

CI/CD Integration

GitHub Actions Example

# .github/workflows/deploy.yml
name: Deploy to Badge

on:
  push:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          pip install mpremote pytest

      - name: Run tests
        run: |
          pytest tests/

  deploy:
    needs: test
    runs-on: self-hosted  # Runner with badge connected
    steps:
      - uses: actions/checkout@v3

      - name: Deploy to badge
        run: |
          ./generate_version.sh
          ./deploy.sh

Pre-commit Hook

# .git/hooks/pre-commit
#!/bin/bash
# Run tests before allowing commit

echo "Running tests..."
python -m pytest tests/

if [ $? -ne 0 ]; then
    echo "Tests failed! Commit aborted."
    exit 1
fi

echo "Tests passed!"
exit 0

Make executable: chmod +x .git/hooks/pre-commit

Hot Reload Development

Watch and Auto-deploy

# watch.py - Watch for file changes and auto-deploy
import time
import os
import subprocess
from pathlib import Path

def get_file_hash(filepath):
    """Get hash of file contents"""
    import hashlib
    with open(filepath, 'rb') as f:
        return hashlib.md5(f.read()).hexdigest()

def watch_and_deploy(watch_files, port='/dev/tty.usbmodem*'):
    """Watch files and deploy on change"""
    print(f"Watching {len(watch_files)} files for changes...")

    file_hashes = {f: get_file_hash(f) for f in watch_files}

    try:
        while True:
            time.sleep(1)  # Check every second

            for filepath in watch_files:
                current_hash = get_file_hash(filepath)

                if current_hash != file_hashes[filepath]:
                    print(f"\n{filepath} changed! Deploying...")

                    # Deploy changed file
                    badge_path = f":/{filepath}"
                    cmd = f"mpremote connect {port} cp {filepath} {badge_path}"
                    subprocess.run(cmd, shell=True)

                    # Soft reset badge
                    cmd = f"mpremote connect {port} exec 'import machine; machine.soft_reset()'"
                    subprocess.run(cmd, shell=True)

                    # Update hash
                    file_hashes[filepath] = current_hash

                    print("Deploy complete!")
    except KeyboardInterrupt:
        print("\nStopped watching.")

if __name__ == '__main__':
    watch_files = ['main.py', 'config.py', 'lib/display.py']
    watch_and_deploy(watch_files)

Best Practices

Pre-deployment Checklist

  • Test code locally (if possible)
  • Update version number
  • Run linter/formatter
  • Commit changes to git
  • Backup current badge code
  • Deploy to test badge first
  • Verify deployment success
  • Test on badge
  • Deploy to production badges

File Organization Tips

  1. Keep main.py simple - Import from modules
  2. Use /lib for reusable code - Separate concerns
  3. Store data in /data - Keep code and data separate
  4. Version control everything - Except secrets
  5. Use .gitignore - Don't commit badge-specific configs

Deployment Optimization

# Minimize deployment time

# Deploy only changed files
git diff --name-only HEAD~1 | grep '.py$' | while read file; do
    mpremote cp "$file" ":/$file"
done

# Compress files before transfer (if network-based)
# gzip files, transfer, decompress on badge

# Parallel deployment to multiple badges
parallel -j 4 ./deploy.sh --port ::: /dev/tty.usbmodem*

Troubleshooting Deployment

Files not updating: Verify file was actually copied, check paths with mpremote ls /system/apps/my_app

Permission denied: Badge may be in use by another process, close other connections

Deployment fails silently: Check disk space on badge, verify file syntax, ensure __init__.py and icon.png exist

App doesn't appear in MonaOS menu:

Changes not reflected: Restart badge to reload app code

Slow transfers: USB cable quality matters, try different cable/port

Official Examples

For inspiration on what to deploy to your badge:

With these deployment workflows, you can efficiently manage and deploy applications to your Universe 2025 Badge's MonaOS launcher!

Badger 2350 Diagnostics and Troubleshooting

Comprehensive diagnostics and troubleshooting tools for verifying your Badger 2350 setup, checking installations, and resolving common issues.

⚠️ When to Use This Skill

Use this skill FIRST in these situations:

  1. Starting a new session - Verify everything works before coding
  2. After setup - Confirm installation completed correctly
  3. Before debugging - Rule out environment issues
  4. When errors occur - Diagnose the root cause
  5. After firmware updates - Verify everything still works

Best Practice: Run diagnostics at the start of EVERY development session. It takes 30 seconds and prevents hours of debugging.

Quick Verification Command

Run this FIRST every session (doesn't require any files to exist):

Level 1: Basic Connection Test

# Simplest test - just verify badge responds
mpremote exec "print('Badge connected!')"
# Should print: Badge connected!

# If this fails, badge isn't connected or mpremote not installed

Level 2: Full Verification

# Complete verification (auto-detects port on macOS/Linux)
mpremote exec "import sys, gc; from badgeware import screen, brushes, shapes, io; print('=== VERIFICATION ==='); print('✓ MicroPython:', sys.version[:30]); print('✓ Memory:', gc.mem_free(), 'bytes'); print('✓ badgeware: loaded'); print('✓ Display: 160x120'); print('=== ALL OK ===')"

Expected output: All checks with ✓ marks and no errors.

With explicit port (if auto-detect fails):

mpremote connect /dev/cu.usbmodem1101 exec "from badgeware import screen; print('✓ Badge OK')"
# Replace /dev/cu.usbmodem1101 with your port

If this fails: Continue with detailed diagnostics below.

Quick System Check

Run this complete system diagnostic in REPL:

# diagnostic.py - Complete system check
import sys
import gc
import os
from machine import freq, unique_id
import ubinascii

def system_info():
    """Display complete system information"""
    print("=" * 50)
    print("BADGER 2350 SYSTEM DIAGNOSTICS")
    print("=" * 50)

    # MicroPython version
    print(f"\n[MicroPython]")
    print(f"  Version: {sys.version}")
    print(f"  Implementation: {sys.implementation}")
    print(f"  Platform: {sys.platform}")

    # Hardware info
    print(f"\n[Hardware]")
    print(f"  CPU Frequency: {freq():,} Hz ({freq() / 1_000_000:.0f} MHz)")
    uid = ubinascii.hexlify(unique_id()).decode()
    print(f"  Unique ID: {uid}")

    # Memory
    gc.collect()
    print(f"\n[Memory]")
    print(f"  Free: {gc.mem_free():,} bytes ({gc.mem_free() / 1024:.1f} KB)")
    print(f"  Allocated: {gc.mem_alloc():,} bytes ({gc.mem_alloc() / 1024:.1f} KB)")
    total = gc.mem_free() + gc.mem_alloc()
    print(f"  Total: {total:,} bytes ({total / 1024:.1f} KB)")

    # File system
    print(f"\n[File System]")
    try:
        stat = os.statvfs('/')
        block_size = stat[0]
        total_blocks = stat[2]
        free_blocks = stat[3]
        total_bytes = block_size * total_blocks
        free_bytes = block_size * free_blocks
        used_bytes = total_bytes - free_bytes

        print(f"  Total: {total_bytes:,} bytes ({total_bytes / 1024 / 1024:.2f} MB)")
        print(f"  Used: {used_bytes:,} bytes ({used_bytes / 1024 / 1024:.2f} MB)")
        print(f"  Free: {free_bytes:,} bytes ({free_bytes / 1024 / 1024:.2f} MB)")
    except:
        print("  Unable to check filesystem")

    # Module path
    print(f"\n[Module Search Paths]")
    for path in sys.path:
        print(f"  {path}")

    print("\n" + "=" * 50)

# Run diagnostic
system_info()

Firmware Version Check

Check MicroPython Firmware

import sys

# Full version info
print(sys.version)
# Example: 3.4.0; MicroPython v1.20.0 on 2023-04-26

# Implementation details
print(sys.implementation)
# (name='micropython', version=(1, 20, 0), _machine='Raspberry Pi Pico W with RP2040', _mpy=6182)

# Extract version number
version = sys.implementation.version
print(f"MicroPython {version[0]}.{version[1]}.{version[2]}")

Check Badger Library Version

import badger2040

# Check if version attribute exists
if hasattr(badger2040, '__version__'):
    print(f"Badger library version: {badger2040.__version__}")
else:
    print("Badger library version not available")

# Check file location
print(f"Badger library: {badger2040.__file__}")

Recommended Firmware Versions

Verify you have compatible firmware:

def check_firmware_compatibility():
    """Check if firmware is compatible with Badger 2350"""
    version = sys.implementation.version

    if version[0] >= 1 and version[1] >= 20:
        print("✓ MicroPython version is compatible")
        return True
    else:
        print("✗ MicroPython version may be outdated")
        print("  Recommended: MicroPython 1.20+")
        print(f"  Current: {version[0]}.{version[1]}.{version[2]}")
        return False

check_firmware_compatibility()

Module Verification

Check Core Modules

def verify_core_modules():
    """Verify essential modules are available"""
    required_modules = {
        'badger2040': 'Badger display library',
        'machine': 'Hardware interface',
        'time': 'Time functions',
        'gc': 'Garbage collection',
        'sys': 'System functions',
        'os': 'Operating system interface'
    }

    optional_modules = {
        'network': 'WiFi support',
        'urequests': 'HTTP client',
        'ujson': 'JSON parsing',
        'ubinascii': 'Binary/ASCII conversion'
    }

    print("Checking required modules...")
    all_ok = True
    for module, description in required_modules.items():
        try:
            __import__(module)
            print(f"  ✓ {module:15s} - {description}")
        except ImportError:
            print(f"  ✗ {module:15s} - MISSING - {description}")
            all_ok = False

    print("\nChecking optional modules...")
    for module, description in optional_modules.items():
        try:
            __import__(module)
            print(f"  ✓ {module:15s} - {description}")
        except ImportError:
            print(f"  ○ {module:15s} - Not installed - {description}")

    return all_ok

verify_core_modules()

List All Installed Packages

import os

def list_installed_packages():
    """List all installed packages in /lib"""
    print("Installed packages:")

    # Check /lib directory
    try:
        lib_contents = os.listdir('/lib')
        if lib_contents:
            for item in sorted(lib_contents):
                # Try to get more info
                path = f'/lib/{item}'
                try:
                    stat = os.stat(path)
                    size = stat[6]  # File size
                    print(f"  {item:30s} {size:8,} bytes")
                except:
                    print(f"  {item}")
        else:
            print("  (no packages in /lib)")
    except OSError:
        print("  /lib directory not found")

    # Check root directory for .py files
    print("\nRoot directory modules:")
    root_contents = os.listdir('/')
    py_files = [f for f in root_contents if f.endswith('.py')]
    for f in sorted(py_files):
        stat = os.stat(f)
        size = stat[6]
        print(f"  {f:30s} {size:8,} bytes")

list_installed_packages()

Hardware Diagnostics

Display Test

import badger2040

def test_display():
    """Test display functionality"""
    print("Testing display...")

    badge = badger2040.Badger2040()

    # Test 1: Clear screen
    badge.set_pen(15)
    badge.clear()
    badge.update()
    print("  ✓ Clear screen")

    # Test 2: Draw text
    badge.set_pen(0)
    badge.text("Display Test", 10, 10, scale=2)
    badge.update()
    print("  ✓ Draw text")

    # Test 3: Draw shapes
    badge.line(10, 40, 100, 40)
    badge.rectangle(10, 50, 50, 30)
    badge.update()
    print("  ✓ Draw shapes")

    print("Display test complete!")

test_display()

Button Test

import badger2040
import time

def test_buttons():
    """Test all buttons"""
    print("Button test - Press each button:")
    print("  A, B, C, UP, DOWN")
    print("Press Ctrl+C to exit")

    badge = badger2040.Badger2040()
    tested = set()

    while len(tested) < 5:
        if badge.pressed(badger2040.BUTTON_A) and 'A' not in tested:
            print("  ✓ Button A works")
            tested.add('A')
        elif badge.pressed(badger2040.BUTTON_B) and 'B' not in tested:
            print("  ✓ Button B works")
            tested.add('B')
        elif badge.pressed(badger2040.BUTTON_C) and 'C' not in tested:
            print("  ✓ Button C works")
            tested.add('C')
        elif badge.pressed(badger2040.BUTTON_UP) and 'UP' not in tested:
            print("  ✓ Button UP works")
            tested.add('UP')
        elif badge.pressed(badger2040.BUTTON_DOWN) and 'DOWN' not in tested:
            print("  ✓ Button DOWN works")
            tested.add('DOWN')

        time.sleep(0.1)

    print("All buttons tested successfully!")

test_buttons()

GPIO Test

from machine import Pin

def test_gpio():
    """Test GPIO pins"""
    print("Testing GPIO pins...")

    # Test output
    test_pin = Pin(25, Pin.OUT)
    test_pin.value(1)
    print(f"  ✓ Pin 25 set to HIGH: {test_pin.value()}")
    test_pin.value(0)
    print(f"  ✓ Pin 25 set to LOW: {test_pin.value()}")

    # Test input with pull-up
    input_pin = Pin(15, Pin.IN, Pin.PULL_UP)
    print(f"  ✓ Pin 15 input (pull-up): {input_pin.value()}")

    print("GPIO test complete!")

test_gpio()

I2C Bus Scan

from machine import I2C, Pin

def scan_i2c():
    """Scan for I2C devices"""
    print("Scanning I2C bus...")

    i2c = I2C(0, scl=Pin(5), sda=Pin(4), freq=400000)
    devices = i2c.scan()

    if devices:
        print(f"  Found {len(devices)} device(s):")
        for device in devices:
            print(f"    0x{device:02X} ({device})")
    else:
        print("  No I2C devices found")

    return devices

scan_i2c()

Network Diagnostics

WiFi Connection Test

import network
import time

def test_wifi(ssid, password, timeout=10):
    """Test WiFi connection"""
    print(f"Testing WiFi connection to '{ssid}'...")

    wlan = network.WLAN(network.STA_IF)
    wlan.active(True)

    # Check if already connected
    if wlan.isconnected():
        print("  ✓ Already connected")
        print(f"    IP: {wlan.ifconfig()[0]}")
        return True

    # Attempt connection
    print("  Connecting...")
    wlan.connect(ssid, password)

    # Wait for connection
    start = time.time()
    while not wlan.isconnected() and (time.time() - start) < timeout:
        time.sleep(0.5)
        print(".", end="")

    print()  # New line

    if wlan.isconnected():
        config = wlan.ifconfig()
        print("  ✓ Connected successfully")
        print(f"    IP Address: {config[0]}")
        print(f"    Subnet Mask: {config[1]}")
        print(f"    Gateway: {config[2]}")
        print(f"    DNS: {config[3]}")
        print(f"    Signal Strength: {wlan.status('rssi')} dBm")
        return True
    else:
        print("  ✗ Connection failed")
        status = wlan.status()
        print(f"    Status code: {status}")
        return False

# Usage
# test_wifi('YourSSID', 'YourPassword')

Network Speed Test

import urequests
import time

def test_network_speed():
    """Test network download speed"""
    print("Testing network speed...")

    url = "http://httpbin.org/bytes/10000"  # 10KB test file

    try:
        start = time.ticks_ms()
        response = urequests.get(url)
        end = time.ticks_ms()

        size = len(response.content)
        duration = time.ticks_diff(end, start) / 1000  # Convert to seconds

        speed = (size / duration) / 1024  # KB/s

        print(f"  Downloaded: {size} bytes")
        print(f"  Time: {duration:.2f}s")
        print(f"  Speed: {speed:.2f} KB/s")

        response.close()
        return True
    except Exception as e:
        print(f"  ✗ Network test failed: {e}")
        return False

# test_network_speed()

Memory Diagnostics

Memory Usage Analysis

import gc

def analyze_memory():
    """Analyze memory usage"""
    print("Memory Analysis:")

    # Before collection
    free_before = gc.mem_free()
    alloc_before = gc.mem_alloc()

    # Collect garbage
    gc.collect()

    # After collection
    free_after = gc.mem_free()
    alloc_after = gc.mem_alloc()

    print(f"\nBefore garbage collection:")
    print(f"  Free: {free_before:,} bytes ({free_before / 1024:.1f} KB)")
    print(f"  Allocated: {alloc_before:,} bytes ({alloc_before / 1024:.1f} KB)")

    print(f"\nAfter garbage collection:")
    print(f"  Free: {free_after:,} bytes ({free_after / 1024:.1f} KB)")
    print(f"  Allocated: {alloc_after:,} bytes ({alloc_after / 1024:.1f} KB)")

    freed = free_after - free_before
    print(f"\nReclaimed: {freed:,} bytes ({freed / 1024:.1f} KB)")

    # Total memory
    total = free_after + alloc_after
    usage_percent = (alloc_after / total) * 100

    print(f"\nTotal memory: {total:,} bytes ({total / 1024:.1f} KB)")
    print(f"Usage: {usage_percent:.1f}%")

    # Warning if low
    if free_after < 10000:
        print("\n⚠ WARNING: Low memory!")
    elif free_after < 50000:
        print("\n⚠ CAUTION: Memory running low")
    else:
        print("\n✓ Memory usage looks good")

analyze_memory()

Find Memory Leaks

import gc

def find_memory_leaks(function, iterations=10):
    """Test function for memory leaks"""
    print(f"Testing for memory leaks ({iterations} iterations)...")

    gc.collect()
    initial_mem = gc.mem_free()

    for i in range(iterations):
        function()
        gc.collect()

        current_mem = gc.mem_free()
        leaked = initial_mem - current_mem

        if leaked > 0:
            print(f"  Iteration {i+1}: Leaked {leaked} bytes")

    gc.collect()
    final_mem = gc.mem_free()
    total_leaked = initial_mem - final_mem

    if total_leaked > 100:  # Allow small variance
        print(f"⚠ Possible memory leak: {total_leaked} bytes leaked")
    else:
        print(f"✓ No significant memory leak detected")

# Usage
# def test_func():
#     data = [i for i in range(100)]
# find_memory_leaks(test_func)

Error Diagnosis

Common Error Patterns

def diagnose_error(error):
    """Provide diagnosis for common errors"""
    error_str = str(error)

    diagnostics = {
        'ImportError': """
        Module not found. Check:
        - Module is installed (use mip.install())
        - Module is in /lib or root directory
        - Module name is spelled correctly
        - File has .py extension
        """,

        'MemoryError': """
        Out of memory. Try:
        - Run gc.collect() before allocation
        - Reduce variable scope
        - Use generators instead of lists
        - Break large operations into smaller chunks
        - Delete unused objects with 'del'
        """,

        'OSError': """
        File/Hardware operation failed. Check:
        - File path is correct
        - File exists (for reading)
        - Filesystem not full (for writing)
        - Hardware is connected properly
        - Pins are not already in use
        """,

        'AttributeError': """
        Attribute not found. Check:
        - Object has the attribute/method
        - Spelling is correct
        - Module is imported correctly
        - Object is initialized
        """,

        'ValueError': """
        Invalid value. Check:
        - Parameter values are in valid range
        - Data types match expected types
        - String formats are correct
        """
    }

    # Find matching error type
    for error_type, advice in diagnostics.items():
        if error_type in error_str:
            print(f"Diagnosis for {error_type}:")
            print(advice)
            return

    print("Error type not recognized. Common debugging steps:")
    print("- Check error message carefully")
    print("- Print variable values before error")
    print("- Simplify code to isolate problem")
    print("- Check MicroPython documentation")

# Usage
# try:
#     import nonexistent_module
# except Exception as e:
#     diagnose_error(e)

System Health Check

def health_check():
    """Comprehensive system health check"""
    print("=" * 50)
    print("SYSTEM HEALTH CHECK")
    print("=" * 50)

    issues = []

    # Memory check
    gc.collect()
    free_mem = gc.mem_free()
    if free_mem < 10000:
        issues.append("CRITICAL: Very low memory")
    elif free_mem < 50000:
        issues.append("WARNING: Low memory")
    else:
        print("✓ Memory: OK")

    # Filesystem check
    try:
        stat = os.statvfs('/')
        free_blocks = stat[3]
        block_size = stat[0]
        free_bytes = free_blocks * block_size

        if free_bytes < 100000:
            issues.append("WARNING: Low disk space")
        else:
            print("✓ Filesystem: OK")
    except:
        issues.append("ERROR: Cannot check filesystem")

    # Core modules check
    required = ['badger2040', 'machine', 'time', 'gc', 'sys', 'os']
    for module in required:
        try:
            __import__(module)
        except:
            issues.append(f"ERROR: Missing module '{module}'")

    if not issues:
        print("✓ Core modules: OK")

    # Display results
    if issues:
        print("\n" + "!" * 50)
        print("ISSUES FOUND:")
        for issue in issues:
            print(f"  {issue}")
        print("!" * 50)
    else:
        print("\n" + "=" * 50)
        print("✓ ALL SYSTEMS HEALTHY")
        print("=" * 50)

health_check()

Recovery Procedures

Safe Mode Boot

If badge won't boot normally:

  1. Hold BOOTSEL button while connecting USB
  2. Badge appears as USB drive
  3. Delete main.py if it's causing crashes
  4. Copy new firmware .uf2 file to drive
  5. Badge will reboot automatically

Factory Reset

import os

def factory_reset():
    """Remove all user files (DANGEROUS!)"""
    print("WARNING: This will delete all files!")
    print("Type 'CONFIRM' to proceed:")

    # In interactive mode, get user confirmation
    # confirm = input()
    # if confirm != 'CONFIRM':
    #     print("Reset cancelled")
    #     return

    print("Removing files...")
    for f in os.listdir('/'):
        if f not in ['boot.py']:  # Keep boot.py
            try:
                os.remove(f)
                print(f"  Removed {f}")
            except:
                pass

    print("Factory reset complete. Reboot badge.")

# Uncomment to use:
# factory_reset()

Firmware Reflash

# From your computer (badge in BOOTSEL mode)

# Download latest MicroPython firmware
# Visit: https://micropython.org/download/rp2-pico-w/

# Flash firmware
# Drag .uf2 file to RPI-RP2 drive
# Or use picotool:
picotool load firmware.uf2

# Verify
picotool info

Troubleshooting Checklist

When encountering issues, work through this checklist:

  • Check MicroPython version (sys.version)
  • Verify core modules load (import badger2040)
  • Run memory diagnostic (gc.mem_free())
  • Check filesystem space (os.statvfs('/'))
  • Test display (badge.update())
  • Test buttons (button test function)
  • Scan I2C bus (if using sensors)
  • Test WiFi connection (if using network)
  • Review error messages carefully
  • Check documentation for API changes
  • Try soft reset (Ctrl+D in REPL)
  • Try hard reset (power cycle)

This comprehensive diagnostic approach will help you quickly identify and resolve issues with your Badger 2350!

Badger 2350 Hardware Integration

Interface with GPIO pins, sensors, and external hardware on the Badger 2350 badge using I2C, SPI, and digital I/O.

GPIO Basics

Pin Configuration

from machine import Pin

# Configure pin as output (LED, relay, etc.)
led = Pin(25, Pin.OUT)
led.value(1)  # Turn on (HIGH)
led.value(0)  # Turn off (LOW)
led.toggle()  # Toggle state

# Configure pin as input (button, switch, etc.)
button = Pin(15, Pin.IN, Pin.PULL_UP)
if button.value() == 0:  # Button pressed (pulled to ground)
    print("Button pressed!")

# Configure pin as input with pull-down
sensor = Pin(16, Pin.IN, Pin.PULL_DOWN)

PWM (Pulse Width Modulation)

from machine import Pin, PWM

# Control LED brightness or servo motor
pwm = PWM(Pin(25))
pwm.freq(1000)  # Set frequency to 1kHz

# Set duty cycle (0-65535, where 65535 is 100%)
pwm.duty_u16(32768)  # 50% brightness
pwm.duty_u16(16384)  # 25% brightness
pwm.duty_u16(65535)  # 100% brightness

# Cleanup
pwm.deinit()

Interrupts

from machine import Pin

button = Pin(15, Pin.IN, Pin.PULL_UP)

def button_callback(pin):
    print(f"Button pressed! Pin: {pin}")

# Trigger on falling edge (button press)
button.irq(trigger=Pin.IRQ_FALLING, handler=button_callback)

# Trigger on rising edge (button release)
button.irq(trigger=Pin.IRQ_RISING, handler=button_callback)

# Trigger on both edges
button.irq(trigger=Pin.IRQ_RISING | Pin.IRQ_FALLING, handler=button_callback)

I2C Communication

I2C Setup

from machine import I2C, Pin

# Initialize I2C (QWIIC connector uses specific pins)
i2c = I2C(0, scl=Pin(5), sda=Pin(4), freq=400000)

# Scan for connected devices
devices = i2c.scan()
print(f"Found {len(devices)} I2C devices:")
for device in devices:
    print(f"  Address: 0x{device:02x}")

Reading from I2C Device

# Read data from I2C device
address = 0x48  # Example: Temperature sensor
data = i2c.readfrom(address, 2)  # Read 2 bytes
print(f"Raw data: {data}")

# Read from specific register
register = 0x00
i2c.writeto(address, bytes([register]))  # Select register
data = i2c.readfrom(address, 2)  # Read data

Writing to I2C Device

# Write single byte
address = 0x48
data = bytes([0x01, 0xA0])
i2c.writeto(address, data)

# Write to specific register
register = 0x01
value = 0xFF
i2c.writeto(address, bytes([register, value]))

Common I2C Sensors

BME280 (Temperature, Humidity, Pressure)

from machine import I2C, Pin
import time

class BME280:
    def __init__(self, i2c, address=0x76):
        self.i2c = i2c
        self.address = address

    def read_temp(self):
        # Read temperature register
        data = self.i2c.readfrom_mem(self.address, 0xFA, 3)
        temp_raw = (data[0] << 12) | (data[1] << 4) | (data[2] >> 4)
        # Apply calibration (simplified)
        temp_c = temp_raw / 100.0
        return temp_c

    def read_humidity(self):
        # Read humidity register
        data = self.i2c.readfrom_mem(self.address, 0xFD, 2)
        hum_raw = (data[0] << 8) | data[1]
        humidity = hum_raw / 1024.0
        return humidity

# Usage
i2c = I2C(0, scl=Pin(5), sda=Pin(4), freq=400000)
sensor = BME280(i2c)

temp = sensor.read_temp()
humidity = sensor.read_humidity()
print(f"Temp: {temp:.1f}°C, Humidity: {humidity:.1f}%")

APDS9960 (Gesture, Proximity, Color Sensor)

class APDS9960:
    def __init__(self, i2c, address=0x39):
        self.i2c = i2c
        self.address = address
        self._init_sensor()

    def _init_sensor(self):
        # Enable device
        self.i2c.writeto_mem(self.address, 0x80, bytes([0x01]))
        # Enable gesture mode
        self.i2c.writeto_mem(self.address, 0x93, bytes([0x01]))

    def read_gesture(self):
        # Read gesture FIFO
        fifo_level = self.i2c.readfrom_mem(self.address, 0xAE, 1)[0]
        if fifo_level > 0:
            data = self.i2c.readfrom_mem(self.address, 0xFC, 4)
            # Process gesture data
            return self._detect_gesture(data)
        return None

    def _detect_gesture(self, data):
        # Simplified gesture detection
        if data[0] > data[2]:
            return "UP"
        elif data[0] < data[2]:
            return "DOWN"
        elif data[1] > data[3]:
            return "LEFT"
        else:
            return "RIGHT"

# Usage
i2c = I2C(0, scl=Pin(5), sda=Pin(4), freq=400000)
gesture_sensor = APDS9960(i2c)

gesture = gesture_sensor.read_gesture()
if gesture:
    print(f"Gesture detected: {gesture}")

VL53L0X (Time-of-Flight Distance Sensor)

class VL53L0X:
    def __init__(self, i2c, address=0x29):
        self.i2c = i2c
        self.address = address

    def read_distance(self):
        # Start measurement
        self.i2c.writeto_mem(self.address, 0x00, bytes([0x01]))

        # Wait for measurement
        time.sleep(0.05)

        # Read distance (mm)
        data = self.i2c.readfrom_mem(self.address, 0x14, 2)
        distance = (data[0] << 8) | data[1]
        return distance

# Usage
i2c = I2C(0, scl=Pin(5), sda=Pin(4), freq=400000)
tof = VL53L0X(i2c)

distance = tof.read_distance()
print(f"Distance: {distance}mm")

SPI Communication

SPI Setup

from machine import SPI, Pin

# Initialize SPI
spi = SPI(0, baudrate=1000000, polarity=0, phase=0,
          sck=Pin(2), mosi=Pin(3), miso=Pin(4))

# Chip select pin
cs = Pin(5, Pin.OUT)
cs.value(1)  # Deselect initially

# Read/write data
cs.value(0)  # Select device
spi.write(bytes([0x01, 0x02, 0x03]))  # Write data
data = spi.read(3)  # Read 3 bytes
cs.value(1)  # Deselect device

print(f"Received: {data}")

SD Card Reader (SPI)

from machine import SPI, Pin
import sdcard
import os

# Initialize SPI and SD card
spi = SPI(0, baudrate=1000000, sck=Pin(2), mosi=Pin(3), miso=Pin(4))
cs = Pin(5, Pin.OUT)

sd = sdcard.SDCard(spi, cs)

# Mount SD card
os.mount(sd, '/sd')

# Write file
with open('/sd/data.txt', 'w') as f:
    f.write('Hello from Badger!')

# Read file
with open('/sd/data.txt', 'r') as f:
    print(f.read())

# Unmount
os.umount('/sd')

Analog Input (ADC)

from machine import ADC, Pin

# Initialize ADC on GPIO pin
adc = ADC(Pin(26))

# Read raw value (0-65535 for 16-bit ADC)
raw_value = adc.read_u16()
print(f"Raw ADC: {raw_value}")

# Convert to voltage (assuming 3.3V reference)
voltage = (raw_value / 65535) * 3.3
print(f"Voltage: {voltage:.2f}V")

# Example: Read potentiometer
while True:
    value = adc.read_u16()
    percentage = (value / 65535) * 100
    print(f"Pot: {percentage:.1f}%")
    time.sleep(0.1)

NeoPixel (WS2812B) LEDs

from machine import Pin
import neopixel
import time

# Initialize NeoPixel strip (8 LEDs on pin 25)
num_leds = 8
np = neopixel.NeoPixel(Pin(25), num_leds)

# Set individual LED color (R, G, B)
np[0] = (255, 0, 0)    # Red
np[1] = (0, 255, 0)    # Green
np[2] = (0, 0, 255)    # Blue
np[3] = (255, 255, 0)  # Yellow
np.write()  # Update LEDs

# Rainbow effect
def rainbow_cycle(wait):
    for j in range(255):
        for i in range(num_leds):
            pixel_index = (i * 256 // num_leds) + j
            np[i] = wheel(pixel_index & 255)
        np.write()
        time.sleep(wait)

def wheel(pos):
    """Generate rainbow colors across 0-255 positions"""
    if pos < 85:
        return (pos * 3, 255 - pos * 3, 0)
    elif pos < 170:
        pos -= 85
        return (255 - pos * 3, 0, pos * 3)
    else:
        pos -= 170
        return (0, pos * 3, 255 - pos * 3)

rainbow_cycle(0.001)

Servo Motor Control

from machine import Pin, PWM
import time

class Servo:
    def __init__(self, pin):
        self.pwm = PWM(Pin(pin))
        self.pwm.freq(50)  # 50Hz for servo

    def angle(self, degrees):
        """Set servo angle (0-180 degrees)"""
        # Convert angle to duty cycle
        # 0° = 1ms (3.2% duty)
        # 90° = 1.5ms (7.5% duty)
        # 180° = 2ms (10% duty)
        min_duty = 1638   # 2.5% of 65535
        max_duty = 8192   # 12.5% of 65535
        duty = int(min_duty + (degrees / 180) * (max_duty - min_duty))
        self.pwm.duty_u16(duty)

    def deinit(self):
        self.pwm.deinit()

# Usage
servo = Servo(25)

# Sweep servo
for angle in range(0, 181, 10):
    servo.angle(angle)
    time.sleep(0.1)

servo.deinit()

Relay Control

from machine import Pin
import time

class Relay:
    def __init__(self, pin):
        self.pin = Pin(pin, Pin.OUT)
        self.off()

    def on(self):
        self.pin.value(1)

    def off(self):
        self.pin.value(0)

    def toggle(self):
        self.pin.toggle()

# Usage
relay = Relay(25)

relay.on()
time.sleep(2)
relay.off()

# Pulse relay
for i in range(5):
    relay.toggle()
    time.sleep(0.5)

Integration with Badge Display

Display Sensor Data

import badger2040
from machine import I2C, Pin
import time

badge = badger2040.Badger2040()
i2c = I2C(0, scl=Pin(5), sda=Pin(4), freq=400000)

def display_sensor_data():
    # Read sensor (example)
    temp = read_temperature()  # Your sensor function
    humidity = read_humidity()

    badge.set_pen(15)
    badge.clear()
    badge.set_pen(0)

    badge.text("Sensor Monitor", 10, 10, scale=2)
    badge.text(f"Temp: {temp:.1f}C", 10, 40, scale=2)
    badge.text(f"Humidity: {humidity:.1f}%", 10, 70, scale=2)

    badge.update()

while True:
    display_sensor_data()
    time.sleep(1)

Interactive Hardware Control

import badger2040
from machine import Pin
import time

badge = badger2040.Badger2040()
led = Pin(25, Pin.OUT)
led_state = False

def draw_ui():
    badge.set_pen(15)
    badge.clear()
    badge.set_pen(0)

    badge.text("LED Control", 10, 10, scale=2)

    status = "ON" if led_state else "OFF"
    badge.text(f"Status: {status}", 10, 50, scale=2)

    badge.text("A: Toggle", 10, 100, scale=1)

    badge.update()

while True:
    draw_ui()

    if badge.pressed(badger2040.BUTTON_A):
        led_state = not led_state
        led.value(1 if led_state else 0)
        time.sleep(0.2)  # Debounce

Power Management for Hardware

from machine import Pin
import machine

# Power control for external hardware
power_pin = Pin(23, Pin.OUT)

def power_on():
    power_pin.value(1)

def power_off():
    power_pin.value(0)

# Use with sleep modes
power_on()
# ... do work with sensor ...
power_off()
machine.lightsleep(5000)  # Sleep 5 seconds

Troubleshooting

I2C device not detected: Check wiring, verify device address, ensure pull-up resistors are present

GPIO not working: Verify pin is not used by internal badge functions, check if pin is input/output capable

SPI communication fails: Check clock polarity and phase, verify baudrate is within device specs

PWM not smooth: Increase PWM frequency, ensure duty cycle calculations are correct

Sensor readings unstable: Add delays between readings, use averaging, check power supply stability

Hardware Safety

  • Never exceed 3.3V on GPIO pins
  • Use level shifters for 5V devices
  • Add current-limiting resistors for LEDs
  • Use flyback diodes with motors and relays
  • Keep I2C wires short (< 20cm) or use bus extenders
  • Use proper power supply for high-current devices

Pinout Reference

Common Badger 2350 pins available for external hardware:

  • GPIO 0-22: General purpose I/O
  • GPIO 26-28: ADC capable (analog input)
  • I2C QWIIC: SCL (Pin 5), SDA (Pin 4)
  • SPI: SCK, MOSI, MISO (check documentation)

Refer to official Badger 2350 pinout diagram for complete details.

Universe 2025 (Tufty) Badge Quickstart Guide

Complete step-by-step guide to go from zero to creating your first app for MonaOS on the Universe 2025 (Tufty) Badge. Perfect for absolute beginners!

About the Badge

The Universe 2025 Badge is a custom version of the Pimoroni Tufty 2350, created for GitHub Universe 2025. It comes pre-loaded with MonaOS, a MicroPython-based operating system with an app launcher.

Hardware Specifications

  • RP2350 Dual-core ARM Cortex-M33 @ 200MHz
  • 512kB SRAM and 16MB QSPI XiP flash
  • 320x240 full colour IPS display (framebuffer pixel doubled from 160x120)
  • 2.4GHz WiFi and Bluetooth 5
  • 1000mAh rechargeable battery (up to 8 hours runtime)
  • IR receiver and transmitter for beacon hunting
  • Five front-facing buttons (A, B, C, UP, DOWN)
  • 4-zone LED backlight
  • USB-C for charging and programming

About MonaOS

Your badge runs MonaOS, which provides:

  • An app launcher that auto-discovers apps in /system/apps/
  • Each app is a directory containing __init__.py, icon.png (24x24), and optional assets/
  • Apps implement update() function called every frame
  • Navigate apps using physical buttons

What You'll Need

Hardware

  • ✓ Universe 2025 (Tufty) Badge
  • ✓ USB-C cable (data capable, not just charging)
  • ✓ Computer (macOS, Linux, or Windows)

Software (we'll install together)

  • Python 3.8 or newer
  • Development tools (mpremote)
  • Text editor or IDE

Time Required

  • First-time setup: 30-45 minutes
  • Your first app: 20-30 minutes

Step-by-Step Setup

Step 1: Install Python on Your Computer

Why: You need Python on your computer to run the tools that communicate with your badge.

macOS:

# Install using Homebrew
brew install python3

# Verify
python3 --version  # Should show 3.8 or higher

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install python3 python3-pip python3-venv
python3 --version

Windows:

  1. Download from https://www.python.org/downloads/
  2. Run installer
  3. ✓ CHECK "Add Python to PATH"
  4. Complete installation
  5. Open PowerShell and verify: python --version

✅ Checkpoint: Run python3 --version (or python --version on Windows). You should see version 3.8 or higher.

Need help? See the python-setup skill for detailed installation guides.

Step 2: Create Your First Project

Why: Keeping projects organized and using virtual environments prevents conflicts.

# Create a directory for your project
mkdir ~/badger-projects
cd ~/badger-projects
mkdir hello-badge
cd hello-badge

# Create a virtual environment
python3 -m venv venv

# Activate it
# macOS/Linux:
source venv/bin/activate

# Windows (PowerShell):
venv\Scripts\Activate.ps1

# Windows (Command Prompt):
venv\Scripts\activate.bat

✅ Checkpoint: Your terminal prompt should now show (venv) at the beginning.

Step 3: Install Badge Tools

Why: These tools let you communicate with your badge, upload files, and run code.

# Make sure venv is activated (you should see "(venv)" in prompt)

# Install essential tool
pip install mpremote

# Verify installation
mpremote --version

✅ Checkpoint: Command should show version number without errors.

Step 4: Connect Your Badge

Why: Let's make sure your computer can talk to your badge.

  1. Connect badge to computer using USB-C cable
  2. Find the device:

macOS/Linux:

ls /dev/tty.usb*
# Should see something like: /dev/tty.usbmodem14201

Windows:

# In PowerShell
[System.IO.Ports.SerialPort]::getportnames()
# Should see something like: COM3
  1. Test connection:

macOS/Linux:

mpremote connect /dev/tty.usbmodem* exec "print('Hello from Badge!')"

Windows:

mpremote connect COM3 exec "print('Hello from Badge!')"

✅ Checkpoint: You should see "Hello from Badge!" printed in your terminal.

Troubleshooting:

  • Badge not found? Try different USB ports
  • Permission denied? See Step 4a below
  • Still stuck? See the badger-diagnostics skill

Step 4a: Fix Permissions (Linux only)

If you get "Permission denied" on Linux:

# Add yourself to dialout group
sudo usermod -a -G dialout $USER

# Log out and log back in for changes to take effect
# Or restart your computer

Step 5: Verify Badge is Ready (CRITICAL)

Why: We must verify everything is working before writing code.

# macOS/Linux:
mpremote connect /dev/tty.usbmodem* exec "
import sys
print('✓ MicroPython:', sys.version)

# Test badgeware module
from badgeware import screen, brushes, shapes
print('✓ badgeware module: loaded')
print('✓ Display size: 160x120')
print('✓ ALL CHECKS PASSED!')
"

# Windows:
mpremote connect COM3 exec "import sys; from badgeware import screen, brushes, shapes; print('✓ MicroPython:', sys.version); print('✓ badgeware loaded'); print('✓ ALL CHECKS PASSED!')"

✅ Checkpoint - ALL must pass:

  • ✓ MicroPython version shown
  • ✓ badgeware module loads
  • ✓ No error messages

DO NOT PROCEED until all checks pass.

Step 6: Understand MonaOS App Structure

MonaOS apps must follow this structure:

my_app/
├── icon.png          # 24x24 PNG icon for launcher
├── __init__.py       # Entry point with update() function
└── assets/          # Optional: app assets (auto-added to path)
    └── ...

Your __init__.py must implement:

  • init() - Optional, called once when app launches
  • update() - Required, called every frame by MonaOS
  • on_exit() - Optional, called when returning to menu

Step 7: Create Your First App

Create the app directory structure:

mkdir hello_app
cd hello_app

Create hello_app/__init__.py:

# hello_app/__init__.py - Your first MonaOS app!
from badgeware import screen, brushes, shapes, io, PixelFont
import math

# Optional: called once when app launches
def init():
    screen.font = PixelFont.load("nope.ppf")
    print("Hello app initialized!")

# Required: called every frame by MonaOS
def update():
    # Clear the framebuffer
    screen.brush = brushes.color(20, 40, 60)
    screen.clear()

    # Draw animated sine wave
    y = (math.sin(io.ticks / 100) * 20) + 60
    screen.brush = brushes.color(0, 255, 0)
    for x in range(160):
        screen.draw(shapes.rectangle(x, int(y), 1, 1))

    # Draw text
    screen.brush = brushes.color(255, 255, 255)
    screen.text("Hello, Badge!", 10, 10)
    screen.text("Press HOME to exit", 10, 100)

    # Handle button presses
    if io.BUTTON_A in io.pressed:
        print("Button A pressed!")
    if io.BUTTON_HOME in io.pressed:
        # HOME button exits to MonaOS menu automatically
        pass

# Optional: called before returning to menu
def on_exit():
    print("App exiting!")

Create hello_app/icon.png:

  • 24x24 pixel PNG image
  • Use any image editor to create a simple icon
  • Or download a free icon and resize it

✅ Checkpoint: Files created:

  • hello_app/__init__.py
  • hello_app/icon.png (24x24 PNG)

Step 8: Test Your App Locally

# From your project directory (not inside hello_app/)
cd ~/badger-projects/hello-badge

# Run the app temporarily (doesn't save to badge)
# macOS/Linux:
mpremote connect /dev/tty.usbmodem* run hello_app/__init__.py

# Windows:
mpremote connect COM3 run hello_app/__init__.py

✅ Checkpoint: Your badge display should show "Hello, Badge!" with an animated wave. Press HOME to exit.

Step 9: Install Your App to MonaOS

Why: Install it permanently so it appears in the MonaOS launcher menu!

⚠️ IMPORTANT: The /system/apps/ directory is READ-ONLY via mpremote. You MUST use USB Mass Storage Mode.

Enter USB Mass Storage Mode
  1. Connect badge via USB-C (if not already connected)
  2. Press RESET button TWICE quickly (double-click the RESET button on the back)
  3. Wait 2-3 seconds - Badge will appear as "BADGER" drive
  4. Verify: Drive should appear in Finder (macOS), File Explorer (Windows), or file manager (Linux)
Install Your App

macOS/Linux:

# Copy your entire app directory to the badge
cp -r hello_app /Volumes/BADGER/apps/

# OR manually via Finder:
# 1. Open BADGER drive in Finder
# 2. Navigate to apps/ folder
# 3. Drag hello_app folder into apps/

Windows:

# Copy your entire app directory
# (Replace D: with your actual BADGER drive letter)
xcopy hello_app D:\apps\hello_app\ /E /I

# OR manually via File Explorer:
# 1. Open BADGER drive
# 2. Navigate to apps\ folder
# 3. Drag hello_app folder into apps\
Exit Mass Storage Mode

macOS:

# Eject the drive
diskutil eject /Volumes/BADGER

# Or right-click BADGER in Finder → Eject

Windows:

  • Right-click BADGER drive → "Eject"
  • Or use "Safely Remove Hardware" in system tray

Linux:

# Eject the drive
sudo umount /media/$USER/BADGER

All Platforms:

  • Press RESET button once on the badge
  • Badge reboots into MonaOS with your app installed!

✅ Checkpoint:

  • BADGER drive was successfully ejected
  • Badge reboots normally (you see MonaOS menu)

Step 10: Launch Your App from the Badge

  1. On your badge: Press HOME if needed to return to MonaOS launcher
  2. Navigate: Use UP/DOWN buttons to find your app
  3. Launch: Press the select button to run your app!

Note: The default MonaOS menu shows 6 apps. You may need to expand pagination (see https://badger.github.io/hack/menu-pagination/)

🎉 Congratulations! Your first MonaOS app is installed and running!

🎉 Congratulations!

You just:

  • ✓ Set up your Python development environment
  • ✓ Installed badge communication tools
  • ✓ Connected to your badge
  • ✓ Created your first MonaOS app with proper structure
  • ✓ Installed your app into MonaOS launcher
  • ✓ Launched your custom app from the badge!

Quick Reference Card

Save these commands - you'll use them a lot:

# Activate your virtual environment
source venv/bin/activate  # macOS/Linux
venv\Scripts\Activate.ps1 # Windows

# Test app temporarily (doesn't save)
mpremote run my_app/__init__.py

# Install app to MonaOS launcher (USB Mass Storage Mode REQUIRED)
# 1. Press RESET button twice on badge (enters Mass Storage Mode)
# 2. Copy app to badge:
cp -r my_app /Volumes/BADGER/apps/           # macOS/Linux
xcopy my_app D:\apps\my_app\ /E /I          # Windows
# 3. Eject BADGER drive safely
# 4. Press RESET once to reboot

# List files (read-only view)
mpremote ls /system/apps

# Connect to REPL (interactive mode)
mpremote
# (Ctrl+C to interrupt, Ctrl+D to soft reset, Ctrl+X to exit)

⚠️ Remember: You CANNOT use mpremote to install apps to /system/apps/ - it's read-only! Always use USB Mass Storage Mode.

Your First Improvements

1. Add Button Interactions

def update():
    screen.brush = brushes.color(20, 40, 60)
    screen.clear()

    screen.brush = brushes.color(255, 255, 255)

    if io.BUTTON_A in io.held:
        screen.text("Button A held!", 10, 50)
    elif io.BUTTON_B in io.pressed:
        screen.text("Button B pressed!", 10, 50)
    elif io.BUTTON_C in io.released:
        screen.text("Button C released!", 10, 50)

2. Draw Shapes

def update():
    screen.brush = brushes.color(20, 40, 60)
    screen.clear()

    # Draw a circle
    screen.brush = brushes.color(255, 0, 0)
    screen.draw(shapes.circle(80, 60, 30))

    # Draw a rectangle
    screen.brush = brushes.color(0, 255, 0)
    screen.draw(shapes.rectangle(10, 10, 50, 30))

    # Draw a line
    screen.brush = brushes.color(255, 255, 255)
    screen.draw(shapes.line(0, 0, 160, 120))

3. Create a Counter

# Add at top level
counter = 0

def update():
    global counter

    screen.brush = brushes.color(0, 0, 0)
    screen.clear()

    screen.brush = brushes.color(255, 255, 255)
    screen.text(f"Count: {counter}", 30, 50)

    if io.BUTTON_A in io.pressed:
        counter += 1
    if io.BUTTON_B in io.pressed:
        counter = 0

Common Beginner Questions

Q: Do I need to activate venv every time?

Yes, activate it each time you open a new terminal.

Q: What if I make a mistake in my code?

Edit locally, test with mpremote, then reinstall via Mass Storage Mode:

# 1. Edit your code locally
# 2. Test it temporarily
mpremote run my_app/__init__.py

# 3. Reinstall via Mass Storage Mode
# - Press RESET twice (enters Mass Storage Mode)
# - Replace files in /Volumes/BADGER/apps/my_app/
# - Eject and press RESET once

Q: Can I edit code directly on the badge?

Yes! Enter USB Mass Storage Mode (press RESET twice). Badge appears as "BADGER" disk. Edit files in /Volumes/BADGER/apps/ using any text editor.

Q: What if my badge freezes?

Press the RESET button on the back of the badge.

Q: How do I see errors?

Connect to REPL:

mpremote

Then test importing: import my_app. Errors will show in terminal.

Q: How do I remove an app?

mpremote rm -rf :/system/apps/my_app

Q: My app doesn't appear in the menu?

The default menu shows 6 apps. Expand pagination: https://badger.github.io/hack/menu-pagination/

Troubleshooting Common Issues

Badge not detected

  1. Check USB cable (must be data cable, not just charging)
  2. Try different USB port
  3. Restart badge (press RESET)
  4. Check connection:
    • macOS/Linux: ls /dev/tty.usb*
    • Windows: Check Device Manager

"Permission denied" error

Linux: Add yourself to dialout group (see Step 4a) Windows: Run PowerShell as Administrator

"Module not found" error

Activate your virtual environment:

source venv/bin/activate  # macOS/Linux
venv\Scripts\Activate.ps1 # Windows

App doesn't appear in MonaOS menu

  1. Verify upload: mpremote ls /system/apps/my_app
  2. Check files exist: __init__.py and icon.png
  3. Icon must be 24x24 PNG
  4. May need to expand menu pagination

Next Steps

Learn More About App Development

→ See badger-app-creator skill

  • Advanced button handling
  • Working with sprites and images
  • WiFi integration
  • State management and persistence

Connect Hardware

→ See badger-hardware skill

  • GPIO pins and sensors
  • I2C/SPI devices
  • IR transmitter/receiver
  • LED backlight control

Use the REPL

→ See micropython-repl skill

  • Interactive development
  • Quick testing
  • Install packages

Improve Your Workflow

→ See badger-deploy skill

  • Automated deployment scripts
  • Project organization
  • Multi-file apps

Official Resources

You're Ready!

You now have everything you need to create amazing projects with your Universe 2025 Badge. Happy coding! 🦡

MicroPython REPL and Package Management

Master the MicroPython REPL (Read-Eval-Print Loop) for interactive development, package management, and quick testing on the Universe 2025 (Tufty) Badge.

Connecting to REPL

Using screen (macOS/Linux)

# Find the device
ls /dev/tty.usb*

# Connect (115200 baud)
screen /dev/tty.usbmodem* 115200

# Exit screen: Ctrl+A then K, then Y to confirm

Using mpremote

# Install mpremote
pip install mpremote

# Connect to REPL
mpremote connect /dev/tty.usbmodem*

# Or auto-detect
mpremote

Using Thonny IDE

  1. Open Thonny
  2. Tools → Options → Interpreter
  3. Select "MicroPython (RP2040)"
  4. Choose correct port
  5. Shell window shows REPL

REPL Basics

Special Commands

# Ctrl+C - Interrupt running program
# Ctrl+D - Soft reboot
# Ctrl+E - Enter paste mode (for multi-line code)
# Ctrl+B - Exit paste mode and execute

# Help system
help()              # General help
help(modules)       # List all modules
help(badgeware)     # Help on specific module

# Quick info
import sys
sys.implementation  # MicroPython version
sys.platform        # Platform info

Interactive Testing

# Test code immediately
>>> from badgeware import screen, display, brushes
>>> screen.brush = brushes.color(255, 255, 255)
>>> screen.text("Test", 10, 10, 2)
>>> display.update()

# Test calculations
>>> temp = 23.5
>>> temp_f = temp * 9/5 + 32
>>> print(f"{temp}C = {temp_f}F")

# Test GPIO
>>> from machine import Pin
>>> led = Pin(25, Pin.OUT)
>>> led.toggle()  # Toggle LED immediately

Paste Mode for Multi-line Code

# Enter paste mode: Ctrl+E
# Paste your code:
def calculate_distance(x1, y1, x2, y2):
    import math
    dx = x2 - x1
    dy = y2 - y1
    return math.sqrt(dx*dx + dy*dy)

print(calculate_distance(0, 0, 3, 4))
# Exit paste mode: Ctrl+D

Package Management

Using mip (MicroPython Package Installer)

# Install package from micropython-lib
import mip
mip.install("urequests")        # HTTP client
mip.install("logging")           # Logging module
mip.install("umqtt.simple")      # MQTT client

# Install from GitHub
mip.install("github:org/repo/package.py")

# Install to specific location
mip.install("urequests", target="/lib")

Using upip (older method)

# Connect to WiFi first
import network
wlan = network.WLAN(network.STA_IF)
wlan.active(True)
wlan.connect('SSID', 'password')

# Wait for connection
while not wlan.isconnected():
    pass

# Install package
import upip
upip.install("micropython-logging")
upip.install("picoweb")

Manual Package Installation

# From your computer, copy files to badge
mpremote cp mymodule.py :/lib/mymodule.py

# Or using ampy
ampy --port /dev/tty.usbmodem* put mymodule.py /lib/mymodule.py

# Then use in REPL
>>> import mymodule

Module Inspection

List Available Modules

# List all built-in and installed modules
help('modules')

# Check if module exists
import sys
'badgeware' in sys.modules  # False until imported

import badgeware
'badgeware' in sys.modules  # True after import

Inspect Module Contents

# See what's in a module
import badgeware
dir(badgeware)  # List all attributes

# Check specific attributes
hasattr(badgeware, 'screen')  # True
hasattr(badgeware, 'brushes')  # True

# Get function signature
help(badgeware.screen)

# Explore submodules
from badgeware import shapes
dir(shapes)  # See all shape functions

# View source (if available)
import inspect
inspect.getsource(mymodule.myfunction)  # May not work on compiled modules

Check Module Location

# Find where module is located
import badgeware
badgeware.__file__  # Shows file path

# List files in system directory
import os
os.listdir('/system')
os.listdir('/system/apps')  # MonaOS apps

Interactive Debugging

Quick Variable Inspection

# Run code and inspect
>>> x = [1, 2, 3, 4, 5]
>>> len(x)
5
>>> type(x)
<class 'list'>
>>> sum(x)
15

# Object inspection
>>> import badgeware
>>> type(badgeware.screen)
<class 'Screen'>
>>> dir(badgeware.screen)  # See all methods
>>> dir(badgeware.brushes)  # See brush functions
>>> dir(badgeware.shapes)  # See shape functions

Print Debugging

# Test function with prints
def process_data(data):
    print(f"Input: {data}")
    result = data * 2
    print(f"Result: {result}")
    return result

>>> process_data(5)
Input: 5
Result: 10
10

Exception Handling

# Test error handling
>>> try:
...     1 / 0
... except ZeroDivisionError as e:
...     print(f"Error: {e}")
Error: division by zero

# Get full traceback
import sys
try:
    buggy_function()
except Exception as e:
    sys.print_exception(e)

Memory Debugging

# Check memory usage
import gc
gc.collect()  # Run garbage collection
gc.mem_free()  # Free memory in bytes
gc.mem_alloc()  # Allocated memory

# Monitor memory during operation
before = gc.mem_free()
# ... do something
after = gc.mem_free()
print(f"Memory used: {before - after} bytes")

Useful REPL Helpers

Create a helpers.py file

# helpers.py - Load in REPL for common tasks
import gc
import sys
import os
from machine import Pin, freq

def info():
    """Display system information"""
    print(f"Platform: {sys.platform}")
    print(f"Version: {sys.version}")
    print(f"CPU Frequency: {freq()} Hz")
    print(f"Free Memory: {gc.mem_free()} bytes")

def ls(path='/'):
    """List files in directory"""
    try:
        files = os.listdir(path)
        for f in files:
            print(f)
    except:
        print(f"Error listing {path}")

def cat(filename):
    """Display file contents"""
    try:
        with open(filename, 'r') as f:
            print(f.read())
    except Exception as e:
        print(f"Error: {e}")

def rm(filename):
    """Remove file"""
    try:
        os.remove(filename)
        print(f"Removed {filename}")
    except Exception as e:
        print(f"Error: {e}")

def blink(pin=25, times=3):
    """Blink LED for testing"""
    import time
    led = Pin(pin, Pin.OUT)
    for i in range(times):
        led.toggle()
        time.sleep(0.5)
    led.value(0)

# Load in REPL with:
# >>> from helpers import *
# >>> info()

Auto-run at REPL start

Create boot.py to run code on startup:

# boot.py - Runs on every boot
import gc
gc.collect()

# Optional: Auto-import common modules
# from badgeware import screen, display, brushes, shapes
# import time

print("Universe 2025 Badge Ready!")
print(f"Free memory: {gc.mem_free()} bytes")

Quick Testing Workflows

Test Hardware Function

# Test I2C scan
from machine import I2C, Pin
i2c = I2C(0, scl=Pin(5), sda=Pin(4), freq=400000)
devices = i2c.scan()
print(f"Found devices: {[hex(d) for d in devices]}")

# Test display
from badgeware import screen, display, brushes
screen.brush = brushes.color(0, 0, 0)
screen.clear()
screen.brush = brushes.color(255, 255, 255)
screen.text("REPL Test", 10, 10, 2)
display.update()

Test Network Connection

import network
import time

wlan = network.WLAN(network.STA_IF)
wlan.active(True)
print("Connecting to WiFi...")
wlan.connect('YOUR_SSID', 'YOUR_PASSWORD')

timeout = 10
while not wlan.isconnected() and timeout > 0:
    print(".", end="")
    time.sleep(1)
    timeout -= 1

if wlan.isconnected():
    print("\nConnected!")
    print(f"IP: {wlan.ifconfig()[0]}")
else:
    print("\nConnection failed")

Test API Call

import urequests
import json

response = urequests.get('https://api.github.com/zen')
print(response.text)
response.close()

# JSON API
response = urequests.get('https://api.example.com/data')
data = response.json()
print(data)
response.close()

File System Operations

List and Navigate Files

import os

# Current directory
os.getcwd()

# List files
os.listdir()
os.listdir('/lib')

# File info
os.stat('main.py')  # Returns (mode, ino, dev, nlink, uid, gid, size, atime, mtime, ctime)

# Check if file exists
try:
    os.stat('main.py')
    print("File exists")
except:
    print("File not found")

Read/Write Files

# Write file
with open('test.txt', 'w') as f:
    f.write('Hello from REPL!\n')

# Read file
with open('test.txt', 'r') as f:
    content = f.read()
    print(content)

# Append to file
with open('log.txt', 'a') as f:
    f.write(f'Log entry: {time.time()}\n')

Remove Files

import os

# Remove file
os.remove('test.txt')

# Remove directory (must be empty)
os.rmdir('mydir')

Checking Installed Packages

Verify Package Installation

# Method 1: Try to import
try:
    import urequests
    print("urequests is installed")
    print(f"Location: {urequests.__file__}")
except ImportError:
    print("urequests not installed")

# Method 2: Check file system
import os
lib_files = os.listdir('/lib')
print("Installed in /lib:")
for f in lib_files:
    print(f"  {f}")

# Method 3: Check sys.path
import sys
print("Module search paths:")
for path in sys.path:
    print(f"  {path}")

Package Version Info

# Some packages have __version__
import urequests
if hasattr(urequests, '__version__'):
    print(f"urequests version: {urequests.__version__}")

# Check MicroPython version
import sys
print(sys.version)
print(sys.implementation)

REPL Tips and Tricks

History Navigation

  • Up/Down arrows: Navigate command history
  • Tab: Auto-completion (limited support)

Copy Output from REPL

# Run command and capture output
>>> result = []
>>> for i in range(10):
...     result.append(i * 2)
>>> print(result)
[0, 2, 4, 6, 8, 10, 12, 14, 16, 18]

# Copy from terminal window

Run Script from REPL

# Import and run
import myapp
myapp.main()

# Or reload after changes
import sys
if 'myapp' in sys.modules:
    del sys.modules['myapp']
import myapp

Timing Code

import time

start = time.ticks_ms()
# ... your code here
for i in range(1000):
    x = i * 2
end = time.ticks_ms()

print(f"Execution time: {time.ticks_diff(end, start)}ms")

Common REPL Issues

REPL not responding: Press Ctrl+C to interrupt, or Ctrl+D to soft reset

Can't import module: Check sys.path, verify file is in /lib or root directory

Out of memory: Run gc.collect(), reduce variable usage, delete large objects

Module changes not reflected: Delete from sys.modules and re-import

Connection lost: Reconnect with screen or mpremote, check USB cable

Using mpremote for Quick Operations

# Execute Python code remotely
mpremote exec "import machine; print(machine.freq())"

# Run local script on device
mpremote run test.py

# Copy file to device
mpremote cp test.py :main.py

# Copy file from device
mpremote cp :main.py local.py

# Mount local directory on device
mpremote mount .

# Filesystem operations
mpremote ls
mpremote mkdir /data
mpremote rm test.txt

# Chain commands
mpremote connect /dev/tty.usbmodem* cp main.py :main.py exec "import main"

REPL Best Practices

  1. Save work frequently - REPL state is lost on reboot
  2. Use paste mode for multi-line code
  3. Run gc.collect() before memory-intensive operations
  4. Test incrementally - Build up complex code piece by piece
  5. Create helper functions in a dedicated module
  6. Use print() liberally for debugging
  7. Soft reset (Ctrl+D) to clear state between tests
  8. Keep REPL sessions short - Move working code to files

Integration with Development Workflow

  1. Prototype in REPL - Test ideas interactively
  2. Save to file - Once code works, save to .py file
  3. Test from file - Import and run from REPL
  4. Iterate - Make changes, reload, test
  5. Deploy - Upload final version to badge

The REPL is your best friend for rapid experimentation and debugging on the Badger 2350!

Python Development Environment Setup

Complete guide to setting up Python on your computer for Universe 2025 (Tufty) Badge development, including virtual environments and all necessary tools.

Quick Start (First Time Setup)

If you're brand new and just want to get started quickly:

# 1. Check if Python is installed
python3 --version
# If not installed, see "Install Python" section below

# 2. Create project directory
mkdir ~/badge-projects
cd ~/badge-projects

# 3. Create virtual environment
python3 -m venv venv

# 4. Activate it
source venv/bin/activate  # macOS/Linux
# venv\Scripts\Activate.ps1 # Windows

# 5. Install badge tools
pip install mpremote

# 6. Test badge connection
mpremote exec "print('Badge connected!')"
# Should print: Badge connected!

# ✓ You're ready! Continue to badger-quickstart skill

If any command fails, continue with the detailed instructions below.

Prerequisites Check

Before starting detailed setup, check what you already have:

# Check Python version
python3 --version

# Check pip
pip3 --version

# Check if tools are installed
which mpremote
which ampy
which rshell

Install Python

macOS

Option 1: Using Homebrew (Recommended)

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python
brew install python3

# Verify installation
python3 --version
pip3 --version

Option 2: Using python.org installer

  1. Download from https://www.python.org/downloads/
  2. Run installer
  3. Check "Add Python to PATH"
  4. Complete installation

Linux (Ubuntu/Debian)

# Update package list
sudo apt update

# Install Python 3 and pip
sudo apt install python3 python3-pip python3-venv

# Verify installation
python3 --version
pip3 --version

Linux (Fedora/RHEL)

# Install Python 3
sudo dnf install python3 python3-pip

# Verify installation
python3 --version
pip3 --version

Windows

Option 1: Using winget (Windows 10/11)

# Install Python
winget install Python.Python.3.11

# Restart terminal, then verify
python --version
pip --version

Option 2: Using python.org installer

  1. Download from https://www.python.org/downloads/
  2. Run installer
  3. IMPORTANT: Check "Add Python to PATH"
  4. Check "Install pip"
  5. Complete installation
  6. Restart terminal

Option 3: Using Microsoft Store

  1. Open Microsoft Store
  2. Search for "Python 3.11"
  3. Install
  4. Verify in terminal

Create Project Directory

Set up a dedicated directory for Badger 2350 projects:

# Create project directory
mkdir -p ~/badger-projects
cd ~/badger-projects

# Create your first project
mkdir my-badge-app
cd my-badge-app

Set Up Virtual Environment

Virtual environments isolate project dependencies and prevent conflicts.

Create Virtual Environment

# Create venv in project directory
python3 -m venv venv

# Alternative name
python3 -m venv .venv

Activate Virtual Environment

macOS/Linux:

# Activate
source venv/bin/activate

# Your prompt should change to show (venv)
(venv) user@computer:~/badger-projects/my-badge-app$

# Deactivate when done
deactivate

Windows (PowerShell):

# Enable script execution (first time only)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Activate
venv\Scripts\Activate.ps1

# Deactivate when done
deactivate

Windows (Command Prompt):

# Activate
venv\Scripts\activate.bat

# Deactivate when done
deactivate

Verify Virtual Environment

# Should show venv Python, not system Python
which python3  # macOS/Linux
where python   # Windows

# Should be venv location like:
# ~/badger-projects/my-badge-app/venv/bin/python3

Install Badger Development Tools

With virtual environment activated:

Core Tools

# Install mpremote (recommended primary tool)
pip install mpremote

# Install ampy (alternative file management)
pip install adafruit-ampy

# Install rshell (interactive shell)
pip install rshell

# Install esptool (firmware flashing)
pip install esptool

# Verify installations
mpremote --version
ampy --version
rshell --version
esptool.py version

Optional Development Tools

# Thonny IDE (beginner-friendly)
pip install thonny

# Code quality tools
pip install black      # Code formatter
pip install pylint     # Linter
pip install mypy       # Type checker

# Testing tools
pip install pytest     # Testing framework
pip install pytest-cov # Coverage reporting

# Documentation tools
pip install mkdocs     # Documentation generator
pip install sphinx     # Alternative documentation

Save Dependencies

Create requirements.txt to track dependencies:

# Generate requirements.txt
pip freeze > requirements.txt

Example requirements.txt:

mpremote==1.20.0
adafruit-ampy==1.1.0
rshell==0.0.32
esptool==4.6.2
black==23.12.1
pylint==3.0.3
pytest==7.4.3

Install from requirements.txt

# Install all dependencies at once
pip install -r requirements.txt

# Or upgrade existing
pip install -r requirements.txt --upgrade

Configure Tools

mpremote Configuration

Create alias for easier use:

macOS/Linux (.bashrc or .zshrc):

# Add to ~/.bashrc or ~/.zshrc
alias badge='mpremote connect /dev/tty.usbmodem*'

# Reload shell
source ~/.bashrc  # or source ~/.zshrc

# Usage
badge ls
badge cp main.py :main.py

Windows (PowerShell profile):

# Open profile
notepad $PROFILE

# Add alias
function badge { mpremote connect COM3 @args }

# Reload
. $PROFILE

# Usage
badge ls

ampy Configuration

Set default port to avoid typing it each time:

macOS/Linux:

# Add to ~/.bashrc or ~/.zshrc
export AMPY_PORT=/dev/tty.usbmodem*

# Reload
source ~/.bashrc

Windows:

# Add to PowerShell profile
$env:AMPY_PORT = "COM3"

# Or set permanently
[Environment]::SetEnvironmentVariable("AMPY_PORT", "COM3", "User")

Verify Complete Setup

Run this verification script:

# verify_setup.sh (macOS/Linux)
#!/bin/bash

echo "Verifying Badger 2350 Development Setup"
echo "========================================"

# Check Python
if command -v python3 &> /dev/null; then
    echo "✓ Python: $(python3 --version)"
else
    echo "✗ Python not found"
    exit 1
fi

# Check pip
if command -v pip3 &> /dev/null; then
    echo "✓ pip: $(pip3 --version)"
else
    echo "✗ pip not found"
    exit 1
fi

# Check virtual environment
if [[ "$VIRTUAL_ENV" != "" ]]; then
    echo "✓ Virtual environment: active"
else
    echo "⚠ Virtual environment: not active"
fi

# Check tools
tools=(mpremote ampy rshell esptool.py)
for tool in "${tools[@]}"; do
    if command -v $tool &> /dev/null; then
        echo "✓ $tool: installed"
    else
        echo "✗ $tool: not installed"
    fi
done

echo "========================================"
echo "Setup verification complete!"

Make executable and run:

chmod +x verify_setup.sh
./verify_setup.sh

Windows PowerShell version:

# verify_setup.ps1
Write-Host "Verifying Badger 2350 Development Setup"
Write-Host "========================================"

# Check Python
if (Get-Command python -ErrorAction SilentlyContinue) {
    $version = python --version
    Write-Host "✓ Python: $version"
} else {
    Write-Host "✗ Python not found"
    exit 1
}

# Check pip
if (Get-Command pip -ErrorAction SilentlyContinue) {
    Write-Host "✓ pip: installed"
} else {
    Write-Host "✗ pip not found"
    exit 1
}

# Check virtual environment
if ($env:VIRTUAL_ENV) {
    Write-Host "✓ Virtual environment: active"
} else {
    Write-Host "⚠ Virtual environment: not active"
}

# Check tools
$tools = @("mpremote", "ampy", "rshell", "esptool.py")
foreach ($tool in $tools) {
    if (Get-Command $tool -ErrorAction SilentlyContinue) {
        Write-Host "✓ $tool: installed"
    } else {
        Write-Host "✗ $tool: not installed"
    }
}

Write-Host "========================================"
Write-Host "Setup verification complete!"

Test Badge Connection

Once tools are installed, test connection to badge:

# List serial ports (macOS/Linux)
ls /dev/tty.usb*

# List serial ports (Windows PowerShell)
[System.IO.Ports.SerialPort]::getportnames()

# Test connection with mpremote
mpremote connect /dev/tty.usbmodem* exec "print('Hello from Badger!')"

# Or on Windows
mpremote connect COM3 exec "print('Hello from Badger!')"

# If successful, you should see: Hello from Badger!

Project Template

Create a standard project structure:

# Create structure
mkdir -p my-badge-app/{lib,assets,data,tests}
cd my-badge-app

# Create files
touch main.py config.py README.md requirements.txt
touch lib/__init__.py
touch tests/test_main.py

# Create .gitignore
cat > .gitignore <<EOF
# Virtual environment
venv/
.venv/
env/

# Python
__pycache__/
*.pyc
*.pyo
*.pyd
.Python

# IDE
.vscode/
.idea/
*.swp
*.swo

# OS
.DS_Store
Thumbs.db

# Local config
config.local.py
.env
EOF

# Initialize git
git init

Project structure:

my-badge-app/
├── venv/                # Virtual environment (gitignored)
├── main.py              # Main application
├── config.py            # Configuration
├── requirements.txt     # Python dependencies
├── README.md
├── .gitignore
├── lib/                 # Reusable modules
│   └── __init__.py
├── assets/              # Images, fonts, etc.
├── data/                # Runtime data
└── tests/               # Test files
    └── test_main.py

IDE Setup

VS Code (Recommended)

# Install VS Code
# macOS
brew install --cask visual-studio-code

# Linux
sudo snap install code --classic

# Windows
winget install Microsoft.VisualStudioCode

Recommended Extensions:

  1. Python (Microsoft)
  2. Pylance
  3. Python Debugger
  4. MicroPython (for syntax)
  5. GitLens

VS Code Settings (.vscode/settings.json):

{
  "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python",
  "python.formatting.provider": "black",
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": true,
  "editor.formatOnSave": true,
  "files.exclude": {
    "**/__pycache__": true,
    "**/*.pyc": true
  }
}

PyCharm

  1. Download from https://www.jetbrains.com/pycharm/
  2. Open project directory
  3. Configure interpreter: Settings → Project → Python Interpreter
  4. Select existing venv or create new one

Thonny (Beginner-Friendly)

# Install Thonny
pip install thonny

# Or download from https://thonny.org

# Run
thonny

Configure Thonny for Badger:

  1. Tools → Options → Interpreter
  2. Select "MicroPython (RP2040)"
  3. Select correct port
  4. Click OK

Workflow Scripts

Activate Script

Create activate.sh in project root:

#!/bin/bash
# activate.sh - Quick project activation

# Activate virtual environment
source venv/bin/activate

# Set badge port
export BADGE_PORT="/dev/tty.usbmodem*"

# Show status
echo "Badge development environment activated!"
echo "Python: $(which python3)"
echo "Badge port: $BADGE_PORT"

# Quick commands
alias badge='mpremote connect $BADGE_PORT'
alias deploy='./deploy.sh'

echo "Ready to develop!"

Usage:

source activate.sh
# Now you're ready to work!

Quick Deploy Script

Create deploy.sh:

#!/bin/bash
# deploy.sh - Quick deploy to badge

if [ -z "$BADGE_PORT" ]; then
    BADGE_PORT="/dev/tty.usbmodem*"
fi

echo "Deploying to badge..."
mpremote connect $BADGE_PORT cp main.py :main.py
mpremote connect $BADGE_PORT cp config.py :config.py
echo "Deployment complete!"

Make executable:

chmod +x deploy.sh activate.sh

Common Setup Issues

"command not found: python"

macOS/Linux:

# Use python3 instead of python
python3 --version  # This should work

# If python3 also not found, install Python (see Install Python section above)

# Optional: Create alias for convenience
alias python=python3
alias pip=pip3
# Add to ~/.bashrc or ~/.zshrc to make permanent

Windows:

# Use python instead of python3
python --version

# If not found, reinstall Python with "Add to PATH" checked

Important: On macOS/Linux, always use python3 and pip3 (not python and pip).

Python not in PATH

macOS/Linux:

# Add to PATH in ~/.bashrc or ~/.zshrc
export PATH="/usr/local/bin:$PATH"
export PATH="/opt/homebrew/bin:$PATH"  # For M1/M2 Macs

# Reload shell
source ~/.bashrc  # or source ~/.zshrc

Windows:

  • Reinstall Python with "Add to PATH" checked
  • Or manually add to PATH:
    • System Properties → Environment Variables
    • Add C:\Python311 and C:\Python311\Scripts

pip install fails with permissions error

# Don't use sudo! Use virtual environment instead
python3 -m venv venv
source venv/bin/activate
pip install mpremote

Virtual environment activation fails (Windows)

# Enable scripts (run as Administrator)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Then activate normally
venv\Scripts\Activate.ps1

Badge not detected

macOS:

# Check if driver needed (usually automatic)
ls /dev/tty.usb*

# Grant permissions
sudo chmod 666 /dev/tty.usbmodem*

Linux:

# Add user to dialout group
sudo usermod -a -G dialout $USER

# Logout and login for changes to take effect

# Or use sudo temporarily
sudo mpremote connect /dev/ttyACM0

Windows:

  • Install USB driver if needed
  • Check Device Manager for COM port
  • Try different USB ports

mpremote connection fails

# Try explicit port
mpremote connect /dev/tty.usbmodem14201

# List available ports
mpremote connect list

# Auto-detect port (usually works)
mpremote exec "print('Hello')"

# Check if badge is in bootloader mode
# (Hold BOOTSEL button while connecting)

"can't open file" or "No such file" errors

If you see errors like can't open file 'test_connection.py':

# This means the script doesn't exist yet

# Option 1: Use basic verification instead
mpremote exec "print('Badge connected!')"

# Option 2: Create the missing script (see badger-diagnostics skill)

# Option 3: Use direct mpremote commands instead of scripts
mpremote run my_app/__init__.py  # Instead of make commands

Common missing files on first setup:

  • test_connection.py - Use mpremote exec for basic testing instead
  • deploy.sh - Use direct mpremote cp commands instead
  • Apps/examples - Create them as you go

Don't let missing scripts block you - use the direct mpremote commands shown in CLAUDE.md and skills.

Update Tools

Keep tools updated:

# Activate virtual environment first
source venv/bin/activate

# Update pip itself
pip install --upgrade pip

# Update all packages
pip install --upgrade mpremote ampy rshell esptool

# Or update from requirements.txt
pip install -r requirements.txt --upgrade

⚠️ Verify Your Setup

CRITICAL: Always verify your setup is working correctly before starting development.

Complete Verification Checklist

Run through this checklist every time you start a new session:

# 1. Verify Python installation
python3 --version
# Should show: Python 3.8.0 or higher

# 2. Verify virtual environment is activated
which python3
# Should show path to venv/bin/python3 (not system Python)

# 3. Verify tools are installed
mpremote --version
ampy --version
# Both should show version numbers

# 4. Verify badge is connected
ls /dev/tty.usb*        # macOS/Linux
# OR
# [System.IO.Ports.SerialPort]::getportnames()  # Windows

# 5. Test badge connection
mpremote connect /dev/tty.usbmodem* exec "print('Hello from Badge!')"
# Should print: Hello from Badge!

# 6. Verify badgeware module
mpremote connect /dev/tty.usbmodem* exec "import badgeware; print('badgeware OK')"
# Should print: badgeware OK

Automated Verification Script

Create verify_setup.sh in your project:

#!/bin/bash
# verify_setup.sh - Complete environment verification

echo "=========================================="
echo "Badger 2350 Environment Verification"
echo "=========================================="

errors=0

# Check Python
if command -v python3 &> /dev/null; then
    version=$(python3 --version)
    echo "✓ Python: $version"
else
    echo "✗ Python not found"
    ((errors++))
fi

# Check virtual environment
if [[ "$VIRTUAL_ENV" != "" ]]; then
    echo "✓ Virtual environment: active ($VIRTUAL_ENV)"
else
    echo "⚠ Virtual environment: not active"
    echo "  Run: source venv/bin/activate"
    ((errors++))
fi

# Check mpremote
if command -v mpremote &> /dev/null; then
    echo "✓ mpremote: installed"
else
    echo "✗ mpremote: not installed"
    echo "  Run: pip install mpremote"
    ((errors++))
fi

# Check badge connection
if mpremote connect list 2>&1 | grep -q "usb"; then
    echo "✓ Badge: detected"

    # Test REPL
    if mpremote exec "print('OK')" 2>&1 | grep -q "OK"; then
        echo "✓ Badge REPL: working"
    else
        echo "✗ Badge REPL: not responding"
        ((errors++))
    fi

    # Test badgeware module
    if mpremote exec "import badgeware" 2>&1; then
        echo "✓ badgeware module: available"
    else
        echo "✗ badgeware module: not found"
        ((errors++))
    fi
else
    echo "✗ Badge: not detected"
    echo "  Check USB connection"
    ((errors++))
fi

echo "=========================================="
if [ $errors -eq 0 ]; then
    echo "✓ ALL CHECKS PASSED - Ready for development!"
    exit 0
else
    echo "✗ $errors ERROR(S) FOUND - Fix issues before proceeding"
    exit 1
fi

Make executable: chmod +x verify_setup.sh

Run this script before every development session: ./verify_setup.sh

What to Do If Verification Fails

IssueSolution
Python not foundReinstall Python, check PATH
venv not activeRun source venv/bin/activate
Tools not installedRun pip install -r requirements.txt
Badge not detectedCheck USB cable, try different port
REPL not respondingRestart badge, check for other programs using port
badgeware missingBadge firmware may need reflashing

Never skip verification - It catches 90% of issues before they become problems.

Best Practices

  1. Always verify setup first - Run verification script at start of session
  2. Always use virtual environments - Isolate project dependencies
  3. Keep requirements.txt updated - pip freeze > requirements.txt
  4. Use version control (git) - Track changes
  5. Document your setup - Update README.md
  6. Test on clean environment - Verify requirements.txt is complete
  7. Don't commit venv/ - Add to .gitignore
  8. Pin versions - Avoid "works on my machine" issues

Next Steps

After setup is complete:

  1. ✓ Python installed
  2. ✓ Virtual environment created
  3. ✓ Tools installed (mpremote, ampy, etc.)
  4. ✓ Badge connected and detected
  5. ✓ Project structure created

Now you're ready to:

  • Flash firmware to badge (see badger-2350-dev skill)
  • Create your first app (see badger-app-creator skill)
  • Connect sensors (see badger-hardware skill)

Your development environment is ready! 🎉

Commands 5

Badge Quick Start Checklist

Run through a complete environment verification checklist to ensure everything is set up correctly for Badger 2350 development.

What to Check

Run verification commands and report status for each step:

1. Python Installation

python3 --version

Expected: Python 3.8.0 or higher

If missing: Provide installation instructions for user's OS:

2. Virtual Environment

Check if user is in a virtual environment:

echo $VIRTUAL_ENV

If not active:

# Create virtual environment
python3 -m venv venv

# Activate it
source venv/bin/activate  # macOS/Linux
venv\Scripts\Activate.ps1 # Windows PowerShell

3. mpremote Installation

mpremote --version

If missing:

pip install mpremote

4. Badge Connection

mpremote exec "print('Badge connected!')"

Expected: "Badge connected!" printed

If fails:

  • Check USB-C cable (must be data cable, not charge-only)
  • Try different USB port
  • Check badge is powered on
  • On Linux: May need to add user to dialout group

5. badgeware Module

mpremote exec "from badgeware import screen, brushes, shapes, io; print('✓ badgeware loaded'); print('✓ Display: 160x120'); print('✓ All OK')"

Expected: All ✓ marks shown

If fails:

  • Badge may need firmware update
  • Check USB connection is stable
  • Try pressing RESET button once

Results Summary

After running all checks, provide a summary:

✅ All checks passed! You're ready to start developing.

Or identify what needs fixing:

⚠️ Issues found:

  • [List any failed checks]
  • [Provide specific fix commands]

Next Steps

If all checks pass, suggest:

  1. Create your first app:

    /create-badge-app my_first_app
    
  2. Browse example apps: Check examples/hello_world and examples/meditation_timer in this plugin

  3. Read the API reference:

    /badgeware-api
    
  4. Get detailed help: Use the badger-quickstart skill for step-by-step guide

Troubleshooting

If verification fails, run:

/troubleshoot <issue>

For comprehensive diagnostics, use the badger-diagnostics skill.

Detailed Setup Guides

For complete setup instructions, refer to these skills:

  • badger-quickstart: Complete beginner guide (30-45 min)
  • python-setup: Detailed Python environment setup
  • badger-2350-dev: Development toolchain reference

You can invoke skills by asking Claude to use them when you need more detailed help.

Badgeware API Reference

Provide a quick reference for the badgeware module API based on the user's search term or show overview if no term provided.

Display & Graphics

Screen Drawing

from badgeware import screen, brushes, shapes

# Set brush color (RGB 0-255)
screen.brush = brushes.color(r, g, b)
screen.brush = brushes.color(r, g, b, alpha)  # With transparency

# Clear screen
screen.clear()

# Draw text
screen.text("Hello", x, y)

# Load and use custom fonts
screen.font = PixelFont.load("/system/assets/fonts/ark.ppf")

Shapes

from badgeware import shapes

# Draw shapes
screen.draw(shapes.rectangle(x, y, width, height))
screen.draw(shapes.circle(x, y, radius))
screen.draw(shapes.line(x1, y1, x2, y2))
screen.draw(shapes.rounded_rectangle(x, y, w, h, radius))

Images & Sprites

from badgeware import Image

# Load and display images
img = Image.load("sprite.png")
screen.blit(img, x, y)
screen.scale_blit(img, x, y, width, height)

# Enable antialiasing for smooth edges
screen.antialias = Image.X4

Button Handling

Button Constants

from badgeware import io

# Available buttons
io.BUTTON_A
io.BUTTON_B
io.BUTTON_C
io.BUTTON_UP
io.BUTTON_DOWN
io.BUTTON_HOME  # Exits to MonaOS menu

Button States

def update():
    # Just pressed this frame
    if io.BUTTON_A in io.pressed:
        print("A pressed")

    # Just released this frame
    if io.BUTTON_B in io.released:
        print("B released")

    # Currently held down
    if io.BUTTON_C in io.held:
        print("C is held")

    # State changed this frame
    if io.BUTTON_UP in io.changed:
        print("UP state changed")

Animation & Timing

Frame Counter

from badgeware import io
import math

frame = 0

def update():
    global frame

    # Use frame counter for animations
    radius = 10 + int(math.sin(frame / 20) * 5)

    # Breathing animation (4-second cycle at 30fps)
    phase = ((frame % 120) / 120.0) * 2 * math.pi
    scale = 20 + int(math.sin(phase) * 15)

    frame += 1

Timing

import time

# Track elapsed time
start_time = time.time()
elapsed = time.time() - start_time

# Sleep (use sparingly, blocks update loop)
time.sleep(0.1)

Transformations

Matrix Transforms

from badgeware import Matrix

# Create and apply transformations
rect = shapes.rectangle(-1, -1, 2, 2)
rect.transform = Matrix() \
    .translate(80, 60) \
    .scale(20, 20) \
    .rotate(io.ticks / 100)  # Animated rotation

screen.draw(rect)

Persistent Storage

File Operations

import json

# Write app data (writable partition)
with open("/storage/myapp_data.json", "w") as f:
    json.dump({"score": 100}, f)

# Read app data
with open("/storage/myapp_data.json", "r") as f:
    data = json.load(f)

Display Specifications

  • Resolution: 160x120 framebuffer (pixel-doubled to 320x240 physical display)
  • Colors: Full RGB (0-255 per channel)
  • Fonts: 30 licensed pixel fonts in /system/assets/fonts/
  • Automatic Updates: Display refreshes after each update() call

Important Notes

⚠️ This badge uses badgeware module, NOT badger2040! The APIs are different.

⚠️ Frame Rate: MonaOS calls update() ~30 times per second. Keep operations fast.

⚠️ Screen Coordinates: Origin (0,0) is top-left corner.

Full Documentation

For complete API documentation, see:

Create Badge App

Create a complete MonaOS application structure with all required files.

What to do

  1. Ask the user for the app name if not provided
  2. Validate the app name (lowercase, no spaces, alphanumeric with underscores/hyphens)
  3. Create the following directory structure:
{app_name}/
├── __init__.py    # Main app file from template
├── icon.png       # 24x24 icon
└── assets/        # Optional assets directory
  1. Use the app template from badger-marketplace/badger-2350-dev/templates/app_template.py
  2. Replace {{APP_NAME}} placeholders with the actual app name
  3. Copy the icon template from badger-marketplace/badger-2350-dev/templates/icon_template.png
  4. Create an empty assets/ directory

After creation

Tell the user:

Next Steps:

  1. Test your app locally:

    mpremote run {app_name}/__init__.py
    
  2. Edit the code:

    • Open {app_name}/__init__.py in your editor
    • Replace TODO comments with your app logic
    • Add button handlers, animations, and content
  3. Deploy to badge when ready:

    /deploy-to-badge {app_name}
    
  4. Customize the icon:

    • Edit {app_name}/icon.png (must be 24x24 pixels)
    • Use any image editor or pixel art tool

Your app structure is ready! The template includes examples of:

  • Button handling for all 5 buttons
  • Simple animation with frame counter
  • Text and shape drawing
  • State management pattern

Check the examples/ directory in this plugin for working examples like hello_world and meditation_timer.

Deploy to Badge

Guide the user through deploying their MonaOS app to the badge using USB Mass Storage Mode.

Critical Information

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

Steps to Deploy

1. Verify App Structure

First, check that the app directory exists and contains required files:

  • __init__.py (required)
  • icon.png (required, 24x24 pixels)
  • assets/ (optional)

If files are missing, inform the user what's needed.

2. Enter USB Mass Storage Mode

Instruct the user:

  1. Connect badge via USB-C cable
  2. Press RESET button TWICE quickly (double-click the button on the back of the badge)
  3. Wait 2-3 seconds - Badge will appear as "BADGER" drive
  4. Verify: The drive should appear in Finder (macOS), File Explorer (Windows), or file manager (Linux)

3. Copy App to Badge

Provide OS-specific instructions:

macOS/Linux:

cp -r {app_name} /Volumes/BADGER/apps/

Windows (PowerShell):

xcopy {app_name} D:\apps\{app_name}\ /E /I

(Replace D: with actual BADGER drive letter)

Or manually:

  1. Open BADGER drive in file manager
  2. Navigate to apps/ folder
  3. Drag {app_name} folder into apps/

4. Exit Mass Storage Mode

macOS:

diskutil eject /Volumes/BADGER

Or right-click BADGER in Finder → Eject

Windows:

  • Right-click BADGER drive → "Eject"
  • Or use "Safely Remove Hardware" in system tray

Linux:

sudo umount /media/$USER/BADGER

5. Reboot Badge

Press RESET button once on the badge. It will reboot into MonaOS with your new app installed!

6. Launch Your App

  1. Navigate the MonaOS menu using UP/DOWN and A/C buttons
  2. Find your app (look for the icon you created)
  3. Press B to launch

Troubleshooting

App doesn't appear in menu

  • Check that you copied the entire folder, not just the files inside
  • Verify the folder is in /Volumes/BADGER/apps/ (or D:\apps\ on Windows)
  • Make sure __init__.py and icon.png are both present
  • If you have 7+ apps, you may need to install the paginated menu (see below)

Badge shows only 6 apps

The default MonaOS menu shows only 6 apps. To enable pagination:

  1. Enter Mass Storage Mode again (double-press RESET)
  2. Download paginated menu: https://raw.githubusercontent.com/badger/home/refs/heads/main/badge/apps/menu/__init__.py
  3. Backup original: Copy /Volumes/BADGER/apps/menu/__init__.py to __init__-backup.py
  4. Replace with paginated version
  5. Eject and reboot

"Read-only file system" error with mpremote

This confirms you're trying to use mpremote, which won't work. Use USB Mass Storage Mode instead (see steps above).

File System Mapping

When in Mass Storage Mode:

  • /Volumes/BADGER/apps/ → /system/apps/ on badge (your apps)
  • /Volumes/BADGER/assets/ → /system/assets/ on badge (system files)
  • /Volumes/BADGER/main.py → /system/main.py on badge (boot script)

Next Steps

After successful deployment:

  • Test your app on the badge
  • Press HOME button to return to menu
  • Make changes locally and redeploy as needed

Troubleshoot Badge Issues

Help diagnose and fix common Badger 2350 development problems.

Common Issues

Badge Not Detected

Symptoms: mpremote can't find badge, no /dev/tty.usbmodem* device

Diagnostics:

# macOS/Linux: Check for USB serial devices
ls /dev/tty.usbmodem* /dev/ttyACM*

# Windows: Check COM ports
[System.IO.Ports.SerialPort]::getportnames()

Solutions:

  1. Check USB cable: Must be data cable, not charge-only
  2. Try different USB port: Some ports may not support data
  3. Press RESET button: Reconnect badge to computer
  4. Check drivers (Windows): May need CH340/CP2102 drivers
  5. Linux permissions: Add user to dialout group:
    sudo usermod -a -G dialout $USER
    # Log out and log back in
    

App Not Appearing in MonaOS Menu

Symptoms: Deployed app doesn't show up in badge menu

Diagnostics:

  1. Check app was deployed via Mass Storage Mode (not mpremote)
  2. Verify file structure:
    /Volumes/BADGER/apps/my_app/
    ├── __init__.py
    └── icon.png
    
  3. Check you have 7+ apps (menu shows max 6 by default)

Solutions:

  1. Redeploy using Mass Storage Mode:

    • Press RESET twice
    • Copy entire app folder to /Volumes/BADGER/apps/
    • Eject drive, press RESET once
  2. Verify required files:

    • __init__.py must exist
    • icon.png must be 24x24 pixels
    • Folder must be in apps/ directory
  3. Install paginated menu if you have 7+ apps:

Memory Errors

Symptoms: MemoryError, app crashes, out of memory

Diagnostics:

# Check available memory in REPL
mpremote exec "import gc; gc.collect(); print('Free:', gc.mem_free())"

Solutions:

  1. Collect garbage frequently:

    import gc
    gc.collect()  # Call in your update() function periodically
    
  2. Load resources once in init(), not in update()

  3. Delete unused variables:

    del large_variable
    gc.collect()
    
  4. Use smaller images: Reduce sprite sizes, compress PNGs

  5. Avoid large lists/dictionaries: Keep data structures minimal

Module Import Errors

Symptoms: ImportError: no module named 'badgeware'

Diagnostics:

# Test badgeware import
mpremote exec "import badgeware; print('OK')"

Solutions:

  1. Verify badge firmware: May need MonaOS firmware update
  2. Check badge is genuine Universe 2025 Badge (not standard Tufty 2040)
  3. Flash latest firmware:

Display Not Updating

Symptoms: Screen frozen, changes don't appear

Diagnostics:

  1. Check update() function is being called
  2. Verify no infinite loops in code
  3. Check for exceptions that halt execution

Solutions:

  1. Ensure update() function exists:

    def update():
        # Your code here
        pass
    
  2. Avoid blocking operations:

    • Don't use while True: loops
    • Don't use time.sleep() in update loop
    • Keep update() fast (< 33ms for 30fps)
  3. Check for errors in REPL:

    mpremote
    # Watch for error messages
    

Button Not Responding

Symptoms: Button presses don't trigger actions

Diagnostics:

# Test button in REPL
mpremote exec "
from badgeware import io
while True:
    io.poll()
    if io.BUTTON_A in io.pressed:
        print('A pressed')
        break
"

Solutions:

  1. Use correct button state check:

    if io.BUTTON_A in io.pressed:  # Just pressed (correct)
    if io.BUTTON_A == io.pressed:  # WRONG!
    
  2. Call io.poll() if needed (MonaOS usually handles this)

  3. Check button isn't physically stuck

Network Connection Failures

Symptoms: WiFi won't connect, timeout errors

Diagnostics:

import network
wlan = network.WLAN(network.STA_IF)
wlan.active(True)
print('Networks:', wlan.scan())

Solutions:

  1. Check WiFi credentials are correct
  2. Verify network is 2.4GHz (badge doesn't support 5GHz)
  3. Check WiFi is enabled on badge
  4. Increase timeout when connecting:
    import time
    wlan.connect('SSID', 'password')
    timeout = 10
    while not wlan.isconnected() and timeout > 0:
        time.sleep(1)
        timeout -= 1
    

Get More Help

Use Skills for Detailed Guides

  • badger-diagnostics: Comprehensive system diagnostics
  • badger-2350-dev: Development toolchain reference
  • badger-deploy: Deployment troubleshooting
  • badger-hardware: GPIO and hardware issues

Check Official Resources

Run Environment Check

/badge-quickstart

This will verify your entire development environment and identify configuration issues.

Sponsors

Details

Marketplace
johnlindquist/badger-2350-plugin
Source
badger-2350-dev
Category
Community