Connection Troubleshooting

Documentation in Progress

This documentation is currently being developed based on common user issues and support requests.

Status: 📝 Documentation in progress based on real-world testing
Expected completion: After hardware validation phase

Coming Soon

This page will provide comprehensive troubleshooting guidance for connection issues, including:

• Common Connection Errors: Device not found, permission denied, timeout issues
• Platform-Specific Solutions: Windows, Linux, and macOS troubleshooting steps
• Driver Issues: USB-to-serial driver problems and solutions
• Port Detection: Finding and identifying correct serial ports
• Permission Problems: Linux/macOS permission and group membership issues
• Hardware Debugging: Physical connection and cable problems
• Firmware Issues: Corrupted firmware recovery procedures

Common Issues Preview

Device Not Found

// Error: No devices discovered
var devices = await Device.DiscoverDevicesAsync();
if (devices.Length == 0)
{
    // Troubleshooting steps will be provided here
    Console.WriteLine("No MicroPython devices found");
}

Connection Timeout

try
{
    var device = Device.FromConnectionString("serial:COM3");
    await device.ConnectAsync(); // May timeout
}
catch (DeviceConnectionException ex)
{
    // Detailed timeout troubleshooting steps coming
    Console.WriteLine($"Connection failed: {ex.Message}");
}

Permission Denied (Linux/macOS)

# Common error on Linux
# SerialException: [Errno 13] Permission denied: '/dev/ttyACM0'

# Solution will include adding user to dialout group
# sudo usermod -a -G dialout $USER

Quick Diagnostic Tools

// Example diagnostic utilities coming soon
public static class ConnectionDiagnostics
{
    public static async Task RunDiagnosticsAsync()
    {
        Console.WriteLine("=== Belay.NET Connection Diagnostics ===");
        
        // Check available ports
        var ports = SerialPort.GetPortNames();
        Console.WriteLine($"Available serial ports: {string.Join(", ", ports)}");
        
        // Attempt device discovery
        var devices = await Device.DiscoverDevicesAsync();
        Console.WriteLine($"Discovered MicroPython devices: {devices.Length}");
        
        // Test each discovered device
        foreach (var device in devices)
        {
            await TestDeviceConnection(device);
        }
    }
    
    private static async Task TestDeviceConnection(DeviceInfo deviceInfo)
    {
        try
        {
            using var device = Device.FromConnectionString(deviceInfo.ConnectionString);
            await device.ConnectAsync();
            
            var response = await device.ExecuteAsync("print('Hello from device')");
            Console.WriteLine($"✅ {deviceInfo.Port}: Connection successful");
            Console.WriteLine($"   Response: {response.Trim()}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"❌ {deviceInfo.Port}: {ex.Message}");
        }
    }
}

Platform-Specific Sections

Windows Issues

• Driver installation (CP210x, CH340, FTDI)
• Device Manager troubleshooting
• COM port conflicts and resolution
• Windows Defender/antivirus interference

Linux Issues

• User permissions and group membership (dialout, tty)
• udev rules for device recognition
• ModemManager conflicts with serial devices
• systemd service conflicts

macOS Issues

• Driver installation for USB-to-serial chips
• System Integrity Protection (SIP) considerations
• Port naming conventions (/dev/cu.* vs /dev/tty.*)
• Homebrew driver installation

Hardware-Specific Issues

ESP32 Boards

• Boot mode selection (normal vs download mode)
• Power supply problems
• CH340 vs CP2102 driver differences

Raspberry Pi Pico

• BOOTSEL mode recognition
• Firmware corruption recovery
• Mass storage vs serial mode switching

PyBoard

• DFU mode entry and exit
• USB cable quality issues
• Power LED indicators

Error Code Reference

Error Code	Description	Common Causes
DEVICE_NOT_FOUND	No devices discovered	Driver, cable, or firmware issues
CONNECTION_TIMEOUT	Device connection timeout	Baud rate, permissions, or hardware
PERMISSION_DENIED	Access denied to serial port	User permissions (Linux/macOS)
PORT_IN_USE	Serial port already in use	Another application using port
INVALID_RESPONSE	Unexpected response from device	Firmware or protocol issues

Related Documentation

• Connection Types - Detailed connection setup
• Hardware Compatibility - Supported devices and known issues
• Getting Started - Initial setup verification
• Device Communication - Communication troubleshooting

Need immediate help? Check our GitHub Discussions for community troubleshooting assistance, or create a new issue with your specific error message and platform details.