# bobby-bash/robo-scout architecture

> Architecture diagram of the GitHub repository bobby-bash/robo-scout, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bobby-bash/robo-scout
- Repository: https://github.com/bobby-bash/robo-scout

## Overview

#### Purpose and Runtime
Robot-Controller is a sense-plan-act system for camera-guided physical robots that move ferrous pallets. Python runs vision, orchestration, and robot control; a C++ motion-planning core is exposed to Python through pybind11. It is intended for webcam/iPhone camera input, ArUco markers, and robot-specific communications hardware.

Key paths: `mainProgram.py`, `CMakeLists.txt`, `src/main.cc`.

#### Application Entry and Orchestration
`mainProgram.py` is the likely top-level runtime coordinator, with shared execution helpers in `mainHelper.py`. It connects perception outputs, planning requests, and controller actions. `controller_main.py` is the controller-facing entry point, while `cv_main.py` is the vision-facing entry point; these separations support independent development/debugging of the loop stages.

Key paths: `mainProgram.py`, `mainHelper.py`, `controller_main.py`.

#### Perception and World-State Boundary
Computer vision obtains camera frames, detects/localizes robots and pallets primarily through ArUco fiducials, and produces poses for the planner/controller. The repository retains an alternate NeoPixel/inverse-affine localization approach. Vision also owns the optional visualization overlay of detected poses, planned paths, and control commands; this is a performance-sensitive display boundary.

Key paths: `cv_main.py`, `cv_fiducial.py`, `computerVisionFragments/cv_cameraCalibration.py`.

#### Planning API and Native Module
The native `planner` module is built as a Python extension. Its binding entry point exports C++ planning capabilities into the Python runtime, establishing the language boundary: Python supplies world/task state and consumes returned discrete paths, while C++ performs search and plan construction. CMake fetches/builds pybind11 and produces the planner target.

Key paths: `CMakeLists.txt`, `src/main.cc`, `src/planner.cc`.

#### Motion-Planning Core
The planner implements 4D state-space A* for robot paths. `Node` represents search-state structure, `MotionPlanner` owns motion/path-search behavior, and `Planner` provides the higher-level planning interface exposed to callers. This layer should remain independent of camera and hardware details; it operates on normalized planning state and returns discrete trajectory steps.

Key paths: `include/node.hh`, `include/motion_planner.hh`, `include/planner.hh`.

#### Task Planning and Multi-Stage Flow
Task planning sits above geometric motion planning: it converts the pallet/robot work to be performed into motion-planner requests, then passes resulting paths back to Python. The primary control flow is: camera frame → pose/world estimate → task and motion plan → discrete path → continuous controller command → robot hardware; subsequent frames close the feedback loop.

Key paths: `include/task_planner.hh`, `src/task_planner.cc`, `src/motion_planner.cc`.

#### Control, Tuning, and External Dependencies
The Python controller interpolates discrete planner output using cubic Hermite splines into continuous-time commands and corrects against current measured pose. Shared tunables—including algorithm and debug settings—are centralized in `constants.py`. Material dependencies are Python, C++, OpenCV-contrib (for ArUco), pybind11, CMake, a camera source, and the physical robots; no cloud service or web infrastructure is indicated.

Key paths: `controller_main.py`, `constants.py`, `include/constants.hh`.

