badger-quickstart

What this skill does

# 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:**
```bash
# Install using Homebrew
brew install python3

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

**Linux (Ubuntu/Debian):**
```bash
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.

```bash
# 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.

```bash
# 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:**
```bash
ls /dev/tty.usb*
# Should see something like: /dev/tty.usbmodem14201
```

**Windows:**
```powershell
# In PowerShell
[System.IO.Ports.SerialPort]::getportnames()
# Should see something like: COM3
```

3. **Test connection**:

**macOS/Linux:**
```bash
mpremote connect /dev/tty.usbmodem* exec "print('Hello from Badge!')"
```

**Windows:**
```powershell
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:

```bash
# 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.

```bash
# 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:

```bash
mkdir hello_app
cd hello_app
```

Create `hello_app/__init__.py`:

```python
# 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

```bash
# 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**: Driv