badger-quickstart

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:

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

3. 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:
        
        


 ():
    ()

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

• 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! 🦡