name	badger-quickstart
description	Complete getting started guide for Universe 2025 (Tufty) Badge from zero to first app. Use when helping absolute beginners, providing step-by-step first-time setup, or when users ask "how do I get started", "where do I begin", or "first steps with the badge".

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:

Download from https://www.python.org/downloads/
Run installer
✓ CHECK "Add Python to PATH"
Complete installation
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.

Connect badge to computer using USB-C cable
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

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

Connect badge via USB-C (if not already connected)
Press RESET button TWICE quickly (double-click the RESET button on the back)
Wait 2-3 seconds - Badge will appear as "BADGER" drive
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

On your badge: Press HOME if needed to return to MonaOS launcher
Navigate: Use UP/DOWN buttons to find your app
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

Check USB cable (must be data cable, not just charging)
Try different USB port
Restart badge (press RESET)
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

Verify upload: mpremote ls /system/apps/my_app
Check files exist: __init__.py and icon.png
Icon must be 24x24 PNG
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

Getting Started: https://badger.github.io/get-started/
Hacks & Tutorials: https://badger.github.io/hacks/
Official Apps: https://badger.github.io/apps/
Source Code: https://github.com/badger/home/tree/main/badgerware
API Docs: https://github.com/badger/home/blob/main/badgerware/

You're Ready!

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

Install Skill

SKILL.md

Universe 2025 (Tufty) Badge Quickstart Guide

About the Badge

Hardware Specifications

About MonaOS

What You'll Need

Hardware

Software (we'll install together)

Time Required

Step-by-Step Setup

Step 1: Install Python on Your Computer

Step 2: Create Your First Project

Step 3: Install Badge Tools

Step 4: Connect Your Badge

Step 4a: Fix Permissions (Linux only)

Step 5: Verify Badge is Ready (CRITICAL)

Step 6: Understand MonaOS App Structure

Step 7: Create Your First App

Step 8: Test Your App Locally

Step 9: Install Your App to MonaOS

Enter USB Mass Storage Mode

Install Your App

Exit Mass Storage Mode

Step 10: Launch Your App from the Badge

🎉 Congratulations!

Quick Reference Card

Your First Improvements

1. Add Button Interactions

2. Draw Shapes

3. Create a Counter

Common Beginner Questions

Q: Do I need to activate venv every time?

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

Q: Can I edit code directly on the badge?

Q: What if my badge freezes?

Q: How do I see errors?

Q: How do I remove an app?

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

Troubleshooting Common Issues

Badge not detected

"Permission denied" error

"Module not found" error

App doesn't appear in MonaOS menu

Next Steps

Learn More About App Development

Connect Hardware

Use the REPL

Improve Your Workflow

Official Resources

You're Ready!