gh-johnlindquist-badger-2350-plugin-badger-2350-dev/commands/troubleshoot.md

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