VNC and Remote Desktop - drexjj/zbitx GitHub Wiki

VNC & Remote Desktop

The Raspberry Pi inside the zBitx has its own graphical desktop, where ham applications like zBitx Toolbox and the zBitx are installed. You can open that desktop inside your web browser using the built‑in VNC feature — no extra software on your device.

What the VNC button does

In the web interface, the VNC button launches the Main Desktop — the Pi's graphical environment — in a new browser window. From there you can run and interact with the desktop apps as if you had a monitor and mouse plugged into the Pi.

Opening the desktop

  1. Make sure the radio is on your network (WiFi Setup).
  2. Remember the IP address from the Wifi menu and use that if you are unable to connect to https://zbitx.local:8443
  3. Open the web interface in your browser and log in.
  4. Click the VNC button.
  5. The desktop starts up (this takes a few seconds while the virtual display comes up) and opens in a new browser window.
  6. Interact with the desktop — launch WSJT‑X, adjust settings, whatever you need.

Closing the desktop — and why it matters

When you're done, close the VNC browser window. This is important: closing that window tells the radio to shut down the virtual display and free up its resources.

  • The virtual desktop uses memory and CPU on the little Pi Zero 2 W.
  • Leaving it running in the background steals resources from the radio's real‑time signal processing.
  • Closing the window cleanly tears it down automatically, so the radio gets those resources back.

The VNC button's status indicator will return to its normal state once the display has been shut down.

Running apps on the desktop

Once you're in the desktop you can use the installed ham applications. Audio and CAT between these apps and the radio are handled internally on the Pi — you don't need extra cables or adapters. For example, WSJT‑X can decode the radio's audio and key it for transmit, all within the Pi.

See Voice & Digital Modes for more on running third‑party software.

Performance notes

The Pi Zero 2 W is a modest computer running a real‑time radio and a graphical desktop at the same time. A few realities:

  • Expect the desktop to feel slower than a normal PC — it's sharing a small processor with the radio.
  • Heavy desktop use can affect radio performance. If you notice the radio getting sluggish, close the VNC window to give resources back.
  • For the smoothest experience, do your desktop configuration (e.g. setting up WSJT‑X) when you're not in the middle of critical operating.

Troubleshooting

Symptom Fix
VNC window doesn't open Allow pop‑ups for the radio's web page in your browser, then click VNC again.
Desktop is very slow Normal for the Pi Zero 2 W under load; close other apps and the radio's heavy tasks.
Resources not freed after use Make sure you closed the VNC browser window — that's what triggers the shutdown of the virtual display.
Button doesn't respond Confirm the radio is on the network and your software is current.

Related: Voice & Digital Modes » · WiFi Setup » · USB Mode »