Skip to content

Troubleshooting

Symptom to cause.

Installation stops partway

If the repository was successfully cloned but failed on setup:

~/fugleramme/install.sh

It reuses the checkout and skips setup that is already complete (idempotent).

SSH over USB

computer sees no USB device. Check you're in the Pi's USB-C port, not USB-A, and not through a hub. Confirm the cable carries data by plugging a phone into it. Then on the Pi, over the network:

cat /sys/class/udc/*/state

not attached means the Pi never saw a host - on a Pi 5 that's almost always an old bootloader, so run the EEPROM step in Install. configured means the link is up and the problem is on the computer.

Device shows up, but no gadget. sudo dmesg | grep -i gadget should say bound driver g_ether. If not, check for leftover manual dtoverlay=dwc2 lines in /boot/firmware/config.txt fighting the package - there should be one at most.

Device shows up, SSH hangs. Check your computer got an address on the link: ifconfig | grep 10.12.194. Use 10.12.194.1, not <host>.local, which resolves to the Wi-Fi address. Disable any VPN - they tend to swallow local subnets.

apt can't resolve deb.debian.org

The Pi has no route out. The USB link only joins your computer and the Pi, so share the computer's connection over it:

  • macOS: System Settings → General → Sharing → Internet Sharing. Share from your active connection, to Raspberry Pi USB Gadget.
  • Windows: enable ICS, per the rpi-usb-gadget README.

SSH dies the moment sharing is enabled. Its DHCP replaces 10.12.194.1 with a leased address. Reconnect as <host>.local, or look up the lease your computer handed out (macOS: cat /var/db/dhcpd_leases).

Computer loses internet with the cable plugged in

The Pi hands out a default route over USB and the computer prefers it over Wi-Fi. Demote the gadget interface in your computer's network service order, so Wi-Fi comes first. On macOS, list every service with the gadget last:

sudo networksetup -ordernetworkservices "Wi-Fi" ... "Raspberry Pi USB Gadget"

SSH keeps working - 10.12.194.1 is a directly connected route.

Panel stays blank

journalctl -u fugleramme-frame -f

Look for Inky panel initialised. If it says not detected, check ls /dev/spidev* and that your login picked up the spi, i2c and gpio groups (id) - the first install needs a reboot. The kiosk on :8080 works either way, so a live web view with a blank panel points here.