Troubleshooting Guide

This guide covers common issues you might encounter while working with Raspberry Pi Pico, Thonny, and the Number Transmitter project.

Table of Contents

1. Thonny Issues
2. Raspberry Pi Pico Connection Issues
3. Flashing and Firmware Issues
4. WiFi Connection Issues
5. API and Networking Issues
6. Code Execution Issues
7. Web Application Issues
8. Performance Issues

---

Thonny Issues

Thonny Won't Start

Symptoms: - Double-clicking Thonny does nothing - Application crashes on startup - Error messages on launch

Solutions:

Windows:

# Try running as administrator
# Right-click Thonny → Run as administrator

# Check if Python is accessible
python --version

# Reinstall Thonny
# Uninstall via Control Panel, then reinstall from thonny.org

macOS:

# Check if Thonny is in quarantine
xattr -d com.apple.quarantine /Applications/Thonny.app

# Or remove and reinstall
brew uninstall thonny
brew install --cask thonny

# Check permissions
ls -la /Applications/Thonny.app

Linux:

# Run from terminal to see error messages
thonny

# Reinstall dependencies
sudo apt install python3-tk python3-pip
pip3 install --upgrade thonny

# Check file permissions
chmod +x $(which thonny)

---

Thonny Interface Issues

Symptoms: - Missing panels (Shell, Files, Variables) - UI elements not displaying correctly - Buttons not working

Solutions:

1. Reset View to Defaults
2. View → Reset view

3. Restart Thonny

4. Check Theme Settings

5. Tools → Options → Theme

6. Try different themes

7. Clear Configuration

   # Backup and remove Thonny config
   # macOS/Linux
   mv ~/.config/Thonny ~/.config/Thonny.backup
   
   # Windows
   # Delete or rename: %APPDATA%\Thonny
   

---

Raspberry Pi Pico Connection Issues

Pico Not Detected

Symptoms: - No device shown in Thonny - "No device found" error - RPI-RP2 drive doesn't appear

Solutions:

1. Check USB Cable
2. Use a data cable, not charge-only cable
3. Try different USB cable

4. Test cable with another device

5. Try Different USB Port

6. Use USB 2.0 port (avoid USB 3.0 hubs initially)
7. Try direct connection, not through hub

8. Test both front and back ports on desktop

9. Verify BOOTSEL Mode

10. Disconnect Pico
11. Hold BOOTSEL button
12. Connect USB while holding
13. Release after 2 seconds

14. Check for RPI-RP2 drive

15. Check Device Manager (Windows)

    # Open Device Manager
    devmgmt.msc
    
    # Look for:
    # - "USB Serial Device (COMx)" - Normal mode
    # - "RP2 Boot" - BOOTSEL mode
    # - Unknown devices or errors
    

16. Check System Info (macOS)

    # List USB devices
    system_profiler SPUSBDataType | grep -A 10 "Pico"
    
    # Check for serial devices
    ls -la /dev/tty.*
    ls -la /dev/cu.*
    

17. Check Devices (Linux)

    # List USB devices
    lsusb | grep -i "Raspberry\|2e8a"
    
    # Check serial devices
    ls -la /dev/ttyACM*
    ls -la /dev/ttyUSB*
    
    # Check dmesg for connection messages
    dmesg | tail -n 50 | grep -i "usb\|tty"
    

---

Permission Denied (Linux/macOS)

Symptoms: - "Permission denied: '/dev/ttyACM0'" - Can't access serial port - Upload fails with permission error

Solutions:

Linux:

# Add user to dialout group
sudo usermod -a -G dialout $USER
sudo usermod -a -G tty $USER

# Create udev rule
sudo nano /etc/udev/rules.d/99-pico.rules

# Add this line:
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2e8a", MODE:="0666", GROUP="dialout"

# Reload udev
sudo udevadm control --reload-rules
sudo udevadm trigger

# Log out and back in (or reboot)

macOS:

# Check permissions
ls -la /dev/cu.usbmodem*

# If needed, grant access
sudo chmod 666 /dev/cu.usbmodem*

# For permanent fix, add user to dialout equivalent
# (macOS doesn't have dialout, but check group memberships)
groups

---

Flashing and Firmware Issues

Flashing Fails

Symptoms: - "Failed to write firmware" - Process hangs during flash - Pico doesn't reboot after flash

Solutions:

1. Verify BOOTSEL Mode
2. Must be in BOOTSEL mode (RPI-RP2 visible)

3. Try entering BOOTSEL mode again

4. Try Manual Flashing

5. Download .uf2 file from micropython.org
6. Drag and drop to RPI-RP2 drive

7. Wait for automatic reboot

8. Check Disk Space

   # Make sure your computer has space
   df -h
   

9. Re-download Firmware

10. Corrupt download might cause issues

11. Download fresh .uf2 file

12. Try Different Computer

13. Rule out computer-specific issues

---

Wrong Firmware Version

Symptoms: - Imports fail for Pico W features - network module not available - Unexpected module errors

Solutions:

1. Check Current Version

   import sys
   print(sys.version)
   print(sys.implementation)
   

