Skip to content

README.md

Latest commit

 

History

History
63 lines (51 loc) · 4.22 KB

README.md

File metadata and controls

63 lines (51 loc) · 4.22 KB
Raw

src/python

Python/ROS2 code that runs on the robot itself: hardware drivers, navigation, the competition state machine, vision, and a headless simulation harness for testing navigation logic without hardware or Gazebo.

Three source trees, one relationship

  • src/ (this directory's own src/, i.e. src/python/src/) - the actual implementation. Plain Python, importable and testable without ROS2 running (tests/unit/ exercises this directly).
  • ros2_ws/src/ - ROS2 ament packages (vtitan_bringup, vtitan_drivers, vtitan_navigation, vtitan_state_machine, vtitan_vision). Node entry points here are thin wrappers: they import from src/ and adapt it to ROS2 topics/params/lifecycle. This keeps the actual logic testable outside ROS2 and avoids duplicating it between a "plain" and a "ROS2" copy.
  • shared/ - a separate installable Python package (shared.config, shared.domain, shared.io), shared across this stack's own ROS2 nodes and simulation harness. Holds the pydantic-settings models and loaders that read the TOML under src/config/ (repo root, outside src/python/ entirely -- Go reads the same TOML tree), not the TOML itself.

Build the ROS2 workspace with task robot:build-ws (Linux only - colcon) before any run-/launch- task.

src/ layout

Directory Contents
hardware/ Per-sensor/actuator drivers (camera, LIDAR passthrough, IMU variants, motors, button, display, Hailo NPU). Each has a Config (pydantic-settings, reads src/config/hardware/*.toml at the repo root) and a Driver.
navigation/ CoreNavigator and its controllers (pure pursuit, collision avoidance, stuck detection), maneuvers (parking, K-turn/slalom escapes), and planning (waypoint generation, sign routing/discovery, corridor estimation). Tunable via NavigationTuning (the shared package's shared.config.navigation_tuning), not hardcoded - the TOML itself lives at src/config/navigation/*.toml (repo root).
state_machine/ The 4-stage competition state machine (BOOT_CHECK → READY → RACING → FINISHED) and its data types.
simulation/ Headless closed-loop simulator: drives the real CoreNavigator against a simulated HardwareGateway (Ackermann kinematics + raycast LIDAR + collision), used for navigation regression testing without Gazebo.
vision/ Traffic-sign detector (Hailo NPU on hardware, Ultralytics/YOLO fallback in sim).
ros2/ The plain-Python side of ROS2 node logic that ros2_ws/'s node wrappers call into (parameter handling, topic callback logic) - kept here rather than in ros2_ws/ for the same testability reason as everything else in src/.
teleop/ Bench-testing joystick teleop tool.
config/, gen/, logger/ Env/config loading (this package's own, distinct from the repo-root src/config/ TOML tree), generated code, structured JSON logging setup.

Hardware config lives under src/config/hardware/*.toml at the repo root (one file per driver, read via pydantic-settings - see each driver's Config), alongside src/config/navigation/*.toml (navigation tuning) and src/config/robot.toml (cross-language physical constants). The shared package's shared.config is the Python loader for this tree, not a copy of it -- Go reads the same TOML files directly.

Testing

  • tests/unit/ - plain-Python tests against src/ directly, no ROS2 required. Includes the closed-loop simulation regression suite (test_obstacles_challenge_sim.py, test_deviation_recovery.py, etc.).
  • tests/ros2/ - tests that exercise the ROS2 node wrappers.
  • tests/hardware/ - tests against real hardware drivers; most require the actual sensor attached and are skipped otherwise.

Run via task robot:test (SCOPE=all|unit|hardware, default all excludes on-device hardware tests).

Key Taskfile entry points

See task --list (or the repo root Taskfile.yml's ROBOT/ROBOT REMOTE sections, defined in tasks/platform.yml) for the full list - robot:install, robot:test, robot:lint, robot:run (single node), robot:launch (node sets: rpi5/rpi-zero/state-machine/telemetry/simulator/lidar), robot:deploy (ship code to the Pi 5 over SSH), and robot:drive/robot:reset-motors for runtime control-mode switching.