add docs

docs/README.md

@@ -0,0 +1,23 @@
+# BOS Documentation
+
+This folder contains project-level docs for the BOS codebase.
+
+## Contents
+
+- [Architecture Overview](architecture.md)
+- [Build and Run](build-and-run.md)
+- [Scripts Reference](scripts.md)
+- [Testing Guide](testing.md)
+
+## Quick Start
+
+```bash
+./scripts/build.sh
+```
+
+Primary executables are built from `src/`:
+
+- `main_bot_main`
+- `second_bot_main`
+- `unambiguous_first`
+- `unambiguous_second`

docs/architecture.md

@@ -0,0 +1,89 @@
+# Architecture Overview
+
+## High-Level Flow
+
+The runtime system is built around a vision and localization pipeline:
+
+1. Camera modules capture frames.
+2. AprilTag detectors produce per-frame detections.
+3. Solvers estimate robot pose from detections.
+4. Position senders publish results to NetworkTables (and optional simulation outputs).
+5. Pathing and controller logic consume localization output and publish control intents.
+
+## Source Tree Map
+
+### `src/camera`
+
+- Camera interfaces and implementations (`CV`, `UVC`, disk replay).
+- Frame production wrappers (`CameraSource`, `MultiCameraSource`).
+- CSCore streaming to webpage and opencv write to disk.
+- Camera constants loading from JSON.
+- Camera selection for testing
+
+### `src/localization`
+
+- AprilTag detector interface and implementations:
+  - OpenCV ArUco AprilTag
+  - 971 GPU AprilTag (austin_gpu)
+  - NVIDIA VPI AprilTag
+- Pose solvers:
+  - `SquareSolver` (single tag)
+  - `MultiTagSolver` (multi-tag)
+  - `JointSolver` (multi-camera optimization)
+  - `UnambiguousEstimator` (ambiguity resolution and fusion)
+- Main localization loop (`run_localization`).
+- Publishers and receivers for position data.
+
+### `src/pathing`
+
+- BFS grid pathfinding.
+- Spline generation.
+- Control loop integration for command publication.
+
+### `src/yolo` and `src/gamepiece`
+
+- TensorRT-based YOLO wrapper.
+- Gamepiece pipeline built on top of camera + yolo + localization utilities.
+
+### `src/utils`
+
+- Shared cross-cutting helpers:
+  - logging
+  - timers
+  - transforms / matrix operations
+  - NetworkTables utility helpers
+  - JSON constant handling
+
+### `src/calibration`
+
+- Intrinsics calibration tools.
+- Frame display and focus calibration binaries.
+
+### `src/test`
+
+- `unit_test`: tests whose output can be decided without human input.
+- `integration_test`: tests whose output is in the form of a log or feed which must be reviewed
+
+## Top-Level Binaries (Some deprecated)
+
+Defined in `src/CMakeLists.txt`:
+
+- `main_bot_main`
+- `second_bot_main`
+- `unambiguous_first`
+- `unambiguous_second`
+
+## Dependency Snapshot
+
+Major linked dependencies across modules:
+
+- OpenCV
+- Eigen3
+- WPILib (`wpilibc`, `wpiutil`, `ntcore`)
+- libuvc
+- NVIDIA VPI
+- TensorRT / CUDA (`nvinfer`, `nvinfer_plugin`, `cudart`)
+- 971 AprilTag
+- abseil
+- nlohmann/json
+- GoogleTest

docs/build-and-run.md

@@ -0,0 +1,47 @@
+# Build and Run
+
+## Prerequisites
+
+You can get set up in two ways:
+
+1. Get access to the build server over Tailscale.
+2. Build your own BOS Docker container from `https://github.com/frc971/bos-docker`.
+
+Also ensure CUDA binaries are on your shell `PATH` by adding this to your `~/.zshrc` or `~/.bashrc`:
+
+```bash
+export PATH="/usr/local/cuda-12.6/bin:$PATH"
+```
+
+If you are using the build server or the BOS Docker container, required toolchains and dependencies are already provided.
+
+## Build
+
+Use the project build script instead of running CMake manually:
+
+```bash
+./scripts/build.sh
+```
+
+Optional named build directory:
+
+```bash
+./scripts/build.sh --name=mybuild
+```
+
+## Main Runtime Binaries
+
+After building, these are the primary app entry points (some deprecated):
+
+- `main_bot_main`
+- `second_bot_main`
+- `unambiguous_first`
+- `unambiguous_second`
+
+## Calibration Tools
+
+Built in `src/calibration`:
+
+- `intrinsics_calibrate`
+- `frame_shower`
+- `focus_calibrate`

