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

description

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:

# 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:

   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:

# Check available memory in REPL
mpremote exec "import gc; gc.collect(); print('Free:', gc.mem_free())"

Solutions:

1. Collect garbage frequently:

   import gc
   gc.collect()  # Call in your update() function periodically
   

2. Load resources once in init(), not in update()

3. Delete unused variables:

   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:

# 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:

   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:

   mpremote
   # Watch for error messages
   

Button Not Responding

Symptoms: Button presses don't trigger actions

Diagnostics:

# 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:

   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:

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:

   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.