add docs

godbrigero · godbrigero · commit d708b2e4445f · 2026-01-12T00:21:19.000-08:00
diff --git a/README.md b/README.md
@@ -1,101 +1,29 @@
-# B.L.I.T.Z (Battle-Linked Intelligent Tactical Pi Swarm)
+## B.L.I.T.Z
 
-BLITZ is a robotics project designed to create a swarm of intelligent tactical Pi-based robots that can work together collaboratively.
+Multi-process robotics stack with a Python watchdog, codegen, and deploy tooling.
 
-## Overview
+## Docs
 
-The BLITZ system combines multiple components for sensing, positioning, AI detection, and coordinated movement. It uses a hybrid approach with both Python and Rust for different system components.
+Start here: `docs/README.md`
 
-## Features
-
-- LiDAR-based obstacle detection and mapping (2D and 3D)
-- Computer vision for object recognition
-- AprilTag-based positioning system
-- Position extrapolation
-- Watchdog monitoring
-
-## Technologies
-
-### Languages
-- Python
-- Rust
-- TypeScript/JavaScript
-
-### Major Dependencies
-- Python: PyTorch, OpenCV, Flask, NumPy, UltraLytics
-- Rust: Tokio, Nalgebra, Kiss3D
-- Communication: Protobuf, Thrift
-
-## Getting Started
-
-### Prerequisites
-- Python 3.x
-- Rust and Cargo
-- npm/Node.js
-
-### Installation
-
-Set up the Python environment and install dependencies:
+## Quickstart (local)
 
 ```bash
 make initiate-project
+echo "dev" > system_data/name.txt
+make generate
+make watchdog
 ```
 
-### Code Generation
-
-Generate required protocol buffer and Thrift files:
+## Tests
 
 ```bash
-make generate
+make test
 ```
 
-## Usage
-
-Start the various system components:
+## Deploy to a target machine
 
 ```bash
-# AI detection server
-make ai-server
-
-# AprilTag positioning server
-make april-server
-
-# 2D LiDAR reader
-make lidar-reader-2d
-
-# LiDAR point processor
-make lidar-point-processor
-
-# Position extrapolation system
-make position-extrapolator
-
-# System monitoring watchdog
-make watchdog
+make send-to-target
+make deploy-to-target
 ```