docs/scripts.md

@@ -0,0 +1,102 @@
+# Scripts Reference
+
+This document describes the scripts under `scripts/` and when to use them.
+
+## Build and Static Analysis
+
+### `scripts/build.sh`
+
+- Main build entrypoint.
+- Initializes submodules.
+- Creates `/bos/constants` when running outside `/bos`.
+- Configures a Release Ninja build with clang-tidy disabled.
+
+Usage:
+
+```bash
+./scripts/build.sh
+./scripts/build.sh --name=mybuild
+```
+
+### `scripts/clang_tidy_build.sh`
+
+- Build helper with clang-tidy enabled.
+- Uses `build/` as the output directory.
+- Usually used for CI checks rather than day-to-day local builds.
+
+Usage:
+
+```bash
+./scripts/clang_tidy_build.sh
+```
+
+## Test Execution
+
+### `scripts/run_tests.sh`
+
+- Runs all executable files in `build/src/test/unit_test`.
+- Returns non-zero if any test fails.
+
+Usage:
+
+```bash
+./scripts/run_tests.sh
+```
+
+## Deploy and Remote Sync
+
+### `scripts/copy_to_bin.sh`
+
+- Collects built executables from `build/src` into `bin/`.
+- Also copies `.so` and `.a` artifacts from `build/` into `bin/`.
+
+Usage:
+
+```bash
+./scripts/copy_to_bin.sh
+```
+
+### `scripts/deploy.sh`
+
+- Builds project, stages binaries into `bin/`, then rsyncs `bin/` and `constants/` to remote `/bos`.
+- Optional remote service restart (`bos.service`).
+
+Usage:
+
+```bash
+./scripts/deploy.sh nvidia@10.99.71.11
+./scripts/deploy.sh nvidia@10.99.71.11 true
+```
+
+### `scripts/remote_deploy.sh`
+
+- Like `deploy.sh`, but lets you pass a custom remote shell command (for jump-host/tunnel setups).
+- Current workflow uses a reverse tunnel through the build server.
+
+Usage:
+
+```bash
+ssh -R 9000:localhost:22 root@build-server
+./scripts/remote_deploy.sh "ssh -J charlie@localhost:9000" "nvidia@10.9.71.11"
+```
+
+### `scripts/upload_navgrid.sh`
+
+- Copies a local navgrid file into the running `orin` Docker container.
+- Then deploys to `nvidia@10.99.71.11` without restart.
+
+Usage:
+
+```bash
+./scripts/upload_navgrid.sh
+```
+
+### `scripts/upload_public_key.sh`
+
+- Uploads local `~/.ssh/id_ed25519.pub` and appends it to remote `authorized_keys`.
+
+Usage:
+
+```bash
+./scripts/upload_public_key.sh nvidia@10.99.71.11
+```

docs/testing.md

@@ -0,0 +1,32 @@
+# Testing Guide
+
+## Test Layout
+
+Tests live under `src/test`:
+
+- `src/test/unit_test`: GoogleTest-based unit tests.
+- `src/test/integration_test`: integration executables for subsystems and end-to-end checks.
+
+## Build Tests
+
+Tests are part of the normal project build. Use the project build script:
+
+```bash
+./scripts/build.sh
+```
+
+If you use a named build directory, keep that same directory when running tests:
+
+```bash
+./scripts/build.sh --name=mybuild
+```
+
+## Run Tests
+
+Use the test runner script instead of running test binaries manually:
+
+```bash
+./scripts/run_tests.sh
+```
+
+This script runs executable tests in `build/src/test/unit_test` and returns a failing exit code if any test fails.

src/calibration/README.md

@@ -0,0 +1,20 @@
+# Calibration
+
+This directory contains camera-calibration tools and the shared ChArUco-board utilities they use.
+
+## Files
+
+- `CMakeLists.txt` builds the standalone calibration executables in this directory.
+- `focus_calibrate.cc` opens a selected camera, streams frames through CSCore, and prints a Laplacian-based focus score so the lens can be adjusted live.
+- `frame_shower.cc` opens a selected camera and streams raw frames to a configurable port for visual inspection and camera bring-up.
+- `intrinsics_calibrate.cc` is the interactive calibration executable. It captures ChArUco detections from a selected camera, generates `calibration_board.png`, calibrates the camera, and writes `intrinsics.json`.
+- `intrinsics_calibrate_lib.h` declares the ChArUco calibration data structures, board constants, detector factory, drawing helpers, JSON conversion, and calibration routine.
+- `intrinsics_calibrate_lib.cc` implements the shared ChArUco workflow: detector construction, board rendering, board detection, annotation, OpenCV calibration, and intrinsic-parameter JSON serialization.
+
+## Main Types And Functions
+
+- `calibration::DetectionResult` holds one frame's ChArUco corners, IDs, object points, and image points.
+- `calibration::CreateDetector` builds an OpenCV `cv::aruco::CharucoDetector` using the project's board geometry.
+- `calibration::GenerateBoard` renders the printable ChArUco board image.
+- `calibration::DetectCharucoBoard` extracts calibration observations from an image.
+- `calibration::CalibrateCamera` converts collected observations into an OpenCV camera matrix and distortion coefficients.

