zhongwei/gh-johnlindquist-badger-2350-plugin-badger-2350-dev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:28:30 +08:00
commit 1f575f61f9
16 changed files with 6086 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
commands/badge-quickstart.md Normal file
View File

@@ -0,0 +1,122 @@
---
description: Verify your development environment is ready for badge development
---
# Badge Quick Start Checklist
Run through a complete environment verification checklist to ensure everything is set up correctly for Badger 2350 development.
## What to Check
Run verification commands and report status for each step:
### 1. Python Installation
```bash
python3 --version
```
**Expected**: Python 3.8.0 or higher
**If missing**: Provide installation instructions for user's OS:
- macOS: `brew install python3`
- Linux: `sudo apt install python3 python3-pip python3-venv`
- Windows: Download from https://python.org/downloads/
### 2. Virtual Environment
Check if user is in a virtual environment:
```bash
echo $VIRTUAL_ENV
```
**If not active**:
```bash
# Create virtual environment
python3 -m venv venv
# Activate it
source venv/bin/activate # macOS/Linux
venv\Scripts\Activate.ps1 # Windows PowerShell
```
### 3. mpremote Installation
```bash
mpremote --version
```
**If missing**:
```bash
pip install mpremote
```
### 4. Badge Connection
```bash
mpremote exec "print('Badge connected!')"
```
**Expected**: "Badge connected!" printed
**If fails**:
- Check USB-C cable (must be data cable, not charge-only)
- Try different USB port
- Check badge is powered on
- On Linux: May need to add user to `dialout` group
### 5. badgeware Module
```bash
mpremote exec "from badgeware import screen, brushes, shapes, io; print('✓ badgeware loaded'); print('✓ Display: 160x120'); print('✓ All OK')"
```
**Expected**: All ✓ marks shown
**If fails**:
- Badge may need firmware update
- Check USB connection is stable
- Try pressing RESET button once
## Results Summary
After running all checks, provide a summary:
✅ **All checks passed!** You're ready to start developing.
Or identify what needs fixing:
⚠️ **Issues found**:
- [List any failed checks]
- [Provide specific fix commands]
## Next Steps
If all checks pass, suggest:
1. **Create your first app**:
```
/create-badge-app my_first_app
```
2. **Browse example apps**:
Check `examples/hello_world` and `examples/meditation_timer` in this plugin
3. **Read the API reference**:
```
/badgeware-api
```
4. **Get detailed help**: Use the `badger-quickstart` skill for step-by-step guide
## Troubleshooting
If verification fails, run:
```
/troubleshoot <issue>
```
For comprehensive diagnostics, use the `badger-diagnostics` skill.
## Detailed Setup Guides
For complete setup instructions, refer to these skills:
- **badger-quickstart**: Complete beginner guide (30-45 min)
- **python-setup**: Detailed Python environment setup
- **badger-2350-dev**: Development toolchain reference
You can invoke skills by asking Claude to use them when you need more detailed help.

176
commands/badgeware-api.md Normal file
View File

