PiTrac Installation Guide

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

Important: 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)
  • ActiveMQ message broker
  • 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 (recommended)
    • Raspberry Pi 4 with 8GB RAM also supported
  • Raspberry Pi OS 64-bit installed and configured (Bookworm or Trixie)
  • 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)
  • Extracts pre-built libraries (OpenCV, ActiveMQ, lgpio)
  • Compiles PiTrac C++ binary
  • Installs web server and services
  • Configures cameras and message broker

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:

  • Using CLI commands
  • Managing services (web server, ActiveMQ)
  • 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
  • Service issues (web server, ActiveMQ)
  • 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)

System Architecture

Understanding what PiTrac installs helps with troubleshooting:

Services

  • activemq.service - Message broker (system service)
  • pitrac-web.service - Web dashboard (system service)
  • 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 templates
~/.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.11.0, ActiveMQ-CPP 3.9.5, lgpio 0.2.2, msgpack, ONNX Runtime
  • Python packages: FastAPI, uvicorn, stomp.py, websockets, and more

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: pitrac web logs or journalctl -u pitrac-web
  • Verify prerequisites were completed

Community support:

CLI help:

pitrac help       # Show all commands
pitrac status     # Check service status

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               │
└─────────────────────────────────────┘

Return To

Table of contents

Back to top

Page last modified: Jan 4 2025 at 12:00 AM.