Troubleshooting - drexjj/zbitx GitHub Wiki

Troubleshooting

This page collects the most common problems and their fixes. Start with the symptom that matches yours.

First move for almost anything: confirm your software versions match. Many odd problems come from a Pi application and front‑panel firmware that are out of sync. Check both under Menu → SETUP and compare against the project's release notes in the repository. When in doubt, update both.

Settings aren't remembered after a power cycle

Symptom: After powering off and on, your callsign, grid, passkey, last frequency, or band‑stack memories come back blank or at defaults.

Things to check:

  1. Shut down cleanly. Always use Menu → SHUTDOWN → OK and wait for the green LED to go out before removing power. Pulling power abruptly can lose recent changes and, over time, corrupt the SD card.
  2. Give changes time to save. The radio saves a few seconds after a change, when you key up to transmit, and on a clean shutdown. A change made and immediately followed by yanking power might not have been written yet.
  3. Update your software. Settings save/recall — especially in the headless configuration — has been fixed and improved across releases. If you're on an older version, update.

If it still won't recall after updating: the settings file is stored on the Pi under sbitx/data/user_settings.ini. On a healthy system the startup log shows a line like loading settings from /home/pi/sbitx/data/user_settings.ini. If your system logs a different path, or can't write that file, that's the culprit — the software includes a fallback for this, so make sure you're on a current build.

The front panel shows blank or default values

Symptom: The panel comes up without your callsign/frequency, or fields look empty even though they should be set.

Cause: The panel gets its values from the Pi over I2C. If the panel finished booting before the Pi was ready (or the panel reset), it may have missed the initial data.

Fix: Current software automatically re‑syncs all values whenever the panel connects, so this heals itself within about a second. If it doesn't, update to a current build, and power‑cycle both cleanly. Persistent blank fields point to a panel↔Pi communication problem or a version mismatch.

The Setup menu's "Software version" stays at ---

Symptom: Opening Menu → SETUP shows the Panel version but the Software (Pi) version stays ---.

Cause: The panel asks the Pi for its version when you open Setup; if the reply never arrives, the panel and Pi aren't communicating.

Fix: Confirm both are powered and running, check the panel firmware isn't badly mismatched, and update both to current versions. A momentary --- that fills in is normal.

WiFi won't connect

See the full WiFi Setup page. The short version:

  • Type the SSID exactly — names are case‑sensitive and may contain spaces.
  • Passwords need lowercase/symbols — the keyboard starts uppercase; tap the case/symbol key.
  • "Connect failed" is almost always a wrong password or a network out of range.
  • Buttons don't respond at all? Update your software — WiFi control has been fixed across releases.

FT8 decodes poorly or not at all

  • Wrong frequency/mode: confirm you're on the band's FT8 frequency in FT8 mode.
  • Clock accuracy: FT8 needs an accurate clock. Connect to WiFi so the Pi can sync time. Poor decodes with a valid signal usually mean clock drift.
  • Activity: try a busier band/time (20 m by day, 40 m by evening are reliable).

See FT8 Operation.

The Watts / SWR meters read wrong during transmit

Symptom: The web interface shows 0 watts / SWR 1.0 during transmit, or an obviously wrong scale.

Fix: This was fixed in a software update — the meters now update from both power and SWR data, show live values during transmit, and use a 0–5 W / 1.0–5.0 SWR scale suited to the QRP radio. Update your software and refresh your browser.

The web interface won't load

  • Confirm the radio is on the network and you have its correct IP address (shown on the WiFi status line, Menu → WIFI).
  • Make sure you're on the same network as the radio (or have set up remote access).
  • Log in with your passkey (Menu → SETUP).
  • Try a different browser or clear the cache/refresh.

VNC desktop is slow or won't free resources

  • Slowness is expected — the Pi Zero 2 W runs the radio and a desktop on a small processor.
  • Always close the VNC browser window when done — that's what shuts the virtual display down and returns resources to the radio.
  • If the VNC window is blocked, allow pop‑ups for the radio's page.

See VNC & Remote Desktop.

High SWR when transmitting

  • Keep SWR under about 2:1. A high reading means the antenna isn't a good match on this frequency.
  • Retune your antenna/tuner, or move frequency.
  • Reduce DRIVE (power) until you sort out the match — protecting the finals.
  • Use a modest TNPWR and short TNDUR when sending a tune carrier (see Options & Controls).

The radio behaves oddly after an update

  • Confirm the panel firmware meets the minimum the new Pi release requires (see the repository's release notes).
  • If you only updated one of the two components, update the other.
  • Reboot cleanly and re‑check both versions under Menu → SETUP.

When all else fails

  • Reboot cleanly (Menu → SHUTDOWN, wait for the LED, then power back up).
  • Re‑seat connections — antenna, USB, power.
  • Check power — a weak/sagging supply causes all sorts of intermittent issues; watch the battery voltage readout.
  • Update both software components to the latest.
  • Consult the project's Releases/issues pages for known problems with your specific version.

Related: Upgrading the Software »