@@ -0,0 +1,176 @@
---
description: Quick reference for the badgeware API with code examples
---
# Badgeware API Reference
Provide a quick reference for the badgeware module API based on the user's search term or show overview if no term provided.
## Display & Graphics
### Screen Drawing
```python
from badgeware import screen, brushes, shapes
# Set brush color (RGB 0-255)
screen.brush = brushes.color(r, g, b)
screen.brush = brushes.color(r, g, b, alpha) # With transparency
# Clear screen
screen.clear()
# Draw text
screen.text("Hello", x, y)
# Load and use custom fonts
screen.font = PixelFont.load("/system/assets/fonts/ark.ppf")
```
### Shapes
```python
from badgeware import shapes
# Draw shapes
screen.draw(shapes.rectangle(x, y, width, height))
screen.draw(shapes.circle(x, y, radius))
screen.draw(shapes.line(x1, y1, x2, y2))
screen.draw(shapes.rounded_rectangle(x, y, w, h, radius))
```
### Images & Sprites
```python
from badgeware import Image
# Load and display images
img = Image.load("sprite.png")
screen.blit(img, x, y)
screen.scale_blit(img, x, y, width, height)
# Enable antialiasing for smooth edges
screen.antialias = Image.X4
```
## Button Handling
### Button Constants
```python
from badgeware import io
# Available buttons
io.BUTTON_A
io.BUTTON_B
io.BUTTON_C
io.BUTTON_UP
io.BUTTON_DOWN
io.BUTTON_HOME # Exits to MonaOS menu
```
### Button States
```python
def update():
# Just pressed this frame
if io.BUTTON_A in io.pressed:
print("A pressed")
# Just released this frame
if io.BUTTON_B in io.released:
print("B released")
# Currently held down
if io.BUTTON_C in io.held:
print("C is held")
# State changed this frame
if io.BUTTON_UP in io.changed:
print("UP state changed")
```
## Animation & Timing
### Frame Counter
```python
from badgeware import io
import math
frame = 0
def update():
global frame
# Use frame counter for animations
radius = 10 + int(math.sin(frame / 20) * 5)
# Breathing animation (4-second cycle at 30fps)
phase = ((frame % 120) / 120.0) * 2 * math.pi
scale = 20 + int(math.sin(phase) * 15)
frame += 1
```
### Timing
```python
import time
# Track elapsed time
start_time = time.time()
elapsed = time.time() - start_time
# Sleep (use sparingly, blocks update loop)
time.sleep(0.1)
```
## Transformations
### Matrix Transforms
```python
from badgeware import Matrix
# Create and apply transformations
rect = shapes.rectangle(-1, -1, 2, 2)
rect.transform = Matrix() \
.translate(80, 60) \
.scale(20, 20) \
.rotate(io.ticks / 100) # Animated rotation
screen.draw(rect)
```
## Persistent Storage
### File Operations
```python
import json
# Write app data (writable partition)
with open("/storage/myapp_data.json", "w") as f:
json.dump({"score": 100}, f)
# Read app data
with open("/storage/myapp_data.json", "r") as f:
data = json.load(f)
```
## Display Specifications
- **Resolution**: 160x120 framebuffer (pixel-doubled to 320x240 physical display)
- **Colors**: Full RGB (0-255 per channel)
- **Fonts**: 30 licensed pixel fonts in `/system/assets/fonts/`
- **Automatic Updates**: Display refreshes after each `update()` call
## Important Notes
⚠️ **This badge uses `badgeware` module, NOT `badger2040`!** The APIs are different.
⚠️ **Frame Rate**: MonaOS calls `update()` ~30 times per second. Keep operations fast.
⚠️ **Screen Coordinates**: Origin (0,0) is top-left corner.
## Full Documentation
For complete API documentation, see:
- https://github.com/badger/home/blob/main/badgerware/Image.md
- https://github.com/badger/home/blob/main/badgerware/shapes.md
- https://github.com/badger/home/blob/main/badgerware/brushes.md
- https://github.com/badger/home/blob/main/PixelFont.md
- https://github.com/badger/home/blob/main/Matrix.md
- https://github.com/badger/home/blob/main/badgerware/io.md

58
commands/create-badge-app.md Normal file
View File

@@ -0,0 +1,58 @@
---
description: Create a new MonaOS app with proper structure, template code, and icon
---
# Create Badge App
Create a complete MonaOS application structure with all required files.
## What to do
1. Ask the user for the app name if not provided
2. Validate the app name (lowercase, no spaces, alphanumeric with underscores/hyphens)
3. Create the following directory structure:
```
{app_name}/
├── __init__.py # Main app file from template
├── icon.png # 24x24 icon
└── assets/ # Optional assets directory
```
4. Use the app template from `badger-marketplace/badger-2350-dev/templates/app_template.py`
5. Replace `{{APP_NAME}}` placeholders with the actual app name
6. Copy the icon template from `badger-marketplace/badger-2350-dev/templates/icon_template.png`
7. Create an empty `assets/` directory
## After creation
Tell the user:
**Next Steps:**
1. **Test your app locally:**
```bash
mpremote run {app_name}/__init__.py
```
2. **Edit the code:**
- Open `{app_name}/__init__.py` in your editor
- Replace TODO comments with your app logic
- Add button handlers, animations, and content
3. **Deploy to badge when ready:**
```bash
/deploy-to-badge {app_name}
```
4. **Customize the icon:**
- Edit `{app_name}/icon.png` (must be 24x24 pixels)
- Use any image editor or pixel art tool
Your app structure is ready! The template includes examples of:
- Button handling for all 5 buttons
- Simple animation with frame counter
- Text and shape drawing
- State management pattern
Check the `examples/` directory in this plugin for working examples like `hello_world` and `meditation_timer`.

112
commands/deploy-to-badge.md Normal file
View File

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

216
commands/troubleshoot.md Normal file
View File

