Initial commit

2025-11-30 08:28:30 +08:00
commit 1f575f61f9
16 changed files with 6086 additions and 0 deletions
--- a/commands/troubleshoot.md
+++ b/commands/troubleshoot.md
@@ -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.