-
-## Development
-
-- Run linting: `make check-all`
-- Run tests: `make test`
-- Deploy to a target: `make send-to-target ARGS=<target-id>`
-
-## Project Structure
-
-- `project/`: Main source code
-  - `lidar/`: LiDAR data processing components
-  - `recognition/`: Computer vision and positioning
-  - `pos_extrapolator/`: Position prediction system
-  - `watchdog/`: System monitoring
-  - `rust/`: Rust components for performance-critical operations
-- `proto/`: Protocol buffer definitions
-- `config/`: System configuration
-- `generated/`: Generated code (Protobuf, Thrift)
-- `scripts/`: Utility scripts
-
-## License
-
-ISC License
-
-## Repository
-
-GitHub: [https://github.com/PinewoodRobotics/B.L.I.T.Z](https://github.com/PinewoodRobotics/B.L.I.T.Z)
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,20 @@
+## BLITZ docs
+
+These docs are organized as parts. Each part is a step toward a bigger workflow (setup, codegen, run, deploy, autostart, testing, troubleshooting).
+
+## Parts (follow in order)
+
+1. `docs/part-01-setup.md` (local setup + verify)
+2. `docs/part-02-codegen.md` (proto/codegen)
+3. `docs/part-03-run-local.md` (run core services locally)
+4. `docs/part-04-deploy.md` (deploy to target + restart)
+5. `docs/part-05-autostart.md` (autostart on target via systemd)
+6. `docs/part-06-testing-ci.md` (tests + repo expectations)
+7. `docs/part-07-troubleshooting.md` (common failures + recovery)
+
+## Glossary
+
+- **target**: the machine you deploy to (typically an Ubuntu host on the robot side).
+- **watchdog**: the Python service that exposes an API and manages subprocesses.
+- **basic system config**: `system_data/basic_system_config.json` (baseline ports/paths).
+- **generated proto**: Python output generated into `watchdog/generated/`.
diff --git a/docs/part-01-setup.md b/docs/part-01-setup.md
@@ -0,0 +1,48 @@
+## Part 1: Local setup + verify
+
+## Goal
+
+Get a working local Python environment and confirm the watchdog starts and responds.
+
+## Prereqs
+
+- `python3` (>= 3.8)
+- `make`
+- macOS: Homebrew (optional, for installing missing tools)
+
+## Steps
+
+1. From the repo root, create the venv and install dependencies:
+
+```bash
+make initiate-project
+```
+
+2. Set a local system name (required by the watchdog):
+
+```bash
+echo "dev" > system_data/name.txt
+```
+
+3. Start the watchdog:
+
+```bash
+make watchdog
+```
+
+4. In a second terminal, verify the HTTP API is up (default port is 5000):
+
+```bash
+curl -sS http://localhost:5000/get/system/status
+```
+
+## Expected result
+
+- `make watchdog` stays running and prints startup logs.
+- `curl` returns JSON with keys like `status`, `active_processes`, `possible_processes`.
+
+## Common failures
+
+- **`system_data/name.txt does not exist`**: create it (step 2) and restart.
+- **`ModuleNotFoundError` inside the venv**: rerun `make initiate-project`.
+- **Port 5000 already in use**: stop the other process or change `watchdog.port` in `system_data/basic_system_config.json`.
diff --git a/docs/part-02-codegen.md b/docs/part-02-codegen.md
@@ -0,0 +1,48 @@
+## Part 2: Proto/codegen
+
+## Goal
+
+Generate Python code from `.proto` files so the watchdog and other Python code can import the generated messages.
+
+## Prereqs
+
+- Part 1 completed (`make initiate-project`)
+- `protoc` installed and on your PATH
+  - Ubuntu: `sudo apt install -y protobuf-compiler`
+  - macOS: `brew install protobuf`
+
+## Steps
+
+1. Generate Python protobuf output:
+
+```bash
+make generate
+```
+
+2. Confirm outputs exist:
+
+```bash
+ls watchdog/generated
+```
+
+## What it does
+
+- Inputs: all `.proto` files in `proto/`
+- Outputs: Python modules into `watchdog/generated/`
+- Post-step: runs `fix-protobuf-imports` from the venv to normalize imports
+
+## When to rerun
+
+- You edited any file under `proto/`
+- You pulled changes that modified `proto/`
+- You see an import error coming from `watchdog/generated/`
+
+## Expected result
+
+- `watchdog/generated/` contains Python files for each `.proto`
+- Imports from generated modules succeed when running `make watchdog`
+
+## Common failures
+
+- **`protoc: command not found`**: install protobuf compiler (see prereqs).
+- **`fix-protobuf-imports: No such file or directory`**: rerun `make initiate-project` to recreate the venv and dependencies.
diff --git a/docs/part-03-run-local.md b/docs/part-03-run-local.md
@@ -0,0 +1,86 @@
+## Part 3: Run core services locally
+
+## Goal
+
+Start the watchdog locally and use it to view system state and manage processes.
+
+## Prereqs
+
+- Part 1 completed (venv + `system_data/name.txt`)
+
+## Steps: run the watchdog
+
+1. Start the watchdog:
+
+```bash
+make watchdog
+```
+
+2. Check status:
+
+```bash
+curl -sS http://localhost:5000/get/system/status
+```
+
+## Steps: set the runtime config (required before starting processes)
+
+The watchdog refuses to start/stop managed processes until a config is set.
+
+1. Create the config file:
+
+```bash
+mkdir -p config
+printf "{}" > config/config.txt
+```
+
+2. Tell the watchdog to load it:
+
+```bash
+curl -sS -X POST http://localhost:5000/set/config \
+  -H 'Content-Type: application/json' \
+  -d '{"config":"{}"}'
+```
+
+## Steps: managed processes (what exists today)
+
+1. List possible processes:
+
+```bash
+curl -sS http://localhost:5000/get/system/status
+```
+
+2. If `possible_processes` is empty, that means there are no runnable modules registered in `backend/deploy.py` yet.
+
+## How process launching is wired
+
+- The watchdog gets process definitions from `backend.deploy.get_modules()`.
+- Only modules that implement runnable behavior are exposed via the API.
+- Today, `backend/deploy.py` returns an empty list, so the watchdog can’t start any extra processes beyond itself.
+
+## Steps: start/stop a process (once modules exist)
+
+1. Start one or more processes:
+
+```bash
+curl -sS -X POST http://localhost:5000/start/process \
+  -H 'Content-Type: application/json' \
+  -d '{"process_types":["<process_name>"]}'
+```
+
+2. Stop one or more processes:
+
+```bash
+curl -sS -X POST http://localhost:5000/stop/process \
+  -H 'Content-Type: application/json' \
+  -d '{"process_types":["<process_name>"]}'
+```
+
+## Expected result
+
+- `get/system/status` shows the system name and watchdog state.
+- If runnable modules are registered, `possible_processes` lists them and `active_processes` changes as you start/stop processes.
+
+## Common failures
+
+- **`Config not set` from start/stop endpoints**: run the “set the runtime config” steps above.
+- **`Unknown process <name>`**: the name must match a process in `possible_processes`.
diff --git a/docs/part-04-deploy.md b/docs/part-04-deploy.md
@@ -0,0 +1,50 @@
+## Part 4: Deploy to a target + restart
+
+## Goal
+
+Sync the repo to the target machine and restart the systemd service.
+
+## Prereqs
+
+- You can SSH to the target as `ubuntu`
+- `sshpass` installed on your local machine
+  - macOS: `make mac-deps`
+  - Ubuntu: `sudo apt install -y sshpass`
+- The target has `rsync` installed
+
+## What the Make targets do
+
+- `make send-to-target`: rsyncs the repo to `TARGET_FOLDER` using `sudo rsync` on the target
+- `make deploy-to-target`: runs `send-to-target` and then restarts `startup.service` on the target
+
+## Steps
+
+1. Pick the target settings (defaults are in `Makefile`):
+
+   - `UBUNTU_TARGET` (e.g. `nathanhale.local`)
+   - `TARGET_PORT` (default `22`)
+   - `SSH_PASS` (default `ubuntu`)
+   - `TARGET_FOLDER` (default `/opt/blitz/B.L.I.T.Z/`)
+
+2. Deploy:
+
+```bash
+make send-to-target UBUNTU_TARGET=<host_or_ip> TARGET_PORT=22 SSH_PASS=ubuntu
+```
+
+3. Restart the system service:
+
+```bash
+make deploy-to-target UBUNTU_TARGET=<host_or_ip> TARGET_PORT=22 SSH_PASS=ubuntu
+```
+
+## Expected result
+
+- The repo contents exist under `TARGET_FOLDER` on the target.
+- `startup.service` is restarted successfully.
+
+## Common failures
+
+- **`sshpass: command not found`**: install it (see prereqs).
+- **Permission errors on the target**: `send-to-target` uses `--rsync-path="sudo rsync"`; the `ubuntu` user needs sudo.
+- **Host key prompt / SSH failure**: confirm you can `ssh ubuntu@<host>` manually first.
diff --git a/docs/part-05-autostart.md b/docs/part-05-autostart.md
diff --git a/docs/part-06-testing-ci.md b/docs/part-06-testing-ci.md
diff --git a/docs/part-07-troubleshooting.md b/docs/part-07-troubleshooting.md
