Skip to content

Network Issues

Troubleshooting network connectivity problems on your PicoCalc.

Quick Diagnostics

Start with these basic checks:

# Check network interfaces
ip addr show

# Check if interfaces are up
ip link show

# Test basic connectivity (if you know a working IP)
ping 8.8.8.8

# Test DNS resolution
ping google.com

# Check routing
ip route show

USB Networking Issues

For detailed USB networking troubleshooting, see the USB Networking Guide.

Quick USB Network Checks

# Check if USB gadget service is running
systemctl status usb-gadget-network

# Check usb0 interface
ip addr show usb0

# Restart USB gadget
sudo systemctl restart usb-gadget-network

Common USB networking issues:

  • Device not appearing on host: Check USB cable (must be data cable), verify service is running
  • Cannot ping device: Verify IP configuration on both host and device
  • No DHCP: Check that host has internet sharing enabled
  • Module errors: Verify kernel modules are loaded with lsmod | grep -E 'libcomposite|rndis|ecm'

See USB Networking Troubleshooting for detailed solutions.

WiFi Not Working

WiFi Interface Not Found

Check if the WiFi interface exists:

# List network interfaces
ip link show

# Look for WiFi adapter
iw dev

If no WiFi interface is found:

  1. Check if the module is loaded:
lsmod | grep -E 'rtl|aic'
  1. Load the WiFi driver module:
sudo modprobe <driver_name>
  1. Check system logs:
dmesg | grep -i wifi
journalctl -u systemd-networkd -b

Cannot Connect to Network

Using iwctl:

# Enter iwctl interactive mode
iwctl

# Scan for networks
station wlan0 scan

# List available networks
station wlan0 get-networks

# Connect to network
station wlan0 connect "NetworkName"

If connection fails:

  1. Check signal strength: Move closer to the access point
  2. Verify password: Ensure correct passphrase
  3. Check network mode: Some routers may need 2.4GHz mode enabled
  4. Check logs:
journalctl -u iwd -f

WiFi Disconnects Frequently

Common causes:

  1. Power management: Disable WiFi power saving:
sudo iw dev wlan0 set power_save off

  1. Weak signal: Move closer to access point or add external antenna

  2. Channel interference: Try changing router channel (especially on 2.4GHz)

  3. Driver issues: Check for kernel messages:

dmesg | grep wlan0

WiFi Adapter in Invalid State

Symptoms:

  • Access points don't appear in WiFi scan results
  • iwctl station wlan0 scan returns empty list
  • WiFi USB adapter doesn't appear in lsusb output
  • Network interface exists but doesn't respond to commands

Cause: The WiFi adapter or module enters an invalid state, preventing normal operation. This can happen after power cycling, resets, or other transient hardware issues.

Solutions:

Option 1: Complete power cycle (most reliable)

A simple reboot (reboot) or sudo systemctl restart iwd often does not work for invalid adapter states. A complete power off is required:

  1. Power off the Picocalc:
sudo poweroff
  1. Press the power button and boot normally
  2. The adapter hardware will fully reinitialize

Option 2: Remove and re-insert USB adapter (for external adapters)

If you have an external USB WiFi adapter, physical disconnection can help reset the hardware:

  1. Unplug the USB WiFi adapter
  2. Wait 10-15 seconds
  3. Re-insert the adapter

Adapter May Get a New Name

In rare cases, a corrupted adapter may be assigned a new interface name upon re-insertion. Instead of wlan0, it may appear as wlan1 in ip addr, dmesg, or other tools. iwd will still connect correctly since its configuration is adapter-independent. To restore the original device naming, reboot or perform a complete power cycle.

Option 3: Software module reload (unreliable for stuck adapters)

Software-only solutions may not work when the adapter itself is in an invalid state, but you can try:

# This may not work if the adapter hardware is truly stuck
# Identify the WiFi driver module (e.g., rtl8188fu, aic8800)
lsmod | grep -E 'rtl|aic'

# Attempt to reload the module (replace with your driver name)
sudo modprobe -r rtl8xxxu
sudo modprobe rtl8xxxu

# Or try restarting the iwd service
sudo systemctl restart iwd

If software reload doesn't resolve the issue within a few minutes, proceed to Option 1 (complete power cycle).

DNS Problems

Cannot Resolve Hostnames

Test DNS resolution:

# Check DNS servers
cat /etc/resolv.conf

# Test DNS lookup
nslookup google.com

# Or use dig
dig google.com

Fix DNS issues:

  1. Manually set DNS servers in /etc/resolv.conf:
nameserver 1.1.1.1
nameserver 8.8.8.8

  1. For WiFi with iwd: DNS should be set automatically via DHCP

  2. For USB networking:

  3. With internet sharing, DNS should come from DHCP
  4. For static config, manually set DNS as above

DNS Lookup Slow

  1. Try alternative DNS servers (Cloudflare, Google, Quad9)
  2. Check if DNS server is accessible:
ping 1.1.1.1

Connection Timeouts

SSH Connection Times Out

If SSH to your PicoCalc times out:

  1. Verify connectivity:
ping <picocalc-ip>
  1. Check if SSH is running:
# On PicoCalc
systemctl status sshd
  1. Check firewall (if enabled):
# On PicoCalc
sudo iptables -L -v
  1. Try verbose SSH to see where it fails:
ssh -vvv pico@<ip-address>

Internet Access Times Out

If you can't reach external sites:

  1. Check default route:
ip route show default
  1. Test local gateway:
ping <gateway-ip>
  1. Test external IP:
ping 8.8.8.8
  1. Test DNS:
ping google.com

This helps identify if the issue is:

  • Local network (can't reach gateway)
  • Internet routing (can reach gateway but not internet)
  • DNS (can reach IPs but not resolve names)

Advanced Diagnostics

Network Interface Details

# Detailed interface info
ethtool usb0  # or wlan0

# Interface statistics
ip -s link show usb0

# Routing table
ip route show table all

Network Traffic Analysis

# Monitor traffic on interface
sudo tcpdump -i usb0

# Show active connections
ss -tunap

# Network statistics
netstat -s

Service Status

# Check network-related services
systemctl status systemd-networkd
systemctl status iwd
systemctl status usb-gadget-network
systemctl status sshd

# View service logs
journalctl -u systemd-networkd -b
journalctl -u iwd -b

Getting Help

If you're still experiencing issues:

  1. Gather diagnostic information:
# Save to a file
{
  echo "=== Network Interfaces ==="
  ip addr show
  echo "=== Routes ==="
  ip route show
  echo "=== DNS ==="
  cat /etc/resolv.conf
  echo "=== Service Status ==="
  systemctl status usb-gadget-network systemd-networkd iwd
} > network-diag.txt
  1. Check the documentation:
  2. USB Networking Guide
  3. First Boot - WiFi setup

  4. FAQ

  5. Ask the community:

  6. Discord
  7. Forum
  8. GitHub Issues

See Also