Skip to content

PiTrac Installation Guide

Install the PiTrac software on your Raspberry Pi and start tracking golf shots.

Prerequisites Required

Complete Raspberry Pi Setup before installing PiTrac. Your Pi must have the OS installed, be updated, and have network access.

Installation Overview

What you'll install:

  • PiTrac launch monitor binary (C++)
  • Web dashboard and configuration interface (Python/FastAPI)
  • Camera libraries and configuration
  • Test resources and calibration tools

Time required: 10--20 minutes (building from source)

Difficulty: Intermediate (script-automated)

Prerequisites

Before starting, ensure you have:

  • Raspberry Pi 5 with 8GB RAM
  • Raspberry Pi OS 64-bit installed and configured (Trixie / Debian 13)
  • Active internet connection for downloading packages
  • Sudo privileges on your Pi
  • At least 5GB free disk space (10GB recommended for development)

Critical

You must have completed the Raspberry Pi Setup before proceeding. This includes OS installation, system updates, and network configuration.

Installation Methods

Choose the installation method that fits your needs:

Build from Source Guide

Building from source is currently the recommended method. Ideal for:

  • Getting the latest features
  • Development and customization
  • Understanding the build process

What it does:

  • Clones PiTrac repository from GitHub
  • Installs system dependencies (~80 packages)
  • Installs pre-built libraries (OpenCV, lgpio)
  • Compiles PiTrac C++ binary
  • Installs web server and services
  • Configures cameras

Time: 10--20 minutes on Pi 5 (first install, network-dependent)

APT Package Installation

Coming Soon: PiTrac will be available as a Debian package for easy installation via apt.

# Future installation (not yet available)
sudo apt update
sudo apt install pitrac

This will provide:

  • One-command installation
  • Automatic dependency resolution
  • System updates through apt upgrade
  • Simpler for end users

Status: Package infrastructure in development. Check GitHub Releases for availability.

After Installation

Once PiTrac is installed, follow these guides in order:

Step 1: First Use

First Use Guide

Learn how to:

  • Access the web dashboard
  • Start the PiTrac process
  • Navigate the web interface
  • Make your first shot
  • Understand shot data

Time: ~10 minutes

Step 2: Managing PiTrac

Managing PiTrac Guide

Essential knowledge for:

  • Managing the web server service
  • Understanding file locations
  • Updating PiTrac
  • Development workflow
  • Backup and restore

Reference guide -- bookmark for when needed

Step 3: Troubleshooting (If Needed)

Troubleshooting Guide

Solutions for:

  • Build failures
  • Web server issues
  • Camera detection problems
  • Web interface access
  • Shot detection issues
  • Performance problems

Use when needed -- comprehensive problem-solving reference

Quick Start Path

For experienced users who want the essentials:

  1. Build from Source 

    git clone https://github.com/PiTracLM/PiTrac.git
cd PiTrac/packaging
sudo ./build.sh dev

  2. First Use

    • Access web dashboard: http://raspberrypi.local:8080
    • Start PiTrac from web interface
    • Hit test shots

  3. Calibrate (after first use)

    • Run Calibration Wizard in web interface
    • See Cameras for details

System Architecture

Understanding what PiTrac installs helps with troubleshooting:

Services

  • pitrac-web.service -- Web dashboard (system service, uses DynamicUser=yes)
  • pitrac_lm process -- Launch monitor (controlled via web UI, NOT a service)

Key Directories

/usr/lib/pitrac/          # Binaries and web server
/etc/pitrac/              # System configuration and models
~/.pitrac/config/         # Your configuration and calibration
~/.pitrac/logs/           # Application logs
~/LM_Shares/Images/       # Captured shot images

Dependencies

  • System packages: ~80 packages (Boost, libcamera, FFmpeg, Python, etc.)
  • Pre-built libraries: OpenCV 4.13.0, lgpio 0.2.2
  • Python packages: FastAPI, uvicorn, python-multipart, jinja2, pillow, pyyaml, aiofiles, websockets, spidev, gpiozero

What's Next?

After completing installation:

Essential:

  1. First Use Guide -- Access web interface and make first shot
  2. Calibration Wizard -- Run through web interface for accurate measurements

Optional:

Reference:

Getting Help

For installation issues:

  • Check the Troubleshooting Guide first
  • Review logs via the web dashboard (3-dot menu > Logs) or journalctl -u pitrac-web
  • Verify prerequisites were completed

Community support:

Installation Workflow

+-------------------------------------+
|  Prerequisites Complete?            |
|  - Pi OS installed                  |
|  - System updated                   |
|  - Network configured               |
+-----------------+-------------------+
                  |
                  v
+-------------------------------------+
|  Build from Source                   |
|  - Clone repository                 |
|  - Run build.sh dev                 |
|  - 10-20 minutes                    |
+-----------------+-------------------+
                  |
                  v
+-------------------------------------+
|  First Use                          |
|  - Access web dashboard             |
|  - Start PiTrac                     |
|  - Make first shot                  |
+-----------------+-------------------+
                  |
                  v
+-------------------------------------+
|  Calibration                        |
|  - Run Calibration Wizard           |
|  - Verify accuracy                  |
|  - Fine-tune settings               |
+-------------------------------------+