bobby-bash/robo-scout

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.