# hubap2/ros2_hutalia architecture

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

- Interactive diagram: https://gitdiagram.com/hubap2/ros2_hutalia
- Repository: https://github.com/hubap2/ros2_hutalia

## Overview

1. **Repository shape**
   - This is a ROS 2 workspace (`ros2_ws`) containing one package, `droneload`.
   - The repo is currently very small on disk: only `camera_node.py` is present in the package tree, while the README describes a broader multi-node system that is likely planned or partially implemented.

2. **System purpose**
   - The project targets an autonomous drone delivery platform (“DroneLoad 2026”).
   - The architecture is centered on sensor ingestion, perception, and autonomous navigation for an indoor/outdoor drone stack.

3. **Core runtime environment**
   - The primary runtime is **ROS 2 Humble**.
   - The system integrates with **MAVROS** and **ArduCopter** for flight control, which makes the drone stack depend on a PX4/ArduPilot-style autopilot bridge rather than direct motor control from ROS.

4. **Sensor ingestion layer**
   - `camera_node` is the entry point for the vision pipeline.
   - It converts **Intel RealSense D4xx** video into a ROS image stream on `camera/image_raw`, making camera data available to downstream perception nodes.

5. **Perception / computer vision layer**
   - `aruco_node` consumes camera imagery and detects **ArUco markers**, publishing detections on `aruco/markers`.
   - `reconnaissance_node` performs **object recognition with ORB**, publishing state or classification results on `camera/object_status`.
   - These two nodes are separate perception branches: one for fiducials / localization cues, one for general object recognition.

6. **Navigation / autonomy layer**
   - `navigation_node` is the control-orchestration boundary for autonomous movement.
   - It fuses or coordinates inputs from **MAVROS**, **Marvelmind indoor positioning**, and **LiDAR** (via MatekSys 3901-L0X) to produce navigation decisions.
   - This node is the main consumer of perception and localization outputs, and likely the main producer of flight commands to the autopilot bridge.

7. **Main data flow**
   - The high-level flow is: **RealSense camera → `camera_node` → image topics → `aruco_node` / `reconnaissance_node` → navigation decisions → MAVROS/ArduCopter**.
   - Parallel to that, **Marvelmind + LiDAR** feed the navigation stack for positioning and obstacle-aware motion.

8. **Important architectural boundaries**
   - **Sensor drivers / adapters**: hardware-specific access to RealSense, Marvelmind, and LiDAR.
   - **Perception**: image interpretation and marker/object detection.
   - **Autonomy / control**: route planning, state management, and command generation.
   - **Flight-control bridge**: MAVROS isolates ROS 2 logic from the autopilot implementation.

9. **Communication model**
   - The architecture is topic-driven, which is standard ROS 2 pub/sub.
   - The topic names in the README indicate explicit contracts between modules, especially `camera/image_raw`, `aruco/markers`, and `camera/object_status`.

10. **Implementation language / package layout**
   - The visible file `camera_node.py` suggests at least part of the package is implemented in **Python**.
   - The package layout under `ros2_ws/src/droneload/droneload` indicates a standard ROS 2 Python package structure rather than a monolithic application.

11. **External dependencies that matter**
   - **Intel RealSense D4xx**: primary visual input.
   - **MAVROS / ArduCopter**: flight control integration.
   - **Marvelmind**: indoor localization input.
   - **MatekSys 3901-L0X**: combines LiDAR and optical flow for navigation support.

12. **What an architecture diagram should show**
   - At minimum: four logical blocks — **sensor acquisition**, **vision perception**, **navigation/autonomy**, and **autopilot bridge**.
   - Show `camera_node` feeding both perception nodes, and show `navigation_node` consuming perception plus localization/safety sensors, then controlling the drone through MAVROS/ArduCopter.