2. Reflash Correct Firmware

3. Pico W requires Pico W firmware (with WiFi support)
4. Regular Pico uses standard firmware
5. Download correct version from micropython.org

---

WiFi Connection Issues

Can't Connect to WiFi

Symptoms: - wlan.isconnected() returns False - Connection timeout - "Failed to connect" errors

Solutions:

1. Verify Pico W Hardware

   # Check if you have Pico W (not regular Pico)
   import network
   wlan = network.WLAN(network.STA_IF)
   # If this fails, you may have regular Pico (no WiFi)
   

2. Check WiFi Credentials

   # Common mistakes:
   # - Wrong SSID (case-sensitive)
   # - Wrong password (case-sensitive)
   # - Special characters in password
   # - Spaces in SSID/password
   
   WIFI_SSID = "YourNetwork"  # Exact name
   WIFI_PASSWORD = "YourPassword"  # Exact password
   

3. Check WiFi Network

4. Pico W supports 2.4 GHz only (not 5 GHz)
5. Check router is broadcasting 2.4 GHz
6. Some enterprise/WPA-Enterprise networks not supported

7. Try personal hotspot for testing

8. Check Signal Strength

9. Move Pico closer to router
10. Remove obstacles between Pico and router

11. Check for interference

12. Debug Connection

    import network
    import time
    
    wlan = network.WLAN(network.STA_IF)
    wlan.active(True)
    
    print("Connecting...")
    wlan.connect("SSID", "PASSWORD")
    
    # Wait and show status
    timeout = 10
    while timeout > 0:
        if wlan.isconnected():
            print("Connected!")
            print(wlan.ifconfig())
            break
        print(f"Status: {wlan.status()}")
        time.sleep(1)
        timeout -= 1
    
    if not wlan.isconnected():
        print("Failed to connect")
        print(f"Final status: {wlan.status()}")
    

13. Status Code Reference

    # wlan.status() return values:
    # 0 = STAT_IDLE -- no connection and no activity
    # 1 = STAT_CONNECTING -- connecting in progress
    # 2 = STAT_WRONG_PASSWORD -- failed due to incorrect password
    # 3 = STAT_NO_AP_FOUND -- failed because no access point replied
    # 4 = STAT_CONNECT_FAIL -- failed due to other problems
    # 5 = STAT_GOT_IP -- connection successful
    

---

Weak WiFi Signal

Symptoms: - Intermittent connection - Slow data transfer - Frequent disconnections

Solutions:

1. Check RSSI

   rssi = wlan.status('rssi')
   print(f"Signal strength: {rssi} dBm")
   
   # Good: -30 to -60 dBm
   # Weak: -60 to -80 dBm
   # Very weak: below -80 dBm
   

2. Improve Signal

3. Move Pico closer to router
4. Use external antenna (if supported)
5. Remove metal objects nearby
6. Change WiFi channel on router

---

API and Networking Issues

API Not Accessible

Symptoms: - "Connection refused" - "No route to host" - Timeout errors

Solutions:

1. Check API Server Running

   # On API server machine
   curl http://localhost:5001/api/status
   
   # Should return JSON response
   

2. Check Firewall

   # macOS - allow Python/Flask
   # Go to System Preferences → Security → Firewall
   
   # Linux - allow port
   sudo ufw allow 5001
   
   # Windows - allow in Windows Defender Firewall
   

3. Check Network Connectivity

   # On Pico, ping test
   import urequests
   
   try:
       response = urequests.get("http://example.com", timeout=5)
       print("Internet works:", response.status_code)
   except Exception as e:
       print("No internet:", e)
   

4. Verify Same Network

5. Pico and API server must be on same network

6. Check IP addresses in same subnet

   # On Pico
   print(wlan.ifconfig()[0])  # Pico IP
   
   # On server
   # macOS/Linux
   ifconfig
   # Windows
   ipconfig
   

7. Use Correct IP Address

   # Don't use localhost on Pico
   # Use actual IP address of server
   API_BASE_URL = "http://192.168.1.100:5001"  # Replace with actual IP
   

---

CORS Errors (Web Application)

Symptoms: - Browser console shows CORS errors - "Access-Control-Allow-Origin" errors - API works in curl but not browser

Solutions:

1. Enable CORS in Flask

   from flask_cors import CORS
   
   app = Flask(__name__)
   CORS(app)  # Enable CORS for all routes
   

2. Specific Origin

   CORS(app, resources={r"/api/*": {"origins": "*"}})
   

---

Code Execution Issues

ImportError: No Module

Symptoms: - ImportError: no module named 'requests' - ImportError: no module named 'flask'

Solutions:

1. MicroPython vs Python
2. MicroPython has limited libraries
3. Use urequests instead of requests
4. Some modules not available

# MicroPython (on Pico)
import urequests  # Not 'requests'
import ujson      # Not 'json'

# Regular Python (on computer)
import requests
import json

1. Install Missing Packages (Computer)

   # Activate venv first
   source .venv/bin/activate  # macOS/Linux
   # or
   .venv\Scripts\activate     # Windows
   
   # Install package
   uv add package-name
   # or
   pip install package-name
   

