Initial commit

2025-11-30 08:28:30 +08:00
commit 1f575f61f9
16 changed files with 6086 additions and 0 deletions
--- a/skills/badger-quickstart/SKILL.md
+++ b/skills/badger-quickstart/SKILL.md
@@ -0,0 +1,587 @@
+---
+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:**
+```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**: Drive should appear in Finder (macOS), File Explorer (Windows), or file manager (Linux)
+
+#### Install Your App
+
+**macOS/Linux:**
+```bash
+# 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:**
+```powershell
+# 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:**
+```bash
+# 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:**
+```bash
+# 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:
+
+```bash
+# 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
+
+```python
+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
+
+```python
+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
+
+```python
+# 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:
+```bash
+# 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:
+```bash
+mpremote
+```
+Then test importing: `import my_app`. Errors will show in terminal.
+
+### Q: How do I remove an app?
+
+```bash
+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:
+```bash
+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! 🦡