# 0range02/heliobox architecture

> Architecture diagram of the GitHub repository 0range02/heliobox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/0range02/heliobox
- Repository: https://github.com/0range02/heliobox

## Overview

Heliobox is a ROS 2 robot software stack: operators or other ROS nodes start capabilities, which consume sensor or joystick input and publish motion, perception, or robot-state outputs. Its source tree covers application-level behaviors, hardware drivers, peripherals, navigation/SLAM, and multi-robot coordination. The README provides no further workflow description, and many launch and runtime files were not sampled; the graph therefore shows documented module calls where visible and avoids asserting wiring for unsampled subsystems.

Main entry points: [`src/app/app/lidar_controller.py`](https://github.com/0range02/heliobox/blob/new-main/src/app/app/lidar_controller.py) (Lidar behavior), [`src/yolov5_ros2/yolov5_ros2/yolo_detect.py`](https://github.com/0range02/heliobox/blob/new-main/src/yolov5_ros2/yolov5_ros2/yolo_detect.py) (YOLO detection), [`src/navigation/launch/navigation.launch.py`](https://github.com/0range02/heliobox/blob/new-main/src/navigation/launch/navigation.launch.py) (Navigation stack), [`src/driver/ros_robot_controller/ros_robot_controller/ros_robot_controller_node.py`](https://github.com/0range02/heliobox/blob/new-main/src/driver/ros_robot_controller/ros_robot_controller/ros_robot_controller_node.py) (Robot controller node)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Robot behaviors"]
  node_lidar_behavior["Lidar behavior"]
  node_app_common["App helpers<br/>[common.py]"]
  node_hand_landmark["Hand landmarks<br/>[hand_landmark.py]"]
  node_vision_utils["Vision geometry<br/>[utils.py]"]
  node_line_follow["Line following<br/>[line_following.py]"]
  node_gesture["Hand gestures<br/>[hand_gesture.py]"]
  node_heliobox_ctrl["Heliobox control<br/>[heliobox_ctrl.py]"]
  node_state_machine["Behavior state<br/>[state_machine.py]"]
end

subgraph group_drivers["Control and drivers"]
  node_robot_node["Robot controller node"]
  node_robot_sdk["Board SDK"]
  node_joystick["Joystick control"]
  node_sdk_common["Control utilities<br/>[common.py]"]
  node_pid["PID controller<br/>[pid.py]"]
  node_odom["Odometry publisher"]
end

subgraph group_sensing["Perception and sensors"]
  node_yolo["YOLO detection<br/>[yolo_detect.py]"]
  node_cv_tool["Image tools<br/>[cv_tool.py]"]
  node_fps["FPS meter<br/>[fps.py]"]
  node_lidar_sensor["Lidar driver<br/>[heliobox_lidar.py]"]
  node_camera_sensor["Camera driver<br/>[heliobox_cam.py]"]
end

subgraph group_autonomy["Navigation and mapping"]
  node_nav_launch["Navigation stack"]
  node_slam_launch["SLAM stack<br/>[slam.launch.py]"]
  node_map_save["Map saving<br/>[map_save.py]"]
  node_calibration["Motion calibration"]
end

subgraph group_coordination["Operations and fleets"]
  node_bringup["Startup checks<br/>[startup_check.py]"]
  node_multi_robot["Fleet coordination"]
  node_teleop["Keyboard teleop"]
end

node_operator(("ROS operator"))

node_operator -.->|"starts behavior"| node_lidar_behavior
node_operator -.->|"starts detection"| node_yolo
node_operator -.->|"starts navigation"| node_nav_launch
node_operator -.->|"starts mapping"| node_slam_launch
node_lidar_behavior -->|"uses helpers"| node_app_common
node_lidar_behavior -->|"uses control"| node_pid
node_lidar_behavior -->|"uses utilities"| node_sdk_common
node_hand_landmark -->|"uses geometry"| node_vision_utils
node_heliobox_ctrl -->|"uses state"| node_state_machine
node_robot_node -->|"uses board SDK"| node_robot_sdk
node_joystick -->|"uses utilities"| node_sdk_common
node_yolo -->|"uses image tools"| node_cv_tool
node_yolo -->|"updates meter"| node_fps
node_lidar_sensor -.->|"supplies scans"| node_lidar_behavior
node_camera_sensor -.->|"supplies images"| node_yolo
node_nav_launch -.->|"uses odometry"| node_odom
node_slam_launch -.->|"saves maps"| node_map_save
node_teleop -.->|"commands motion"| node_robot_node
node_multi_robot -.->|"coordinates robots"| node_nav_launch

click node_lidar_behavior "https://github.com/0range02/heliobox/blob/new-main/src/app/app/lidar_controller.py"
click node_app_common "https://github.com/0range02/heliobox/blob/new-main/src/app/app/common.py"
click node_hand_landmark "https://github.com/0range02/heliobox/blob/new-main/src/app/app/model/hand_landmark.py"
click node_vision_utils "https://github.com/0range02/heliobox/blob/new-main/src/app/app/model/utils.py"
click node_line_follow "https://github.com/0range02/heliobox/blob/new-main/src/app/app/line_following.py"
click node_gesture "https://github.com/0range02/heliobox/blob/new-main/src/app/app/hand_gesture.py"
click node_heliobox_ctrl "https://github.com/0range02/heliobox/blob/new-main/src/heliobox/heliobox/heliobox_ctrl.py"
click node_state_machine "https://github.com/0range02/heliobox/blob/new-main/src/heliobox/heliobox/state_machine.py"
click node_robot_node "https://github.com/0range02/heliobox/blob/new-main/src/driver/ros_robot_controller/ros_robot_controller/ros_robot_controller_node.py"
click node_robot_sdk "https://github.com/0range02/heliobox/blob/new-main/src/driver/ros_robot_controller/ros_robot_controller/ros_robot_controller_sdk.py"
click node_joystick "https://github.com/0range02/heliobox/blob/new-main/src/peripherals/peripherals/joystick_control.py"
click node_sdk_common "https://github.com/0range02/heliobox/blob/new-main/src/driver/sdk/sdk/common.py"
click node_pid "https://github.com/0range02/heliobox/blob/new-main/src/driver/sdk/sdk/pid.py"
click node_odom "https://github.com/0range02/heliobox/blob/new-main/src/driver/controller/controller/odom_publisher_node.py"
click node_yolo "https://github.com/0range02/heliobox/blob/new-main/src/yolov5_ros2/yolov5_ros2/yolo_detect.py"
click node_cv_tool "https://github.com/0range02/heliobox/blob/new-main/src/yolov5_ros2/yolov5_ros2/cv_tool.py"
click node_fps "https://github.com/0range02/heliobox/blob/new-main/src/yolov5_ros2/yolov5_ros2/fps.py"
click node_lidar_sensor "https://github.com/0range02/heliobox/blob/new-main/src/heliobox/heliobox/heliobox_lidar.py"
click node_camera_sensor "https://github.com/0range02/heliobox/blob/new-main/src/heliobox/heliobox/heliobox_cam.py"
click node_nav_launch "https://github.com/0range02/heliobox/blob/new-main/src/navigation/launch/navigation.launch.py"
click node_slam_launch "https://github.com/0range02/heliobox/blob/new-main/src/slam/launch/slam.launch.py"
click node_map_save "https://github.com/0range02/heliobox/blob/new-main/src/slam/slam/map_save.py"
click node_calibration "https://github.com/0range02/heliobox/blob/new-main/src/calibration/calibration/calibrate_linear.py"
click node_bringup "https://github.com/0range02/heliobox/blob/new-main/src/bringup/bringup/startup_check.py"
click node_multi_robot "https://github.com/0range02/heliobox/blob/new-main/src/multi/multi/formation_update.py"
click node_teleop "https://github.com/0range02/heliobox/blob/new-main/src/peripherals/peripherals/teleop_key_control.py"

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_lidar_behavior,node_app_common,node_hand_landmark,node_vision_utils,node_line_follow,node_gesture,node_heliobox_ctrl,node_state_machine toneBlue
class node_robot_node,node_robot_sdk,node_joystick,node_sdk_common,node_pid,node_odom toneAmber
class node_yolo,node_cv_tool,node_fps,node_lidar_sensor,node_camera_sensor toneMint
class node_nav_launch,node_slam_launch,node_map_save,node_calibration toneRose
class node_bringup,node_multi_robot,node_teleop,node_operator toneIndigo
```

## Components

### Robot behaviors

- [Lidar behavior](https://github.com/0range02/heliobox/blob/new-main/src/app/app/lidar_controller.py): `src/app/app/lidar_controller.py`
- [App helpers](https://github.com/0range02/heliobox/blob/new-main/src/app/app/common.py): `src/app/app/common.py`
- [Hand landmarks](https://github.com/0range02/heliobox/blob/new-main/src/app/app/model/hand_landmark.py): `src/app/app/model/hand_landmark.py`
- [Vision geometry](https://github.com/0range02/heliobox/blob/new-main/src/app/app/model/utils.py): `src/app/app/model/utils.py`
- [Line following](https://github.com/0range02/heliobox/blob/new-main/src/app/app/line_following.py): `src/app/app/line_following.py`
- [Hand gestures](https://github.com/0range02/heliobox/blob/new-main/src/app/app/hand_gesture.py): `src/app/app/hand_gesture.py`
- [Heliobox control](https://github.com/0range02/heliobox/blob/new-main/src/heliobox/heliobox/heliobox_ctrl.py): `src/heliobox/heliobox/heliobox_ctrl.py`
- [Behavior state](https://github.com/0range02/heliobox/blob/new-main/src/heliobox/heliobox/state_machine.py): `src/heliobox/heliobox/state_machine.py`

### Control and drivers

- [Robot controller node](https://github.com/0range02/heliobox/blob/new-main/src/driver/ros_robot_controller/ros_robot_controller/ros_robot_controller_node.py): `src/driver/ros_robot_controller/ros_robot_controller/ros_robot_controller_node.py`
- [Board SDK](https://github.com/0range02/heliobox/blob/new-main/src/driver/ros_robot_controller/ros_robot_controller/ros_robot_controller_sdk.py): `src/driver/ros_robot_controller/ros_robot_controller/ros_robot_controller_sdk.py`
- [Joystick control](https://github.com/0range02/heliobox/blob/new-main/src/peripherals/peripherals/joystick_control.py): `src/peripherals/peripherals/joystick_control.py`
- [Control utilities](https://github.com/0range02/heliobox/blob/new-main/src/driver/sdk/sdk/common.py): `src/driver/sdk/sdk/common.py`
- [PID controller](https://github.com/0range02/heliobox/blob/new-main/src/driver/sdk/sdk/pid.py): `src/driver/sdk/sdk/pid.py`
- [Odometry publisher](https://github.com/0range02/heliobox/blob/new-main/src/driver/controller/controller/odom_publisher_node.py): `src/driver/controller/controller/odom_publisher_node.py`

### Perception and sensors

- [YOLO detection](https://github.com/0range02/heliobox/blob/new-main/src/yolov5_ros2/yolov5_ros2/yolo_detect.py): `src/yolov5_ros2/yolov5_ros2/yolo_detect.py`
- [Image tools](https://github.com/0range02/heliobox/blob/new-main/src/yolov5_ros2/yolov5_ros2/cv_tool.py): `src/yolov5_ros2/yolov5_ros2/cv_tool.py`
- [FPS meter](https://github.com/0range02/heliobox/blob/new-main/src/yolov5_ros2/yolov5_ros2/fps.py): `src/yolov5_ros2/yolov5_ros2/fps.py`
- [Lidar driver](https://github.com/0range02/heliobox/blob/new-main/src/heliobox/heliobox/heliobox_lidar.py): `src/heliobox/heliobox/heliobox_lidar.py`
- [Camera driver](https://github.com/0range02/heliobox/blob/new-main/src/heliobox/heliobox/heliobox_cam.py): `src/heliobox/heliobox/heliobox_cam.py`

### Navigation and mapping

- [Navigation stack](https://github.com/0range02/heliobox/blob/new-main/src/navigation/launch/navigation.launch.py): `src/navigation/launch/navigation.launch.py`
- [SLAM stack](https://github.com/0range02/heliobox/blob/new-main/src/slam/launch/slam.launch.py): `src/slam/launch/slam.launch.py`
- [Map saving](https://github.com/0range02/heliobox/blob/new-main/src/slam/slam/map_save.py): `src/slam/slam/map_save.py`
- [Motion calibration](https://github.com/0range02/heliobox/blob/new-main/src/calibration/calibration/calibrate_linear.py): `src/calibration/calibration/calibrate_linear.py`

### Operations and fleets

- [Startup checks](https://github.com/0range02/heliobox/blob/new-main/src/bringup/bringup/startup_check.py): `src/bringup/bringup/startup_check.py`
- [Fleet coordination](https://github.com/0range02/heliobox/blob/new-main/src/multi/multi/formation_update.py): `src/multi/multi/formation_update.py`
- [Keyboard teleop](https://github.com/0range02/heliobox/blob/new-main/src/peripherals/peripherals/teleop_key_control.py): `src/peripherals/peripherals/teleop_key_control.py`

### Other components

- **ROS operator**

## Connections

- ROS operator → Lidar behavior: starts behavior
- ROS operator → YOLO detection: starts detection
- ROS operator → Navigation stack: starts navigation
- ROS operator → SLAM stack: starts mapping
- Lidar behavior → App helpers: uses helpers (evidence: `src/app/app/lidar_controller.py`)
- Lidar behavior → PID controller: uses control (evidence: `src/app/app/lidar_controller.py`)
- Lidar behavior → Control utilities: uses utilities (evidence: `src/app/app/lidar_controller.py`)
- Hand landmarks → Vision geometry: uses geometry (evidence: `src/app/app/model/hand_landmark.py`)
- Heliobox control → Behavior state: uses state (evidence: `src/heliobox/heliobox/heliobox_ctrl.py`)
- Robot controller node → Board SDK: uses board SDK (evidence: `src/driver/ros_robot_controller/ros_robot_controller/ros_robot_controller_node.py`)
- Joystick control → Control utilities: uses utilities (evidence: `src/peripherals/peripherals/joystick_control.py`)
- YOLO detection → Image tools: uses image tools (evidence: `src/yolov5_ros2/yolov5_ros2/yolo_detect.py`)
- YOLO detection → FPS meter: updates meter (evidence: `src/yolov5_ros2/yolov5_ros2/yolo_detect.py`)
- Lidar driver → Lidar behavior: supplies scans
- Camera driver → YOLO detection: supplies images
- Navigation stack → Odometry publisher: uses odometry
- SLAM stack → Map saving: saves maps
- Keyboard teleop → Robot controller node: commands motion
- Fleet coordination → Navigation stack: coordinates robots
