diff --git a/Software/web-server/requirements.txt b/Software/web-server/requirements.txt index 13caa926..bea8e344 100644 --- a/Software/web-server/requirements.txt +++ b/Software/web-server/requirements.txt @@ -1,10 +1,10 @@ -fastapi==0.104.1 -uvicorn[standard]==0.24.0 -python-multipart==0.0.6 -jinja2==3.1.2 -msgpack==1.0.7 +fastapi==0.120.4 +uvicorn[standard]==0.38.0 +python-multipart==0.0.20 +jinja2==3.1.6 +msgpack==1.1.2 stomp.py==8.2.0 -pillow==10.1.0 -pyyaml==6.0.1 -aiofiles==23.2.1 -websockets==12.0 +pillow==11.3.0 +pyyaml==6.0.3 +aiofiles==25.1.0 +websockets==15.0.1 diff --git a/docs/_config.yml b/docs/_config.yml index db615ea7..601d4157 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -39,6 +39,23 @@ plugins: feed: excerpt_only: true +# SEO and Social Media +author: PiTrac Community +social: + name: PiTrac + links: + - https://github.com/pitraclm/pitrac + - https://discord.gg/j9YWCMFVHN + - https://www.youtube.com/@PiTrac + +# Default front matter +defaults: + - scope: + path: "" + values: + image: /assets/images/logos/PiTrac_Square.png + author: PiTrac Community + search: # Split pages into sections that can be searched individually # Supports 1 - 6, default: 2 diff --git a/docs/getting-started.md b/docs/build-guide.md similarity index 88% rename from docs/getting-started.md rename to docs/build-guide.md index 76b74467..20650ee6 100644 --- a/docs/getting-started.md +++ b/docs/build-guide.md @@ -1,11 +1,14 @@ --- -title: Getting Started +title: Build Your PiTrac layout: default nav_order: 2 -description: Step-by-step guide to building and setting up your PiTrac golf launch monitor +description: Complete step-by-step guide to building your PiTrac DIY golf launch monitor from ordering parts to tracking your first shot. Hardware assembly, software installation, and camera calibration included. +keywords: build golf launch monitor, DIY launch monitor tutorial, raspberry pi golf setup, launch monitor assembly guide, golf tracker build instructions +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 --- -# Getting Started with PiTrac +# Build Your PiTrac Welcome to PiTrac! This guide will walk you through the complete process of building your own DIY golf launch monitor. diff --git a/docs/camera/auto-calibration.md b/docs/camera/auto-calibration.md index eca6f1ae..92d0432f 100755 --- a/docs/camera/auto-calibration.md +++ b/docs/camera/auto-calibration.md @@ -3,6 +3,10 @@ title: Auto-Calibration layout: default nav_order: 2 parent: Cameras +description: Automatic camera calibration guide for PiTrac using the built-in calibration wizard to determine focal length and camera angles for accurate ball tracking. +keywords: automatic camera calibration, golf camera calibration wizard, focal length calibration, camera angle setup, launch monitor calibration +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 --- # Auto-Calibration diff --git a/docs/camera/camera-calibration.md b/docs/camera/camera-calibration.md index 28c96c96..81310256 100644 --- a/docs/camera/camera-calibration.md +++ b/docs/camera/camera-calibration.md @@ -3,6 +3,10 @@ title: Camera Calibration layout: default nav_order: 1 parent: Cameras +description: Manual camera calibration guide for PiTrac including tape measure method, manual focal length calculation, and advanced calibration techniques for accurate ball tracking. +keywords: manual camera calibration golf, tape measure calibration, focal length calculation, camera angle measurement, calibration troubleshooting +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 --- # PiTrac - Camera Calibration diff --git a/docs/camera/cameras.md b/docs/camera/cameras.md index 870b38a1..f4c7457d 100644 --- a/docs/camera/cameras.md +++ b/docs/camera/cameras.md @@ -1,8 +1,12 @@ --- title: Cameras layout: default -nav_order: 5 +nav_order: 6 has_children: true +description: Complete guide to camera selection, configuration, and calibration for PiTrac golf launch monitor including global shutter cameras, IMX296 sensors, and camera setup. +keywords: raspberry pi global shutter camera, IMX296 camera golf, pi camera setup, camera configuration launch monitor, libcamera golf, golf camera calibration +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 --- # Camera System diff --git a/docs/contributors.md b/docs/contributors.md index 8dea960b..7fd8738d 100644 --- a/docs/contributors.md +++ b/docs/contributors.md @@ -1,8 +1,12 @@ --- -title: Contributors and Attribution +title: Contributors layout: default -nav_order: 1.5 +nav_order: 1.4 parent: Home +description: PiTrac project contributors and attribution for open-source technologies including OpenCV, libcamera, ActiveMQ, and other software used in the golf launch monitor. +keywords: pitrac contributors, open source attribution, golf project team, technology credits, opensource golf +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 --- # Contributors and Attribution diff --git a/docs/development/index.md b/docs/development/index.md index 574c944b..87f6916a 100644 --- a/docs/development/index.md +++ b/docs/development/index.md @@ -4,6 +4,10 @@ title: Development Guide nav_order: 10 has_children: true permalink: /development/ +description: Complete PiTrac development guide for contributors including build system, packaging, CLI interface, testing framework, and architecture documentation. +keywords: pitrac development, contribute to pitrac, build pitrac source, docker development, apt packaging, raspberry pi development +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 --- # PiTrac Development Guide diff --git a/docs/errata.md b/docs/errata.md index d4fcc90b..c89c4bac 100755 --- a/docs/errata.md +++ b/docs/errata.md @@ -1,8 +1,12 @@ --- -title: Errata and Future Hopes +title: Known Issues layout: default -nav_order: 1.4 +nav_order: 1.3 parent: Home +description: Known issues, limitations, and future development hopes for PiTrac golf launch monitor including current errata and planned improvements. +keywords: pitrac known issues, launch monitor limitations, golf tracker problems, pitrac future features, development plans +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 --- # Errata and Future Hopes for the DIY LM diff --git a/docs/glossary.md b/docs/glossary.md index 085eee55..1f587280 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -2,8 +2,10 @@ title: Glossary layout: default nav_order: 100 -description: Technical terms and definitions used throughout PiTrac documentation, based on terms found in the existing documentation. -keywords: PiTrac glossary, technical terms, golf launch monitor terminology +description: Technical terms and definitions used throughout PiTrac documentation including golf launch monitor terminology, camera concepts, and software components. +keywords: PiTrac glossary, technical terms, golf launch monitor terminology, golf tech definitions, launch monitor glossary +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 --- # Glossary diff --git a/docs/hardware/3d-printing.md b/docs/hardware/3d-printing.md index 1cbc0d2a..3a008b0a 100644 --- a/docs/hardware/3d-printing.md +++ b/docs/hardware/3d-printing.md @@ -3,6 +3,10 @@ title: 3D Printing layout: default nav_order: 3 parent: Hardware +description: 3D printing guide for PiTrac enclosure components including STL file downloads, printer requirements, material recommendations, and printing tips for the launch monitor housing. +keywords: 3D print golf enclosure, launch monitor 3D printing, PLA golf project, DIY enclosure printing, STL files golf +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 --- # 3D Printing diff --git a/docs/hardware/hardware.md b/docs/hardware/hardware.md index bc86836a..a2cbde78 100644 --- a/docs/hardware/hardware.md +++ b/docs/hardware/hardware.md @@ -1,8 +1,12 @@ --- title: Hardware layout: default -nav_order: 3 +nav_order: 4 has_children: true +description: Complete hardware build guide for PiTrac golf launch monitor including parts list, PCB assembly, 3D printing enclosure, and final assembly instructions. +keywords: DIY golf hardware, launch monitor parts, raspberry pi golf components, PCB assembly golf, 3D print golf enclosure +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 --- # Hardware diff --git a/docs/hardware/pcb-assembly.md b/docs/hardware/pcb-assembly.md index 3d1f69e8..a2c2d3c3 100644 --- a/docs/hardware/pcb-assembly.md +++ b/docs/hardware/pcb-assembly.md @@ -3,6 +3,10 @@ title: PCB Assembly layout: default nav_order: 4 parent: Hardware +description: Complete guide to ordering and assembling the PiTrac Connector Board PCB, including manufacturing options, component sourcing, and assembly instructions for the custom circuit board. +keywords: PCB assembly launch monitor, custom golf PCB, raspberry pi PCB, DIY circuit board, launch monitor electronics, JLCPCB assembly +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 --- # Connector Board diff --git a/docs/index.md b/docs/index.md index 3b69d502..0f5fb1ff 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,7 +3,9 @@ title: Home layout: home nav_order: 1 description: PiTrac - Open source DIY golf launch monitor using Raspberry Pi and global shutter cameras. Build your own golf simulator with ball speed, launch angle, and spin tracking. -keywords: golf launch monitor, DIY golf simulator, raspberry pi golf, open source launch monitor, golf ball tracking, launch angle measurement, spin rate measurement +keywords: golf launch monitor, DIY golf simulator, raspberry pi golf, open source launch monitor, golf ball tracking, launch angle measurement, spin rate measurement, build golf launch monitor, homemade launch monitor +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 --- ![PiTrac Logo]({{ '/assets/images/logos/PiTrac.png' | relative_url }}){: width="300"} @@ -38,7 +40,7 @@ We are hoping to inspire a community of developers to help test and continue PiT ## Documentation Sections -- **[Getting Started]({% link getting-started.md %})** - Learn about PiTrac, project status, and roadmap +- **[Build Your PiTrac]({% link build-guide.md %})** - Complete build guide from parts to first shot - **[Hardware]({% link hardware/hardware.md %})** - Parts list, assembly guides, and 3D printing - **[Software]({% link software/software.md %})** - Raspberry Pi setup, configuration, and startup - **[Integration]({% link simulator-integration.md %})** - Connect to golf simulators and third-party systems diff --git a/docs/quickstart.md b/docs/quickstart.md index a8f925ee..5aedfc68 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,13 +1,16 @@ --- -title: Quickstart +title: Express Path layout: default nav_order: 3 -description: Get PiTrac running fast - install software, configure cameras, calibrate, and start tracking shots +description: Fast-track setup for experienced users - streamlined installation, configuration, and calibration to get your PiTrac tracking shots quickly. Assumes hardware is assembled. +keywords: quick start launch monitor, fast setup golf tracker, raspberry pi golf quick install, launch monitor express setup +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 --- -# Quickstart Guide +# Express Path Setup -So you've built your PiTrac hardware and you're ready to start smacking some golf balls. This guide walks you through the essential steps to get from bare Raspberry Pi to tracking shots. +**For experienced users.** Streamlined setup to get your PiTrac tracking shots quickly. If you're new to Raspberry Pi or want detailed explanations, use the [Build Your PiTrac]({% link build-guide.md %}) guide instead. ## What You'll Need @@ -19,7 +22,7 @@ Before starting, make sure you have: - Network connection (Ethernet cable highly recommended for faster setup) - Computer to access the Pi remotely -**Don't have hardware yet?** Check out the full [Getting Started]({% link getting-started.md %}) guide. +**Don't have hardware yet?** Check out the full [Build Your PiTrac]({% link build-guide.md %}) guide. --- diff --git a/docs/roadmap.md b/docs/roadmap.md index af3a9a72..b7966dc4 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,8 +1,12 @@ --- title: Roadmap layout: default -nav_order: 1.3 +nav_order: 1.2 parent: Home +description: PiTrac development roadmap and project status including hardware versions, software features, and future development plans for the open-source golf launch monitor. +keywords: pitrac roadmap, launch monitor development, golf project status, pitrac versions, future features golf +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 --- # PiTrac Roadmap (as of June 23, 2025) diff --git a/docs/simulator-integration.md b/docs/simulator-integration.md index d85e6a5b..1b1b6c21 100644 --- a/docs/simulator-integration.md +++ b/docs/simulator-integration.md @@ -1,7 +1,11 @@ --- title: Simulator Integration layout: default -nav_order: 5 +nav_order: 7 +description: Connect PiTrac golf launch monitor to E6 Connect, GSPro, and TruGolf simulators. Complete network setup, configuration, and integration guide for golf simulation software. +keywords: connect golf simulator, gspro integration, e6 connect setup, trugolf pitrac, golf simulator network, launch monitor integration +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 --- # Connecting to Golf Simulators diff --git a/docs/software/install/build-from-source.md b/docs/software/install/build-from-source.md new file mode 100644 index 00000000..9e8034ad --- /dev/null +++ b/docs/software/install/build-from-source.md @@ -0,0 +1,322 @@ +--- +title: Build from Source +layout: default +nav_order: 1 +parent: PiTrac Installation +grand_parent: Software +description: Complete guide to building PiTrac from source including cloning repository, running developer build, and verifying installation on Raspberry Pi. +keywords: build pitrac source, compile pitrac, developer build raspberry pi, install pitrac from git, pitrac build script +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 +--- + +# Build PiTrac from Source + +Building from source is the current recommended installation method. It's ideal for development or if you want the latest features. + +**Time Required:** 10-20 minutes on a Pi 5 (first installation, network-dependent) + +**Difficulty:** Intermediate (script-automated, but requires command line comfort) + +--- + +## Prerequisites + +Before starting, ensure you have: + +- **Raspberry Pi 5 with 8GB RAM** (recommended) or Pi 4 with 8GB +- **Raspberry Pi OS 64-bit** installed (Bookworm or Trixie) + - See [Pi Setup Guide]({% link software/pi-setup.md %}) if not installed +- **Active internet connection** for downloading packages +- **Sudo privileges** on your Pi +- **At least 5GB free disk space** (10GB recommended) + +{: .warning } +**Important**: You must complete [Raspberry Pi Setup]({% link software/pi-setup.md %}) before proceeding. The Pi must have OS installed, be updated, and have network access. + +--- + +## Overview + +The build process automatically: +- Installs all required system dependencies (~80+ packages) +- Extracts pre-built libraries (OpenCV, ActiveMQ, lgpio, msgpack) +- Compiles the PiTrac C++ binary +- Installs the Python web server and all dependencies +- Configures ActiveMQ message broker +- Sets up libcamera for dual Pi cameras +- Creates user directories and configuration files + +--- + +## Step 1: Clone the Repository + +Clone the PiTrac repository using HTTPS: + +```bash +git clone https://github.com/PiTracLM/PiTrac.git +cd PiTrac +``` + +{: .note } +We use HTTPS instead of SSH to avoid requiring SSH key setup. Contributors can switch to SSH after cloning: `git remote set-url origin git@github.com:PiTracLM/PiTrac.git` + +--- + +## Step 2: Run the Developer Build + +Navigate to the packaging directory and run the developer installation: + +```bash +cd packaging +sudo ./build.sh dev +``` + +{: .warning } +**Important**: You must use `sudo` as the script installs system packages and configures services. + +--- + +## What Happens During Installation + +The `build.sh dev` script performs these steps automatically: + +### 1. Platform Validation + +- Verifies you're running on a Raspberry Pi +- Checks for sudo privileges +- Confirms all pre-built artifacts are available + +### 2. System Configuration + +- Fixes known Pi OS issues (initramfs configuration bug) +- Updates package state +- Prepares the system for installation + +### 3. Dependency Installation + +**System Packages Installed** (~80+ packages): +- Build tools: `build-essential`, `meson`, `ninja-build`, `pkg-config` +- Boost libraries (1.74.0): `libboost-system`, `libboost-thread`, `libboost-filesystem`, and many others +- Camera libraries: `libcamera0.0.3`, `libcamera-dev`, `rpicam-apps` (Pi5) or `libcamera-apps` (Pi4) +- Video processing: FFmpeg libraries, image libraries (JPEG, PNG, TIFF) +- Message broker: `activemq`, `libapr1`, `libaprutil1` +- Python: `python3`, `python3-pip`, and related packages +- Configuration tools: `yq` (YAML query tool) + +**Pre-built Dependencies Extracted**: + +These are extracted from the `packaging/deps-artifacts/` directory: +- **OpenCV 4.11.0** - Computer vision library (Debian only has 4.6.0) +- **ActiveMQ-CPP 3.9.5** - C++ messaging client +- **lgpio 0.2.2** - GPIO library for Pi 5 (not in Debian repos) +- **msgpack-cxx 6.1.1** - Message serialization +- **ONNX Runtime 1.17.3** - AI inference engine + +{: .note } +**Why pre-built?**: Building OpenCV from source takes 45-60 minutes. The pre-built artifacts are checked into the git repository so you don't have to wait. + +### 4. Build PiTrac Binary + +The script compiles the C++ launch monitor binary: +- Sets up proper build environment with library paths +- Applies Boost C++20 compatibility fix +- Detects stale builds and cleans if necessary +- Runs Meson build system with Ninja +- Compiles only changed files (incremental build) + +**Build times**: +- **Total first install**: 10-20 minutes (all dependencies + services + build) +- **PiTrac binary build**: 2-5 minutes +- **Incremental rebuild**: 30 seconds - 2 minutes +- **Clean rebuild** (with `force` flag): 2-5 minutes + +### 5. Installation + +**Binaries and Tools**: +- `/usr/lib/pitrac/pitrac_lm` - Main launch monitor binary +- `/usr/bin/pitrac` - Unified CLI interface (Bashly-generated) +- `/usr/lib/pitrac/ImageProcessing/CameraTools/` - Camera utilities and scripts + +**Configuration**: +- `/etc/pitrac/models/` - ONNX AI models for ball detection +- `/usr/lib/pitrac/web-server/configurations.json` - Configuration metadata (283 settings) + +**Test Resources**: +- `/usr/share/pitrac/test-images/` - Sample test images (teed-ball.png, strobed.png) +- `/usr/share/pitrac/test-suites/` - Automated test suites + +**User Directories**: +- `~/.pitrac/config/` - User configuration and calibration data + - `user_settings.json` - Your configuration overrides + - `calibration_data.json` - Camera calibration results (focal lengths, angles) + - `generated_golf_sim_config.json` - Merged runtime configuration +- `~/.pitrac/state/` - Runtime state +- `~/.pitrac/calibration/` - Calibration tools (checkerboard images, scripts) +- `~/LM_Shares/Images/` - Captured images from shots +- `~/LM_Shares/WebShare/` - Web-accessible data + +### 6. Camera Configuration + +The script configures libcamera for dual Pi cameras: +- Copies IMX296 NOIR sensor files for your Pi model (4 or 5) +- Creates `rpi_apps.yaml` with extended timeout (1000ms) +- Sets `LIBCAMERA_RPI_CONFIG_FILE` environment variable +- Configures camera detection in boot config + +### 7. ActiveMQ Message Broker Setup + +ActiveMQ provides communication between PiTrac components: +- Installs ActiveMQ configuration from templates +- Sets up broker on `tcp://localhost:61616` (OpenWire protocol) +- Configures STOMP protocol on port 61613 +- Enables and starts the `activemq.service` + +**Verification**: The script checks that ActiveMQ is listening on port 61616. + +### 8. Python Web Server Installation + +The FastAPI-based web dashboard is installed: +- Copies web server code to `/usr/lib/pitrac/web-server/` +- Installs Python dependencies from `requirements.txt`: + - `fastapi` - Modern web framework + - `uvicorn` - ASGI server + - `stomp.py` - ActiveMQ connectivity + - `msgpack`, `pyyaml`, `websockets`, and more +- Configures `pitrac-web.service` to run as your user +- Restarts the service if it was already running + +### 9. Service Configuration + +The script sets up systemd services: +- `activemq.service` - Message broker (system service) +- `pitrac-web.service` - Web dashboard (user service) + +{: .note } +**Note**: The main `pitrac.service` is no longer automatically installed. You control the launch monitor through the web interface Start/Stop buttons. + +### 10. Cleanup and Verification + +- Reloads systemd daemon +- Updates shared library cache (`ldconfig`) +- Displays installation summary + +--- + +## Installation Output + +During installation, you'll see progress like this: + +``` +==================================== + PiTrac Developer Build +==================================== + +✓ Platform validation +✓ Checking for pre-built artifacts +✓ Installing system dependencies (80+ packages) +✓ Extracting OpenCV 4.11.0 +✓ Extracting ActiveMQ-CPP 3.9.5 +✓ Extracting lgpio 0.2.2 +✓ Configuring build environment +✓ Building PiTrac binary (this may take a few minutes) +✓ Installing binaries and tools +✓ Configuring libcamera +✓ Installing test resources +✓ Setting up ActiveMQ broker +✓ Installing Python web server +✓ Configuring services + +==================================== + Installation Complete! +==================================== + +Next steps: + 1. Access web dashboard: http://raspberrypi.local:8080 + 2. Start PiTrac from the web interface + 3. Run tests: pitrac test quick + 4. View status: pitrac status + +For help: pitrac help +``` + +--- + +## Step 3: Verify Installation + +After installation completes, verify everything is working: + +### Check Service Status + +```bash +# Check all services +pitrac status + +# Or check individually +systemctl status activemq +systemctl status pitrac-web +``` + +**Expected output**: +- `activemq.service` - **active (running)** +- `pitrac-web.service` - **active (running)** or **inactive** (can start manually) + +### Test Camera Detection + +```bash +# Pi 5 +rpicam-hello --list-cameras + +# Pi 4 +libcamera-hello --list-cameras +``` + +Should list 2 cameras if both are connected. + +### Run Quick Test + +```bash +pitrac test quick +``` + +This runs basic system tests to verify everything is configured correctly. + +--- + +## Next Steps + +**Installation Complete!** + +**Continue to:** +- **[First Use Guide]({% link software/install/first-use.md %})** - Access web dashboard and start PiTrac + +**Or:** +- **[Troubleshooting]({% link software/install/troubleshooting.md %})** - If you encountered errors + +**Return to:** +- **[Installation Overview]({% link software/pitrac-install.md %})** + +--- + +## Build Modes Reference + +The `build.sh` script supports multiple modes: + +```bash +# Developer install (recommended) +sudo ./build.sh dev + +# Force clean rebuild +sudo ./build.sh dev force + +# Build dependencies only +sudo ./build.sh deps + +# Build PiTrac binary only +sudo ./build.sh build + +# Clean build artifacts +sudo ./build.sh clean +``` + +For more details, see [Managing PiTrac]({% link software/install/managing.md %}). \ No newline at end of file diff --git a/docs/software/install/first-use.md b/docs/software/install/first-use.md new file mode 100644 index 00000000..f52a6cec --- /dev/null +++ b/docs/software/install/first-use.md @@ -0,0 +1,317 @@ +--- +title: First Use +layout: default +nav_order: 2 +parent: PiTrac Installation +grand_parent: Software +description: First-time setup for PiTrac including accessing the web dashboard, starting the launch monitor, and using the web interface for configuration and control. +keywords: pitrac first use, web dashboard access, start pitrac, golf monitor setup, web interface tutorial +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 +--- + +# First Use Guide + +After installing PiTrac, you're ready to access the web interface and start tracking shots! + +**Time Required:** ~10 minutes + +**Difficulty:** Beginner + +--- + +## Step 1: Access the Web Dashboard + +The web interface provides control and monitoring for PiTrac. + +### Start the Web Server + +If not already running: + +```bash +sudo systemctl start pitrac-web +``` + +Or use the CLI: + +```bash +pitrac web start +``` + +### Access the Dashboard + +Open a web browser and navigate to: + +``` +http://[YOUR_PI_IP_ADDRESS]:8080 +``` + +To find your Pi's IP address: + +```bash +hostname -I +``` + +Or use the hostname: + +``` +http://raspberrypi.local:8080 +``` + +{: .note } +**Note**: The default port is 8080. You can change this in the web server configuration if needed. + +--- + +## Step 2: Start PiTrac + +From the web dashboard: + +1. Navigate to the **PiTrac Process** section +2. Click **Start** to launch the launch monitor +3. Monitor the status indicators for Camera 1 and Camera 2 + +The web interface will show: +- Camera connection status +- ActiveMQ broker connectivity +- WebSocket connection to browser +- Real-time shot data when balls are hit + +--- + +## Web Interface Overview + +The PiTrac web dashboard provides comprehensive control across several sections: + +### Main Dashboard + +**Real-time Shot Display**: +- Ball speed and carry distance +- Launch angles (horizontal and vertical) +- Spin rates (backspin and sidespin) +- Shot trajectory visualization + +**System Status Indicators**: +- WebSocket connection status +- ActiveMQ broker connectivity +- Camera 1 and Camera 2 status +- PiTrac process state + +**Shot Images Gallery**: +- Browse captured images from recent shots +- View dual-camera synchronized captures +- Analyze ball position and strobing + +### Configuration + +**Camera Settings**: +- Configure camera types (Pi Global Shutter, Innomaker) +- Lens parameters (focal length, sensor size) +- Camera gain and exposure settings +- Flip and rotation adjustments + +**Detection Methods**: +- **HoughCircles**: Traditional circle detection +- **YOLO**: AI-based ball detection +- **YOLO+SAHI**: Enhanced detection for small objects + +**Simulator Integration**: +- **E6 Connect**: Configure E6 simulator connectivity +- **GSPro**: Set up GSPro communication +- **TruGolf**: Configure TruGolf interfaces +- Port and protocol settings + +**Logging**: +- Control log levels (debug, info, warning, error) +- Enable/disable specific logging categories +- Diagnostic verbosity settings + +**Calibration**: +- Fine-tune strobing parameters +- Adjust spin analysis thresholds +- Camera positioning settings +- Ball detection sensitivity + +### Process Control + +**Start/Stop PiTrac**: +- Launch the PiTrac process +- Stop running processes cleanly +- Monitor resource usage +- View process health + +**Monitor Status**: +- Real-time health monitoring +- Service dependency checks +- Error alerts and warnings + +**Dual Camera Management**: +- Independent camera control +- Per-camera configuration +- Camera status indicators + +### Calibration Wizard + +The calibration wizard provides a 4-step process: + +**Step 1: Setup Cameras** +- Verify both cameras are detected +- Set camera types and lens parameters +- Confirm camera positioning + +**Step 2: Verify Ball Placement** +- Check ball is visible in both cameras +- Ensure proper lighting +- Validate strobing + +**Step 3: Run Calibration** +- Automated calibration sequence +- Takes multiple reference shots +- Calculates camera angles and distances + +**Step 4: Review and Save Results** +- View calculated parameters +- Compare before/after accuracy +- Save calibration data + +{: .note } +**Tip**: Run calibration after any camera position changes or hardware adjustments. + +### Testing Tools + +**Hardware Testing**: +- IR strobe test (verify strobes fire) +- Still image capture (test cameras) +- Ball detection test (verify algorithms) + +**Calibration Verification**: +- Test shots against known references +- Accuracy validation +- Consistency checks + +**Automated Test Suites**: +- Comprehensive system tests +- Regression testing +- Performance benchmarks + +### Logs Viewer + +**Real-time Logs**: +- View logs from all services +- Filter by service (pitrac, activemq, web-server) +- Filter by log level (debug, info, warning, error) + +**Log Management**: +- Download logs for offline analysis +- Clear old logs +- Configure log retention + +--- + +## First Shot Checklist + +Before hitting your first shot: + +- [ ] Web dashboard accessible at http://raspberrypi.local:8080 +- [ ] Both cameras showing "Connected" status +- [ ] ActiveMQ broker showing "Connected" +- [ ] PiTrac process showing "Running" +- [ ] Cameras positioned and secured +- [ ] Ball on tee and visible in camera views +- [ ] IR strobes tested and working +- [ ] Simulator connected (if using E6/GSPro/TruGolf) + +--- + +## Making Your First Shot + +1. **Open the main dashboard** in your web browser +2. **Verify all systems are green** (cameras, ActiveMQ, WebSocket) +3. **Set up a ball** on the tee in view of both cameras +4. **Hit the shot!** +5. **Watch the dashboard** display real-time shot data + +The web interface will show: +- Ball speed (mph or km/h) +- Carry distance (yards or meters) +- Launch angle (degrees) +- Launch direction (degrees) +- Backspin (rpm) +- Sidespin (rpm) +- Captured images from both cameras + +--- + +## Understanding Shot Data + +### Ball Speed +- **What it measures**: Initial velocity after impact +- **Typical values**: 100-180 mph for drivers +- **Accuracy**: ±1 mph with proper calibration + +### Launch Angle +- **What it measures**: Vertical angle off ground +- **Typical values**: 8-15° for drivers +- **Lower = less carry, higher = more carry (to a point)** + +### Launch Direction +- **What it measures**: Horizontal angle (left/right) +- **0° = straight, positive = right, negative = left** + +### Spin +- **Backspin**: Affects carry distance and ball flight shape +- **Sidespin**: Causes hooks (negative) or slices (positive) +- **Typical driver backspin**: 2000-3000 rpm + +--- + +## Next Steps + +**Now that PiTrac is running:** + +1. **Calibrate Your Cameras** - [Calibration Guide]({% link camera/cameras.md %}) +2. **Configure Your Simulator** - Set up E6, GSPro, or TruGolf in Configuration section +3. **Hit Test Shots** - Verify shot detection and accuracy +4. **Fine-tune Settings** - Adjust detection parameters for your setup +5. **Check Managing Guide** - [Managing PiTrac]({% link software/install/managing.md %}) + +**If you encounter issues:** +- **[Troubleshooting Guide]({% link software/install/troubleshooting.md %})** - Common problems and solutions + +**Return to:** +- **[Installation Overview]({% link software/pitrac-install.md %})** + +--- + +## Quick Tips + +**Improve Detection Accuracy**: +- Ensure consistent lighting (avoid windows, bright sunlight) +- Clean camera lenses regularly +- Use high-quality balls (avoid scuffed or dirty balls) +- Keep cameras stable and secure + +**Web Interface Not Responding?** +```bash +# Check service status +systemctl status pitrac-web + +# Restart if needed +sudo systemctl restart pitrac-web +``` + +**Camera Status Shows Disconnected?** +```bash +# Test cameras +rpicam-hello --list-cameras # Pi 5 +libcamera-hello --list-cameras # Pi 4 + +# Check PiTrac logs +tail -f ~/.pitrac/logs/pitrac.log +``` + +**No Shot Data Appearing?** +- Verify ball is visible in both camera views +- Check IR strobes are firing (should see brief flashes) +- Ensure ActiveMQ is connected +- Try adjusting detection sensitivity in Configuration \ No newline at end of file diff --git a/docs/software/install/managing.md b/docs/software/install/managing.md new file mode 100644 index 00000000..a27e4590 --- /dev/null +++ b/docs/software/install/managing.md @@ -0,0 +1,447 @@ +--- +title: Managing PiTrac +layout: default +nav_order: 3 +parent: PiTrac Installation +grand_parent: Software +description: Complete guide to managing PiTrac including CLI commands, service management, file locations, updating software, and development workflows. +keywords: pitrac commands, manage pitrac services, file locations raspberry pi, update pitrac, development workflow +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 +--- + +# Managing PiTrac + +Everything you need to know about managing, updating, and maintaining your PiTrac installation. + +--- + +## Command Reference + +### Web Server Commands + +The web server provides the user interface and configuration management: + +```bash +# Start the web server +pitrac web start + +# Stop the web server +pitrac web stop + +# Restart the web server +pitrac web restart + +# Check status +pitrac web status + +# View logs +pitrac web logs + +# Follow logs in real-time +pitrac web logs --follow +``` + +### Launch Monitor Control + +{: .warning } +**Important**: Use the web interface to start/stop the PiTrac launch monitor process. It is NOT a systemd service. + +**From the web interface**: +- Navigate to "PiTrac Process" section +- Click Start/Stop buttons +- Monitor camera status indicators + +**Direct command line** (advanced): +```bash +# Run manually (debugging) +/usr/lib/pitrac/pitrac_lm --logging_level=debug + +# View PiTrac process logs +tail -f ~/.pitrac/logs/pitrac.log +``` + +### ActiveMQ Management + +ActiveMQ provides message passing between components: + +```bash +# Check broker status +systemctl status activemq + +# Restart broker (if needed) +sudo systemctl restart activemq + +# View ActiveMQ logs +journalctl -u activemq -f +``` + +**ActiveMQ Web Console**: +``` +URL: http://raspberrypi.local:8161/admin +Default credentials: admin/admin +``` + +Use the web console to: +- Monitor queue depths +- View message statistics +- Inspect active connections +- Troubleshoot communication issues + +### System Status + +```bash +# Check all PiTrac services +pitrac status + +# View system logs +journalctl -u pitrac-web -f +journalctl -u activemq -f + +# Check camera detection +rpicam-hello --list-cameras # Pi 5 +libcamera-hello --list-cameras # Pi 4 + +# Check disk space +df -h + +# Check memory usage +free -h + +# Monitor CPU temperature +vcgencmd measure_temp +``` + +--- + +## File Locations + +Understanding where PiTrac stores its files helps with troubleshooting and maintenance. + +### Binaries + +**Installed executables**: +- `/usr/bin/pitrac` - CLI interface (Bashly-generated wrapper) +- `/usr/lib/pitrac/pitrac_lm` - Launch monitor binary (C++ application) +- `/usr/lib/pitrac/web-server/` - Python web application (FastAPI) + +**Camera tools**: +- `/usr/lib/pitrac/ImageProcessing/CameraTools/` - Camera utilities and calibration scripts + +### Configuration + +**System-wide templates**: +- `/etc/pitrac/pitrac.yaml` - Main config template (reference only, don't edit) +- `/etc/pitrac/models/` - ONNX AI models for ball detection + +**User configuration** (these are YOUR settings): +- `~/.pitrac/config/user_settings.json` - Your configuration overrides +- `~/.pitrac/config/calibration_data.json` - Camera calibration results +- `~/.pitrac/config/generated_golf_sim_config.json` - Runtime configuration (auto-generated) + +{: .note } +**Configuration Best Practice**: Always use the web interface to change settings. The web server manages the three-tier configuration system and generates the runtime config automatically. + +### User Data + +**Runtime data**: +- `~/.pitrac/state/` - Runtime state files +- `~/.pitrac/logs/` - Application logs (pitrac.log, web-server.log) +- `~/.pitrac/run/` - PID files for process management + +**Captured data**: +- `~/LM_Shares/Images/` - Captured images from shots +- `~/LM_Shares/WebShare/` - Web-accessible data + +**Calibration resources**: +- `~/.pitrac/calibration/` - Calibration tools (checkerboard images, scripts) + +### Test Resources + +**Pre-installed test files**: +- `/usr/share/pitrac/test-images/` - Sample images (teed-ball.png, strobed.png) +- `/usr/share/pitrac/test-suites/` - Automated test suites + +### Web Server Configuration + +**Web server metadata**: +- `/usr/lib/pitrac/web-server/configurations.json` - Configuration metadata (283 settings with defaults, validation, descriptions) + +This file defines all available settings, their types, defaults, and validation rules. The web interface uses this to dynamically generate the configuration UI. + +--- + +## Development Workflow + +### Updating PiTrac + +To get the latest changes from GitHub: + +```bash +cd ~/PiTrac +git pull +cd packaging +sudo ./build.sh dev +``` + +**What happens**: +- Downloads latest code from GitHub +- Detects if dependencies changed (rarely) +- Rebuilds only changed files (incremental) +- Updates web server if changed +- Restarts services if they were running + +**Time**: 30 seconds - 2 minutes for incremental builds + +### Incremental Builds + +After making code changes locally: + +```bash +cd ~/PiTrac/packaging +sudo ./build.sh dev +``` + +This performs an **incremental build**: +- Only rebuilds changed files +- Copies updated web server files +- Restarts services automatically +- Preserves configuration and calibration + +**When to use**: +- After pulling updates +- After modifying C++ source +- After changing Python web server +- Testing local changes + +### Clean Rebuild + +To force a complete rebuild from scratch: + +```bash +cd ~/PiTrac/packaging +sudo ./build.sh dev force +``` + +**What it does**: +- Deletes all build artifacts +- Rebuilds entire C++ binary +- Reinstalls all components +- Takes 2-5 minutes + +**When to use**: +- Build errors that persist +- Dependency changes +- Switching between branches with significant changes +- Want to ensure clean state + +### Build Artifacts + +The `build.sh` script uses cached artifacts from `packaging/deps-artifacts/`: +- Pre-built OpenCV 4.11.0 (saves ~60 minutes) +- Pre-built ActiveMQ-CPP 3.9.5 +- Pre-built lgpio 0.2.2 +- Pre-built msgpack-cxx 6.1.1 +- Pre-built ONNX Runtime 1.17.3 + +**If artifacts are missing**: +```bash +cd ~/PiTrac +git lfs pull +``` + +These artifacts are stored using Git LFS (Large File Storage) and are checked into the repository. + +--- + +## Build Mode Reference + +```bash +# Full developer install (recommended) +sudo ./build.sh dev + +# Force clean rebuild +sudo ./build.sh dev force + +# Build dependencies only +sudo ./build.sh deps + +# Build PiTrac binary only +sudo ./build.sh build + +# Clean build artifacts +sudo ./build.sh clean +``` + +--- + +## Backup and Restore + +### Backup Your Configuration + +Save your calibration and settings: + +```bash +# Create backup directory +mkdir -p ~/pitrac-backup + +# Backup configuration +cp -r ~/.pitrac/config/ ~/pitrac-backup/ + +# Backup captured images (optional, can be large) +cp -r ~/LM_Shares/Images/ ~/pitrac-backup/ +``` + +### Restore Configuration + +```bash +# Restore configuration +cp -r ~/pitrac-backup/config/* ~/.pitrac/config/ + +# Restart services +sudo systemctl restart pitrac-web +``` + +--- + +## Disk Space Management + +PiTrac can generate many images over time: + +### Check Disk Usage + +```bash +# Check overall disk space +df -h + +# Check PiTrac data sizes +du -sh ~/.pitrac/ +du -sh ~/LM_Shares/Images/ +du -sh ~/.pitrac/logs/ +``` + +### Clean Up Old Data + +```bash +# Remove old images (be careful!) +rm ~/LM_Shares/Images/old-shot-*.png + +# Clear old logs +rm ~/.pitrac/logs/*.log.old + +# Clear PiTrac process logs +echo "" > ~/.pitrac/logs/pitrac.log +``` + +{: .warning } +**Important**: Only delete files you're sure you don't need. Configuration files and calibration data should be backed up before removal. + +--- + +## Service Management + +### Systemd Services + +PiTrac uses two systemd services: + +**activemq.service** - Message broker (system service) +```bash +sudo systemctl start activemq +sudo systemctl stop activemq +sudo systemctl restart activemq +sudo systemctl status activemq +sudo systemctl enable activemq # Start on boot +sudo systemctl disable activemq # Don't start on boot +``` + +**pitrac-web.service** - Web dashboard (system service) +```bash +sudo systemctl start pitrac-web +sudo systemctl stop pitrac-web +sudo systemctl restart pitrac-web +sudo systemctl status pitrac-web +sudo systemctl enable pitrac-web # Start on boot +sudo systemctl disable pitrac-web # Don't start on boot +``` + +{: .note } +**Note**: The PiTrac launch monitor process is NOT a service. It's controlled through the web interface. + +--- + +## Uninstalling PiTrac + +If you need to completely remove PiTrac: + +### Stop All Services + +```bash +# Stop web server +sudo systemctl stop pitrac-web +sudo systemctl disable pitrac-web + +# Stop ActiveMQ +sudo systemctl stop activemq +sudo systemctl disable activemq +``` + +### Remove Binaries and Libraries + +```bash +# Remove installed files +sudo rm -rf /usr/lib/pitrac/ +sudo rm /usr/bin/pitrac +sudo rm -rf /etc/pitrac/ +sudo rm -rf /usr/share/pitrac/ +``` + +### Remove User Data + +{: .warning } +**Warning**: This deletes all your configuration, calibration, and captured images! + +```bash +rm -rf ~/.pitrac/ +rm -rf ~/LM_Shares/ +``` + +### Remove System Packages (Optional) + +```bash +# Remove PiTrac-specific dependencies +sudo apt remove activemq libapr1 libaprutil1 +``` + +{: .note } +Most dependencies (OpenCV, Boost, libcamera) are also used by other software. Only remove if you're sure nothing else needs them. + +--- + +## Next Steps + +**For common issues:** +- **[Troubleshooting Guide]({% link software/install/troubleshooting.md %})** - Solutions to common problems + +**To improve your setup:** +- **[Camera Calibration]({% link camera/cameras.md %})** - Advanced calibration techniques +- **[Simulator Integration]({% link simulator-integration.md %})** - Connect to E6, GSPro, TruGolf + +**Return to:** +- **[Installation Overview]({% link software/pitrac-install.md %})** +- **[First Use Guide]({% link software/install/first-use.md %})** + +--- + +## Quick Command Reference + +| Task | Command | +|------|---------| +| Start web server | `pitrac web start` | +| Stop web server | `pitrac web stop` | +| Check status | `pitrac status` | +| View logs | `pitrac web logs --follow` | +| Update PiTrac | `cd ~/PiTrac && git pull && cd packaging && sudo ./build.sh dev` | +| Clean rebuild | `sudo ./build.sh dev force` | +| Test cameras | `rpicam-hello --list-cameras` | +| Check disk space | `df -h` | +| Backup config | `cp -r ~/.pitrac/config/ ~/pitrac-backup/` | diff --git a/docs/software/install/troubleshooting.md b/docs/software/install/troubleshooting.md new file mode 100644 index 00000000..4cc1ba40 --- /dev/null +++ b/docs/software/install/troubleshooting.md @@ -0,0 +1,594 @@ +--- +title: Troubleshooting +layout: default +nav_order: 4 +parent: PiTrac Installation +grand_parent: Software +description: Comprehensive troubleshooting guide for PiTrac installation issues including build failures, service problems, camera detection, and web interface access. +keywords: pitrac troubleshooting, fix pitrac errors, camera not detected, build fails, web server not starting +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 +--- + +# Installation Troubleshooting + +Solutions to common issues encountered during and after PiTrac installation. + +--- + +## Build Issues + +### Build Fails with Missing Artifacts + +**Symptom**: Build script reports missing pre-built artifacts + +**Solution**: +```bash +cd ~/PiTrac/packaging +git lfs pull +sudo ./build.sh dev +``` + +**Why it happens**: Pre-built dependencies (OpenCV, ActiveMQ, etc.) are stored using Git LFS. If Git LFS wasn't installed when you cloned, these files won't be downloaded. + +**Prevention**: +```bash +# Install Git LFS before cloning +sudo apt install git-lfs +git lfs install +``` + +### Build Errors with Dependencies + +**Symptom**: Compilation fails with missing headers or libraries + +**Solution**: +```bash +# Ensure all system dependencies are installed +cd ~/PiTrac/packaging +sudo apt update +sudo ./build.sh deps # Reinstall dependencies + +# Then rebuild +sudo ./build.sh dev force +``` + +**Common missing dependencies**: +- `build-essential` - C++ compiler +- `meson`, `ninja-build` - Build tools +- `pkg-config` - Library detection +- `libboost-*` - Boost libraries + +### Insufficient Disk Space + +**Symptom**: Build fails with "No space left on device" + +**Check disk space**: +```bash +df -h +``` + +**Solution**: +```bash +# Need at least 5GB free, 10GB recommended + +# Free up space +sudo apt clean +sudo apt autoremove + +# Remove old logs +rm ~/.pitrac/logs/*.log.old + +# Move images to external storage +mv ~/LM_Shares/Images/ /mnt/external/ +``` + +### Build Hangs or Takes Too Long + +**Symptom**: Build appears stuck or takes more than 30 minutes + +**Possible causes**: +1. Building OpenCV from source instead of using pre-built (60+ minutes) +2. Low memory causing swapping +3. Network issues downloading packages + +**Solution**: +```bash +# Verify pre-built artifacts exist +ls -lh packaging/deps-artifacts/ + +# Check memory usage +free -h + +# If low memory, increase swap +sudo dphys-swapfile swapoff +sudo nano /etc/dphys-swapfile +# Set CONF_SWAPSIZE=2048 +sudo dphys-swapfile setup +sudo dphys-swapfile swapon +``` + +--- + +## Service Issues + +### Web Server Won't Start + +**Symptom**: `pitrac web start` fails or service shows inactive + +**Diagnosis**: +```bash +systemctl status pitrac-web +journalctl -u pitrac-web -n 50 +``` + +**Common causes and solutions**: + +**1. Python dependencies not installed** +```bash +cd /usr/lib/pitrac/web-server +sudo pip3 install -r requirements.txt --break-system-packages +sudo systemctl restart pitrac-web +``` + +**2. ActiveMQ not running** +```bash +sudo systemctl status activemq +sudo systemctl start activemq +sudo systemctl restart pitrac-web +``` + +**3. Port 8080 already in use** +```bash +# Check what's using port 8080 +sudo netstat -tlnp | grep 8080 + +# Kill the process or change PiTrac port +# (Edit /usr/lib/pitrac/web-server/main.py to change port) +``` + +**4. File permissions** +```bash +# Fix ownership +sudo chown -R $USER:$USER /usr/lib/pitrac/web-server/ +sudo systemctl restart pitrac-web +``` + +### ActiveMQ Connection Issues + +**Symptom**: Web interface shows "ActiveMQ disconnected" or PiTrac can't send messages + +**Verify ActiveMQ is running**: +```bash +systemctl status activemq +``` + +**Check port 61616 is listening**: +```bash +sudo netstat -tln | grep 61616 +# Should show: tcp6 0 0 :::61616 :::* LISTEN +``` + +**If not running**: +```bash +sudo systemctl start activemq +sudo systemctl enable activemq + +# Check logs for errors +journalctl -u activemq -f +``` + +**If still not working**: +```bash +# Reinstall ActiveMQ configuration +cd ~/PiTrac/packaging +sudo ./src/lib/activemq-service-install.sh + +# Restart +sudo systemctl restart activemq +``` + +### PiTrac Process Won't Start + +**Symptom**: Click "Start" in web interface but process stays stopped + +**Check logs**: +```bash +tail -f ~/.pitrac/logs/pitrac.log +``` + +**Common causes**: + +**1. Cameras not detected** +```bash +# Test cameras +rpicam-hello --list-cameras # Pi 5 +libcamera-hello --list-cameras # Pi 4 + +# Should show 2 cameras +``` + +**2. Configuration file errors** +```bash +# Check configuration exists +ls -l ~/.pitrac/config/ + +# Regenerate configuration through web interface +# Or manually: +rm ~/.pitrac/config/generated_golf_sim_config.json +# Restart web server to regenerate +``` + +**3. Binary permissions** +```bash +# Ensure binary is executable +sudo chmod +x /usr/lib/pitrac/pitrac_lm + +# Test manually +/usr/lib/pitrac/pitrac_lm --logging_level=debug +``` + +--- + +## Camera Issues + +### Camera Not Detected + +**Symptom**: `rpicam-hello --list-cameras` shows no cameras or error + +**Check boot configuration**: +```bash +# Pi 5 +cat /boot/firmware/config.txt | grep camera + +# Pi 4 +cat /boot/config.txt | grep camera +``` + +**Should have**: `camera_auto_detect=1` + +**If missing, add it**: +```bash +# Pi 5 +sudo nano /boot/firmware/config.txt + +# Pi 4 +sudo nano /boot/config.txt + +# Add this line: +camera_auto_detect=1 + +# Save and reboot +sudo reboot now +``` + +**Verify ribbon cable connection**: +- Power off Pi +- Check cable is fully inserted in both camera and Pi +- Check cable orientation (blue side up for most cameras) +- Check for damage to cable or connectors + +**Check libcamera environment**: +```bash +echo $LIBCAMERA_RPI_CONFIG_FILE +``` + +Should point to correct pipeline: +- Pi 4: `/usr/share/libcamera/pipeline/rpi/vc4/rpi_apps.yaml` +- Pi 5: `/usr/share/libcamera/pipeline/rpi/pisp/rpi_apps.yaml` + +### Only One Camera Detected + +**Symptom**: `rpicam-hello --list-cameras` shows 1 camera instead of 2 + +**Check both ribbon cables**: +- Verify both cameras are connected +- Check both CSI ports on the Pi +- Ensure both cables are secure + +**Identify which camera is missing**: +```bash +# Pi 5 +rpicam-hello --list-cameras +# Shows camera IDs and ports + +# Try each camera individually +rpicam-hello --camera 0 +rpicam-hello --camera 1 +``` + +**Hardware checks**: +- Swap ribbon cables between cameras +- Test suspected bad camera on known-good port +- Try different ribbon cable + +### Camera Images Too Dark/Bright + +**Symptom**: Captured images are unusable due to exposure + +**Solution**: Adjust camera settings in web interface +- Navigate to Configuration → Camera Settings +- Adjust "Gain" or "Exposure Time" +- For darker images: Increase gain (try 8-12) +- For brighter images: Decrease gain (try 2-4) +- Test with "Hardware Test" → "Capture Still Image" + +**Lighting considerations**: +- IR strobes may need adjustment +- Avoid direct sunlight or bright windows +- Consistent indoor lighting works best + +--- + +## Web Interface Issues + +### Cannot Access Web Interface + +**Symptom**: Browser can't connect to http://raspberrypi.local:8080 + +**1. Verify web server is running**: +```bash +systemctl status pitrac-web +# Should show "active (running)" +``` + +**2. Check firewall isn't blocking port 8080**: +```bash +sudo ufw status +# If active, allow port 8080: +sudo ufw allow 8080 +``` + +**3. Confirm correct IP address**: +```bash +hostname -I +# Note the IP (e.g., 192.168.1.100) + +# Try accessing with IP instead of hostname +# http://192.168.1.100:8080 +``` + +**4. Test locally on the Pi**: +```bash +curl http://localhost:8080 +# Should return HTML +``` + +**5. Check Pi is on same network**: +```bash +# From your computer, ping the Pi +ping raspberrypi.local + +# Or use IP address +ping 192.168.1.100 +``` + +### Web Interface Loads But Shows Errors + +**Symptom**: Page loads but displays connection errors or missing data + +**Check WebSocket connection**: +- Open browser developer console (F12) +- Look for WebSocket errors +- Verify WebSocket status indicator in UI + +**Check ActiveMQ connectivity**: +- Verify ActiveMQ status indicator +- Check ActiveMQ logs: `journalctl -u activemq -f` + +**Clear browser cache**: +```bash +# Hard refresh: Ctrl+Shift+R (or Cmd+Shift+R on Mac) +``` + +**Check web server logs**: +```bash +journalctl -u pitrac-web -n 100 +# Look for Python errors or stack traces +``` + +### Configuration Changes Don't Take Effect + +**Symptom**: Changes in web interface don't affect PiTrac behavior + +**Solution**: +1. Some settings require PiTrac restart +2. Look for "Restart Required" indicator in UI +3. Stop and restart PiTrac process through web interface + +**If still not working**: +```bash +# Check configuration was saved +cat ~/.pitrac/config/user_settings.json + +# Verify generated config was updated +cat ~/.pitrac/config/generated_golf_sim_config.json + +# Restart web server +sudo systemctl restart pitrac-web +``` + +--- + +## Shot Detection Issues + +### No Shot Data Appearing + +**Symptom**: Hit shots but no data appears in web interface + +**Checklist**: +- [ ] PiTrac process is running (check status indicator) +- [ ] Both cameras show "Connected" +- [ ] ActiveMQ shows "Connected" +- [ ] Ball is visible in camera views +- [ ] IR strobes are firing (should see brief flashes) +- [ ] Ball is on tee in expected location + +**Test ball detection**: +1. Navigate to Testing Tools +2. Run "Ball Detection Test" +3. Review results and adjust sensitivity if needed + +**Check logs for clues**: +```bash +tail -f ~/.pitrac/logs/pitrac.log +# Look for: +# - Camera errors +# - Ball detection failures +# - Processing errors +``` + +### Inaccurate Shot Data + +**Symptom**: Shot data seems wrong (speed too high/low, angles off) + +**Calibration needed**: +1. Run Calibration Wizard in web interface +2. Verify camera positions haven't moved +3. Check calibration data: `cat ~/.pitrac/config/calibration_data.json` + +**Environmental factors**: +- Lighting changes (time of day, room lights) +- Camera position shifted +- Ball type changed (different size/reflectivity) +- Net or objects in camera view + +**Detection method**: +- Try different detection method (HoughCircles vs YOLO) +- Adjust detection sensitivity in Configuration + +--- + +## System Performance Issues + +### High CPU Usage + +**Check what's using CPU**: +```bash +top +# Look for pitrac_lm, python3, or other processes +``` + +**Common causes**: +- Multiple PiTrac instances running +- Detection method too intensive (YOLO+SAHI on Pi 4) +- Logging level set too high (debug) + +**Solutions**: +```bash +# Kill extra processes +pkill -f pitrac_lm + +# Reduce logging verbosity in Configuration +# Switch to lighter detection method (HoughCircles) +``` + +### High Memory Usage + +**Check memory**: +```bash +free -h +``` + +**If low on memory**: +```bash +# Increase swap space +sudo dphys-swapfile swapoff +sudo nano /etc/dphys-swapfile +# Set CONF_SWAPSIZE=2048 +sudo dphys-swapfile setup +sudo dphys-swapfile swapon +``` + +**Consider**: +- Upgrade to Pi 5 with 8GB RAM +- Reduce image resolution in Configuration +- Use lighter detection method + +### System Feels Slow + +**Check temperature**: +```bash +vcgencmd measure_temp +# Should be < 80°C +``` + +**If overheating**: +- Ensure proper ventilation +- Add heatsinks or fan +- Reduce processing load + +**Check disk I/O**: +```bash +iostat -x 2 +# High %util means disk bottleneck +``` + +**Consider**: +- Upgrade to NVMe SSD (Pi 5) +- Use faster SD card (A2 class) +- Reduce image saving frequency + +--- + +## Getting Additional Help + +If you're still experiencing issues: + +**1. Check Logs**: +```bash +# PiTrac process logs +tail -f ~/.pitrac/logs/pitrac.log + +# Web server logs +journalctl -u pitrac-web -f + +# ActiveMQ logs +journalctl -u activemq -f + +# System logs +dmesg | tail -n 50 +``` + +**2. Run System Status**: +```bash +pitrac status +``` + +**3. Gather System Information**: +```bash +# OS version +cat /etc/os-release + +# Architecture (should be aarch64) +uname -m + +# Disk space +df -h + +# Memory +free -h + +# Camera detection +rpicam-hello --list-cameras +``` + +**4. Get Help from Community**: +- **[Discord Community](https://discord.gg/j9YWCMFVHN)** - Active community support +- **[GitHub Issues](https://github.com/PiTracLM/PiTrac/issues)** - Report bugs or request features +- **[Troubleshooting Guide]({% link troubleshooting.md %})** - General troubleshooting + +**When asking for help, include**: +- What you were trying to do +- What happened instead +- Error messages from logs +- System information (Pi model, OS version, architecture) +- Steps you've already tried + +--- + +## Return To + +- **[Installation Overview]({% link software/pitrac-install.md %})** +- **[First Use Guide]({% link software/install/first-use.md %})** +- **[Managing PiTrac]({% link software/install/managing.md %})** diff --git a/docs/software/pi-setup.md b/docs/software/pi-setup.md index 78d1a796..388bdeca 100644 --- a/docs/software/pi-setup.md +++ b/docs/software/pi-setup.md @@ -3,393 +3,218 @@ title: Raspberry Pi Setup layout: default nav_order: 1 parent: Software -description: Complete guide for setting up Raspberry Pi computers for PiTrac, including OS installation, software dependencies, camera configuration, and network setup. -keywords: raspberry pi setup, PiTrac installation, linux configuration, camera setup, libcamera, activemq, tomee -toc: true +has_children: true +description: Complete guide for setting up Raspberry Pi computers for PiTrac, including OS installation, first login, system updates, and optional advanced configurations. +keywords: raspberry pi setup, PiTrac installation, pi OS configuration, raspberry pi first boot, SSH setup +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 --- -# PiTrac - Raspberry Pi Setup and Configuration +# Raspberry Pi Setup & Configuration -> **Quick Start**: This guide covers Raspberry Pi OS installation and initial system configuration. Once complete, proceed to the [Startup Guide]({% link software/pitrac-install.md %}) to install PiTrac. +This guide covers setting up your Raspberry Pi from a blank SD card to a fully configured system ready for PiTrac installation. -## Table of Contents +{: .note } +**Quick Start**: This guide covers Raspberry Pi OS installation and initial system configuration. Once complete, proceed to **[Install PiTrac Software]({% link software/pitrac-install.md %})**. -- [Summary](#summary) -- [Necessary & Recommended Components](#necessary--recommended-components) - - [Standard Setup](#standard-setup) - 1. [Environment](#environment) - 2. [Operating System](#operating-system) - 3. [Log Into Pi](#log-into-pi) - 4. [Remote Log Into Pi](#remote-log-into-pi) - 5. [Sudo Privileges](#sudo-privileges) - 6. [Install NVME Board](#install-nvme-board) *(Optional)* - 7. [NAS Drive Setup and Mounting](#nas-drive-setup-and-mounting) *(Optional)* - 8. [Samba Server Setup](#samba-server-setup) *(Optional)* - 9. [SSH Stored Key](#ssh-stored-key) *(Optional - recommended)* - 10. [Additional Setup](#additional-setup) - 11. [Git and GitHub](#git-and-github) - -## Summary - -This guide covers the **initial Raspberry Pi setup** for PiTrac, from installing the operating system to configuring your Pi for network access and basic system administration. It's designed for users of all experience levels, from beginners to experienced developers. - -**What's covered in this guide:** -- Installing Raspberry Pi OS (Desktop or Lite, 64-bit only) -- Using Raspberry Pi Imager to configure SSH, WiFi, username, and password -- Initial system updates and user configuration -- Optional advanced configurations (NVMe boot, NAS mounting, multi-Pi setups) - -**What's NOT covered here:** -- Installing PiTrac software → See the [Startup Guide]({% link software/pitrac-install.md %}) -- Camera calibration → See the [Camera Documentation]({% link camera/cameras.md %}) -- Hardware assembly → See the [Assembly Guide]({% link hardware/assembly-guide.md %}) - -**Current System Architecture:** -- **Single Pi setup** is now standard (legacy dual-Pi configurations are still supported but not recommended for new builds) -- All services (launch monitor, message broker, web interface) run on one Raspberry Pi -- Simplified installation using pre-built packages - -> **Note**: Modern PiTrac uses a streamlined installation process with pre-built packages. You no longer need to manually build dependencies like OpenCV, ActiveMQ, or other libraries - the installation process handles everything automatically. - -## Necessary & Recommended Components - -- A Raspberry Pi 5 with at least 8 GB of memory -- A Micro SD card with at least 64Gig -- Especially if you are planning on using the larger Pi 5 as a development environment, an NVMe hat with an NVMe SSD drive is a great investment. -- Power supplies for the Pi’s -- Network cabling if using the Pi’s wired ethernet port (recommended \- some of the packages we’ll be downloading are large and slow over WiFi) -- Monitor, keyboard and mouse to connect to the Pi (recommended, but can also run the Pi ‘headless’ without any direct connections -- Especially if running headless, a Mac, PC, or other Linux machine that you will use to interact with the Pi, along with a terminal tool to login to the Pi, such as Putty. -- Visual Studio (optional) for your PC or MAC - - Most of the PiTrac system runs not only in the Pi, but can also (mostly) run from a Visual Studio platform on a PC or Mac. The more comfortable graphical programming environment in VS is great for testing and debugging and coding new features into the same code base. -- A separate file server, such as a NAS is highly recommended if you expect to be making changes to the PiTrac system. Pi’s are a little fragile, so keeping the PiTrac files elsewhere in a safer environment (and then mounting those files on the Pi remotely) is a good practice. - - We typically have a separate server that we use both from the Pi and also from a PC running Visual Studio that is used to help debugging. - - It’s wise to think of the Pi as a temporary, write-only device that could be erased at any time. - -### Standard Setup - -#### Environment - -1. Create a secure, static-safe environment to run your Pi’s on. 3D-printing the two Pi-side “floors” from the plans on GitHub is one way to provide this environment, and you’ll need to print them at some point anyway. - -#### Operating System - -2. **Installing Raspberry Pi OS** - - {: .warning } - > **CRITICAL - OS Version Requirements** - > - > PiTrac currently requires **Raspberry Pi OS (Legacy, 64-bit)** - > - > - **Debian version:** 12 (Bookworm) - > - **Kernel version:** 6.12 - > - **System:** 64-bit - > - > **Do NOT use:** - > - The latest Raspberry Pi OS (based on Debian 13 Trixie) - PiTrac packages not yet updated for this version - > - 32-bit versions - will not work with PiTrac - - **Why the Legacy version?** - - The latest Raspberry Pi OS moved to Debian 13 (Trixie), but PiTrac's dependency packages haven't been updated yet. The Legacy version based on Debian 12 (Bookworm) is what's currently supported and tested. - - **Desktop or Lite?** - - Both work fine. Desktop has a GUI and is easier for first-timers. Lite is command-line only and uses fewer resources. - - - **Installation Steps** - - a. **Prepare your hardware** - - Start with the Pi powered off (unplugged) - - Have a Cat5/6 ethernet cable connected to your local network if possible (recommended for faster downloads) - - On your PC/Mac, connect a Micro SD card via USB adapter - - Use a 64GB card minimum (32GB may work but 64GB recommended for room to expand) - - b. **Download and install Raspberry Pi Imager** - - Download from [raspberrypi.com/software](https://www.raspberrypi.com/software/) - - Install for your operating system (Windows, macOS, or Ubuntu) - - Launch the application - - c. **Select your device** - - Click "CHOOSE DEVICE" - - Select either "Raspberry Pi 4" or "Raspberry Pi 5" depending on your hardware - - This optimizes the OS for your specific Pi model - - d. **Choose the operating system** - - Click "CHOOSE OS" - - Navigate to "Raspberry Pi OS (other)" - - Select **ONE** of the following Legacy versions: - - **"Raspberry Pi OS (Legacy, 64-bit)"** - Desktop version with GUI - - **"Raspberry Pi OS (Legacy, 64-bit) Lite"** - Command-line only - - Based on Debian 12 (Bookworm), Kernel 6.12 - - **Important**: Must be Legacy version. Do not use regular Raspberry Pi OS (Trixie) or 32-bit versions. - - e. **Select storage** - - Click "CHOOSE STORAGE" - - Select your Micro SD card - - **WARNING**: Triple-check this is your SD card and NOT your computer's hard drive! Everything on this storage will be erased. - - f. **Configure OS customization settings** - - Click "NEXT" - - When prompted "Would you like to apply OS customisation settings?", click **"EDIT SETTINGS"** - - If you're American, feel free to ignore the British spelling of "customisation" ;) - - **In the GENERAL tab:** - - 1. **Set hostname** - - Choose a descriptive hostname to identify your Pi on the network - - Examples: `pitrac`, `pitrac-main`, `rsp01`, `rsp02` - - This will be how you connect to the Pi (e.g., `ssh pitrac.local`) - - 2. **Set username and password** - - **Username**: Enter a username for your Pi account - - Recommended: `pitrac` or your preferred username - - This will be `` throughout this documentation - - **Password**: Choose a strong password - - This is what you'll use to log in via SSH or at the console - - Write this down securely - you'll need it for first login - - Make sure "Password" checkbox is enabled - - 3. **Configure wireless LAN (WiFi)** - - **SSID**: Your WiFi network name - - **Password**: Your WiFi password - - **Wireless LAN country**: Select your country (required for regulatory compliance) - - This allows the Pi to connect to WiFi on first boot - - Even if using ethernet, configuring WiFi provides a backup connection method - - 4. **Set locale settings** - - **Time zone**: Select your timezone (e.g., `America/New_York`) - - **Keyboard layout**: Select your keyboard layout (e.g., `us` for US English) - - **In the SERVICES tab:** - - 1. **Enable SSH** - - Check the box for "Enable SSH" - - This allows you to remotely connect to your Pi - - Select "Use password authentication" - - SSH is required for headless operation and remote management - - You can set up key-based authentication later for enhanced security (see step 10) - - **In the OPTIONS tab:** - - 1. **Eject media when finished** - - Enable this option to safely eject the SD card after writing - 2. **Enable telemetry** - - This is optional and sends anonymous usage statistics to Raspberry Pi Foundation - - g. **Start the imaging process** - - Review all settings carefully - - Click "SAVE" to save your customization settings - - Click "YES" to apply OS customisation settings - - Click "YES" again to confirm you want to erase the SD card - - The imaging process will begin - - ⏱**Time estimate**: 15-25 minutes depending on your SD card speed and internet connection - - The imager will: - - Download the OS image if not cached - - Write the image to your SD card - - Verify the write was successful - - Apply your custom settings - - Eject the card (if enabled) - - h. **First boot** - - Once the SD card is written and verified, eject it from your computer - - Insert the Micro SD card into your Pi's card slot - - **Never** insert or remove the SD card while the Pi is powered on - - If you have a keyboard, mouse, and monitor, connect them now - - Even for headless setups, having a monitor for first boot helps troubleshoot any issues - - Connect the ethernet cable (if using wired network) - - Finally, connect the power supply to boot the Pi - - i. **First boot process** - - The first boot takes 2-3 minutes as the Pi: - - Expands the filesystem to use the full SD card - - Applies your custom settings (hostname, username, WiFi, SSH) - - Generates SSH host keys - - Connects to WiFi/network - - Resizes partitions - - The Pi will automatically reboot once during this process - - **Desktop version**: You'll see the LXDE desktop after boot completes - - **Lite version**: You'll see a login prompt at the console - - If using headless, wait 3-4 minutes then try to SSH (see next step) - - j. **Find your Pi's IP address** (for SSH connection) - - **Option 1**: If you have a monitor connected, log in and run: - ```bash - hostname -I - ``` - - **Option 2**: Check your router's DHCP client list - - **Option 3**: Use hostname with mDNS (usually works on local networks): - ```bash - ssh @.local - # Example: ssh pitrac@pitrac.local - ``` - - **Option 4**: Use a network scanner like `nmap` or "Angry IP Scanner" - -#### Log into Pi - -4. Log into the Pi using whatever credentials you expect to use to run PiTrac (the ``). - a. If running headless, remotely login using PuTTY or an SSH tool of your choice. - 1. Logging in from whatever computer you are reading this setup document on will make it easy to copy-paste from this document into files on the Pi. - 2. For example: - ```bash - putty rsp02 -l - ``` - (the boot image should already allow PuTTY) - b. If running directly with a monitor and keyboard, click on the updates icon near the top-right to make sure everything is up to date. - c. Install everything to get up to date. - - Or, equivalently, do the following from the command line: - ```bash - sudo apt -y update - sudo apt -y upgrade - sudo reboot now - ``` - (to make sure everything is updated) - -#### Remote Log into Pi - -5. Remotely login (to be able to paste from this setup document): - ```bash - putty rsp01 -l - ``` - (the boot image should already allow PuTTY) - Then, follow the instructions below… - -#### Sudo Privileges - -6. If necessary, make sure that `` has sudo privileges. - a. Some guidance [here](https://askubuntu.com/questions/168280/how-do-i-grant-sudo-privileges-to-an-existing-user). - -#### Install NVME Board - -7. **To Install an NVME Board on the Pi** [Optional, and probably only for the Pi 5 (confusingly referred to as the “Pi 1” computer in the PiTrac project)]: - a. If you have an SSD drive, best to get it up and booting now before you install everything on the slower, smaller MicroSD card instead. - b. See also the instructions here, which will work in most cases: [NVMe SSD boot with the Raspberry Pi 5](https://wiki.geekworm.com/NVMe_SSD_boot_with_the_Raspberry_Pi_5) - Although the instructions below should work as well. - c. With the Pi off, install the NVMe Board and NVMe SSD drive per instructions of whatever board you are using. - d. Power up and enable the PCIe interface (your instructions may differ): - 1. `cd /boot/firmware/` - 2. `sudo cp config.txt config.txt.ORIGINAL` - 3. By default the PCIe connector is not enabled. - 4. To enable it, add the following option into `/boot/firmware/config.txt` before the last “[all]” at the end of the file and reboot (`sudo reboot now`): - - `# Enable the PCIe External Connector.` - - `dtparam=pciex1` - - A more memorable alias for `pciex1` exists, so you can alternatively add `dtparam=nvme` to the `/boot/firmware/config.txt` file. - e. After the reboot, we will image the NVMe drive. - 5. First, ***if using a non-HAT+ adapter***, add on the first non-commented line of `/boot/firmware/config.txt`: - - `PCIE_PROBE=1` (see instructions for your device) - 6. Change `BOOT_ORDER` to `BOOT_ORDER=0xf416` (to boot off NVM first), OR — better yet: - 1. `sudo raspi-config` - 2. Go to the Advanced Options → Boot Order - 3. Select whatever order you want, usually NVMe card first. - 7. Shutdown, remove power to the Pi, and reboot. Afterward, an `lsblk` command should show something like this (see last line): - ``` - pitrac@rsp05:~ $ lsblk - - NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS - - mmcblk0 179:0 0 29.7G 0 disk - - |-mmcblk0p1 179:1 0 512M 0 part /boot/firmware - - `-mmcblk0p2 179:2 0 29.2G 0 part / - - nvme0n1 259:0 0 238.5G 0 disk - ``` - 8. At this point, the NVMe drive should be accessible, and we will make a copy (image) of the bootup MicroSD card onto the SSD drive. - 9. From the Pi Graphical Desktop, **Applications → Accessories → SD Card Copier** on the main screen, run the SD Card Copier program, and copy the OS to the NVMe SSD. There’s no need to select the separate UUID option. - - If running headless, see the internet for other ways to image the SSD. - 10. Power down, remove power, then remove the SSD card. - 11. When you turn the power on, the Pi should reboot from the SSD drive, and it should be pretty quick! - -#### NAS Drive Setup and Mounting - -8. **Setup mounting of a remote NAS drive (or similar)** - a. Many folks use an external NAS drive for development so that you can’t lose everything if an individual Pi has an issue. An external drive also allows for easier transfers of files to the Pi from another computer that can also see that drive. - b. The remote drive will store the development environment, though you can obviously set up the PiTrac not to need a separate drive once you have everything working. However, it’s really a good idea to have the development and test environment on a different computer than on the individual Pis. - c. There are many ways to automatically mount a removable drive to a Pi. The following is just one way that assumes you have a NAS with NFS services enabled and with a shareable drive that the Pi can read/write to. - - **NOTE:** If this Pi will be anywhere in a public network, do not include your password in the fstab! - d. `sudo mkdir /mnt/PiTracShare` - e. `cd /etc` - f. `sudo cp fstab fstab.original` - g. `sudo chmod 600 /etc/fstab` *(to try to protect any passwords in the file)* - h. `sudo vi fstab` - d. If using NFS (usually easier), put the following in the fstab file: - - `:/ /mnt/PiTracShare nfs _netdev,auto 0 0` - - **Example:** - - `10.0.0.100:/NAS_Share_Drive /mnt/PiTracShare nfs _netdev,auto 0 0` - e. If using CIFS: - 1. Add the following to `/etc/fstab` after the last non-comment line, replacing `PWD` and other things in `[]` with the real password and info: - - `/// /mnt/PiTracShare cifs username=[PiTracUserName],password=[PWD],workgroup=WORKGROUP,users,exec,auto,rw,file_mode=0777,dir_mode=0777,user_xattr 0 0` - 2. `sudo systemctl daemon-reload` - 3. `sudo mount -a` - 4. If there’s an error, make sure the password is correct. - 5. `ls -al /mnt/PiTracShare` should show any files there. - -#### Samba Server Setup - -9. **Setup Samba server** (to allow the two Pis to share a folder between themselves) - a. This allows the Pis to serve out directories to each other to share information like debugging pictures. - b. See [this guide](https://pimylifeup.com/raspberry-pi-samba/) for the basics. - c. We suggest the faster Pi 5 (or whatever will be connected to Camera 1) be the Pi from which the shared directory is shared. - d. On the Pi from which the directory will be shared: - 1. `sudo apt-get install samba samba-common-bin` - 2. `sudo systemctl restart smbd` - 3. `sudo systemctl status smbd` *(should show “active (running)”)* - 4. Create the directory structure to be shared: - - `mkdir -p /home//LM_Shares/WebShare` - - `mkdir /home//LM_Shares/Images` - 5. `sudo vi /etc/samba/smb.conf` and add at the bottom: - ``` - [LM_Shares] - path = /home//LM_Shares - writeable = Yes - create mask = 0777 - directory mask = 0777 - public = no - ``` - 6. `sudo smbpasswd -a ` *(enter the same password as the PiTracUsername)* - 7. `sudo systemctl restart smbd` - e. On the Pi to which the directory will be shared: - 1. Add the following to `/etc/fstab` after the last non-comment line, replacing `PWD` and other info: - - `///LM_Shares /home//LM_Shares cifs username=[PiTracUserName],password=[PWD],workgroup=WORKGROUP,users,exec,auto,rw,file_mode=0777,dir_mode=0777,user_xattr 0 0` - 2. `mkdir /home//LM_Shares` *(this will be the Pi 2 mount point)* - 3. `sudo systemctl daemon-reload` - 4. `sudo mount -a` - 5. Check to make sure the second Pi can “see” the other Pi’s LM_Shares sub-directories (Images and WebShare). - - -#### SSH Stored Key - -10. **Setup SSH to use a stored key** (optional, but really useful to avoid having to type a password every time) - 1. **WARNING –** This step assumes your PiTrac is secure in your own network and that the machine you use to log in is not used by others (given that this helps automate remote logins). - 2. If not already, remotely log into the Pi from the machine where you’re reading this document. - 3. Create an SSH directory: - ```bash - install -d -m 700 ~/.ssh - ``` - 4. Install PuTTY on the remote (non-Pi Mac/PC) machine that you’ll use to log in. - 5. Use the PuTTYgen utility to generate a public key. This is just a long text string or two. - 6. Edit `~/.ssh/authorized_keys` and paste in the public key for PuTTY. - 7. (Alternatively, you can just use the mount to get a copy of the file from another Pi.) - 8. The key would have been generated using PuTTYgen. - 9. The file should simply have each key (no spaces!) preceded on the same line with `ssh-rsa `. - 10. Set permissions: - ```bash - sudo chmod 644 ~/.ssh/authorized_keys - ``` - -#### Additional Setup - -11. If you don’t already have your development world set up the way you want it, we suggest trying some of the environments/tools at the bottom of these instructions labeled “[**Nice-to-Haves for an easy-to-use development environment**](#nice-to-haves)”. - -#### Git and GitHub - -12. **Git and GitHub** - 1. If the project will be hosted on a shared drive, and you 100% control that drive and it’s not public, then let GitHub know that we’re all family here. On the Pi and on whatever computer you log in from, do: - ```bash - git config --global --add safe.directory "*" - ``` - 2. Otherwise, Git Desktop and Visual Studio often have problems. +--- + +## Overview + +**What you'll do:** +1. Install Raspberry Pi OS using Raspberry Pi Imager +2. Log in and perform initial updates +3. (Optional) Configure advanced features like NVMe boot or NAS mounting + +**Time Required:** +- **Essential setup**: ~45 minutes +- **With optional configs**: ~75 minutes + +**Difficulty:** Beginner-friendly with step-by-step instructions + +--- + +## System Requirements + +### Required Hardware + +- **Raspberry Pi 5** with at least 8GB RAM (Pi 4 also supported) +- **MicroSD card** - 64GB minimum (32GB may work but 64GB+ recommended) +- **Power supply** - Official Raspberry Pi power supply recommended +- **Network connection** - Ethernet cable strongly recommended for initial setup + +### Recommended (Optional) + +- **Monitor, keyboard, mouse** - Helpful for first boot, even if running headless later +- **NVMe HAT + SSD** - For significantly faster performance (Pi 5 only) +- **Second computer** - For SSH access and easier copy-paste from documentation +- **NAS or file server** - For development work and safer file storage + +--- + +## Setup Process + +### Step 1: Install Operating System + +Install Raspberry Pi OS using Raspberry Pi Imager with proper configuration for PiTrac. + +**→ [Install Raspberry Pi OS]({% link software/pi-setup/install-os.md %})** + +**What you'll do:** +- Download and use Raspberry Pi Imager +- Choose correct OS version (64-bit Bookworm or Trixie) +- Configure hostname, username, WiFi, and SSH +- Image your SD card and first boot + +**Time:** ~30 minutes + +--- + +### Step 2: First Login & Updates + +Log into your Pi (via SSH or console) and perform essential system updates. + +**→ [First Login & Updates]({% link software/pi-setup/first-login.md %})** + +**What you'll do:** +- Connect via SSH or console +- Update system packages +- Verify sudo privileges +- Check system configuration + +⏱ **Time:** ~15 minutes + +--- + +### Step 3: Advanced Configuration (Optional) + +Configure optional features for enhanced performance and development workflows. + +**→ [Advanced Configuration]({% link software/pi-setup/advanced.md %})** + +**Optional features:** +- **NVMe Boot** - Boot from SSD for 5-10x speed improvement +- **NAS Mounting** - Mount remote drives for safer development +- **Samba Server** - Share files between Pis +- **SSH Keys** - Passwordless authentication +- **Git Setup** - Configure for shared drives + +**Time:** Varies by feature (15-60 minutes) + +{: .note } +These are optional. PiTrac works fine without them. + +--- + +## Current System Architecture + +Modern PiTrac uses a simplified architecture: + +- **Single Pi setup** is now standard +- All services run on one Raspberry Pi 5 +- Legacy dual-Pi configurations still supported but not recommended +- Pre-built packages handle dependencies automatically + +You **do not** need to manually build OpenCV, ActiveMQ, or other dependencies - the installation process handles everything. + +--- + +## After Setup + +Once your Pi is set up, continue to: + +**→ [Install PiTrac Software]({% link software/pitrac-install.md %})** + +This will install the launch monitor binary, web dashboard, and all required services. + +--- + +## Quick Reference + +### Essential Commands + +```bash +# Update system +sudo apt update && sudo apt -y upgrade + +# Check OS version +cat /etc/os-release + +# Check architecture (must be aarch64) +uname -m + +# Find IP address +hostname -I + +# Reboot +sudo reboot now + +# Shutdown +sudo poweroff +``` + +### Network Access + +**SSH from another computer:** +```bash +# Using hostname (usually works) +ssh @pitrac.local + +# Using IP address +ssh @192.168.1.100 +``` + +**Find Pi's IP address:** +- Check router's DHCP client list +- On Pi with monitor: `hostname -I` +- Network scanner: `nmap` or Angry IP Scanner + +--- + +## Troubleshooting + +**Can't find Pi on network:** +- Wait 5 minutes after first boot +- Check router for new DHCP clients +- Verify ethernet cable connected +- Check WiFi credentials if using wireless +- Try connecting a monitor to see boot progress + +**SD card won't boot:** +- Verify you selected 64-bit OS +- Check SD card isn't corrupted +- Try re-imaging with Raspberry Pi Imager +- Ensure SD card is properly inserted +- Try different SD card + +**SSH connection refused:** +- Verify SSH was enabled during OS installation +- Check Pi is on network: `ping pitrac.local` +- Wait longer - first boot takes 3-4 minutes +- Try IP address instead of hostname +- Check firewall isn't blocking port 22 + +**System updates fail:** +- Check internet connection: `ping google.com` +- Verify DNS works: `nslookup google.com` +- Check disk space: `df -h` +- Try: `sudo apt update --fix-missing` + +--- + +## Need Help? + +- **Discord Community**: [Join the PiTrac Discord](https://discord.gg/j9YWCMFVHN) +- **GitHub Issues**: [Report issues](https://github.com/PiTracLM/PiTrac/issues) +- **Troubleshooting Guide**: [Common Issues]({% link troubleshooting.md %}) + +--- + +## What's Next? + +After completing Pi setup: + +1. **OS Installed** - Raspberry Pi OS running +2. **System Updated** - All packages current +3. **Network Configured** - SSH access working +4. **Install PiTrac** - [Next: Install PiTrac Software]({% link software/pitrac-install.md %}) \ No newline at end of file diff --git a/docs/software/pi-setup/advanced.md b/docs/software/pi-setup/advanced.md new file mode 100644 index 00000000..24b3191d --- /dev/null +++ b/docs/software/pi-setup/advanced.md @@ -0,0 +1,474 @@ +--- +title: Advanced Configuration +layout: default +nav_order: 3 +parent: Raspberry Pi Setup +grand_parent: Software +description: Advanced Raspberry Pi configuration for PiTrac including NVMe boot setup, NAS drive mounting, Samba server configuration, and SSH key authentication. +keywords: raspberry pi nvme boot, NAS mount raspberry pi, samba server pi, SSH keys raspberry pi, pi advanced setup +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 +--- + +# Advanced Configuration + +**Optional configurations for enhanced performance and development workflows.** + +{: .note } +These are **optional** configurations. PiTrac works fine without them. Only proceed if you need these specific features. + +**What's covered:** +- NVMe SSD boot for faster performance +- NAS drive mounting for safer development +- Samba server for file sharing between Pis +- SSH key authentication for passwordless login +- Git configuration for shared drives + +--- + +## NVMe Boot Setup + +Boot from an NVMe SSD for significantly faster performance compared to SD cards. + +**Benefits:** +- 5-10x faster read/write speeds +- More reliable than SD cards +- Larger storage capacity + +**Requirements:** +- Raspberry Pi 5 (Pi 4 requires USB boot, not NVMe) +- NVMe HAT or adapter board +- NVMe M.2 SSD drive +- Already have working Pi with OS on SD card + +**Time Required:** ~30 minutes + +--- + +### Installation Steps + +**1. Install Hardware** + +With Pi powered off: +- Install NVMe HAT/adapter per manufacturer instructions +- Insert NVMe SSD into M.2 slot +- Ensure secure connections + +**2. Enable PCIe Interface** + +Boot the Pi from SD card and enable PCIe: + +```bash +cd /boot/firmware/ +sudo cp config.txt config.txt.ORIGINAL +sudo nano /boot/firmware/config.txt +``` + +Add before the last `[all]` section: +``` +# Enable the PCIe External Connector +dtparam=pciex1 +``` + +Alternative (more memorable): +``` +dtparam=nvme +``` + +{: .note } +For non-HAT+ adapters, add `PCIE_PROBE=1` on the first non-commented line. + +Save and reboot: +```bash +sudo reboot now +``` + +**3. Verify NVMe Detection** + +After reboot: +```bash +lsblk +``` + +You should see `nvme0n1` listed: +``` +NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS +mmcblk0 179:0 0 29.7G 0 disk +|-mmcblk0p1 179:1 0 512M 0 part /boot/firmware +`-mmcblk0p2 179:2 0 29.2G 0 part / +nvme0n1 259:0 0 238.5G 0 disk +``` + +**4. Configure Boot Order** + +Use raspi-config for easiest setup: +```bash +sudo raspi-config +``` + +Navigate to: +- **Advanced Options** → **Boot Order** +- Select **NVMe/USB Boot** (boots from NVMe first) +- Exit and don't reboot yet + +**5. Copy OS to NVMe** + +**Desktop version (GUI):** +- Open: **Applications → Accessories → SD Card Copier** +- Source: SD card +- Destination: NVMe drive +- Click "Start" +- Wait 10-15 minutes + +**Lite version (command line):** +```bash +# Use dd or similar tool - see online guides +# Or temporarily boot Desktop to use SD Card Copier +``` + +**6. Boot from NVMe** + +```bash +sudo poweroff +``` + +Remove power, **remove the SD card**, then power on. + +Pi should boot from NVMe - much faster! + +**Troubleshooting:** +- If it doesn't boot, reinsert SD card and check boot order +- Verify NVMe was detected in step 3 +- Check [Geekworm NVMe guide](https://wiki.geekworm.com/NVMe_SSD_boot_with_the_Raspberry_Pi_5) + +--- + +## NAS Drive Mounting + +Mount a remote NAS drive for safer development and easier file sharing. + +**Benefits:** +- Keep important files off the Pi (Pis can be fragile) +- Easy file access from multiple computers +- Centralized backup location + +**Requirements:** +- NAS or file server with NFS or CIFS/SMB +- Network connectivity between Pi and NAS +- NAS credentials (username/password) + +--- + +### Setup NFS Mount (Recommended) + +NFS is simpler and faster for Linux-to-Linux connections. + +**1. Create Mount Point** + +```bash +sudo mkdir /mnt/PiTracShare +``` + +**2. Backup fstab** + +```bash +cd /etc +sudo cp fstab fstab.original +sudo chmod 600 /etc/fstab +``` + +**3. Edit fstab** + +```bash +sudo nano /etc/fstab +``` + +Add at the end: +``` +:/ /mnt/PiTracShare nfs _netdev,auto 0 0 +``` + +Example: +``` +10.0.0.100:/NAS_Share_Drive /mnt/PiTracShare nfs _netdev,auto 0 0 +``` + +**4. Mount** + +```bash +sudo systemctl daemon-reload +sudo mount -a +``` + +**5. Verify** + +```bash +ls -la /mnt/PiTracShare +``` + +Should show NAS contents. + +--- + +### Setup CIFS/SMB Mount (Windows NAS) + +For Windows file servers or Samba shares. + +**1. Install CIFS utils** + +```bash +sudo apt install cifs-utils +``` + +**2. Create Mount Point** + +```bash +sudo mkdir /mnt/PiTracShare +``` + +**3. Edit fstab** + +```bash +sudo nano /etc/fstab +``` + +Add at the end: +``` +/// /mnt/PiTracShare cifs username=,password=,workgroup=WORKGROUP,users,exec,auto,rw,file_mode=0777,dir_mode=0777,user_xattr 0 0 +``` + +{: .warning } +**Security Warning**: Storing passwords in fstab is insecure. Only do this on private networks. For better security, use credentials file. + +**4. Mount** + +```bash +sudo systemctl daemon-reload +sudo mount -a +``` + +--- + +## Samba Server Setup + +Set up Samba to share directories between Pis or with other computers. + +**Use case:** Share images/data between two-Pi setups (legacy configurations). + +**Requirements:** +- Two Raspberry Pis on same network +- Designated "server" Pi (faster Pi recommended) + +--- + +### On the Server Pi + +**1. Install Samba** + +```bash +sudo apt-get install samba samba-common-bin +sudo systemctl restart smbd +sudo systemctl status smbd +``` + +Should show "active (running)". + +**2. Create Shared Directory** + +```bash +mkdir -p ~/LM_Shares/WebShare +mkdir ~/LM_Shares/Images +``` + +**3. Configure Samba** + +```bash +sudo nano /etc/samba/smb.conf +``` + +Add at the bottom: +``` +[LM_Shares] +path = /home//LM_Shares +writeable = Yes +create mask = 0777 +directory mask = 0777 +public = no +``` + +**4. Set Samba Password** + +```bash +sudo smbpasswd -a +``` + +Enter your Pi user password. + +**5. Restart Samba** + +```bash +sudo systemctl restart smbd +``` + +--- + +### On the Client Pi + +**1. Create Mount Point** + +```bash +mkdir ~/LM_Shares +``` + +**2. Edit fstab** + +```bash +sudo nano /etc/fstab +``` + +Add: +``` +///LM_Shares /home//LM_Shares cifs username=,password=,workgroup=WORKGROUP,users,exec,auto,rw,file_mode=0777,dir_mode=0777,user_xattr 0 0 +``` + +**3. Mount** + +```bash +sudo systemctl daemon-reload +sudo mount -a +``` + +**4. Verify** + +```bash +ls -la ~/LM_Shares +``` + +Should show Images and WebShare directories from server Pi. + +--- + +## SSH Key Authentication + +Set up passwordless SSH login using SSH keys. + +**Benefits:** +- No password typing for every login +- More secure than password authentication +- Required for some automation scripts + +{: .warning } +**Security Note**: Only use this on your private network with a secure computer. + +--- + +### Setup SSH Keys + +**1. On Your Computer (Not the Pi)** + +Generate SSH key pair: + +**Windows (using PuTTY):** +- Launch PuTTYgen +- Click "Generate" +- Move mouse to generate randomness +- Save private key (keep secure!) +- Copy public key text + +**Mac/Linux:** +```bash +ssh-keygen -t rsa -b 4096 +# Press Enter for default location +# Optional: Enter passphrase for extra security +``` + +**2. On the Pi** + +Create SSH directory: +```bash +install -d -m 700 ~/.ssh +``` + +Edit authorized keys: +```bash +nano ~/.ssh/authorized_keys +``` + +Paste your public key (starts with `ssh-rsa`). + +Set permissions: +```bash +chmod 644 ~/.ssh/authorized_keys +``` + +**3. Test Connection** + +From your computer: +```bash +ssh @pitrac.local +``` + +Should log in without password! + +--- + +## Git Configuration + +Configure Git for shared drive development. + +**Only needed if:** +- Using Git with NAS/shared drives +- Experiencing "unsafe repository" warnings +- Using Git Desktop or Visual Studio + +**Setup:** + +```bash +git config --global --add safe.directory "*" +``` + +This tells Git to trust all repositories. + +{: .warning } +Only use this on drives you fully control. Not for public/shared systems. + +--- + +## Next Steps + +**Advanced Configuration Complete!** + +**Continue to:** +- **[Install PiTrac Software]({% link software/pitrac-install.md %})** - Install the launch monitor + +**Return to:** +- **[Pi Setup Overview]({% link software/pi-setup.md %})** + +--- + +## Troubleshooting + +**NVMe not detected:** +- Check HAT is properly seated +- Verify M.2 SSD is inserted fully +- Check `/boot/firmware/config.txt` has `dtparam=pciex1` +- Try different boot order settings + +**NAS mount fails:** +- Verify NAS IP is correct: `ping ` +- Check NAS share exists and is accessible +- For NFS: Ensure NFS is enabled on NAS +- For CIFS: Verify username/password +- Check `/var/log/syslog` for mount errors + +**Samba connection fails:** +- Verify Samba is running: `sudo systemctl status smbd` +- Check firewall isn't blocking port 445 +- Verify server Pi IP in client fstab +- Test connection: `smbclient -L // -U ` + +**SSH key not working:** +- Verify public key is in `~/.ssh/authorized_keys` +- Check permissions: `ls -la ~/.ssh/` +- Ensure key format is correct (starts with `ssh-rsa`) +- Try verbose SSH: `ssh -v @pitrac.local` \ No newline at end of file diff --git a/docs/software/pi-setup/first-login.md b/docs/software/pi-setup/first-login.md new file mode 100644 index 00000000..816ac55d --- /dev/null +++ b/docs/software/pi-setup/first-login.md @@ -0,0 +1,213 @@ +--- +title: First Login & Updates +layout: default +nav_order: 2 +parent: Raspberry Pi Setup +grand_parent: Software +description: Initial login to Raspberry Pi, system updates, and basic configuration for PiTrac including SSH access and sudo privileges. +keywords: raspberry pi first login, SSH raspberry pi, pi system update, sudo privileges, remote login pi +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 +--- + +# First Login & Updates + +After installing Raspberry Pi OS, you need to log in and perform initial system updates. + +**Time Required:** ~15 minutes + +**Difficulty:** Beginner + +--- + +## Login Options + +You have two ways to access your Pi: + +### Option 1: Direct Login (With Monitor & Keyboard) + +If you have a monitor, keyboard, and mouse connected: + +1. You'll see either the desktop (Desktop version) or login prompt (Lite version) +2. Enter your username and password (configured during OS installation) +3. For Desktop version, you're logged in automatically after entering credentials +4. For Lite version, you'll see a command prompt after successful login + +### Option 2: Remote Login via SSH + +SSH (Secure Shell) allows you to access your Pi remotely from another computer. + +**Prerequisites:** +- Pi must be on same network as your computer +- SSH must be enabled (configured during OS installation) +- Know your Pi's hostname or IP address + +**From Windows:** +```bash +# Using PuTTY or Windows Terminal +ssh @.local +# Example: ssh pitrac@pitrac.local + +# Or with IP address +ssh @192.168.1.100 +``` + +**From Mac/Linux:** +```bash +# Open Terminal +ssh @.local +# Example: ssh pitrac@pitrac.local +``` + +**First SSH Connection:** +- You'll see a message about host authenticity (ECDSA key fingerprint) +- Type `yes` to continue +- Enter your password when prompted +- You won't see characters while typing password - this is normal + +{: .note } +**Tip**: Logging in remotely makes it easy to copy-paste commands from this documentation directly into your Pi terminal. + +--- + +## Initial System Updates + +After logging in, immediately update your system to get the latest security patches and software versions. + +### Update Package Lists + +```bash +sudo apt update +``` + +This downloads information about the newest versions of packages and their dependencies. + +### Upgrade Installed Packages + +```bash +sudo apt -y upgrade +``` + +The `-y` flag automatically answers "yes" to prompts. This can take 5-15 minutes depending on how many packages need updating. + +### Reboot + +After updates complete, reboot to ensure all changes take effect: + +```bash +sudo reboot now +``` + +Your SSH connection will close. Wait 1-2 minutes, then log back in. + +--- + +## Verify Sudo Privileges + +The user account you created during OS installation should automatically have sudo (administrator) privileges. Let's verify: + +### Test Sudo Access + +```bash +sudo whoami +``` + +If configured correctly, this should output: `root` + +### If Sudo Doesn't Work + +If you get an error like "` is not in the sudoers file`", you need to add your user to the sudo group. + +**From another account with sudo access:** +```bash +sudo usermod -aG sudo +``` + +**Or edit sudoers file directly** (advanced): +```bash +su - # Switch to root +visudo +# Add this line: +# ALL=(ALL:ALL) ALL +``` + +More guidance: [How to grant sudo privileges](https://askubuntu.com/questions/168280/how-do-i-grant-sudo-privileges-to-an-existing-user) + +--- + +## Verify System Information + +Check your Pi is configured correctly: + +### Check OS Version + +```bash +cat /etc/os-release +``` + +Look for: +- `VERSION_CODENAME` should be `bookworm` (Debian 12) or `trixie` (Debian 13) +- `PRETTY_NAME` should say "Raspberry Pi OS" + +### Check Architecture + +```bash +uname -m +``` + +Should output: `aarch64` (64-bit ARM) + +{: .warning } +If you see `armv7l` or `armhf`, you're running 32-bit OS. PiTrac requires 64-bit - you must re-image your SD card. + +### Check Available Disk Space + +```bash +df -h +``` + +Look for the root filesystem (`/`): +- Should show most of your SD card size (minus OS overhead) +- Ensure you have at least 10GB free for PiTrac installation + +--- + +## Next Steps + +**Basic Setup Complete!** + +**Essential Next Step:** +- **[Install PiTrac Software]({% link software/pitrac-install.md %})** - Install the launch monitor software + +**Optional Advanced Configuration:** +- **[Advanced Setup]({% link software/pi-setup/advanced.md %})** - NVMe boot, NAS mounting, SSH keys + +**Return to:** +- **[Pi Setup Overview]({% link software/pi-setup.md %})** + +--- + +## Troubleshooting + +**Can't SSH to Pi:** +- Verify Pi is powered on and network cable connected +- Check router to confirm Pi has IP address +- Try using IP address instead of hostname +- Verify SSH was enabled during OS installation +- Ping the Pi: `ping .local` or `ping ` + +**Updates failing:** +- Check internet connection: `ping google.com` +- Verify DNS is working: `nslookup google.com` +- Try different mirror: `sudo apt update --fix-missing` +- Check disk space: `df -h` + +**Permission denied errors:** +- Verify you're using `sudo` for system commands +- Check sudo privileges as shown above +- Ensure you're logged in as the correct user: `whoami` + +**Forgot password:** +- If you have physical access, you can reset via recovery mode +- Otherwise, you'll need to re-image the SD card +- This is why it's important to write down your password! \ No newline at end of file diff --git a/docs/software/pi-setup/install-os.md b/docs/software/pi-setup/install-os.md new file mode 100644 index 00000000..2e4561e5 --- /dev/null +++ b/docs/software/pi-setup/install-os.md @@ -0,0 +1,236 @@ +--- +title: Install Raspberry Pi OS +layout: default +nav_order: 1 +parent: Raspberry Pi Setup +grand_parent: Software +description: Step-by-step guide to installing Raspberry Pi OS using Raspberry Pi Imager including OS selection, configuration settings, and first boot for PiTrac. +keywords: raspberry pi imager, install pi OS, bookworm trixie setup, pi OS configuration, raspberry pi first boot +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 +--- + +# Install Raspberry Pi OS + +This guide walks through installing Raspberry Pi OS using Raspberry Pi Imager with all necessary configuration for PiTrac. + +**Time Required:** ~30 minutes (including imaging and first boot) + +**Difficulty:** Beginner-friendly + +--- + +## OS Version Requirements + +{: .warning } +> **CRITICAL - OS Version Requirements** +> +> PiTrac requires **Raspberry Pi OS 64-bit** +> +> - **Supported versions:** Debian 12 (Bookworm) or Debian 13 (Trixie) +> - **System:** 64-bit (required) +> +> **Do NOT use:** +> - 32-bit versions - will not work with PiTrac + +## Desktop or Lite? + +Both work fine: +- **Desktop**: Has GUI, easier for first-timers +- **Lite**: Command-line only, uses fewer resources + +Choose based on your comfort level with Linux command line. + +--- + +## Installation Steps + +### 1. Prepare Your Hardware + +Before starting: +- Pi powered off (unplugged) +- Cat5/6 ethernet cable connected to your local network (recommended for faster downloads) +- Micro SD card connected to your PC/Mac via USB adapter +- Use 64GB card minimum (32GB may work but 64GB recommended) + +### 2. Download Raspberry Pi Imager + +- Download from [raspberrypi.com/software](https://www.raspberrypi.com/software/) +- Install for your operating system (Windows, macOS, or Ubuntu) +- Launch the application + +### 3. Select Your Device + +- Click **"CHOOSE DEVICE"** +- Select either **"Raspberry Pi 4"** or **"Raspberry Pi 5"** depending on your hardware +- This optimizes the OS for your specific Pi model + +### 4. Choose the Operating System + +- Click **"CHOOSE OS"** +- Select **ONE** of the following 64-bit versions: + - **"Raspberry Pi OS (64-bit)"** - Desktop with GUI (Debian 13 Trixie) + - **"Raspberry Pi OS (64-bit) Lite"** - Command-line only (Debian 13 Trixie) + - **"Raspberry Pi OS (Legacy, 64-bit)"** - Desktop with GUI (Debian 12 Bookworm) + - **"Raspberry Pi OS (Legacy, 64-bit) Lite"** - Command-line only (Debian 12 Bookworm) + +Both Bookworm (Debian 12) and Trixie (Debian 13) are fully supported. + +{: .note } +**Important**: Must be 64-bit version. Do not use 32-bit versions. + +### 5. Select Storage + +- Click **"CHOOSE STORAGE"** +- Select your Micro SD card + +{: .warning } +**WARNING**: Triple-check this is your SD card and NOT your computer's hard drive! Everything on this storage will be erased. + +### 6. Configure OS Customization Settings + +- Click **"NEXT"** +- When prompted "Would you like to apply OS customisation settings?", click **"EDIT SETTINGS"** + +#### GENERAL Tab + +**Set hostname:** +- Choose a descriptive hostname to identify your Pi on the network +- Examples: `pitrac`, `pitrac-main`, `rsp01`, `rsp02` +- This will be how you connect to the Pi (e.g., `ssh pitrac.local`) + +**Set username and password:** +- **Username**: Enter a username for your Pi account + - Recommended: `pitrac` or your preferred username + - This will be `` throughout documentation +- **Password**: Choose a strong password + - This is what you'll use to log in via SSH or console + - Write this down securely - you'll need it for first login + - Make sure "Password" checkbox is enabled + +**Configure wireless LAN (WiFi):** +- **SSID**: Your WiFi network name +- **Password**: Your WiFi password +- **Wireless LAN country**: Select your country (required for regulatory compliance) +- Even if using ethernet, configuring WiFi provides a backup connection method + +**Set locale settings:** +- **Time zone**: Select your timezone (e.g., `America/New_York`) +- **Keyboard layout**: Select your keyboard layout (e.g., `us` for US English) + +#### SERVICES Tab + +**Enable SSH:** +- Check the box for "Enable SSH" +- This allows you to remotely connect to your Pi +- Select "Use password authentication" +- SSH is required for headless operation and remote management +- You can set up key-based authentication later for enhanced security + +#### OPTIONS Tab + +**Eject media when finished:** +- Enable this option to safely eject the SD card after writing + +**Enable telemetry:** +- Optional - sends anonymous usage statistics to Raspberry Pi Foundation + +### 7. Start the Imaging Process + +- Review all settings carefully +- Click **"SAVE"** to save your customization settings +- Click **"YES"** to apply OS customisation settings +- Click **"YES"** again to confirm you want to erase the SD card +- The imaging process will begin + +**Time estimate**: 15-25 minutes depending on SD card speed and internet connection + +The imager will: +- Download the OS image if not cached +- Write the image to your SD card +- Verify the write was successful +- Apply your custom settings +- Eject the card (if enabled) + +--- + +## First Boot + +### 8. Prepare for Boot + +Once the SD card is written and verified: +- Eject the SD card from your computer +- Insert the Micro SD card into your Pi's card slot + - **Never** insert or remove the SD card while the Pi is powered on +- If you have keyboard, mouse, and monitor, connect them now + - Even for headless setups, having a monitor for first boot helps troubleshoot issues +- Connect the ethernet cable (if using wired network) +- Finally, connect the power supply to boot the Pi + +### 9. First Boot Process + +The first boot takes 2-3 minutes as the Pi: +- Expands the filesystem to use the full SD card +- Applies your custom settings (hostname, username, WiFi, SSH) +- Generates SSH host keys +- Connects to WiFi/network +- Resizes partitions + +The Pi will automatically reboot once during this process. + +**What you'll see:** +- **Desktop version**: LXDE desktop after boot completes +- **Lite version**: Login prompt at the console +- **Headless**: Wait 3-4 minutes then try to SSH + +### 10. Find Your Pi's IP Address + +For SSH connection, you need the Pi's IP address: + +**Option 1** - If you have a monitor connected: +```bash +hostname -I +``` + +**Option 2** - Check your router's DHCP client list + +**Option 3** - Use hostname with mDNS (usually works): +```bash +ssh @.local +# Example: ssh pitrac@pitrac.local +``` + +**Option 4** - Use a network scanner like `nmap` or "Angry IP Scanner" + +--- + +## Next Steps + +**OS Installation Complete!** + +Continue to: **[First Login & Updates]({% link software/pi-setup/first-login.md %})** + +Or return to: **[Pi Setup Overview]({% link software/pi-setup.md %})** + +--- + +## Troubleshooting + +**Can't find Pi on network:** +- Wait 5 minutes - first boot takes time +- Check router for new DHCP clients +- Try connecting monitor to see boot progress +- Verify ethernet cable is connected +- Check WiFi credentials if using wireless + +**Imager fails to write:** +- Try a different SD card +- Check if SD card is write-protected +- Run imager as administrator +- Verify SD card is not corrupted + +**SD card won't eject:** +- Safely eject from your OS before removing +- On Windows: Right-click drive → Eject +- On Mac: Drag to trash or use Eject button +- On Linux: Use `umount` command \ No newline at end of file diff --git a/docs/software/pitrac-install.md b/docs/software/pitrac-install.md index 374cb1a9..15d74181 100644 --- a/docs/software/pitrac-install.md +++ b/docs/software/pitrac-install.md @@ -3,11 +3,36 @@ title: PiTrac Installation layout: default nav_order: 2 parent: Software +has_children: true +description: Step-by-step PiTrac software installation guide including building from source, APT package installation, dependency management, and service configuration for the golf launch monitor. +keywords: install pitrac software, build from source raspberry pi, apt package install, golf monitor software setup, compile opencv raspberry pi +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 --- # PiTrac Installation Guide -This guide covers installing PiTrac on your Raspberry Pi. Choose the installation method that best fits your needs. +Install the PiTrac software on your Raspberry Pi and start tracking golf shots. + +{: .note } +**Important**: Complete [Raspberry Pi Setup]({% link software/pi-setup.md %}) 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 @@ -15,605 +40,237 @@ Before starting, ensure you have: - **Raspberry Pi 5 with 8GB RAM** (recommended) - Raspberry Pi 4 with 8GB RAM also supported -- **Raspberry Pi OS Bookworm 64-bit** installed and configured +- **Raspberry Pi OS 64-bit** installed and configured (Bookworm or Trixie) - See [Pi Setup Guide]({% link software/pi-setup.md %}) for OS installation - **Active internet connection** for downloading packages - **Sudo privileges** on your Pi - **At least 5GB free disk space** (10GB recommended for development) ---- - -# Installing from APT Repository - -> **Coming Soon**: PiTrac will be available as a Debian package for easy installation via `apt`. This section will be updated when the package repository is available. +{: .warning } +**Critical**: You must have completed the [Raspberry Pi Setup]({% link software/pi-setup.md %}) before proceeding. This includes OS installation, system updates, and network configuration. --- -# Building from Source - -Building from source is the current recommended installation method and is ideal for development or if you want the latest features. - -## Overview +## Installation Methods -The build process: -- Installs all required system dependencies (~80+ packages) -- Extracts pre-built libraries (OpenCV, ActiveMQ, lgpio, msgpack) -- Compiles the PiTrac C++ binary -- Installs the Python web server and all dependencies -- Configures ActiveMQ message broker -- Sets up libcamera for dual Pi cameras -- Creates user directories and configuration files +Choose the installation method that fits your needs: -**Expected time**: 10-20 minutes on a Pi 5 (first installation, network-dependent) +### Build from Source (Recommended) -## Step 1: Clone the Repository +**→ [Build from Source Guide]({% link software/install/build-from-source.md %})** -Clone the PiTrac repository using HTTPS: - -```bash -git clone https://github.com/PiTracLM/PiTrac.git -cd PiTrac -``` +Building from source is currently the recommended method. Ideal for: +- Getting the latest features +- Development and customization +- Understanding the build process -> **Note**: We use HTTPS instead of SSH for the clone URL to avoid requiring SSH key setup. If you're a contributor with write access, you can switch to SSH after cloning using `git remote set-url origin git@github.com:PiTracLM/PiTrac.git` - -## Step 2: Run the Developer Build - -Navigate to the packaging directory and run the developer installation: - -```bash -cd packaging -sudo ./build.sh dev -``` - -> **Important**: You must use `sudo` as the script installs system packages and configures services. - -### What Happens During Installation - -The `build.sh dev` script performs the following steps: - -#### 1. Platform Validation -- Verifies you're running on a Raspberry Pi -- Checks for sudo privileges -- Confirms all pre-built artifacts are available - -#### 2. System Configuration -- Fixes known Pi OS issues (initramfs configuration bug) -- Updates package state -- Prepares the system for installation - -#### 3. Dependency Installation - -**System Packages Installed**: -- Build tools: `build-essential`, `meson`, `ninja-build`, `pkg-config` -- Boost libraries (1.74.0): `libboost-system`, `libboost-thread`, `libboost-filesystem`, and many others -- Camera libraries: `libcamera0.0.3`, `libcamera-dev`, `rpicam-apps` (Pi5) or `libcamera-apps` (Pi4) -- Video processing: FFmpeg libraries, image libraries (JPEG, PNG, TIFF) -- Message broker: `activemq`, `libapr1`, `libaprutil1` -- Python: `python3`, `python3-pip`, and related packages -- Configuration tools: `yq` (YAML query tool) - -**Pre-built Dependencies Installed**: -These are extracted from the `packaging/deps-artifacts/` directory: -- **OpenCV 4.11.0** - Computer vision library (Debian only has 4.6.0) -- **ActiveMQ-CPP 3.9.5** - C++ messaging client -- **lgpio 0.2.2** - GPIO library for Pi 5 (not in Debian repos) -- **msgpack-cxx 6.1.1** - Message serialization -- **ONNX Runtime 1.17.3** - AI inference engine - -> **Why pre-built?**: Building OpenCV from source takes 45-60 minutes. The pre-built artifacts are checked into the git repository so you don't have to wait. - -#### 4. Build PiTrac Binary - -The script compiles the C++ launch monitor binary: -- Sets up proper build environment with library paths -- Applies Boost C++20 compatibility fix -- Detects stale builds and cleans if necessary -- Runs Meson build system with Ninja -- Compiles only changed files (incremental build) - -**Build times**: -- **Total first install**: 10-20 minutes (all dependencies + services + build) -- **PiTrac binary build**: 2-5 minutes -- Incremental rebuild: 30 seconds - 2 minutes -- Clean rebuild (with `force` flag): 2-5 minutes - -#### 5. Installation - -**Binaries and Tools**: -- `/usr/lib/pitrac/pitrac_lm` - Main launch monitor binary -- `/usr/bin/pitrac` - Unified CLI interface (Bashly-generated) -- `/usr/lib/pitrac/ImageProcessing/CameraTools/` - Camera utilities and scripts - -**Configuration**: -- `/etc/pitrac/models/` - ONNX AI models for ball detection -- `/usr/lib/pitrac/web-server/configurations.json` - Configuration metadata (283 settings) - -**Test Resources**: -- `/usr/share/pitrac/test-images/` - Sample test images (teed-ball.png, strobed.png) -- `/usr/share/pitrac/test-suites/` - Automated test suites - -**User Directories**: -- `~/.pitrac/config/` - User configuration and calibration data - - `user_settings.json` - Your configuration overrides - - `calibration_data.json` - Camera calibration results (focal lengths, angles) - - `generated_golf_sim_config.json` - Merged runtime configuration -- `~/.pitrac/state/` - Runtime state -- `~/.pitrac/calibration/` - Calibration tools (checkerboard images, scripts) -- `~/LM_Shares/Images/` - Captured images from shots -- `~/LM_Shares/WebShare/` - Web-accessible data - -#### 6. Camera Configuration - -The script configures libcamera for dual Pi cameras: -- Copies IMX296 NOIR sensor files for your Pi model (4 or 5) -- Creates `rpi_apps.yaml` with extended timeout (1000ms) -- Sets `LIBCAMERA_RPI_CONFIG_FILE` environment variable -- Configures camera detection in boot config - -#### 7. ActiveMQ Message Broker Setup - -ActiveMQ provides communication between PiTrac components: -- Installs ActiveMQ configuration from templates -- Sets up broker on `tcp://localhost:61616` (OpenWire protocol) -- Configures STOMP protocol on port 61613 -- Enables and starts the `activemq.service` - -**Verification**: The script checks that ActiveMQ is listening on port 61616. - -#### 8. Python Web Server Installation - -The FastAPI-based web dashboard is installed: -- Copies web server code to `/usr/lib/pitrac/web-server/` -- Installs Python dependencies from `requirements.txt`: - - `fastapi` - Modern web framework - - `uvicorn` - ASGI server - - `stomp.py` - ActiveMQ connectivity - - `msgpack`, `pyyaml`, `websockets`, and more -- Configures `pitrac-web.service` to run as your user -- Restarts the service if it was already running - -#### 9. Service Configuration - -The script sets up systemd services: -- `activemq.service` - Message broker (system service) -- `pitrac-web.service` - Web dashboard (user service) - -> **Note**: The main `pitrac.service` is no longer automatically installed. You control the launch monitor through the web interface Start/Stop buttons. - -#### 10. Cleanup and Verification - -- Reloads systemd daemon -- Updates shared library cache (`ldconfig`) -- Displays installation summary - -### Installation Output - -During installation, you'll see: -``` -==================================== - PiTrac Developer Build -==================================== - -✓ Platform validation -✓ Checking for pre-built artifacts -✓ Installing system dependencies (80+ packages) -✓ Extracting OpenCV 4.11.0 -✓ Extracting ActiveMQ-CPP 3.9.5 -✓ Extracting lgpio 0.2.2 -✓ Configuring build environment -✓ Building PiTrac binary (this may take a few minutes) -✓ Installing binaries and tools -✓ Configuring libcamera -✓ Installing test resources -✓ Setting up ActiveMQ broker -✓ Installing Python web server -✓ Configuring services - -==================================== - Installation Complete! -==================================== - -Next steps: - 1. Access web dashboard: http://raspberrypi.local:8080 - 2. Start PiTrac from the web interface - 3. Run tests: pitrac test quick - 4. View status: pitrac status - -For help: pitrac help -``` +**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 -## Step 3: Verify Installation - -After installation completes, verify everything is working: - -### Check Service Status - -```bash -# Check all services -pitrac status - -# Or check individually -systemctl status activemq -systemctl status pitrac-web -``` - -**Expected output**: -- `activemq.service` - **active (running)** -- `pitrac-web.service` - **active (running)** or **inactive** (you can start it manually) - -### Test Camera Detection - -```bash -# Pi 5 -rpicam-hello --list-cameras - -# Pi 4 -libcamera-hello --list-cameras -``` - -You should see 2 cameras listed if your hardware is connected. - -### Run Quick Test - -```bash -pitrac test quick -``` - -This runs PiTrac against test images to verify the build is functional. - -## Step 4: Access the Web Dashboard - -The web interface provides control and monitoring for PiTrac. - -### Start the Web Server - -If not already running: - -```bash -sudo systemctl start pitrac-web -``` - -Or use the CLI: - -```bash -pitrac web start -``` - -### Access the Dashboard - -Open a web browser and navigate to: - -``` -http://[YOUR_PI_IP_ADDRESS]:8080 -``` - -To find your Pi's IP address: - -```bash -hostname -I -``` - -Or use the hostname: - -``` -http://raspberrypi.local:8080 -``` +**Time:** 10-20 minutes on Pi 5 (first install, network-dependent) -> **Note**: The default port is 8080. You can change this in the web server configuration. - -## Step 5: Start PiTrac - -From the web dashboard: - -1. Navigate to the **PiTrac Process** section -2. Click **Start** to launch the launch monitor -3. Monitor the status indicators for Camera 1 and Camera 2 - -The web interface will show: -- Camera connection status -- ActiveMQ broker connectivity -- WebSocket connection to browser -- Real-time shot data when balls are hit - -## Web Interface Overview - -The PiTrac web dashboard provides comprehensive control: - -### Main Dashboard -- **Real-time Shot Display**: Ball speed, carry distance, launch angles, spin rates -- **System Status Indicators**: WebSocket, ActiveMQ, cameras -- **Shot Images Gallery**: Browse captured images - -### Configuration -- **Camera Settings**: Configure camera types, lens parameters, gain -- **Detection Methods**: Choose HoughCircles, YOLO, or YOLO+SAHI -- **Simulators**: Set up E6, GSPro, or TruGolf connectivity -- **Logging**: Control log levels and diagnostics -- **Calibration**: Fine-tune strobing, spin analysis - -### Process Control -- **Start/Stop PiTrac**: Control launch monitor processes -- **Monitor Status**: Real-time health monitoring -- **Dual Camera Management**: Independent camera control - -### Calibration Wizard -4-step calibration process: -1. Setup cameras -2. Verify ball placement -3. Run calibration -4. Review and save results - -### Testing Tools -- Hardware testing (IR strobes, still images) -- Calibration verification -- Automated test suites - -### Logs Viewer -- Real-time logs from all services -- Filter by service and log level -- Download logs for analysis - -## Managing PiTrac - -### Web Server Commands - -```bash -# Start the web server -pitrac web start - -# Stop the web server -pitrac web stop - -# Restart the web server -pitrac web restart - -# Check status -pitrac web status - -# View logs -pitrac web logs - -# Follow logs in real-time -pitrac web logs --follow -``` - -### Launch Monitor Control - -**Use the web interface** to start/stop the PiTrac launch monitor: -- Navigate to "PiTrac Process" section -- Click Start/Stop buttons -- Monitor camera status indicators - -### ActiveMQ Management - -```bash -# Check broker status -systemctl status activemq - -# Restart broker (if needed) -sudo systemctl restart activemq - -# View ActiveMQ web console -# Open browser to: http://raspberrypi.local:8161/admin -# Default credentials: admin/admin -``` - -## File Locations - -After installation: - -**Binaries**: -- `/usr/bin/pitrac` - CLI interface -- `/usr/lib/pitrac/pitrac_lm` - Launch monitor binary -- `/usr/lib/pitrac/web-server/` - Python web application - -**Configuration**: -- `/etc/pitrac/pitrac.yaml` - Main config template (system-wide) -- `~/.pitrac/config/user_settings.json` - Your configuration overrides -- `~/.pitrac/config/calibration_data.json` - Camera calibration results -- `~/.pitrac/config/generated_golf_sim_config.json` - Merged runtime configuration - -**User Data**: -- `~/.pitrac/state/` - Runtime state -- `~/.pitrac/logs/` - Application logs -- `~/LM_Shares/Images/` - Captured images -- `~/LM_Shares/WebShare/` - Web-accessible data - -**Test Resources**: -- `/usr/share/pitrac/test-images/` - Sample images -- `/usr/share/pitrac/test-suites/` - Test suites - -**AI Models**: -- `/etc/pitrac/models/` - ONNX models for ball detection - -## Development Workflow +--- -### Updating PiTrac +### APT Package Installation -To get the latest changes from GitHub: +**Coming Soon**: PiTrac will be available as a Debian package for easy installation via `apt`. ```bash -cd ~/PiTrac -git pull -cd packaging -sudo ./build.sh dev +# Future installation (not yet available) +sudo apt update +sudo apt install pitrac ``` -### Incremental Builds +This will provide: +- One-command installation +- Automatic dependency resolution +- System updates through `apt upgrade` +- Simpler for end users -After making code changes, rebuild with: +**Status**: Package infrastructure in development. Check [GitHub Releases](https://github.com/PiTracLM/PiTrac/releases) for availability. -```bash -cd ~/PiTrac/packaging -sudo ./build.sh dev -``` +--- -This performs an **incremental build** (only rebuilds changed files): -- Build time: 30 seconds - 2 minutes -- Web server is automatically updated -- Services are restarted if they were running +## After Installation -### Clean Rebuild +Once PiTrac is installed, follow these guides in order: -To force a complete rebuild from scratch: +### Step 1: First Use -```bash -sudo ./build.sh dev force -``` +**→ [First Use Guide]({% link software/install/first-use.md %})** -Use this if you encounter build errors or want to ensure a clean state. +Learn how to: +- Access the web dashboard +- Start the PiTrac process +- Navigate the web interface +- Make your first shot +- Understand shot data -### Build Artifacts +**Time:** ~10 minutes -The `build.sh` script uses cached artifacts from `packaging/deps-artifacts/`: -- These are checked into Git using Git LFS -- If missing, pull them with: `git lfs pull` -- They contain pre-built OpenCV, ActiveMQ, lgpio, msgpack +--- -## Troubleshooting +### Step 2: Managing PiTrac -### Build Fails with Missing Artifacts +**→ [Managing PiTrac Guide]({% link software/install/managing.md %})** -```bash -cd ~/PiTrac/packaging -git lfs pull -sudo ./build.sh dev -``` +Essential knowledge for: +- Using CLI commands +- Managing services (web server, ActiveMQ) +- Understanding file locations +- Updating PiTrac +- Development workflow +- Backup and restore -### Web Server Won't Start +**Reference guide** - bookmark for when needed -Check status and logs: +--- -```bash -systemctl status pitrac-web -journalctl -u pitrac-web -n 50 -``` +### Step 3: Troubleshooting (If Needed) -Common causes: -- Python dependencies not installed -- ActiveMQ not running -- Port 8080 already in use +**→ [Troubleshooting Guide]({% link software/install/troubleshooting.md %})** -Fix: -```bash -# Reinstall Python dependencies -cd /usr/lib/pitrac/web-server -sudo pip3 install -r requirements.txt --break-system-packages +Solutions for: +- Build failures +- Service issues (web server, ActiveMQ) +- Camera detection problems +- Web interface access +- Shot detection issues +- Performance problems -# Restart ActiveMQ -sudo systemctl restart activemq +**Use when needed** - comprehensive problem-solving reference -# Restart web server -sudo systemctl restart pitrac-web -``` +--- -### Cannot Access Web Interface +## Quick Start Path -1. Verify web server is running: - ```bash - systemctl status pitrac-web - ``` +For experienced users who want the essentials: -2. Check firewall isn't blocking port 8080: +1. **[Build from Source]({% link software/install/build-from-source.md %})** ```bash - sudo ufw status + git clone https://github.com/PiTracLM/PiTrac.git + cd PiTrac/packaging + sudo ./build.sh dev ``` -3. Confirm correct IP address: - ```bash - hostname -I - ``` +2. **[First Use]({% link software/install/first-use.md %})** + - Access web dashboard: `http://raspberrypi.local:8080` + - Start PiTrac from web interface + - Hit test shots -4. Try accessing locally first: - ```bash - curl http://localhost:8080 - ``` +3. **Calibrate** (after first use) + - Run Calibration Wizard in web interface + - See [Camera Calibration]({% link camera/cameras.md %}) for details -### ActiveMQ Connection Issues +--- -Verify ActiveMQ is running: +## System Architecture -```bash -systemctl status activemq -``` +Understanding what PiTrac installs helps with troubleshooting: -Check port 61616 is listening: +### 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) -```bash -sudo netstat -tln | grep 61616 +### 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 ``` -If not running: +### 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 -```bash -sudo systemctl start activemq -sudo systemctl enable activemq -``` +--- -### Camera Not Detected +## What's Next? -Check boot configuration: +After completing installation: -```bash -# Pi 5 -cat /boot/firmware/config.txt | grep camera +**Essential:** +1. **[First Use Guide]({% link software/install/first-use.md %})** - Access web interface and make first shot +2. **Calibration Wizard** - Run through web interface for accurate measurements -# Pi 4 -cat /boot/config.txt | grep camera -``` +**Optional:** +- **[Camera Calibration]({% link camera/cameras.md %})** - Advanced calibration techniques +- **[Simulator Integration]({% link simulator-integration.md %})** - Connect to E6, GSPro, TruGolf +- **[Express Path]({% link quickstart.md %})** - Streamlined setup for experienced users -Should have: `camera_auto_detect=1` +**Reference:** +- **[Managing PiTrac]({% link software/install/managing.md %})** - Commands, file locations, updates +- **[Troubleshooting]({% link software/install/troubleshooting.md %})** - Problem-solving guide -Verify libcamera environment: +--- -```bash -echo $LIBCAMERA_RPI_CONFIG_FILE -``` +## Getting Help -Should point to correct pipeline (vc4 for Pi4, pisp for Pi5). +**For installation issues:** +- Check the **[Troubleshooting Guide]({% link software/install/troubleshooting.md %})** first +- Review logs: `pitrac web logs` or `journalctl -u pitrac-web` +- Verify prerequisites were completed -Test cameras: +**Community support:** +- **[Discord Community](https://discord.gg/j9YWCMFVHN)** - Active community for questions and help +- **[GitHub Issues](https://github.com/PiTracLM/PiTrac/issues)** - Report bugs or request features +- **[General Troubleshooting]({% link troubleshooting.md %})** - Broader system issues +**CLI help:** ```bash -# Pi 5 -rpicam-hello --list-cameras - -# Pi 4 -libcamera-hello --list-cameras +pitrac help # Show all commands +pitrac status # Check service status ``` -### Build Errors +--- -If build fails, try a clean rebuild: +## Installation Workflow -```bash -cd ~/PiTrac/packaging -sudo ./build.sh dev force ``` - -Check you have enough disk space: - -```bash -df -h +┌─────────────────────────────────────┐ +│ 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 │ +└─────────────────────────────────────┘ ``` -Need at least 5GB free. - -## Next Steps - -Once PiTrac is running: - -1. **Calibrate Your Cameras**: Use the Calibration Wizard in the web interface -2. **Configure Your Simulator**: Set up E6, GSPro, or TruGolf in the Configuration section -3. **Test the System**: Hit test shots and verify shot detection -4. **Fine-tune Settings**: Adjust detection parameters for your lighting and setup -5. **Review Documentation**: Check the [Camera Calibration Guide]({% link camera/cameras.md %}) for advanced calibration +--- -## Getting Help +## Return To -- **CLI Help**: Run `pitrac help` for all available commands -- **System Status**: Run `pitrac status` to check all services -- **Logs**: Check logs with `pitrac web logs` or `journalctl -u pitrac-web` -- **Discord Community**: Join the [PiTrac Discord](https://discord.gg/j9YWCMFVHN) -- **GitHub Issues**: Report bugs at [github.com/PiTracLM/PiTrac](https://github.com/PiTracLM/PiTrac/issues) +- **[Software Overview]({% link software/software.md %})** - Software section home +- **[Raspberry Pi Setup]({% link software/pi-setup.md %})** - Pi OS installation and configuration diff --git a/docs/software/software.md b/docs/software/software.md index e2539971..b2602ec9 100644 --- a/docs/software/software.md +++ b/docs/software/software.md @@ -1,8 +1,12 @@ --- title: Software layout: default -nav_order: 4 +nav_order: 5 has_children: true +description: Complete software setup guide for PiTrac including Raspberry Pi OS installation, PiTrac software installation, web dashboard configuration, and camera calibration. +keywords: raspberry pi golf software, launch monitor software install, pitrac setup, golf tracker configuration, raspberry pi OS setup +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 --- # Software diff --git a/docs/software/using-pitrac.md b/docs/software/using-pitrac.md index 37f1e4b4..6c61bf11 100644 --- a/docs/software/using-pitrac.md +++ b/docs/software/using-pitrac.md @@ -3,6 +3,10 @@ title: Using PiTrac layout: default nav_order: 3 parent: Software +description: Complete guide to operating PiTrac golf launch monitor including web dashboard usage, configuration management, shot tracking, data review, and daily operation tips. +keywords: use pitrac golf monitor, web dashboard golf, launch monitor operation, track golf shots, configure launch monitor, golf data review +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 --- # Using PiTrac diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 65868ae2..f82e1428 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,7 +1,11 @@ --- title: Troubleshooting layout: default -nav_order: 6 +nav_order: 8 +description: Comprehensive troubleshooting guide for PiTrac golf launch monitor covering installation issues, camera problems, calibration failures, and common software errors. +keywords: pitrac troubleshooting, golf monitor problems, camera not detected, calibration failed, installation errors, raspberry pi issues +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 --- # Troubleshooting diff --git a/docs/what-is-pitrac.md b/docs/what-is-pitrac.md index 25bcb03f..85417113 100644 --- a/docs/what-is-pitrac.md +++ b/docs/what-is-pitrac.md @@ -1,9 +1,11 @@ --- title: What is PiTrac? layout: default -nav_order: 1.2 -description: Learn about PiTrac, the open-source DIY golf launch monitor that measures ball speed, launch angles, and spin using affordable Raspberry Pi hardware and infrared strobe imaging. -keywords: PiTrac introduction, golf launch monitor DIY, ball speed measurement, launch angle tracking, spin rate analysis, raspberry pi camera +nav_order: 1.1 +description: Learn about PiTrac, the open-source DIY golf launch monitor that measures ball speed, launch angles, and spin using affordable Raspberry Pi hardware and infrared strobe imaging. Community-built learning project for makers. +keywords: PiTrac introduction, golf launch monitor DIY, ball speed measurement, launch angle tracking, spin rate analysis, raspberry pi camera, open source golf project, maker community golf +og_image: /assets/images/logos/PiTrac_Square.png +last_modified_date: 2025-01-04 parent: Home --- diff --git a/packaging/build-apt-package.sh b/packaging/build-apt-package.sh index 8a86e0a0..39b67f70 100755 --- a/packaging/build-apt-package.sh +++ b/packaging/build-apt-package.sh @@ -289,7 +289,7 @@ Version: $VERSION Architecture: $ARCH Maintainer: $MAINTAINER Installed-Size: $size -Depends: libc6 (>= 2.36), libstdc++6 (>= 12), libgcc-s1 (>= 12), libcamera0.0.3, libcamera-dev, libcamera-tools, rpicam-apps, libboost-system1.74.0, libboost-thread1.74.0, libboost-program-options1.74.0, libboost-filesystem1.74.0, libboost-log1.74.0, libboost-regex1.74.0, libboost-timer1.74.0, libfmt9, libssl3, libtbb12, libgstreamer1.0-0, libgstreamer-plugins-base1.0-0, libgtk-3-0, libavcodec59, libavformat59, libswscale6, libopenexr-3-1-30, libavutil57, libavdevice59, libexif12, libjpeg62-turbo, libtiff6, libpng16-16, libdrm2, libx11-6, libepoxy0, libqt5core5a, libqt5widgets5, libqt5gui5, libapr1, libaprutil1, libuuid1, activemq, default-jre-headless | openjdk-17-jre-headless, gpiod, net-tools, python3, python3-opencv, python3-numpy, python3-yaml, yq +Depends: libc6 (>= 2.36), libstdc++6 (>= 12), libgcc-s1 (>= 12), libcamera-dev, libcamera-tools, rpicam-apps | libcamera-apps, libboost-system1.74.0 | libboost-system1.83.0 | libboost-system1.88.0, libboost-thread1.74.0 | libboost-thread1.83.0 | libboost-thread1.88.0, libboost-program-options1.74.0 | libboost-program-options1.83.0 | libboost-program-options1.88.0, libboost-filesystem1.74.0 | libboost-filesystem1.83.0 | libboost-filesystem1.88.0, libboost-log1.74.0 | libboost-log1.83.0 | libboost-log1.88.0, libboost-regex1.74.0 | libboost-regex1.83.0 | libboost-regex1.88.0, libboost-timer1.74.0 | libboost-timer1.83.0 | libboost-timer1.88.0, libfmt9 | libfmt10 | libfmt11, libssl3t64 | libssl3, libtbb12, libgstreamer1.0-0, libgstreamer-plugins-base1.0-0, libgtk-3-0 | libgtk-3-0t64, libavcodec59 | libavcodec60 | libavcodec61, libavformat59 | libavformat60 | libavformat61, libswscale6 | libswscale7 | libswscale8, libopenexr-3-1-30, libavutil57 | libavutil58 | libavutil59, libavdevice59 | libavdevice60 | libavdevice61, libexif12, libjpeg62-turbo, libtiff6 | libtiff6t64, libpng16-16 | libpng16-16t64, libdrm2, libx11-6, libepoxy0, libqt5core5a | libqt5core5t64, libqt5widgets5 | libqt5widgets5t64, libqt5gui5 | libqt5gui5t64, libapr1 | libapr1t64, libaprutil1 | libaprutil1t64, libuuid1, activemq, default-jre-headless | openjdk-17-jre-headless, gpiod, net-tools, python3, python3-opencv, python3-numpy, python3-yaml, yq Recommends: maven Section: misc Priority: optional diff --git a/packaging/build.sh b/packaging/build.sh index 334d5a0c..dc56801c 100755 --- a/packaging/build.sh +++ b/packaging/build.sh @@ -113,7 +113,7 @@ check_artifacts() { build_deps() { log_info "Building dependency artifacts..." - if [ "$FORCE_REBUILD" = "true" ]; then + if [ "$FORCE_REBUILD" = "true" ] || [ "$FORCE_REBUILD" = "force" ]; then log_warn "Force rebuild enabled - removing existing artifacts" rm -f "$ARTIFACT_DIR"/*.tar.gz fi @@ -249,12 +249,6 @@ build_dev() { exit 1 fi - # Check for force rebuild flag - if [[ "${2:-}" == "force" ]]; then - FORCE_REBUILD="true" - log_info "Force rebuild requested - will clean build directory" - fi - log_info "Regenerating pitrac CLI tool..." if [[ -f "$SCRIPT_DIR/generate.sh" ]]; then cd "$SCRIPT_DIR" @@ -284,17 +278,15 @@ build_dev() { fi done - # Boost libraries (runtime and dev) - for pkg in libboost-system1.74.0 libboost-thread1.74.0 libboost-filesystem1.74.0 \ - libboost-program-options1.74.0 libboost-timer1.74.0 libboost-log1.74.0 \ - libboost-regex1.74.0 libboost-dev libboost-all-dev libyaml-cpp-dev; do + # Boost libraries (dev packages pull in correct runtime versions automatically) + for pkg in libboost-dev libboost-all-dev libyaml-cpp-dev; do if ! dpkg -l | grep -q "^ii $pkg"; then missing_deps+=("$pkg") fi done - # Core libraries - for pkg in libcamera0.0.3 libcamera-dev libcamera-tools libfmt-dev libssl-dev libssl3 \ + # Core libraries (libcamera-dev pulls in correct runtime version) + for pkg in libcamera-dev libcamera-tools libfmt-dev libssl-dev \ libmsgpack-cxx-dev \ libapr1 libaprutil1 libapr1-dev libaprutil1-dev; do if ! dpkg -l | grep -q "^ii $pkg"; then @@ -334,9 +326,9 @@ build_dev() { fi fi - # OpenCV runtime dependencies - for pkg in libgtk-3-0 libavcodec59 libavformat59 libswscale6 libtbb12 \ - libgstreamer1.0-0 libgstreamer-plugins-base1.0-0 libopenexr-3-1-30; do + # OpenCV runtime dependencies (using -dev packages to handle version differences) + # Note: GTK3 changed from libgtk-3-0 to libgtk-3-0t64 in Trixie + for pkg in libgtk-3-dev libtbb-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev libopenexr-dev; do if ! dpkg -l | grep -q "^ii $pkg"; then missing_deps+=("$pkg") fi @@ -453,7 +445,29 @@ build_dev() { log_info "Installing pre-built dependencies..." mkdir -p /usr/lib/pitrac - extract_all_dependencies "$ARTIFACT_DIR" "/usr/lib/pitrac" + + # Try APT repository first, fall back to local packages + local use_apt=false + if configure_pitrac_apt_repo; then + if install_dependencies_from_apt; then + use_apt=true + log_success "Dependencies installed from APT repository" + else + log_warn "APT installation failed, falling back to local packages" + fi + else + log_info "APT repository not available, using local packages" + fi + + # Fall back to local packages if APT didn't work + if [[ "$use_apt" == "false" ]]; then + if ! check_artifacts; then + log_error "Neither APT repository nor local packages available" + log_info "Local packages should be in: $ARTIFACT_DIR" + exit 1 + fi + extract_all_dependencies "$ARTIFACT_DIR" "/usr/lib/pitrac" + fi # Update library cache ldconfig @@ -516,13 +530,13 @@ build_dev() { fi # Determine if we need a clean build - if [[ "$FORCE_REBUILD" == "true" ]]; then + if [[ "$FORCE_REBUILD" == "true" ]] || [[ "$FORCE_REBUILD" == "force" ]]; then log_info "Force rebuild requested - cleaning build directory..." rm -rf build fi - # Only run meson setup if build directory doesn't exist - if [[ ! -d "build" ]]; then + # Only run meson setup if build directory doesn't exist or force rebuild was requested + if [[ ! -d "build" ]] || [[ "$FORCE_REBUILD" == "true" ]] || [[ "$FORCE_REBUILD" == "force" ]]; then log_info "Configuring build with Meson..." meson setup build --buildtype=release -Denable_recompile_closed_source=false elif [[ "meson.build" -nt "build/build.ninja" ]] 2>/dev/null; then @@ -813,7 +827,17 @@ EOF echo " Configs: /etc/pitrac/" echo " Web Server: /usr/lib/pitrac/web-server (updated)" echo "" + + # Show dependency source + if [[ -f /etc/apt/sources.list.d/pitrac.list ]]; then + echo "Dependencies: PiTrac APT Repository" + echo " Repository: https://github.com/PiTracLM/packages" + echo " Distribution: $(detect_debian_codename)" + else + echo "Dependencies: Local packages (deps-artifacts)" + fi echo "" + echo "Web server status:" if systemctl is-active --quiet pitrac-web.service; then echo " Web service is running" diff --git a/packaging/scripts/build-webserver.sh b/packaging/scripts/build-webserver.sh index 5b888b96..4caf44c3 100755 --- a/packaging/scripts/build-webserver.sh +++ b/packaging/scripts/build-webserver.sh @@ -43,8 +43,8 @@ mkdir -p "$INSTALL_DIR" cp -r web-server/* "$INSTALL_DIR/" # Install Python dependencies -pip3 install -r "$INSTALL_DIR/requirements.txt" --break-system-packages 2>/dev/null || \ -pip3 install -r "$INSTALL_DIR/requirements.txt" +pip3 install -r "$INSTALL_DIR/requirements.txt" --break-system-packages --ignore-installed 2>/dev/null || \ +pip3 install -r "$INSTALL_DIR/requirements.txt" --ignore-installed # Install systemd service cp "$INSTALL_DIR/pitrac-web.service" /etc/systemd/system/ diff --git a/packaging/src/lib/pitrac-common-functions.sh b/packaging/src/lib/pitrac-common-functions.sh index 51340477..04d157fd 100755 --- a/packaging/src/lib/pitrac-common-functions.sh +++ b/packaging/src/lib/pitrac-common-functions.sh @@ -532,6 +532,18 @@ extract_all_dependencies() { log_info "Installing all dependencies..." + # Check if packages were already installed from APT repository + local has_apt_packages=false + if dpkg -l | grep -qE "^ii\s+(libopencv4\.11|libactivemq-cpp)\s"; then + # Check if they came from our APT repo (not from local debs) + if grep -q "pitrac" /etc/apt/sources.list.d/pitrac.list 2>/dev/null; then + has_apt_packages=true + log_info "Dependencies already installed from PiTrac APT repository" + log_info "Skipping local package installation" + return 0 + fi + fi + if [[ "$use_debs" == "true" ]]; then # Check if deb packages exist if [[ -f "$artifacts_dir/libopencv4.11_4.11.0-1_arm64.deb" ]]; then @@ -598,23 +610,23 @@ install_python_dependencies() { log_info "Installing Python dependencies for web server..." if [[ $EUID -eq 0 ]]; then - if pip3 install -r "$web_server_dir/requirements.txt" --break-system-packages 2>/dev/null; then + if pip3 install -r "$web_server_dir/requirements.txt" --break-system-packages --ignore-installed 2>/dev/null; then log_success "Python dependencies installed successfully" - elif pip3 install -r "$web_server_dir/requirements.txt" 2>/dev/null; then + elif pip3 install -r "$web_server_dir/requirements.txt" --ignore-installed 2>/dev/null; then log_success "Python dependencies installed successfully" else log_error "Failed to install Python dependencies" - log_info "Try manually: pip3 install -r $web_server_dir/requirements.txt --break-system-packages" + log_info "Try manually: pip3 install -r $web_server_dir/requirements.txt --break-system-packages --ignore-installed" return 1 fi else - if sudo pip3 install -r "$web_server_dir/requirements.txt" --break-system-packages 2>/dev/null; then + if sudo pip3 install -r "$web_server_dir/requirements.txt" --break-system-packages --ignore-installed 2>/dev/null; then log_success "Python dependencies installed successfully" - elif sudo pip3 install -r "$web_server_dir/requirements.txt" 2>/dev/null; then + elif sudo pip3 install -r "$web_server_dir/requirements.txt" --ignore-installed 2>/dev/null; then log_success "Python dependencies installed successfully" else log_error "Failed to install Python dependencies" - log_info "Try manually: sudo pip3 install -r $web_server_dir/requirements.txt --break-system-packages" + log_info "Try manually: sudo pip3 install -r $web_server_dir/requirements.txt --break-system-packages --ignore-installed" return 1 fi fi @@ -742,6 +754,164 @@ install_service_from_template() { fi log_success "$service_name service installed successfully!" - + + return 0 +} + +# ======================================================================== +# Detect Debian distribution codename +# ======================================================================== +# Returns: bookworm, trixie, or unknown +# Used for: Multi-distribution APT repository support +# ======================================================================== +detect_debian_codename() { + local codename="unknown" + + # Try lsb_release first (most reliable) + if command -v lsb_release &> /dev/null; then + codename=$(lsb_release -cs 2>/dev/null) + fi + + # Fallback to /etc/os-release + if [[ "$codename" == "unknown" ]] && [[ -f /etc/os-release ]]; then + codename=$(grep "^VERSION_CODENAME=" /etc/os-release | cut -d'=' -f2) + fi + + # Fallback to /etc/debian_version (numeric to codename mapping) + if [[ "$codename" == "unknown" ]] && [[ -f /etc/debian_version ]]; then + local version=$(cat /etc/debian_version) + case "$version" in + 12.*) codename="bookworm" ;; + 13.*) codename="trixie" ;; + esac + fi + + echo "$codename" +} + +# ======================================================================== +# Configure PiTrac APT Repository +# ======================================================================== +# Adds the PiTrac APT repository with GPG key and distribution detection +# Returns: 0 on success, 1 if repo unavailable (falls back to local) +# ======================================================================== +configure_pitrac_apt_repo() { + local repo_url="https://pitraclm.github.io/packages" + local key_url="$repo_url/pitrac-repo.asc" + local sources_file="/etc/apt/sources.list.d/pitrac.list" + local keyring_file="/usr/share/keyrings/pitrac.gpg" + + log_info "Configuring PiTrac APT repository..." + + # Detect Debian codename + local codename=$(detect_debian_codename) + + if [[ "$codename" != "bookworm" ]] && [[ "$codename" != "trixie" ]]; then + log_warn "Unsupported Debian version: $codename" + log_info "Supported: bookworm (12.x), trixie (13.x)" + return 1 + fi + + log_info "Detected Debian $codename" + + # Check if repository is accessible + if ! curl --head --silent --fail "$repo_url/dists/$codename/Release" > /dev/null 2>&1; then + log_warn "PiTrac APT repository not accessible at $repo_url" + log_info "Will use local packages from deps-artifacts instead" + return 1 + fi + + # Download and install GPG key + log_info "Installing repository GPG key..." + # Remove existing key file to avoid overwrite prompts + rm -f "$keyring_file" + if ! curl -fsSL "$key_url" | gpg --dearmor -o "$keyring_file" 2>/dev/null; then + log_error "Failed to download repository GPG key" + return 1 + fi + + # Create APT sources list entry + log_info "Adding repository to APT sources..." + echo "deb [arch=arm64 signed-by=$keyring_file] $repo_url $codename main" > "$sources_file" + + # Update APT cache + log_info "Updating APT package index..." + if ! apt-get update 2>&1 | grep -v "^Ign:" | grep -v "^Get:" | grep -v "^Hit:"; then + log_error "Failed to update APT cache" + rm -f "$sources_file" "$keyring_file" + return 1 + fi + + log_success "PiTrac APT repository configured for Debian $codename" + return 0 +} + +# ======================================================================== +# Install Dependencies from APT Repository +# ======================================================================== +# Installs PiTrac dependencies from the configured APT repo +# Returns: 0 on success, 1 on failure +# ======================================================================== +install_dependencies_from_apt() { + log_info "Installing PiTrac dependencies from APT repository..." + + local packages=( + "liblgpio1" + "libmsgpack-cxx-dev" + "libactivemq-cpp" + "libactivemq-cpp-dev" + "libopencv4.11" + "libopencv-dev" + ) + + # Add ONNX Runtime based on distribution + local codename=$(detect_debian_codename) + case "$codename" in + bookworm) + packages+=("libonnxruntime1.17.3") + ;; + trixie) + packages+=("libonnxruntime1.22.1") + ;; + *) + log_warn "Unknown distribution, will attempt generic ONNX install" + ;; + esac + + # Check which packages are available + log_info "Verifying package availability..." + local available_packages=() + local missing_packages=() + + for pkg in "${packages[@]}"; do + if apt-cache show "$pkg" &>/dev/null; then + available_packages+=("$pkg") + else + missing_packages+=("$pkg") + fi + done + + if [ ${#missing_packages[@]} -gt 0 ]; then + log_warn "Some packages not available in APT: ${missing_packages[*]}" + log_info "Will fall back to local packages for missing dependencies" + fi + + if [ ${#available_packages[@]} -eq 0 ]; then + log_error "No packages available from APT repository" + return 1 + fi + + # Install available packages + log_info "Installing packages: ${available_packages[*]}" + if ! INITRD=No apt-get install -y "${available_packages[@]}"; then + log_error "Failed to install packages from APT repository" + return 1 + fi + + log_success "Installed ${#available_packages[@]} packages from APT repository" + + # Update library cache + ldconfig + return 0 } \ No newline at end of file diff --git a/packaging/templates/postinst.sh b/packaging/templates/postinst.sh index fe2acb64..d12a3e3a 100644 --- a/packaging/templates/postinst.sh +++ b/packaging/templates/postinst.sh @@ -93,8 +93,8 @@ case "$1" in install_python_dependencies "/usr/lib/pitrac/web-server" else echo "Installing Python web server dependencies..." - pip3 install -r /usr/lib/pitrac/web-server/requirements.txt --break-system-packages 2>/dev/null || \ - pip3 install -r /usr/lib/pitrac/web-server/requirements.txt || true + pip3 install -r /usr/lib/pitrac/web-server/requirements.txt --break-system-packages --ignore-installed 2>/dev/null || \ + pip3 install -r /usr/lib/pitrac/web-server/requirements.txt --ignore-installed || true fi if [ -x /usr/lib/pitrac/web-service-install.sh ] && [ -n "$ACTUAL_USER" ]; then