This step-by-step guide installs APRS-PropView inside a virtual Python environment to prevent conflicts with other ham radio tools. It configures the app as a manual system service controlled via desktop menu entries.

Prerequisites

Ensure your Raspberry Pi OS is updated and has Python 3.11 or higher installed. You can verify your version with:

python3 --version

Step 1: Clone the Repository & Setup Environment

Open your terminal and run the following commands to download the source files and create an isolated virtual python environment (venv):

cd ~
git clone https://github.com/RF-YVY/APRS-PropView.git
cd APRS-PropView
python3 -m venv venv
source venv/bin/activate

(You will see a (venv) prefix in your terminal, indicating the isolated environment is active.)

Now, install all the required Python modules:

pip install -r requirements.txt

Step 2: The Headless / USB-C Gadget Browser Fix

By default, APRS-PropView automatically triggers a local web browser on startup. If you operate your Pi headless (e.g., running as a mobile USB-C Gadget controlled entirely via a browser on an iPad), this automated trigger causes the system to hang, trying to launch a text-based terminal browser (w3m or lynx).

To prevent this loop, we disable the automated browser launch task:

1. Open the main file in the text editor:

   nano main.py

2. Scroll down near the bottom of the file and locate the following line:

   tasks.append(asyncio.create_task(open_browser()))

3. Comment this line out by adding a # at the very beginning:

   # tasks.append(asyncio.create_task(open_browser()))

4. Save and exit (Press CTRL+O, Enter, then CTRL+X).

Step 3: Configure the Background Service (No Autostart)

To ensure the app doesn’t capture your serial/TCP TNC ports automatically upon booting, we create a systemd service that remains completely manual.

Create the service file:

sudo nano /etc/systemd/system/aprs-propview.service

Paste the following configuration into the file:

[Unit]
Description=APRS PropView Service
After=network.target

[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi/APRS-PropView
Environment="PATH=/home/pi/APRS-PropView/venv/bin"
ExecStart=/home/pi/APRS-PropView/venv/bin/python main.py
KillSignal=SIGINT

[Install]
WantedBy=multi-user.target

(Note: We use KillSignal=SIGINT to cleanly shut down the webserver using the equivalent of a CTRL+C command when stopping the service.)

Save and exit (CTRL+O, Enter, CTRL+X), then reload the system manager configuration:

sudo systemctl daemon-reload

Step 4: Create Desktop START and STOP Menu Buttons

Now we map the terminal service controls into clean, clickable desktop buttons inside the Raspberry Pi’s Internet menu category.

1. Create the START Switch:

nano ~/.local/share/applications/aprs-start.desktop

Add this content:

[Desktop Entry]
Name=APRS PropView START
Comment=Starts the APRS-PropView Server
Exec=sudo systemctl start aprs-propview.service
Icon=network-transmit-receive
Terminal=false
Type=Application
Categories=Network;

2. Create the STOP Switch:

nano ~/.local/share/applications/aprs-stop.desktop

Add this content:

[Desktop Entry]
Name=APRS PropView STOP
Comment=Stops the APRS-PropView Server
Exec=sudo systemctl stop aprs-propview.service
Icon=network-offline
Terminal=false
Type=Application
Categories=Network;

What’s Next in Practice?

Once you have completed the setup, you no longer need to type cryptic commands into the terminal. Simply click on APRS PropView START under the Internet category in your Raspberry Pi menu.

The tool starts completely quietly and invisibly in the background. Now grab your iPad (or notebook), type your Pi’s IP address followed by the port into the browser (e.g., http://172.0.0.1:14501, and you will have the entire dashboard, the live map with animated path lines, and the propagation meters crystal clear on your screen!

Do you want to stop the tool to free up the interface exclusively for YAAC or graywolf again? A single click on APRS PropView STOP in the menu is enough, and the port is immediately available.