Platform: Raspberry Pi • Debian/Raspberry Pi OS • WPSD
Purpose: Routine maintenance, operating-system updates, WPSD updates, and migration from Bookworm to Trixie
Last reviewed: 1 November 2026
Important: WPSD is an appliance-style Linux distribution, not just an application installed on a generic Debian system. For routine WPSD maintenance, use the WPSD-provided update mechanisms. For a major operating-system generation change such as Bookworm → Trixie, the WPSD documentation recommends writing the current WPSD image to an SD card and restoring your configuration rather than attempting an in-place distribution upgrade.
Maintenance at a Glance
A healthy hotspot needs several different kinds of maintenance. They are related, but they are not the same operation.
| Maintenance item | What it maintains | Recommended method |
|---|---|---|
| WPSD software update | WPSD dashboard, hotspot software and project-supplied fixes | WPSD Update function |
| WPSD automatic update | Keeps normal WPSD software current without manual intervention | WPSD normally checks/updates overnight |
| Linux package maintenance | Debian/Raspberry Pi OS packages and security fixes | Prefer the WPSD update process; use APT manually only when you have a specific reason |
| Host/data files | Reflectors, networks, DMR/NXDN IDs and talkgroup-name data used by WPSD | WPSD manages these automatically |
| Modem firmware | Firmware running on the MMDVM/ZUMSpot-type modem board | Admin → Advanced → Modem Firmware Upgrade or wpsd-modemupgrade |
| Major OS migration | Changes the underlying OS generation, e.g. Bookworm → Trixie | Back up, write the new WPSD image, restore |
[!IMPORTANT]
The Central Rule
Do not treat a WPSD hotspot like a general-purpose Raspberry Pi server.
Keep the operating system and hotspot current, but let WPSD manage WPSD wherever possible. WPSD is an integrated appliance-style system. Routine maintenance should use the WPSD-provided update tools rather than treating the hotspot like a general-purpose Debian machine and independently changing packages, repositories, or WPSD components.
1. Backups and Recovery
Back up before:
- moving to a new WPSD image;
- moving between major OS generations;
- making extensive configuration changes;
- experimenting with networking;
- performing repair work that could affect configuration;
- just in case. Murphy will show up at the most inopportune time.
Store at least one backup off the hotspot. A backup that exists only on the same SD card does not help when the card fails.
For a major release migration, the combination of configuration backup + new SD card + untouched old SD card gives you a very practical recovery path.
2. Before Doing Maintenance
Before any significant change:
- Make sure the hotspot has reliable power.
- Confirm that its Internet connection is working.
- Make a fresh WPSD configuration backup.
- Note the current WPSD version.
- Note the current operating-system version.
- For a major OS migration, use a new SD card if possible so that the old working card remains an immediate rollback option.
Check the WPSD version
The WPSD project documents this command:
wpsd-version
The running version/hash is also shown in the dashboard.
Check the operating system
From a shell:
cat /etc/os-release
Within WPSD, the OS information can also be found under:
Admin → System Details → Operating System
3. Keeping the Linux Operating System Current
WPSD sits on top of Debian/Raspberry Pi OS, so the underlying operating system contains the kernel, system libraries, networking components, security packages and utilities on which WPSD depends.
Why Linux updates matter
Keeping the OS current helps provide:
- security fixes;
- operating-system bug fixes;
- current libraries used by WPSD and its supporting services;
- networking and hardware fixes;
- package dependency corrections.
For a dedicated WPSD hotspot, however, more updating is not automatically better. WPSD is a coordinated software distribution, so blindly changing packages, repositories or distribution releases can create combinations the WPSD project did not intend.
Normal APT maintenance
If you have a reason to inspect Debian package status from the shell, start with:
sudo apt update
apt list --upgradable
apt update refreshes the local package index. It does not install upgrades.
On a normal Debian system, installed packages can be brought current with:
sudo apt upgrade
and a more comprehensive dependency-resolving update is:
sudo apt full-upgrade
WPSD caution
For a WPSD appliance, do not make apt full-upgrade, repository editing, or unattended package manipulation your routine maintenance strategy unless WPSD’s current documentation specifically calls for it. Use the WPSD updater for ordinary hotspot maintenance. The updater is the project-controlled path for keeping the hotspot’s software stack synchronized.
Rebooting
Do not reboot merely because you ran an update command unless the update requires it. When a reboot is appropriate, use a controlled reboot:
sudo reboot
Never remove power while package installation, filesystem activity, an SD-card write, a restore, or a modem firmware flash is in progress. You may regret it.
4. Updating WPSD from the Web GUI
WPSD normally performs routine updating automatically overnight. The official manual also provides a manual Update button for starting the process on demand.
Manual GUI update
Open the WPSD dashboard in a browser, normally:
http://wpsd.localor open the hotspot by its IP address.
Log in if prompted.
Open the WPSD Update function from the dashboard.
Start the update.
Let it finish. Do not interrupt power or networking during the operation.
Return to the dashboard and verify normal operation.
If troubleshooting is necessary, check Admin → Log Viewer and record the output of
wpsd-version.
Menu wording can change as WPSD evolves. The important point is to use WPSD’s dashboard Update function rather than manually replacing WPSD program files.
5. Updating WPSD from the GUI Shell / Command Line
WPSD includes its own update utility. From Admin → Advanced → Tools → SSH Access, or from a normal SSH session to the hotspot, the command to perform the complete WPSD update is:
sudo wpsd-update all
This is the command-line counterpart to performing a complete WPSD maintenance update. Run it from a stable network connection and allow it to finish without interruption.
Useful wpsd-update forms
The update script supports update targets. The two particularly useful forms for routine maintenance are:
sudo wpsd-update all
Performs the full update process and is the preferred manual command when you simply want to bring the hotspot current.
sudo wpsd-update os
Invokes the updater’s operating-system update path. This is useful when specifically working with the underlying OS packages. It is not a Bookworm-to-Trixie distribution migration command.
Because WPSD’s scripts can change over time, check the version installed on the hotspot rather than relying on an old command list. The current public WPSD script requires root privileges and prevents a second updater instance from running at the same time.
Other useful WPSD maintenance commands
# Display installed WPSD version/hash
wpsd-version
# Update WPSD hostfiles/data
sudo wpsd-hostfile-update
# Attempt to identify the installed modem
sudo wpsd-detectmodem
# Modem firmware upgrade utility; requires the correct device argument
sudo wpsd-modemupgrade
wpsd-hostfile-update is worth knowing about, although normal hostfile maintenance is automatic. It refreshes the locally stored network, reflector and identification data used by WPSD.
wpsd-modemupgrade is a separate firmware operation, not part of a routine wpsd-update all. See Chapter 6 before using it.
Debian inspection commands
These are useful for seeing what is happening underneath WPSD:
cat /etc/os-release
sudo apt update
apt list --upgradable
df -h
apt maintains Debian packages. It does not replace wpsd-update for maintaining the complete WPSD software stack.
6. What the WPSD Updates Do
It helps to separate the different things that users often call an “update.”
6.1 WPSD software update
Purpose: Bring the installed WPSD software to the current project release for that supported image.
The WPSD manual says normal WPSD updates occur automatically overnight and can also be started manually with the Update button.
Why it matters: This is the normal mechanism for receiving WPSD project fixes and changes while keeping the components of the hotspot aligned with one another.
6.2 Hostfile and identification-data updates
WPSD uses locally stored hostfiles for digital-voice destinations and identification. Depending on mode, these contain such information as reflector names and addresses, network information, P25/NXDN talkgroup data, DMR network data, and DMR/NXDN ID-to-callsign mappings. WPSD downloads and updates these files automatically.
Why it matters: Digital-voice infrastructure changes. Updated data lets the dashboard present current destination and callsign information instead of stale entries or bare numeric IDs.
6.3 Debian/Raspberry Pi OS package updates
These maintain the operating system beneath WPSD.
Why they matter: They provide security, stability, library, kernel and hardware-support maintenance. On WPSD, however, OS changes should remain compatible with the WPSD image and its supported base operating system.
6.4 Modem firmware update
This is not a WPSD dashboard/software update. It programs the firmware on the MMDVM/ZUMSpot-compatible radio modem.
The GUI tool is located at:
Admin → Advanced → Modem Firmware Upgrade
The CLI utility is:
wpsd-modemupgrade
It requires a modem-specific argument. Examples documented by WPSD include:
wpsd-modemupgrade hs_hat
wpsd-modemupgrade hs_dual_hat
wpsd-modemupgrade zum_rpi
wpsd-modemupgrade zum_rpi-duplex
[!CAUTION]
Do Not Guess the Modem Type
Do not guess which modem firmware your hotspot requires. The modem type must be identified correctly before running a firmware upgrade. Installing the wrong firmware can leave the modem unusable until it is reflashed correctly.
If you are not certain what modem is installed, stop and identify it before continuing. WPSD provides a modem-detection helper:
sudo wpsd-detectmodemTreat modem firmware upgrades as deliberate maintenance, not as something to run simply because an update is available.
Why modem firmware matters: The modem and WPSD host software work together to handle the actual digital radio interface. Firmware changes may be needed for modem fixes or compatibility, but modem firmware should be updated intentionally rather than simply because a WPSD software update exists.
6.5 Major WPSD/OS image upgrade
Occasionally WPSD requires a new disk image, typically when the underlying OS moves to a new major version. This is different from clicking Update.
Why it matters: A clean image gives WPSD the operating-system version, packages, configuration layout and dependencies against which that WPSD release was built and tested.
7. Suggested Maintenance Schedule
This is a practical recommendation rather than a WPSD-mandated schedule.
Weekly or whenever convenient
- Glance at the dashboard for errors.
- Confirm expected networks/modes are connected.
- Let WPSD’s automatic update process do its normal work.
Monthly
Start a manual WPSD update if you want to confirm the hotspot is current.
Check
wpsd-version.Check available storage:
df -hReview Admin → Log Viewer if anything looks abnormal.
Before any major change
- Download a fresh WPSD configuration backup.
- Verify the backup exists on another computer.
- Record the current WPSD and OS versions.
When a new OS-based WPSD image is announced
Treat a major WPSD/OS release as a planned migration rather than a routine update. There is no prize for being the first hotspot on the block to run a new base OS. A little preparation makes the change easy to reverse if something unexpected appears.
- Read the WPSD announcement and release notes first. Determine whether the release requires a new image and note any hardware-specific or configuration-related instructions.
- Make a fresh WPSD configuration backup. Download it to another computer and keep the ZIP file intact.
- Record the working system. Note the current WPSD version, OS version, hotspot frequency, modem type, enabled digital modes, and network settings that would be useful if you had to rebuild manually.
- Use another SD card for the new image whenever possible. Do not destroy a known-good installation merely to save the cost of an SD card. The existing card is your fastest rollback method.
- Download the correct WPSD image for the hotspot hardware. Verify the image/checksum when the project supplies one, then write the image using the method recommended by WPSD.
- Restore the saved WPSD configuration using the WPSD-supported restore process for the new image.
- Allow the first boot to finish completely. Do not interrupt power while WPSD is initializing the filesystem, applying configuration, or bringing services online.
- Verify the hotspot systematically. Check the OS and WPSD versions, network connectivity, callsign/identity, modem selection, frequency, enabled modes, network connections, and normal dashboard/log behavior.
- Test actual radio operation. Confirm the modes and networks you normally use rather than assuming that a healthy-looking dashboard means every path is working.
- Create a new post-migration backup after the new installation has been verified. Keep it separately from the pre-upgrade backup.
- Keep the previous SD card intact for a while. If the new release produces an unexpected problem, shut down normally, reinstall the old card, and you have a known-good rollback point.
Remember: a normal WPSD update and a major OS/image migration are different operations. Do not assume the Update button or
sudo wpsd-update allconverts an older base OS to the new major release. Follow the WPSD image-migration instructions whenever the project calls for a new image.
8. Troubleshooting After an Update
If the hotspot does not behave normally after maintenance, collect facts before changing more things.
Basic checks
wpsd-version
cat /etc/os-release
df -h
Then check:
Admin → Log Viewer
Record:
- what you were trying to do;
- what you expected;
- what actually happened;
- WPSD version/hash;
- OS version/image generation;
- enabled mode(s);
- relevant log entries;
- recent changes;
- troubleshooting already attempted.
That is the information the WPSD project recommends gathering when asking the community for help.
9. Command Reference
# WPSD version/hash
wpsd-version
# Identify the OS release
cat /etc/os-release
# Complete WPSD update
sudo wpsd-update all
# WPSD OS update path
sudo wpsd-update os
# Refresh WPSD hostfiles/data
sudo wpsd-hostfile-update
# Refresh Debian package metadata
sudo apt update
# Show packages for which Debian upgrades are available
apt list --upgradable
# Check disk usage
df -h
# Controlled reboot
sudo reboot
# Attempt modem identification
sudo wpsd-detectmodem
# WPSD modem-firmware utility; requires the correct modem argument
wpsd-modemupgrade
Avoid cookbook distribution upgrades on WPSD. Commands that rewrite APT sources from
bookwormtotrixiemay be valid in a generic Debian upgrade guide but are not the WPSD image-migration procedure.
10. The Short Version
For day-to-day maintenance:
- Keep reliable power and networking.
- Let WPSD perform its normal updates.
- Use the WPSD Update button when you want to update manually.
- Back up the configuration regularly.
- Use APT for inspection or specific OS maintenance, not as a replacement for WPSD’s updater.
- Treat modem firmware as a separate operation.
- For Bookworm → Trixie, back up WPSD, write the official Trixie WPSD image to a new SD card, restore the backup and verify the hotspot.
That approach keeps the hotspot boring, which is exactly what you want from infrastructure that is supposed to be available when you reach for the radio.
Appendix A: Upgrading WPSD from Bookworm to Trixie
As of 2026, WPSD provides Trixie-based Raspberry Pi images. The WPSD transition documentation says its current disk-image line is Trixie/Bookworm based, and the WPSD manual describes major OS-version changes as occasions when a fresh image may be required.
Do not perform an ordinary Debian in-place distribution upgrade
Debian itself documents a supported Debian 12 Bookworm → Debian 13 Trixie package upgrade procedure. That procedure is appropriate for ordinary Debian installations, but a WPSD hotspot is a pre-integrated appliance image.
For WPSD, use the WPSD image migration procedure instead of changing bookworm to trixie in APT sources and running apt full-upgrade.
This also avoids mixing a Bookworm-era WPSD installation with Trixie packages outside the WPSD project’s image upgrade path.
Recommended Bookworm → Trixie procedure
Step 1: Make a WPSD configuration backup
Use WPSD’s backup facility and download the backup to another computer.
The backup filename has the form:
WPSD_Config__YYYYMMDD_HHMMSS.zip
Keep that ZIP file intact. Do not extract it.
Step 2: Keep the old SD card
Shut down the hotspot cleanly and remove the Bookworm SD card.
If practical, do not overwrite it. WPSD’s manual specifically recommends using another SD card for the new image. The old card then becomes your immediate rollback plan.
Step 3: Download the correct Trixie image
Go to the official WPSD download page and obtain the image for your supported Raspberry Pi/hardware platform.
A typical Raspberry Pi image name follows the pattern:
WPSD_RPi-Trixie.img.xz
Also obtain the project’s checksum file if you want to verify the downloaded image before writing it.
Step 4: Write the image
Write the compressed image to the new SD card. The WPSD manual recommends Balena Etcher for less-experienced users and cautions that imaging tools which make post-write modifications can interfere with WPSD’s preconfigured image.
Do not boot the hotspot yet if you intend to use automatic first-boot configuration restore.
Step 5: Put the configuration backup on the new card
After imaging, copy the complete backup ZIP file to the top level of the boot volume on the new SD card.
Example:
WPSD_Config__YYYYMMDD_HHMMSS.zip
Again, do not extract the ZIP.
Step 6: Boot the Trixie card
Insert the new card and power on the Raspberry Pi.
On first boot WPSD performs initialization work including generating SSH keys and expanding the filesystem. If it finds a WPSD configuration backup in the boot volume, its startup process restores it before completing normal startup.
Be patient during the first boot and do not interrupt power.
Step 7: Verify the migration
After the dashboard becomes available:
Confirm access to the dashboard.
Check Admin → System Details → Operating System and verify Trixie.
Check the WPSD version:
wpsd-versionVerify your callsign and hotspot identity.
Verify Wi-Fi/Ethernet connectivity.
Verify modem selection and frequency settings.
Verify each digital mode and network you actually use.
Check Admin → Log Viewer for services that do not start normally.
Make a new backup of the working Trixie configuration.
Step 8: Retain the Bookworm card temporarily
Do not immediately erase the working Bookworm card. Keep it until the Trixie hotspot has operated normally long enough for you to be comfortable with the migration.
References
- WPSD Project: https://w0chp.radio/
- WPSD User Manual: https://manual.wpsd.radio/
- WPSD User Manual, Maintenance Items: https://manual.wpsd.radio/maintenance_items/
- WPSD User Manual, Installing the Software: https://manual.wpsd.radio/install_software/
- WPSD transition information: https://w0chp.radio/articles/wpsd-transitions/
- WPSD Bookworm information: https://w0chp.radio/articles/wpsd-bookworm-for-rpi-released/
- Debian 13 (Trixie) release notes: https://www.debian.org/releases/trixie/release-notes/
Source notes
The operational WPSD guidance in this manual was checked against the current WPSD User Manual and W0CHP/WPSD project articles. Debian’s release notes document an in-place Bookworm-to-Trixie upgrade for generic Debian systems; this manual intentionally does not reproduce that procedure for WPSD because WPSD’s own maintenance documentation describes major OS transitions using the backup/new-image/restore workflow.
