badger-deploy

What this skill does

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

```bash
# 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):
- Download: https://raw.githubusercontent.com/badger/home/refs/heads/main/badge/apps/menu/__init__.py
- Replace `/Volumes/BADGER/apps/menu/__init__.py` in Mass Storage Mode

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

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

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

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

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

```bash
#!/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:
```bash
./deploy.sh my_app
```

## Deployment Workflows

### Development Workflow

Quick iteration during development:

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

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