HAMORA Bridge for Raspberry Pi

HAMORA Bridge 0.5 only reads: it reads your radio’s frequency, mode and meters, listens to WSJT-X, and receives the APRS your radio hears. It doesn’t transmit or change your radio.

• A Raspberry Pi 3, 4, 5 or Zero 2 W. The Raspberry Pi 1 and the first Zero (ARMv6) aren’t supported.
• Raspberry Pi OS 64-bit, Bookworm or newer. The Lite version is enough.
• Python 3.11 or newer and systemd, as Raspberry Pi OS Bookworm has.
• Your phone and the Pi on the same network, over Wi-Fi or Ethernet.
• For your radio: a radio Hamlib supports, and its USB (CAT) cable. The installer adds Hamlib for you.
• Optional: WSJT-X for FT8 and FT4, and Dire Wolf with a receiver and a USB sound card for APRS RF.

For the free programs HAMORA Bridge works with, see Compatibility.

1. Prepare the Pi

   In Raspberry Pi Imager, choose Raspberry Pi OS Lite (64-bit). Turn on SSH and set your Wi-Fi before writing the card, then start the Pi.

2. Copy the installer to the Pi

   Download the installer script and the HAMORA Bridge package file from this page, check their checksums (see Verifying your download), and copy both to the same folder on the Pi. Or use the .deb package instead.

3. Run the installer

   On the Pi, run the installer script with sudo bash from that folder. With the .deb package, install it with apt instead:

   sudo apt install ./hamora-bridge_<version>_arm64.deb

   Copy

4. What the installer does

   It checks the system, installs Python and Hamlib, creates a system user called hamora that can open USB serial ports, installs HAMORA Bridge in /opt/hamora-bridge with its settings in /var/lib/hamora-bridge, and starts its service. It never changes your router or firewall: no UPnP and no port forwarding.

5. Open the setup page

   When it finishes, the installer shows the setup page’s address, such as http://raspberrypi.local:8765/, with the computer’s IP addresses, and a 6-digit setup code. Open the address in a browser on any phone, tablet or computer on the same network, enter the code and follow the five steps.

Running, updating and removing

1. It runs as a service

   HAMORA Bridge runs as the systemd service hamora-bridge, as its own user (hamora), and starts when the computer starts. To follow its log:

   journalctl -u hamora-bridge -f

   Copy

2. A new setup code

   In HAMORA, More → HAMORA Bridge → Open HAMORA Bridge Setup shows a code and opens the page. Or, on the HAMORA Bridge computer:

   sudo -u hamora env HAMORA_BRIDGE_DATA_DIR=/var/lib/hamora-bridge /opt/hamora-bridge/.venv/bin/hamora-bridge admin-code

   Copy

3. Updating and removing

   To update, run the newer installer or install the newer package: your settings and paired phones are kept. HAMORA Bridge doesn’t update itself. The uninstall script that comes with the installer removes HAMORA Bridge and keeps your settings, or deletes them too with --purge. With the .deb package, apt remove keeps your settings, and apt purge deletes them and the hamora user.

4. If the computer runs a firewall

   Allow HAMORA Bridge’s port from your own network only, using your network’s range. If WSJT-X runs on another computer, allow UDP port 2237 the same way. HAMORA Bridge never changes firewall settings itself. Never forward port 8765 or 2237 on your router.

   sudo ufw allow from 192.168.1.0/24 to any port 8765 proto tcp

   Copy

After installing, everything happens on HAMORA Bridge’s setup page, in a browser. HAMORA Bridge serves it itself, on your own network: no HAMORA account and no internet are needed. The first visit opens a guided setup in five steps. Everything technical, such as Hamlib models, serial speeds and ports, waits under Advanced, and a normal setup never needs it.

1. Station computer

   Give your station a name, such as “Shack”.

2. Detect radio

   Plug in your radio’s USB cable and turn the radio on. The page shows what it found, such as “Possible radio: Icom IC-7300”. Press Test Radio; when it shows your frequency and mode, press Use This Radio. If Hamlib’s rigctld already runs on the computer, choose Use it. No radio yet? Press Next and add it later.

3. Station software

   WSJT-X appears by itself when it sends to HAMORA Bridge; otherwise the page shows the two settings to type into WSJT-X. Dire Wolf on the same computer is found by itself. Both are optional.

4. Pair HAMORA

   Press Pair HAMORA. Scan the QR code with your phone’s camera, which opens HAMORA, or in HAMORA open More→HAMORA Bridge and type the 6-digit code.

5. Ready

   A last check of everything. Press Finish.

Pairing by QR code or 6-digit code

Only phones you pair can see your station. A pairing code is 6 digits, works once and expires after 10 minutes. HAMORA shows HAMORA Bridge’s address to compare with the page before you confirm. Each phone gets its own pairing, kept in the phone’s secure storage, and you can remove any phone at any time: in HAMORA, or on the setup page under Devices.

Check Station

The setup page shows HAMORA Bridge’s health: Ready, Needs setup or Needs attention. Check Station tests the whole chain and lists each part with what to do, for example “Radio · Not responding — check that the radio is on and its USB cable is connected”. Optional things that are off, such as WSJT-X or MQTT, never count as problems. In HAMORA, More→HAMORA Bridge shows the same health.

For support, Advanced → Download diagnostics saves a file with HAMORA Bridge’s version, settings and recent log. It never contains passwords, codes, tokens or radio traffic.

More in the HAMORA Bridge guide.

• Raspberry Pi is HAMORA Bridge’s main target.
• HAMORA Bridge hasn’t run on Raspberry Pi hardware yet, so no Pi CPU or memory figures have been measured. On a Mac it idles at about 0.3 % of a core and about 50 MB of memory. A Pi core is several times slower, so expect a few percent: that’s an estimate.
• HAMORA Bridge keeps up to 24 hours of APRS RF stations, tracks and messages in memory, with fixed limits: about 70 MB for the whole of HAMORA Bridge at the limit on a Mac. If memory is tight, as on a Pi Zero 2 W with 512 MB, check its use on yours.
• Dire Wolf, for APRS RF, runs comfortably on a Pi 3 or newer.
• Debian’s Hamlib can lag behind the latest Hamlib. A very new radio may need a newer Hamlib.
• HAMORA hasn’t been tested with physical radios yet, so no radio model is listed as supported. See Compatibility.
• Keep HAMORA Bridge on your own network. Never forward its port (8765) on your router.

A checksum shows that the file you downloaded is exactly the file HAMORA published, unchanged on the way. Each release on this page is published with the SHA-256 checksum of every file, next to the file.

1. Work out the file’s checksum

   In a terminal on the Pi:

   sha256sum <file name>

   Copy

   Replace <file name> with the name of the file you downloaded.

2. Compare it with the published checksum

   It prints a long string of letters and digits. It must match the SHA-256 published here for that file exactly. If it doesn’t, don’t open the file: delete it and download it again from this page.

Published checksums

Checking on another computer

If you download the file on a different computer, check it there before copying it:

• On a Mac, in Terminal: shasum -a 256 ~/Downloads/<file name>
• On Windows, in PowerShell: Get-FileHash .\<file name> -Algorithm SHA256