Main entry points: [`mainProgram.py`](https://github.com/bobby-bash/robo-scout/blob/master/mainProgram.py) (Runtime coordinator), [`src/main.cc`](https://github.com/bobby-bash/robo-scout/blob/master/src/main.cc) (Planner binding), [`cv_main.py`](https://github.com/bobby-bash/robo-scout/blob/master/cv_main.py) (Vision entry), [`src/motion_planner.cc`](https://github.com/bobby-bash/robo-scout/blob/master/src/motion_planner.cc) (Motion planner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python Runtime"]
  node_app["Runtime coordinator<br/>Python orchestration<br/>[mainProgram.py]"]
  node_helpers["Execution helpers<br/>Python support<br/>[mainHelper.py]"]
  node_controller["Controller entry<br/>Python control<br/>[controller_main.py]"]
  node_tunables_py["Python tunables<br/>Runtime settings<br/>[constants.py]"]
end

subgraph group_vision["Perception"]
  node_vision_entry["Vision entry<br/>Python vision<br/>[cv_main.py]"]
  node_fiducials["ArUco localization<br/>Pose estimation<br/>[cv_fiducial.py]"]
  node_calibration["Camera calibration<br/>Vision calibration"]
end

subgraph group_native["Native Planning"]
  node_cmake["Native build<br/>CMake / pybind11<br/>[CMakeLists.txt]"]
  node_binding{{"Planner binding<br/>pybind11 module<br/>[main.cc]"}}
  node_planner_api["Planner API<br/>C++ planning interface<br/>[planner.hh]"]
  node_task_planner["Task planner<br/>C++ task planning<br/>[task_planner.cc]"]
  node_motion_planner["Motion planner<br/>4D A* search<br/>[motion_planner.cc]"]
  node_search_node["Search node<br/>C++ search state<br/>[node.hh]"]
  node_native_constants["Native tunables<br/>C++ settings<br/>[constants.hh]"]
end

subgraph group_physical["Physical Loop"]
  node_camera(("Camera source<br/>External hardware"))
  node_robot(("Physical robots<br/>Robot hardware"))
end

node_app -->|"uses"| node_helpers
node_app -->|"requests poses"| node_vision_entry
node_app -->|"submits world and task state"| node_binding
node_app -->|"passes discrete paths"| node_controller
node_camera -->|"frames"| node_vision_entry
node_vision_entry -->|"localizes"| node_fiducials
node_calibration -->|"calibration data"| node_vision_entry
node_fiducials -->|"robot and pallet poses"| node_app
node_binding -->|"exports"| node_planner_api
node_planner_api -->|"plans tasks"| node_task_planner
node_task_planner -->|"motion requests"| node_motion_planner
node_motion_planner -->|"expands 4D states"| node_search_node
node_binding -->|"discrete paths"| node_app
node_controller -->|"continuous commands"| node_robot
node_robot -.->|"observed next frame"| node_camera
node_cmake -->|"builds"| node_binding
node_tunables_py -.->|"configures"| node_app
node_native_constants -.->|"configures"| node_motion_planner

click node_app "https://github.com/bobby-bash/robo-scout/blob/master/mainProgram.py"
click node_helpers "https://github.com/bobby-bash/robo-scout/blob/master/mainHelper.py"
click node_vision_entry "https://github.com/bobby-bash/robo-scout/blob/master/cv_main.py"
click node_fiducials "https://github.com/bobby-bash/robo-scout/blob/master/cv_fiducial.py"
click node_calibration "https://github.com/bobby-bash/robo-scout/blob/master/computerVisionFragments/cv_cameraCalibration.py"
click node_controller "https://github.com/bobby-bash/robo-scout/blob/master/controller_main.py"
click node_tunables_py "https://github.com/bobby-bash/robo-scout/blob/master/constants.py"
click node_cmake "https://github.com/bobby-bash/robo-scout/blob/master/CMakeLists.txt"
click node_binding "https://github.com/bobby-bash/robo-scout/blob/master/src/main.cc"
click node_planner_api "https://github.com/bobby-bash/robo-scout/blob/master/include/planner.hh"
click node_task_planner "https://github.com/bobby-bash/robo-scout/blob/master/src/task_planner.cc"
click node_motion_planner "https://github.com/bobby-bash/robo-scout/blob/master/src/motion_planner.cc"
click node_search_node "https://github.com/bobby-bash/robo-scout/blob/master/include/node.hh"
click node_native_constants "https://github.com/bobby-bash/robo-scout/blob/master/include/constants.hh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_helpers,node_controller,node_tunables_py toneBlue
class node_vision_entry,node_fiducials,node_calibration toneAmber
class node_cmake,node_binding,node_planner_api,node_task_planner,node_motion_planner,node_search_node,node_native_constants toneMint
class node_camera,node_robot toneRose
```

## Components

### Python Runtime

- [Runtime coordinator](https://github.com/bobby-bash/robo-scout/blob/master/mainProgram.py): Python orchestration · Connects perception, planning, and control. · `mainProgram.py`
- [Execution helpers](https://github.com/bobby-bash/robo-scout/blob/master/mainHelper.py): Python support · `mainHelper.py`
- [Controller entry](https://github.com/bobby-bash/robo-scout/blob/master/controller_main.py): Python control · Interpolates paths and corrects against measured pose. · `controller_main.py`
- [Python tunables](https://github.com/bobby-bash/robo-scout/blob/master/constants.py): Runtime settings · `constants.py`

### Perception

- [Vision entry](https://github.com/bobby-bash/robo-scout/blob/master/cv_main.py): Python vision · `cv_main.py`
- [ArUco localization](https://github.com/bobby-bash/robo-scout/blob/master/cv_fiducial.py): Pose estimation · Produces robot and pallet poses from camera frames. · `cv_fiducial.py`
- [Camera calibration](https://github.com/bobby-bash/robo-scout/blob/master/computerVisionFragments/cv_cameraCalibration.py): Vision calibration · `computerVisionFragments/cv_cameraCalibration.py`

### Native Planning

- [Native build](https://github.com/bobby-bash/robo-scout/blob/master/CMakeLists.txt): CMake / pybind11 · Builds the planner Python extension. · `CMakeLists.txt`
- [Planner binding](https://github.com/bobby-bash/robo-scout/blob/master/src/main.cc): pybind11 module · Python-to-C++ planning boundary. · `src/main.cc`
- [Planner API](https://github.com/bobby-bash/robo-scout/blob/master/include/planner.hh): C++ planning interface · `include/planner.hh`
- [Task planner](https://github.com/bobby-bash/robo-scout/blob/master/src/task_planner.cc): C++ task planning · Converts pallet work into motion-planning requests. · `src/task_planner.cc`
- [Motion planner](https://github.com/bobby-bash/robo-scout/blob/master/src/motion_planner.cc): 4D A* search · Constructs discrete robot trajectories. · `src/motion_planner.cc`
- [Search node](https://github.com/bobby-bash/robo-scout/blob/master/include/node.hh): C++ search state · `include/node.hh`
- [Native tunables](https://github.com/bobby-bash/robo-scout/blob/master/include/constants.hh): C++ settings · `include/constants.hh`

### Physical Loop

- **Camera source**: External hardware · Webcam or iPhone frame source.
- **Physical robots**: Robot hardware

## Connections

- Runtime coordinator → Execution helpers: uses
- Runtime coordinator → Vision entry: requests poses
- Runtime coordinator → Planner binding: submits world and task state
- Runtime coordinator → Controller entry: passes discrete paths
- Camera source → Vision entry: frames
- Vision entry → ArUco localization: localizes
- Camera calibration → Vision entry: calibration data
- ArUco localization → Runtime coordinator: robot and pallet poses
- Planner binding → Planner API: exports
- Planner API → Task planner: plans tasks
- Task planner → Motion planner: motion requests
- Motion planner → Search node: expands 4D states
- Planner binding → Runtime coordinator: discrete paths
- Controller entry → Physical robots: continuous commands
- Physical robots → Camera source: observed next frame · Closes the physical feedback loop.
- Native build → Planner binding: builds
- Python tunables → Runtime coordinator: configures
- Native tunables → Motion planner: configures