Deploy to Badge

Guide the user through deploying their MonaOS app to the badge using USB Mass Storage Mode.

Critical Information

⚠️ IMPORTANT: The /system/apps/ directory is READ-ONLY via mpremote. You MUST use USB Mass Storage Mode to install apps.

Steps to Deploy

1. Verify App Structure

First, check that the app directory exists and contains required files:

• __init__.py (required)
• icon.png (required, 24x24 pixels)
• assets/ (optional)

If files are missing, inform the user what's needed.

2. Enter USB Mass Storage Mode

Instruct the user:

1. Connect badge via USB-C cable
2. Press RESET button TWICE quickly (double-click the button on the back of the badge)
3. Wait 2-3 seconds - Badge will appear as "BADGER" drive
4. Verify: The drive should appear in Finder (macOS), File Explorer (Windows), or file manager (Linux)

3. Copy App to Badge

Provide OS-specific instructions:

macOS/Linux:

cp -r {app_name} /Volumes/BADGER/apps/

Windows (PowerShell):

xcopy {app_name} D:\apps\{app_name}\ /E /I

(Replace D: with actual BADGER drive letter)

Or manually:

1. Open BADGER drive in file manager
2. Navigate to apps/ folder
3. Drag {app_name} folder into apps/

4. Exit Mass Storage Mode

macOS:

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:

sudo umount /media/$USER/BADGER

5. Reboot Badge

Press RESET button once on the badge. It will reboot into MonaOS with your new app installed!

6. Launch Your App

1. Navigate the MonaOS menu using UP/DOWN and A/C buttons
2. Find your app (look for the icon you created)
3. Press B to launch

Troubleshooting

App doesn't appear in menu

• Check that you copied the entire folder, not just the files inside
• Verify the folder is in /Volumes/BADGER/apps/ (or D:\apps\ on Windows)
• Make sure __init__.py and icon.png are both present
• If you have 7+ apps, you may need to install the paginated menu (see below)

Badge shows only 6 apps

The default MonaOS menu shows only 6 apps. To enable pagination:

1. Enter Mass Storage Mode again (double-press RESET)
2. Download paginated menu: https://raw.githubusercontent.com/badger/home/refs/heads/main/badge/apps/menu/__init__.py
3. Backup original: Copy /Volumes/BADGER/apps/menu/__init__.py to __init__-backup.py
4. Replace with paginated version
5. Eject and reboot

"Read-only file system" error with mpremote

This confirms you're trying to use mpremote, which won't work. Use USB Mass Storage Mode instead (see steps above).

File System Mapping

When in Mass Storage Mode:

• /Volumes/BADGER/apps/ → /system/apps/ on badge (your apps)
• /Volumes/BADGER/assets/ → /system/assets/ on badge (system files)
• /Volumes/BADGER/main.py → /system/main.py on badge (boot script)

Next Steps

After successful deployment:

• Test your app on the badge
• Press HOME button to return to menu
• Make changes locally and redeploy as needed