113 lines
3.2 KiB
Markdown
113 lines
3.2 KiB
Markdown
---
|
|
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
|