src/camera/README.md

@@ -0,0 +1,29 @@
+# Camera
+
+This directory defines the camera abstraction used by localization, calibration, gamepiece detection, tests, and replay tooling.
+
+## Files
+
+- `CMakeLists.txt` builds the `camera` library from the camera implementations and helpers.
+- `camera.h` defines `camera::TimestampedFrame`, the common frame-plus-timestamp payload, and `camera::ICamera`, the interface implemented by all frame sources.
+- `camera_constants.h` declares `camera::CameraConstant`, `camera::DetectorType`, the camera-constant map type, and loaders for configured camera constants.
+- `camera_constants.cc` loads camera configuration data from JSON into `CameraConstant` records.
+- `camera_source.h` / `camera_source.cc` wrap one `ICamera` in a background acquisition thread and expose the most recent timestamped frame safely.
+- `multi_camera_source.h` / `multi_camera_source.cc` coordinate several `ICamera` instances, including replay-oriented modes that wait for consumers to use every frame.
+- `cv_camera.h` / `cv_camera.cc` adapt OpenCV/GStreamer `cv::VideoCapture` cameras to the `ICamera` interface and optionally log captured frames.
+- `uvc_camera.h` / `uvc_camera.cc` adapt libuvc devices to `ICamera`, including UVC-specific setup, frame buffering, restart, and cleanup.
+- `disk_camera.h` / `disk_camera.cc` replay timestamped image logs from disk as an `ICamera`, preserving logged timing with optional speed, start, and end controls.
+- `cscore_streamer.h` / `cscore_streamer.cc` publish OpenCV frames through WPILib CSCore MJPEG streams for debugging and dashboards.
+- `select_camera.h` / `select_camera.cc` choose a configured camera interactively or from a provided camera name.
+- `write_frame.h` / `write_frame.cc` write timestamped frames to disk for later replay.
+
+## Main Types
+
+- `camera::ICamera` is the polymorphic interface for live cameras and replay sources.
+- `camera::CameraSource` is a frame provider which independently spins up a thread to read the latest frame.
+- `camera::MultiCameraSource` is basically a bundle of camera sources, but it is responsible for maintaining all the latest frames across 2+ cameras.
+- `camera::CVCamera`, `camera::UVCCamera`, and `camera::DiskCamera` provide the concrete live and replay frame sources.
+  - `camera::CVCamera` is the standard camera stream reader, can process anything like IMX or USB. WARNING usb cameras using usb 2.0 will claim too much bandwidth over this protocol, so use `camera::UVCCamera` instead.
+  - `camera::UVCCamera` is for USB specifically, and manually adjusts payload size so that we can get many simultaneous USB camera feeds.
+  - `camera::DiskCamera` is for testing, and can process frames in a specific time range and go faster if requested.
+- `camera::CscoreStreamer` is the standard debug-stream output path.

src/gamepiece/README.md

@@ -0,0 +1,14 @@
+# Gamepiece
+
+This directory connects YOLO object detections to robot-relative gamepiece positions. TODO extend
+
+## Files
+
+- `CMakeLists.txt` builds the `gamepiece` library.
+- `gamepiece.h` declares the gamepiece detection entry points.
+- `gamepiece.cc` runs YOLO on camera frames, estimates coral and algae positions from camera intrinsics/extrinsics and bounding-box centers, publishes the resulting `frc::Pose2d` values to NetworkTables, and provides a no-image inference path for model testing.
+
+## Main Functions
+
+- `gamepiece::run_gamepiece_detect` consumes frames from `camera::CameraSource`, runs a `yolo::Yolo` model, converts detections into robot-relative poses, and publishes coral/algae pose topics.
+- `gamepiece::run_gamepiece_detect_no_img` exercises the YOLO model without the live camera-position publishing loop.