---

Memory Errors on Pico

Symptoms: - MemoryError - Pico crashes or resets - Code runs once then fails

Solutions:

1. Check Memory Usage

   import gc
   gc.collect()
   print(f"Free memory: {gc.mem_free()} bytes")
   print(f"Allocated: {gc.mem_alloc()} bytes")
   

2. Optimize Code

   # Call garbage collector regularly
   import gc
   gc.collect()
   
   # Use generators instead of lists
   # Delete large variables when done
   del large_variable
   gc.collect()
   
   # Avoid string concatenation in loops
   # Use list and join instead
   

3. Simplify Code

4. Remove debug print statements
5. Use shorter variable names
6. Split large files into modules

---

Infinite Loops/Hangs

Symptoms: - Code doesn't respond - Can't stop program - Thonny frozen

Solutions:

1. Interrupt with Ctrl+C
2. In Thonny Shell, press Ctrl+C

3. May need to press multiple times

4. Disconnect/Reconnect

5. Unplug Pico USB
6. Wait 2 seconds

7. Reconnect

8. Reset Pico

9. Press RUN button on Pico (if available)

10. Or disconnect power

11. Add Safety Timeouts

    import time
    
    start_time = time.time()
    while True:
        # Your code here
    
        # Safety timeout
        if time.time() - start_time > 60:  # 60 seconds
            print("Timeout!")
            break
    

---

Web Application Issues

Flask App Won't Start

Symptoms: - "Address already in use" - "Permission denied" - Import errors

Solutions:

1. Port Already in Use

   # Find process using port 5000
   # macOS/Linux
   lsof -i :5000
   sudo kill -9 <PID>
   
   # Windows
   netstat -ano | findstr :5000
   taskkill /PID <PID> /F
   
   # Or use different port
   app.run(port=5001)
   

2. Permission Denied (Port < 1024)

   # Use port >= 1024
   app.run(port=5000)  # Good
   
   # Or run with sudo (not recommended)
   sudo python app.py
   

3. Module Import Errors

   # Make sure venv is activated
   source .venv/bin/activate
   
   # Install dependencies
   uv add flask flask-cors
   

---

Page Not Loading

Symptoms: - "This site can't be reached" - "Connection refused" - Blank page

Solutions:

1. Check Flask is Running

   # Should see:
   # * Running on http://0.0.0.0:5000
   # * Running on http://127.0.0.1:5000
   

2. Use Correct URL

   # Local testing
   http://localhost:5000
   http://127.0.0.1:5000
   
   # From other devices
   http://<your-ip>:5000
   # e.g., http://192.168.1.100:5000
   

3. Check Browser Console

4. Press F12 to open developer tools
5. Check Console tab for JavaScript errors
6. Check Network tab for failed requests

---

Performance Issues

Slow Response Times

Symptoms: - API responses take too long - Web page loads slowly - Pico responses delayed

Solutions:

1. Check Network Latency

   # Ping test
   ping <pico-ip>
   ping <server-ip>
   

2. Optimize API Queries

3. Reduce query frequency
4. Cache responses

5. Use smaller data payloads

6. Reduce Print Statements

   # Remove or reduce print() calls in production
   # Printing to serial is slow
   

---

High CPU Usage

Symptoms: - Computer fan running high - Flask using lots of CPU - System slowdown

Solutions:

1. Check for Infinite Loops
2. Review code for tight loops

3. Add delays in loops

4. Disable Debug Mode

   # Production
   app.run(debug=False)
   
   # Development only
   app.run(debug=True)
   

5. Limit Concurrent Requests

6. Flask development server is single-threaded
7. For production, use gunicorn or similar

---

Getting Additional Help

If your issue isn't covered here:

1. Check Project Documentation
2. Read the relevant guide

3. Review example code

4. Community Resources

5. Raspberry Pi Forums
6. MicroPython Forum

7. Thonny Issues

8. Debug Systematically

9. Isolate the problem
10. Test components individually
11. Add debug print statements

12. Check logs and error messages

13. Report Issues

14. Include error messages
15. Specify OS and versions
16. Describe steps to reproduce
17. Include minimal code example

---

Quick Reference: Common Commands

Thonny Debug Commands

# Check MicroPython version
import sys
print(sys.version)

# Check memory
import gc
gc.collect()
print(f"Free: {gc.mem_free()}")

# List files
import os
print(os.listdir())

# Check WiFi (Pico W)
import network
wlan = network.WLAN(network.STA_IF)
print(f"Connected: {wlan.isconnected()}")
if wlan.isconnected():
    print(f"IP: {wlan.ifconfig()[0]}")

System Commands

# Check USB devices (Linux)
lsusb

# Check serial ports (Linux)
ls /dev/ttyACM*

# Check serial ports (macOS)
ls /dev/cu.*

# Check COM ports (Windows)
mode

# Test API
curl http://localhost:5001/api/status

---

Need more help? See the Installation Guide or Flashing Guide.