Skip to content

Upgrading the Software

Jump to bottom
jj edited this page Sep 30, 2026 · 4 revisions

Upgrading the Software

Keeping the radio current means updating both components when needed:

  • the Pi application (rebuilt from the repository), and
  • the front‑panel firmware (a new .uf2), if the new Pi release requires a newer panel version.

Always read the project's release notes (release_notes.md in the repository) for the version you're moving to. Each entry tells you the minimum front‑panel firmware required — that's the single most important thing to check.

The golden rule: check the version pairing

At the bottom of most release notes you'll see a line like:

Requires front panel firmware v5.11f or higher

If the release you're installing needs a newer panel firmware than you have, you must flash the Pico too, or you'll see mismatched behavior (missing menu items, blank Setup fields, controls that don't respond).

Check your current versions any time under Menu → SETUP on the front panel.

Upgrading the Pi software

The install ships with an update helper script that pulls the latest code and rebuilds everything. From a terminal on the Pi:

cd $HOME/sbitx
./update

You can also use the Update Manager app inside the zBitx Toolbox. toolboximg updatemgrimg

Under the hood this:

  1. Stashes any local changes so they don't block the update,
  2. Pulls the latest code from the repository,
  3. Rebuilds the FT8 library and then the main application,
  4. Prints a success message when done.

When it finishes, restart the software (or reboot the Pi) so the new build takes effect.

Prefer to do it by hand? The equivalent manual steps are:

cd $HOME/sbitx
git pull
make clean && make

If the update reports errors

The update script stops at the first error and shows which command failed. The most common causes are:

  • No internet — the Pi can't reach the repository. Connect to WiFi first.
  • Local edits conflict — if you've modified files yourself, the stash/pull can conflict. Back up your changes and resolve them, or start from a clean clone.
  • Out of disk space — a full SD card can fail the build. Free some space and retry.

Upgrading the front‑panel firmware

Only needed when the new Pi release requires a newer panel version (or a release note lists a panel‑side fix you want).

  1. Download the new .uf2 from the front‑panel repository's build folder or Releases.
  2. Put the Pico into bootloader mode (hold BOOTSEL while connecting/powering it — it appears as the RPI-RP2 USB drive).
  3. Drag the .uf2 onto that drive. The Pico reboots into the new firmware.

Full details are on the Installation & Flashing page.

Recommended upgrade order

  1. Read the release notes for the target version and note the required panel firmware.
  2. Back up your data and web folders if you're doing anything unusual (a normal ./update preserves them, but backups are cheap insurance).
  3. Update the Pi software with ./update.
  4. Flash the panel firmware if the release requires a newer version.
  5. Reboot and confirm both versions under Menu → SETUP.
  6. Spot‑check: receive on a band, open the web interface, and verify your callsign/frequency came back.

After upgrading — verify your settings survived

Your callsign, grid, passkey, last frequency, and band‑stack memories are stored on the Pi and should carry across an upgrade untouched. After rebooting:

  • Confirm your callsign and grid are still set (Menu → SETUP).
  • Confirm the radio came up on your last frequency and band.

If any of these came up blank or default, see the settings section of Troubleshooting.

Next: Front Panel Operation »

zBitx Operator Manual

Getting Started

Using the Radio

Operating Modes

Connectivity & Features

Miscellaneous

Reference

Clone this wiki locally