Skip to content

Developer Guide

Welcome to the PiTrac development documentation. This guide covers developing, building, packaging, and maintaining PiTrac.

  • System Overview

    Architecture, core components, data flow, and design principles.

    Overview

  • Configuration

    Three-tier configuration system, web UI settings, and the C++ ConfigurationManager.

    Configuration

  • Service Architecture

    The pitrac-web systemd service, pitrac_lm process lifecycle, and how the web server manages everything.

    Services

  • Testing

    Web UI testing suite, Python pytest tests, and C++ test infrastructure.

    Testing

  • Dependencies

    Library versions, build-from-source dependencies, and platform differences.

    Dependencies

Quick Start for Developers

Prerequisites

  • Raspberry Pi 5 with 8GB RAM (for native development)
  • Ubuntu/Debian Linux (for cross-compilation)
  • Docker installed (for containerized builds)
  • Git
  • Basic familiarity with C++, Bash, and Linux systems

Getting Started

1. Clone the repository:

git clone --recursive https://github.com/pitraclm/pitrac.git
cd PiTrac

2. Build and install on the Pi:

cd packaging
sudo ./build.sh dev    # Build and install locally

3. Make changes and test:

# Edit source files in Software/LMSourceCode/ImageProcessing/
sudo ./build.sh dev         # Incremental rebuild

Development Workflow

1. Fork and Setup

# Fork the repository on GitHub, then:
git clone --recursive https://github.com/YOUR_USERNAME/PiTrac.git
cd PiTrac
git remote add upstream https://github.com/pitraclm/pitrac.git

2. Develop

git fetch upstream
git checkout main
git merge upstream/main
git checkout -b feature/your-feature-name

3. Test

Access the web UI at http://your-pi-ip:8080 and use the Testing section, or run Python tests directly:

cd Software/web-server
python -m pytest tests/

4. Submit

git push origin feature/your-feature-name

Create a pull request from your fork to upstream main.

Project Structure

PiTrac/
├── Software/
│   ├── LMSourceCode/ImageProcessing/   # Core C++ code (pitrac_lm)
│   └── web-server/                     # Python FastAPI web server
├── packaging/
│   ├── build.sh                        # Main build script
│   ├── build-apt-package.sh            # APT package creator
│   ├── bashly.yml                      # CLI specification
│   ├── generate.sh                     # CLI generator
│   ├── src/                            # CLI command implementations
│   ├── scripts/                        # Build helper scripts
│   └── templates/                      # Config and service templates
├── docs/                               # Source documentation
└── Hardware/                           # 3D models and PCB designs

Getting Help