Initial commit

2025-11-30 08:28:30 +08:00
commit 1f575f61f9
16 changed files with 6086 additions and 0 deletions
--- a/commands/deploy-to-badge.md
+++ b/commands/deploy-to-badge.md
@@ -0,0 +1,112 @@
+---
+description: Deploy your app to the badge via USB Mass Storage Mode
+---
+
+# 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:**
+```bash
+cp -r {app_name} /Volumes/BADGER/apps/
+```
+
+**Windows (PowerShell):**
+```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:**
+```bash
+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
+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