Troubleshooting

Solutions for common issues with the web UI, GPIO, USB HID, and networking.

Common Issues

The web UI won't load

1. Check the service is running: sudo systemctl status morse-pi
2. Check the logs: sudo journalctl -u morse-pi -n 50
3. Make sure you're using the right IP and port (default 5000)
4. If ufw is active, verify port 5000 is open: sudo ufw status

Updated code, but the UI still looks old

1. Hard-refresh your browser (Ctrl+Shift+R) or clear cache.
2. For Rust installs, run the updater again: curl -sSL https://raw.githubusercontent.com/Nerd-or-Geek/Morse-Pi/main/update-rust.sh | sudo bash
3. If you updated manually, rebuild and sync templates:

   cd /opt/morse-pi/morse-translator-rust
   cargo build --release --features gpio
   sudo cp target/release/morse-pi /opt/morse-pi/morse-translator/morse-pi
   sudo mkdir -p /opt/morse-pi/morse-translator/templates
   sudo cp -r templates/. /opt/morse-pi/morse-translator/templates/
   sudo systemctl restart morse-pi

4. Open the dedicated radio page directly to verify route updates: http://<pi-ip>:5000/network (legacy /radio also works).

Service won't start

1. Check logs: sudo journalctl -u morse-pi -n 50
2. Try running manually:
   • Rust: cd /opt/morse-pi/morse-translator && ./morse-pi
   • Python: cd /opt/morse-pi/morse-translator && python3 app.py
3. Check file permissions: ls -la /opt/morse-pi/morse-translator/
4. Re-run the installer to fix the service configuration

Rust Backend

Build fails with "out of memory"

Pi Zero has only 512 MB RAM. The Rust compiler can exhaust memory during linking.

• Ensure a swap file exists: free -h — look for "Swap" row
• Add or enlarge swap: sudo dphys-swapfile swapoff && sudo sed -i 's/CONF_SWAPSIZE=.*/CONF_SWAPSIZE=512/' /etc/dphys-swapfile && sudo dphys-swapfile setup && sudo dphys-swapfile swapon
• Retry the build: cd /opt/morse-pi/morse-translator-rust && cargo build --release --features gpio

Build fails with "linker cc not found"

• Install build tools: sudo apt install build-essential -y

Build fails with "pigpiod_if2.h not found"

• Install pigpio dev headers: sudo apt install libpigpio-dev -y
• If you don't need GPIO (not on a Pi), build without the feature: cargo build --release

Rust binary crashes on startup

• Check that pigpiod is running: sudo systemctl start pigpiod
• Check logs: sudo journalctl -u morse-pi -n 50
• Verify the binary has execute permission: chmod +x /opt/morse-pi/morse-translator/morse-pi
• Run manually to see the error: cd /opt/morse-pi/morse-translator && ./morse-pi

Cargo / rustup not found after install

• Source the environment: source "$HOME/.cargo/env"
• Or log out and log back in to pick up the PATH change

Settings aren't saving

• Check file permissions: ls -la /opt/morse-pi/morse-translator/settings.json
• The file should be owned by your user (not root): sudo chown $USER:$USER /opt/morse-pi/morse-translator/settings.json

GPIO Errors

GPIO indicator shows red / "GPIO unavailable"

• You may not be on a Raspberry Pi — GPIO only works on Pi hardware
• Check that pigpiod is running: sudo systemctl status pigpiod
• Start it: sudo systemctl start pigpiod
• Make sure your user is in the gpio group: groups
• Add yourself: sudo usermod -aG gpio $USER then log out/in

No sound from speaker

• Check wiring — speaker positive to the speaker pin (default BCM 18), negative to GND (or second speaker pin)
• Verify pin assignment in CONFIG matches your wiring
• Check that output type is set to "speaker" (not "led")
• Try the GPIO Diagnostic page (click the GPIO indicator dot) to see live pin states
• Increase volume in CONFIG
• If using dual-pin speaker, ensure both Speaker Pin 1 and Speaker Pin 2 are set and pigpio is available

Key presses not detected

• Check wiring — key should short the data pin to GND when pressed
• Verify pin assignment in CONFIG
• Make sure pin mode matches your hardware (single = straight key, dual = iambic)
• Use the GPIO Diagnostic page to see if the pin toggles when you press the key
• Internal pull-ups are enabled — no external resistors needed

Connection Errors

"Connection to Pi lost" message

This appears when the browser can't reach the Pi's web server. Common causes:

• Pi rebooting — wait 30–60 seconds for boot to complete
• Service crashed — check with sudo systemctl status morse-pi
• Network change — Pi may have gotten a new IP address. Check: hostname -I
• WiFi interference — move closer to the router or use Ethernet

Slow or laggy UI

• The UI polls the Pi every 250ms — on a Pi Zero this is near its limit
• Make sure no other heavy processes are running on the Pi
• Use a wired Ethernet connection if possible for lower latency

USB HID Errors

"USB HID not available" in KB tab

• /dev/hidg0 doesn't exist — reboot after installation
• Check modules: lsmod | grep dwc2 — should show dwc2 and libcomposite
• Check service: sudo systemctl status morse-pi-hid
• Check kernel config: grep dtoverlay=dwc2 /boot/config.txt

g_ether blocking HID (most common)

The Pi Zero has only one USB controller. If g_ether (USB Ethernet for SSH-over-USB) loads before the HID gadget, it monopolises the port. Run lsmod | grep g_ether to check.

• Quick fix: sudo rmmod g_ether usb_f_ecm usb_f_rndis u_ether 2>/dev/null, then echo "20980000.usb" | sudo tee /sys/kernel/config/usb_gadget/morse-pi-keyboard/UDC
• Permanent fix: echo "blacklist g_ether" | sudo tee /etc/modprobe.d/morse-pi-no-gadget-conflict.conf and reboot
• The installer (v2+) does this automatically. Re-run the installer to apply the fix.
• ⚠ Disabling g_ether removes USB-over-Ethernet SSH. Ensure WiFi is configured first.

"Permission denied" writing to /dev/hidg0

• Fix permissions: sudo chmod 666 /dev/hidg0
• The udev rule should handle this automatically — run sudo udevadm trigger
• Verify rule exists: cat /etc/udev/rules.d/99-morse-pi-hid.rules

Wrong characters being typed

• HID scan codes assume a US keyboard layout
• If your computer has a different keyboard layout, some characters may map differently

See the USB HID Keyboard page for more setup details and manual configuration steps.

Network Errors

No peers discovered

• Both Pis must be on the same subnet (same WiFi network)
• UDP broadcast (port 5001) must not be blocked by the router
• Wait at least 5 seconds — beacons are sent every 3 seconds
• Some enterprise/hotel WiFi networks block broadcast traffic — use a home network

Messages not arriving

• Verify the peer shows as online in the RADIO page (peers disappear after 15 seconds without a beacon)
• Check that port 5000 is reachable on the target Pi: curl http://<peer-ip>:5000/status
• Check for firewall rules: sudo ufw status