@@ -0,0 +1,216 @@
---
description: Diagnostic guide for common Badge 2350 development issues
---
# Troubleshoot Badge Issues
Help diagnose and fix common Badger 2350 development problems.
## Common Issues
### Badge Not Detected
**Symptoms**: `mpremote` can't find badge, no /dev/tty.usbmodem* device
**Diagnostics**:
```bash
# macOS/Linux: Check for USB serial devices
ls /dev/tty.usbmodem* /dev/ttyACM*
# Windows: Check COM ports
[System.IO.Ports.SerialPort]::getportnames()
```
**Solutions**:
1. **Check USB cable**: Must be data cable, not charge-only
2. **Try different USB port**: Some ports may not support data
3. **Press RESET button**: Reconnect badge to computer
4. **Check drivers** (Windows): May need CH340/CP2102 drivers
5. **Linux permissions**: Add user to `dialout` group:
```bash
sudo usermod -a -G dialout $USER
# Log out and log back in
```
### App Not Appearing in MonaOS Menu
**Symptoms**: Deployed app doesn't show up in badge menu
**Diagnostics**:
1. **Check app was deployed via Mass Storage Mode** (not mpremote)
2. **Verify file structure**:
```
/Volumes/BADGER/apps/my_app/
├── __init__.py
└── icon.png
```
3. **Check you have 7+ apps** (menu shows max 6 by default)
**Solutions**:
1. **Redeploy using Mass Storage Mode**:
- Press RESET twice
- Copy entire app folder to `/Volumes/BADGER/apps/`
- Eject drive, press RESET once
2. **Verify required files**:
- `__init__.py` must exist
- `icon.png` must be 24x24 pixels
- Folder must be in `apps/` directory
3. **Install paginated menu** if you have 7+ apps:
- Enter Mass Storage Mode
- Download: https://raw.githubusercontent.com/badger/home/refs/heads/main/badge/apps/menu/__init__.py
- Replace `/Volumes/BADGER/apps/menu/__init__.py`
### Memory Errors
**Symptoms**: `MemoryError`, app crashes, out of memory
**Diagnostics**:
```python
# Check available memory in REPL
mpremote exec "import gc; gc.collect(); print('Free:', gc.mem_free())"
```
**Solutions**:
1. **Collect garbage frequently**:
```python
import gc
gc.collect() # Call in your update() function periodically
```
2. **Load resources once in `init()`**, not in `update()`
3. **Delete unused variables**:
```python
del large_variable
gc.collect()
```
4. **Use smaller images**: Reduce sprite sizes, compress PNGs
5. **Avoid large lists/dictionaries**: Keep data structures minimal
### Module Import Errors
**Symptoms**: `ImportError: no module named 'badgeware'`
**Diagnostics**:
```bash
# Test badgeware import
mpremote exec "import badgeware; print('OK')"
```
**Solutions**:
1. **Verify badge firmware**: May need MonaOS firmware update
2. **Check badge is genuine Universe 2025 Badge** (not standard Tufty 2040)
3. **Flash latest firmware**:
- Download `.uf2` from https://github.com/badger/home/releases
- Hold HOME button, press RESET, release HOME
- Badge appears as RP2350 drive
- Drag `.uf2` file to drive
### Display Not Updating
**Symptoms**: Screen frozen, changes don't appear
**Diagnostics**:
1. Check `update()` function is being called
2. Verify no infinite loops in code
3. Check for exceptions that halt execution
**Solutions**:
1. **Ensure `update()` function exists**:
```python
def update():
# Your code here
pass
```
2. **Avoid blocking operations**:
- Don't use `while True:` loops
- Don't use `time.sleep()` in update loop
- Keep update() fast (< 33ms for 30fps)
3. **Check for errors in REPL**:
```bash
mpremote
# Watch for error messages
```
### Button Not Responding
**Symptoms**: Button presses don't trigger actions
**Diagnostics**:
```python
# Test button in REPL
mpremote exec "
from badgeware import io
while True:
io.poll()
if io.BUTTON_A in io.pressed:
print('A pressed')
break
"
```
**Solutions**:
1. **Use correct button state check**:
```python
if io.BUTTON_A in io.pressed: # Just pressed (correct)
if io.BUTTON_A == io.pressed: # WRONG!
```
2. **Call io.poll() if needed** (MonaOS usually handles this)
3. **Check button isn't physically stuck**
### Network Connection Failures
**Symptoms**: WiFi won't connect, timeout errors
**Diagnostics**:
```python
import network
wlan = network.WLAN(network.STA_IF)
wlan.active(True)
print('Networks:', wlan.scan())
```
**Solutions**:
1. **Check WiFi credentials** are correct
2. **Verify network is 2.4GHz** (badge doesn't support 5GHz)
3. **Check WiFi is enabled** on badge
4. **Increase timeout** when connecting:
```python
import time
wlan.connect('SSID', 'password')
timeout = 10
while not wlan.isconnected() and timeout > 0:
time.sleep(1)
timeout -= 1
```
## Get More Help
### Use Skills for Detailed Guides
- **badger-diagnostics**: Comprehensive system diagnostics
- **badger-2350-dev**: Development toolchain reference
- **badger-deploy**: Deployment troubleshooting
- **badger-hardware**: GPIO and hardware issues
### Check Official Resources
- Official docs: https://badger.github.io/
- GitHub source: https://github.com/badger/home
- API reference: https://github.com/badger/home/blob/main/badgerware/
### Run Environment Check
```
/badge-quickstart
```
This will verify your entire development environment and identify configuration issues.