badger-diagnostics

What this skill does

# Badger 2350 Diagnostics and Troubleshooting

Comprehensive diagnostics and troubleshooting tools for verifying your Badger 2350 setup, checking installations, and resolving common issues.

## ⚠️ When to Use This Skill

**Use this skill FIRST** in these situations:
1. **Starting a new session** - Verify everything works before coding
2. **After setup** - Confirm installation completed correctly
3. **Before debugging** - Rule out environment issues
4. **When errors occur** - Diagnose the root cause
5. **After firmware updates** - Verify everything still works

**Best Practice**: Run diagnostics at the start of EVERY development session. It takes 30 seconds and prevents hours of debugging.

## Quick Verification Command

**Run this FIRST every session** (doesn't require any files to exist):

### Level 1: Basic Connection Test
```bash
# Simplest test - just verify badge responds
mpremote exec "print('Badge connected!')"
# Should print: Badge connected!

# If this fails, badge isn't connected or mpremote not installed
```

### Level 2: Full Verification
```bash
# Complete verification (auto-detects port on macOS/Linux)
mpremote exec "import sys, gc; from badgeware import screen, brushes, shapes, io; print('=== VERIFICATION ==='); print('✓ MicroPython:', sys.version[:30]); print('✓ Memory:', gc.mem_free(), 'bytes'); print('✓ badgeware: loaded'); print('✓ Display: 160x120'); print('=== ALL OK ===')"
```

**Expected output**: All checks with ✓ marks and no errors.

**With explicit port** (if auto-detect fails):
```bash
mpremote connect /dev/cu.usbmodem1101 exec "from badgeware import screen; print('✓ Badge OK')"
# Replace /dev/cu.usbmodem1101 with your port
```

**If this fails**: Continue with detailed diagnostics below.

## Quick System Check

Run this complete system diagnostic in REPL:

```python
# diagnostic.py - Complete system check
import sys
import gc
import os
from machine import freq, unique_id
import ubinascii

def system_info():
    """Display complete system information"""
    print("=" * 50)
    print("BADGER 2350 SYSTEM DIAGNOSTICS")
    print("=" * 50)

    # MicroPython version
    print(f"\n[MicroPython]")
    print(f"  Version: {sys.version}")
    print(f"  Implementation: {sys.implementation}")
    print(f"  Platform: {sys.platform}")

    # Hardware info
    print(f"\n[Hardware]")
    print(f"  CPU Frequency: {freq():,} Hz ({freq() / 1_000_000:.0f} MHz)")
    uid = ubinascii.hexlify(unique_id()).decode()
    print(f"  Unique ID: {uid}")

    # Memory
    gc.collect()
    print(f"\n[Memory]")
    print(f"  Free: {gc.mem_free():,} bytes ({gc.mem_free() / 1024:.1f} KB)")
    print(f"  Allocated: {gc.mem_alloc():,} bytes ({gc.mem_alloc() / 1024:.1f} KB)")
    total = gc.mem_free() + gc.mem_alloc()
    print(f"  Total: {total:,} bytes ({total / 1024:.1f} KB)")

    # File system
    print(f"\n[File System]")
    try:
        stat = os.statvfs('/')
        block_size = stat[0]
        total_blocks = stat[2]
        free_blocks = stat[3]
        total_bytes = block_size * total_blocks
        free_bytes = block_size * free_blocks
        used_bytes = total_bytes - free_bytes

        print(f"  Total: {total_bytes:,} bytes ({total_bytes / 1024 / 1024:.2f} MB)")
        print(f"  Used: {used_bytes:,} bytes ({used_bytes / 1024 / 1024:.2f} MB)")
        print(f"  Free: {free_bytes:,} bytes ({free_bytes / 1024 / 1024:.2f} MB)")
    except:
        print("  Unable to check filesystem")

    # Module path
    print(f"\n[Module Search Paths]")
    for path in sys.path:
        print(f"  {path}")

    print("\n" + "=" * 50)

# Run diagnostic
system_info()
```

## Firmware Version Check

### Check MicroPython Firmware

```python
import sys

# Full version info
print(sys.version)
# Example: 3.4.0; MicroPython v1.20.0 on 2023-04-26

# Implementation details
print(sys.implementation)
# (name='micropython', version=(1, 20, 0), _machine='Raspberry Pi Pico W with RP2040', _mpy=6182)

# Extract version number
version = sys.implementation.version
print(f"MicroPython {version[0]}.{version[1]}.{version[2]}")
```

### Check Badger Library Version

```python
import badger2040

# Check if version attribute exists
if hasattr(badger2040, '__version__'):
    print(f"Badger library version: {badger2040.__version__}")
else:
    print("Badger library version not available")

# Check file location
print(f"Badger library: {badger2040.__file__}")
```

### Recommended Firmware Versions

Verify you have compatible firmware:

```python
def check_firmware_compatibility():
    """Check if firmware is compatible with Badger 2350"""
    version = sys.implementation.version

    if version[0] >= 1 and version[1] >= 20:
        print("✓ MicroPython version is compatible")
        return True
    else:
        print("✗ MicroPython version may be outdated")
        print("  Recommended: MicroPython 1.20+")
        print(f"  Current: {version[0]}.{version[1]}.{version[2]}")
        return False

check_firmware_compatibility()
```

## Module Verification

### Check Core Modules

```python
def verify_core_modules():
    """Verify essential modules are available"""
    required_modules = {
        'badger2040': 'Badger display library',
        'machine': 'Hardware interface',
        'time': 'Time functions',
        'gc': 'Garbage collection',
        'sys': 'System functions',
        'os': 'Operating system interface'
    }

    optional_modules = {
        'network': 'WiFi support',
        'urequests': 'HTTP client',
        'ujson': 'JSON parsing',
        'ubinascii': 'Binary/ASCII conversion'
    }

    print("Checking required modules...")
    all_ok = True
    for module, description in required_modules.items():
        try:
            __import__(module)
            print(f"  ✓ {module:15s} - {description}")
        except ImportError:
            print(f"  ✗ {module:15s} - MISSING - {description}")
            all_ok = False

    print("\nChecking optional modules...")
    for module, description in optional_modules.items():
        try:
            __import__(module)
            print(f"  ✓ {module:15s} - {description}")
        except ImportError:
            print(f"  ○ {module:15s} - Not installed - {description}")

    return all_ok

verify_core_modules()
```

### List All Installed Packages

```python
import os

def list_installed_packages():
    """List all installed packages in /lib"""
    print("Installed packages:")

    # Check /lib directory
    try:
        lib_contents = os.listdir('/lib')
        if lib_contents:
            for item in sorted(lib_contents):
                # Try to get more info
                path = f'/lib/{item}'
                try:
                    stat = os.stat(path)
                    size = stat[6]  # File size
                    print(f"  {item:30s} {size:8,} bytes")
                except:
                    print(f"  {item}")
        else:
            print("  (no packages in /lib)")
    except OSError:
        print("  /lib directory not found")

    # Check root directory for .py files
    print("\nRoot directory modules:")
    root_contents = os.listdir('/')
    py_files = [f for f in root_contents if f.endswith('.py')]
    for f in sorted(py_files):
        stat = os.stat(f)
        size = stat[6]
        print(f"  {f:30s} {size:8,} bytes")

list_installed_packages()
```

## Hardware Diagnostics

### Display Test

```python
import badger2040

def test_display():
    """Test display functionality"""
    print("Testing display...")

    badge = badger2040.Badger2040()

    # Test 1: Clear screen
    badge.set_pen(15)
    badge.clear()
    badge.update()
    print("  ✓ Clear screen")

    # Test 2: Draw text
    badge.set_pen(0)
    badge.text("Display Test", 10, 10, scale=2)
    badge.update()
    print("  ✓ Draw text")

    # Test 3: Draw shapes
    badge.line(10, 40, 100, 40)
    badge.rectangle(10, 50, 50, 30)
    badge.update()
    print("  ✓ Draw shapes")

    print("Display test complete!")

test_display()
```

##