Main entry points: [`ros2_ws/src/droneload/droneload/camera_node.py`](https://github.com/hubap2/ros2_hutalia/blob/main/ros2_ws/src/droneload/droneload/camera_node.py) (Camera node), [`ros2_ws/src/droneload`](https://github.com/hubap2/ros2_hutalia/tree/main/ros2_ws/src/droneload) (droneload), [`ros2_ws`](https://github.com/hubap2/ros2_hutalia/tree/main/ros2_ws) (ros2_ws)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["ROS 2 Workspace"]
  node_ros2_ws["ros2_ws<br/>ROS 2 workspace"]
  node_droneload_pkg["droneload<br/>ROS package"]
end

subgraph group_sensors["Sensor Layer"]
  node_camera_node["Camera node<br/>vision publisher<br/>[camera_node.py]"]
  node_realsense[("RealSense<br/>camera driver")]
  node_marvelmind[("Marvelmind<br/>indoor positioning")]
  node_lidar[("LiDAR<br/>range sensor")]
end

subgraph group_perception["Perception"]
  node_aruco_node["ArUco node<br/>fiducial detector"]
  node_reconnaissance_node["ORB node<br/>object recognizer"]
end

subgraph group_autonomy["Autonomy"]
  node_navigation_node["Navigation node<br/>autonomy coordinator"]
end

subgraph group_bridge["Flight Bridge"]
  node_mavros["MAVROS<br/>ROS flight bridge"]
  node_arducopter[("ArduCopter<br/>autopilot")]
end

node_ros2_ws -->|"contains"| node_droneload_pkg
node_droneload_pkg -->|"implements"| node_camera_node
node_realsense -->|"frames"| node_camera_node
node_camera_node -->|"camera/image_raw"| node_aruco_node
node_camera_node -->|"camera/image_raw"| node_reconnaissance_node
node_aruco_node -->|"aruco/markers"| node_navigation_node
node_reconnaissance_node -->|"camera/object_status"| node_navigation_node
node_marvelmind -->|"positioning"| node_navigation_node
node_lidar -->|"obstacles"| node_navigation_node
node_navigation_node -->|"commands"| node_mavros
node_mavros -->|"vehicle control"| node_arducopter

click node_ros2_ws "https://github.com/hubap2/ros2_hutalia/tree/main/ros2_ws"
click node_droneload_pkg "https://github.com/hubap2/ros2_hutalia/tree/main/ros2_ws/src/droneload"
click node_camera_node "https://github.com/hubap2/ros2_hutalia/blob/main/ros2_ws/src/droneload/droneload/camera_node.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_ros2_ws,node_droneload_pkg toneBlue
class node_camera_node,node_realsense,node_marvelmind,node_lidar toneAmber
class node_aruco_node,node_reconnaissance_node toneMint
class node_navigation_node toneRose
class node_mavros,node_arducopter toneIndigo
```

## Components

### ROS 2 Workspace

Humble workspace hosting the drone package

- [ros2_ws](https://github.com/hubap2/ros2_hutalia/tree/main/ros2_ws): ROS 2 workspace · Top-level ROS 2 workspace for the project · `ros2_ws`
- [droneload](https://github.com/hubap2/ros2_hutalia/tree/main/ros2_ws/src/droneload): ROS package · Main package containing drone runtime nodes · `ros2_ws/src/droneload`

### Sensor Layer

Hardware adapters and incoming data sources

- [Camera node](https://github.com/hubap2/ros2_hutalia/blob/main/ros2_ws/src/droneload/droneload/camera_node.py): vision publisher · Reads Intel RealSense D4xx frames and publishes camera/image_raw · `ros2_ws/src/droneload/droneload/camera_node.py`
- **RealSense**: camera driver · Intel RealSense D4xx video source
- **Marvelmind**: indoor positioning · Indoor localization input for navigation
- **LiDAR**: range sensor · MatekSys 3901-L0X obstacle and flow support input

### Perception

Vision interpretation and detection nodes

- **ArUco node**: fiducial detector · Detects ArUco markers from camera images and publishes aruco/markers
- **ORB node**: object recognizer · Performs ORB-based object recognition and publishes camera/object_status

### Autonomy

Navigation and command orchestration

- **Navigation node**: autonomy coordinator · Fuses localization and perception inputs to produce navigation decisions

### Flight Bridge

Autopilot integration and vehicle control

- **MAVROS**: ROS flight bridge · ROS-to-autopilot communication layer
- **ArduCopter**: autopilot · Flight controller receiving navigation commands

## Connections

- ros2_ws → droneload: contains · Workspace hosts the drone package
- droneload → Camera node: implements · Package includes the camera runtime
- RealSense → Camera node: frames · Camera hardware feeds the ROS image publisher
- Camera node → ArUco node: camera/image_raw · Published image stream used for marker detection
- Camera node → ORB node: camera/image_raw · Published image stream used for object recognition
- ArUco node → Navigation node: aruco/markers · Fiducial detections inform navigation
- ORB node → Navigation node: camera/object_status · Object status feeds autonomy decisions
- Marvelmind → Navigation node: positioning · Indoor localization supports motion planning
- LiDAR → Navigation node: obstacles · Range and flow sensing support safe navigation
- Navigation node → MAVROS: commands · Autonomy outputs are sent through the flight bridge
- MAVROS → ArduCopter: vehicle control · MAVROS relays commands to the autopilot