Installation

Setting up the full DeskRadar system from scratch.

Prerequisites

Hardware

Software

Step 1 — Install MatrixPortal Firmware

This step is done from your Mac or Linux machine, not the Pi.

  1. Ensure CircuitPython is already installed on the MatrixPortal S3. If not, download the latest .uf2 file from circuitpython.org and drag it onto the device's boot drive.
  2. Clone the firmware repository: 
    git clone https://github.com/deskradario/deskradar-matrixportals3.git
cd deskradar-matrixportals3
  3. Connect the MatrixPortal S3 via USB-C. It will appear as CIRCUITPY at /Volumes/CIRCUITPY/.
  4. Edit src/wifi.txt — set line 1 to your WiFi SSID and line 2 to your password. For initial setup on the Pi's AP, use: 
    deskradar
deskradaradsb
  5. Copy all files to the device: 
    ./install.sh
  6. The device reboots. Check the serial console (screen /dev/tty.usbmodem* 115200) to confirm it connects to WiFi and prints its IP address.

Step 2 — Raspberry Pi Base Setup

  1. Flash Raspberry Pi OS (Bookworm, 64-bit) to a microSD card and boot the Pi.
  2. Install Python 3.13: 
    sudo apt update
sudo apt install -y python3.13 python3.13-venv python3.13-dev
sudo apt install -y i2c-tools git nmcli
  3. Enable I2C in raspi-config: 
    sudo raspi-config

    Navigate to Interface Options → I2C → Enable.

  4. Install and start dump1090 (if not already running): 
    sudo apt install -y dump1090-fa
sudo systemctl enable dump1090-fa
sudo systemctl start dump1090-fa

    Verify it's serving data: curl http://127.0.0.1:8080/data/aircraft.json

  5. Connect the I2C LCD to the Pi's GPIO I2C pins (SDA/SCL on pins 3/5). Verify detection: 
    sudo i2cdetect -y 1

    You should see address 7c in the output.

Step 3 — Deploy Pi Services

  1. Clone the services repository: 
    sudo git clone https://github.com/deskradario/deskradar-pi-services.git /opt/deskradar-pi-services
cd /opt/deskradar-pi-services
  2. Create the virtual environment and install dependencies: 
    python3.13 -m venv .venv
.venv/bin/pip install -r requirements.txt
  3. Set up mDNS and sudoers (run once): 
    bash configurator/setup_mdns.sh

    The Pi is now reachable as deskradar.local.

  4. Set up the WiFi access point (run once): 
    bash scripts/setup_ap.sh
  5. Create the config directory and default config: 
    sudo mkdir -p /etc/deskradar
sudo cp configurator/config.json /etc/deskradar/config.json
  6. Edit the config to set your location: 
    sudo nano /etc/deskradar/config.json

    Set LAT and LON to your coordinates.

  7. Install and enable the systemd services: 
    bash install_services.sh

Step 4 — Deploy Main deskradar App

  1. Clone the main application: 
    sudo git clone https://github.com/deskradario/deskradar.git /opt/deskradar
cd /opt/deskradar
  2. Create the virtual environment and install dependencies: 
    python3.13 -m venv .venv
.venv/bin/pip install -r requirements.txt
  3. Verify the config file is in place: 
    cat /etc/deskradar/config.json

Step 5 — First Boot

  1. Connect the MatrixPortal S3 to the 64×64 LED matrix and power both on.
  2. Make sure the MatrixPortal has joined the Pi's AP (deskradar SSID) — its wifi.txt should already have these credentials from Step 1.
  3. Reboot the Pi: 
    sudo reboot
  4. The LCD display will show status messages as the Pi boots:
    • LCD service starts first
    • Boot check resolves deskradar-portal.local and shows the MatrixPortal's IP
    • Main app starts and begins sending data to the matrix
  5. Check service status: 
    sudo systemctl status deskradar deskradar-lcd deskradar-configurator deskradar-bootstrap
  6. Watch live logs: 
    sudo journalctl -u deskradar -f

Step 6 — Switch to Home WiFi

For production use, you'll want both the Pi and the MatrixPortal on your home network instead of the Pi's AP.

  1. Connect your laptop/phone to the Pi's AP network (deskradar / deskradaradsb).
  2. Open http://10.42.0.50:5000 in a browser.
  3. Enter your home WiFi SSID and password and submit.
  4. The configurator connects the Pi to your home network, writes the credentials to the MatrixPortal's wifi.txt via the CIRCUITPY mount, and triggers a reboot.
  5. After rebooting, both devices should appear on your home network. The Pi is reachable as deskradar.local.
If the WiFi switch fails, the Pi automatically restores the deskradarAP access point and reboots. You can reconnect to the AP and try again.

Ongoing Configuration

Once on your home network, access the web configurator at:

http://deskradar.local:5000/config

From here you can adjust display radius, altitude threshold, fade factor, location, and other settings. Saving restarts the main app automatically.

Troubleshooting

LCD shows "resolving..." indefinitely

The boot check cannot find deskradar-portal.local. Check that the MatrixPortal S3 is powered on and connected to the same network as the Pi. Verify with:

ping deskradar-portal.local

If it's unreachable, check the MatrixPortal's serial console for WiFi connection errors.

Matrix display is blank

Check that MATRIX_HTTP_URL in /etc/deskradar/config.json contains the correct IP. Verify the MatrixPortal is reachable:

curl http://<matrix-ip>/ping

Check the main app logs: sudo journalctl -u deskradar -n 50

No aircraft appearing

Confirm dump1090 is receiving data:

curl http://127.0.0.1:8080/data/aircraft.json | python3 -m json.tool | head -30

Check that LAT, LON, and DISPLAY_RADIUS_NM are set correctly for your location. Aircraft must be within the configured radius and above MIN_ALT.

Web configurator unreachable

sudo systemctl status deskradar-configurator
sudo journalctl -u deskradar-configurator -n 30

I2C LCD not detected

sudo i2cdetect -y 1

Address 7c should appear. If not, check wiring (SDA=pin 3, SCL=pin 5, 3.3V power). Some LCD backpacks use address 27 or 3f — if yours differs, update the address in lcd/lib/LCD1602.py.

MatrixPortal keeps rebooting

The 60-second watchdog reboots the device if no request arrives. If the main deskradar app is not running or cannot reach the MatrixPortal, the device will repeatedly reboot. Ensure deskradar.service is running and MATRIX_HTTP_URL is correct.

WiFi switch left Pi on AP mode

The switch failed and the Pi restored the AP. Connect to deskradar SSID and try again via http://10.42.0.50:5000. Check sudo journalctl -u deskradar-configurator -n 50 for the failure reason.