From 2bb4a911ebbffc49405edb2a11aa08dea5d984e1 Mon Sep 17 00:00:00 2001 From: Charlie Huang Date: Sat, 16 May 2026 02:00:22 +0000 Subject: [PATCH 1/3] add docs Signed-off-by: Charlie Huang --- docs/README.md | 23 +++++ docs/architecture.md | 88 +++++++++++++++++ docs/build-and-run.md | 47 ++++++++++ docs/scripts.md | 213 ++++++++++++++++++++++++++++++++++++++++++ docs/testing.md | 32 +++++++ 5 files changed, 403 insertions(+) create mode 100644 docs/README.md create mode 100644 docs/architecture.md create mode 100644 docs/build-and-run.md create mode 100644 docs/scripts.md create mode 100644 docs/testing.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..ac7b544c --- /dev/null +++ b/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` diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 00000000..acc6af3e --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,88 @@ +# 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`). +- Optional CSCore streaming and frame writing utilities. +- Camera constants loading from JSON. + +### `src/localization` + +- AprilTag detector interface and implementations: + - OpenCV ArUco AprilTag + - 971 GPU AprilTag + - 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 + - NetworkTables utility helpers + - JSON constant handling + +### `src/calibration` + +- Intrinsics calibration tools. +- Frame display and focus calibration binaries. + +### `src/test` + +- `unit_test`: solver and pathing focused tests. +- `integration_test`: end-to-end and subsystem executable tests. + +## Top-Level Binaries + +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 diff --git a/docs/build-and-run.md b/docs/build-and-run.md new file mode 100644 index 00000000..66f1f5bb --- /dev/null +++ b/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: + +- `main_bot_main` +- `second_bot_main` +- `unambiguous_first` +- `unambiguous_second` + +## Calibration Tools + +Built in `src/calibration`: + +- `intrinsics_calibrate` +- `frame_shower` +- `focus_calibrate` diff --git a/docs/scripts.md b/docs/scripts.md new file mode 100644 index 00000000..b9773d0a --- /dev/null +++ b/docs/scripts.md @@ -0,0 +1,213 @@ +# 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 +``` + +### `scripts/download_constants.sh` + +- Rsyncs `/bos/constants` from remote host into the current local directory. + +Usage: + +```bash +./scripts/download_constants.sh nvidia@10.99.71.11 +``` + +### `scripts/download_logs.sh` + +- Rsyncs `/bos/logs` from remote host into the current local directory. + +Usage: + +```bash +./scripts/download_logs.sh nvidia@10.99.71.11 +``` + +## Log and Image Utilities + +### `scripts/rsync_between.sh` + +- Syncs only images whose filename timestamp seconds are in a given range. +- Works on a single remote folder. + +Usage: + +```bash +./scripts/rsync_between.sh nvidia@10.9.71.11:/bos/logs/log51/left ./local_logs 50 450 +``` + +### `scripts/get_log.sh` + +- Similar range-based sync, but runs for both `second_bot_left` and `second_bot_right` subfolders. + +Usage: + +```bash +./scripts/get_log.sh nvidia@10.9.71.11:/bos/logs/log51 ./local_logs 50 450 +``` + +### `scripts/check_log.py` + +- Interactive preview utility that grabs one representative image per chunk from remote folders. +- Uses OpenCV windows; press any key to continue, `Esc` to stop. +- Operates on `left` and `right` subfolders. + +Usage: + +```bash +python3 scripts/check_log.py nvidia@10.9.71.11:/bos/logs/log51 ./local_logs +``` + +### `scripts/check_log.sh` + +- Python script (despite `.sh` extension) similar to `check_log.py`. +- Operates on `second_bot_left` and `second_bot_right` subfolders. + +Usage: + +```bash +python3 scripts/check_log.sh nvidia@10.9.71.11:/bos/logs/log51 ./local_logs +``` + +### `scripts/img_opener.py` + +- Local timestamped image viewer built with Tkinter/Pillow. +- Shows images in timestamp order, optionally starting from a given time. + +Usage: + +```bash +python3 scripts/img_opener.py ./local_logs/left +python3 scripts/img_opener.py ./local_logs/left 120.0 +``` + +### `scripts/log_culler.sh` + +- Deletes images outside a timestamp range in a local folder. + +Usage: + +```bash +./scripts/log_culler.sh ./local_logs/left 50 450 +``` + +### `scripts/delete-logs.sh` + +- Removes `log1` through `logN` directories (with optional dry-run mode). + +Usage: + +```bash +./scripts/delete-logs.sh --last=30 --dir=/bos/logs --dry-run +./scripts/delete-logs.sh --last=30 --dir=/bos/logs +``` + +### `scripts/fix_log_times.sh` + +- Python utility that normalizes WPILOG timestamps so the first non-zero timestamp becomes `0`. +- Writes `_fixed.wpilog` unless output path is provided. + +Usage: + +```bash +python3 scripts/fix_log_times.sh input.wpilog +python3 scripts/fix_log_times.sh input.wpilog output.wpilog +``` diff --git a/docs/testing.md b/docs/testing.md new file mode 100644 index 00000000..6ec3dabc --- /dev/null +++ b/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. From e3158b294900d4d4fa0f2f966d49326a68ba6762 Mon Sep 17 00:00:00 2001 From: Charlie Huang Date: Sat, 16 May 2026 03:43:34 +0000 Subject: [PATCH 2/3] wip Signed-off-by: Charlie Huang --- docs/scripts.md | 111 ------------------------------------------------ 1 file changed, 111 deletions(-) diff --git a/docs/scripts.md b/docs/scripts.md index b9773d0a..4d6df4ed 100644 --- a/docs/scripts.md +++ b/docs/scripts.md @@ -100,114 +100,3 @@ Usage: ```bash ./scripts/upload_public_key.sh nvidia@10.99.71.11 ``` - -### `scripts/download_constants.sh` - -- Rsyncs `/bos/constants` from remote host into the current local directory. - -Usage: - -```bash -./scripts/download_constants.sh nvidia@10.99.71.11 -``` - -### `scripts/download_logs.sh` - -- Rsyncs `/bos/logs` from remote host into the current local directory. - -Usage: - -```bash -./scripts/download_logs.sh nvidia@10.99.71.11 -``` - -## Log and Image Utilities - -### `scripts/rsync_between.sh` - -- Syncs only images whose filename timestamp seconds are in a given range. -- Works on a single remote folder. - -Usage: - -```bash -./scripts/rsync_between.sh nvidia@10.9.71.11:/bos/logs/log51/left ./local_logs 50 450 -``` - -### `scripts/get_log.sh` - -- Similar range-based sync, but runs for both `second_bot_left` and `second_bot_right` subfolders. - -Usage: - -```bash -./scripts/get_log.sh nvidia@10.9.71.11:/bos/logs/log51 ./local_logs 50 450 -``` - -### `scripts/check_log.py` - -- Interactive preview utility that grabs one representative image per chunk from remote folders. -- Uses OpenCV windows; press any key to continue, `Esc` to stop. -- Operates on `left` and `right` subfolders. - -Usage: - -```bash -python3 scripts/check_log.py nvidia@10.9.71.11:/bos/logs/log51 ./local_logs -``` - -### `scripts/check_log.sh` - -- Python script (despite `.sh` extension) similar to `check_log.py`. -- Operates on `second_bot_left` and `second_bot_right` subfolders. - -Usage: - -```bash -python3 scripts/check_log.sh nvidia@10.9.71.11:/bos/logs/log51 ./local_logs -``` - -### `scripts/img_opener.py` - -- Local timestamped image viewer built with Tkinter/Pillow. -- Shows images in timestamp order, optionally starting from a given time. - -Usage: - -```bash -python3 scripts/img_opener.py ./local_logs/left -python3 scripts/img_opener.py ./local_logs/left 120.0 -``` - -### `scripts/log_culler.sh` - -- Deletes images outside a timestamp range in a local folder. - -Usage: - -```bash -./scripts/log_culler.sh ./local_logs/left 50 450 -``` - -### `scripts/delete-logs.sh` - -- Removes `log1` through `logN` directories (with optional dry-run mode). - -Usage: - -```bash -./scripts/delete-logs.sh --last=30 --dir=/bos/logs --dry-run -./scripts/delete-logs.sh --last=30 --dir=/bos/logs -``` - -### `scripts/fix_log_times.sh` - -- Python utility that normalizes WPILOG timestamps so the first non-zero timestamp becomes `0`. -- Writes `_fixed.wpilog` unless output path is provided. - -Usage: - -```bash -python3 scripts/fix_log_times.sh input.wpilog -python3 scripts/fix_log_times.sh input.wpilog output.wpilog -``` From ad080d3aa43015af0e25d8d4c23d020dfb7e894a Mon Sep 17 00:00:00 2001 From: Charlie Huang Date: Sat, 16 May 2026 03:45:52 +0000 Subject: [PATCH 3/3] wip Signed-off-by: Charlie Huang --- README.md | 28 ---------------------------- 1 file changed, 28 deletions(-) delete mode 100644 README.md diff --git a/README.md b/README.md deleted file mode 100644 index 686beb25..00000000 --- a/README.md +++ /dev/null @@ -1,28 +0,0 @@ -# BOS README -*** -## What is Docker? -### What does it do? -Basically, Docker lets you package an application
-into a container that can be distributed as images to
-run on other platforms. For example, let's say you have
-an application that works on your computer, but not on
-the server you want to eventually run it on. Docker
-solves that. It lets you package an application and
-the environment it needs to run on into a bundle that
-can then be run anywhere. - -## Docker commands you need to know -### How to pull images using docker pull -run `docker pull ghcr.io/frc971/bos/orin:latest`. - -This will pull a docker image for you to use on your computer. - -### How to run the container on your computer -To run the docker container on your computer,
-run the following commands in the terminal: -```bash - docker run --privileged --network host --name orin -it ghcr.io/frc971/bos/orin:latest - docker exec -it orin /bin/bash -``` -This will run the docker container on your computer within a
-contained environment that simulates an ORIN.