# ark-electronics/tracktor-beam architecture

> Architecture diagram of the GitHub repository ark-electronics/tracktor-beam, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ark-electronics/tracktor-beam
- Repository: https://github.com/ark-electronics/tracktor-beam

## Overview

##### Project Type and Purpose
- This is a full-stack robotics application built on ROS2 and PX4. It integrates a simulated drone (PX4 SITL in Gazebo) with OpenCV-based ArUco marker detection and ROS2-based precision landing logic. The goal is to detect fiducial markers in real time and command the PX4 autopilot to perform centimeter-level landings.

##### File Structure Analysis
- Top-level scripts & services
- install_opencv.sh, Makefile (PX4 SITL launch target), systemd unit files under services/ (usb_cam, dds-agent, aruco_tracker)
- src/
- aruco_tracker/ — ROS2 package: subscribes to camera topics, runs OpenCV ArUco detection, publishes marker pose
- precision_land/ — ROS2 package: subscribes to marker pose, computes landing setpoints, commands PX4 via ROS2 topics
- px4-ros2-interface-lib, px4_msgs, vision_opencv — support libraries and message definitions
- Launch & config
- launch/*.launch.py and cfg/params.yaml per package for parameterization
- CMakeLists.txt & package.xml define build and dependencies

##### README Insights
- Shows the run sequence:
1) make px4_sitl gz_x500_mono_cam_down_aruco
2) MicroXRCEAgent for PX4 <-> ROS2 bridging
3) ros_gz_bridge for camera and camera_info topics
4) ros2 run aruco_tracker / precision_land (or launch files)
5) QGroundControl for monitoring & mode switching
- Key technologies: ROS2 Humble, Micro XRCE-DDS, ROS_GZ Bridge, Gazebo, PX4 SITL, OpenCV 4.10

a. Main Components
- Simulation Block: Gazebo world with downward-facing camera + ArUco marker + PX4 SITL autopilot
- Middleware Layer:
– Micro XRCE-DDS Agent (UDP bridge to PX4)
– ros_gz_bridge (bridges Gazebo topics to ROS2 DDS)
– ROS2 DDS network
- ROS2 Nodes:
– usb_cam (real USB camera node or sim camera stub)
– aruco_tracker (image subscriber → OpenCV → publishes marker pose)
– precision_land (pose subscriber → landing controller → publishes setpoints to PX4)
- Ground Station: QGroundControl (MAVLink telemetry)
- Storage/Config: Params loaded from cfg/params.yaml, launch files

b. Relationships & Data Flow
1) Gazebo publishes /camera and /camera_info → ros_gz_bridge → ROS2 topics
2) aruco_tracker subscribes → CV detection → publishes /aruco_pose
3) precision_land subscribes /aruco_pose → computes setpoints → publishes to PX4 command topics
4) Micro XRCE-DDS Agent bridges ROS2 ↔ PX4 SITL (state, setpoints)
5) QGroundControl ↔ PX4 SITL via MAVLink

c. Architectural Patterns
- Publisher/Subscriber (ROS2 DDS) decoupling perception and control
- Layered: Simulation → Middleware → Perception → Control → Autopilot → Ground Station
- Modular ROS2 packages for reusability and unit testing

d. Key Technologies & Libraries
- ROS2 Humble (rclcpp, launch system)
- OpenCV ArUco module
- Micro XRCE-DDS for lightweight DDS
- ros_gz_bridge for Gazebo-ROS2 integration
- PX4 SITL (gazebo)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Simulation & Middleware Layer
    subgraph "Simulation & Middleware"
        direction TB
        GZ[/"Gazebo w/ PX4 SITL"/]:::sim
        RGZ["ros_gz_bridge"]:::sim
        MUGDDS["Micro XRCE-DDS Agent\n(UDP 8888)"]:::sim
        PX["PX4 SITL Autopilot"]:::sim
    end

    %% Perception Layer
    subgraph "Perception"
        direction TB
        USB["usb_cam node"]:::per
        ARU["aruco_tracker"]:::per
    end

    %% Control Layer
    subgraph "Control"
        direction TB
        PRE["precision_land"]:::ctrl
    end

    %% External Systems
    subgraph "External"
        direction TB
        QGC[(QGroundControl)]:::ext
    end

    %% Configuration Store
    subgraph "Configuration"
        direction TB
        CFG[(cfg/params.yaml)]:::data
    end

    %% Support Libraries
    subgraph "Support Libraries"
        direction TB
        LIB1["px4-ros2-interface-lib"]:::lib
        LIB2["px4_msgs"]:::lib
        LIB3["vision_opencv"]:::lib
    end

    %% Deployment Services
    subgraph "Deployment Services"
        direction TB
        S1["usb_cam.service"]:::deploy
        S2["dds-agent.service"]:::deploy
        S3["aruco_tracker.service"]:::deploy
    end

    %% Project Files
    subgraph "Project Files"
        direction TB
        MAKE["Makefile"]:::deploy
        INS["install_opencv.sh"]:::deploy
        RM["README.md"]:::deploy
    end

    %% Data Flows
    GZ -->|"camera topics"| RGZ
    RGZ -->|"ROS2 /camera"| ARU
    USB --> ARU
    ARU -->|"aruco_pose"| PRE
    PRE -->|"setpoints"| MUGDDS
    MUGDDS -.-> PX
    GZ --> PX
    QGC -->|"MAVLink telemetry"| PX
    ARU --> CFG
    PRE --> CFG

    %% Support Libraries Usage
    PRE --> LIB1
    PRE --> LIB2
    ARU --> LIB3
    USB --> LIB3

    %% Deployment Links
    USB --> S1
    MUGDDS --> S2
    ARU --> S3

    %% Project Files Links
    MAKE --- GZ
    INS --- ARU
    RM --- GZ

    %% Click Events
    click ARU "https://github.com/ark-electronics/tracktor-beam/tree/main/src/aruco_tracker/"
    click PRE "https://github.com/ark-electronics/tracktor-beam/tree/main/src/precision_land/"
    click LIB1 "https://github.com/ark-electronics/tracktor-beam/tree/main/src/px4-ros2-interface-lib/"
    click LIB2 "https://github.com/ark-electronics/tracktor-beam/tree/main/src/px4_msgs/"
    click LIB3 "https://github.com/ark-electronics/tracktor-beam/tree/main/src/vision_opencv/"
    click S1 "https://github.com/ark-electronics/tracktor-beam/blob/main/services/usb_cam.service"
    click S2 "https://github.com/ark-electronics/tracktor-beam/blob/main/services/dds-agent.service"
    click S3 "https://github.com/ark-electronics/tracktor-beam/blob/main/services/aruco_tracker.service"
    click MAKE "https://github.com/ark-electronics/tracktor-beam/tree/main/Makefile"
    click INS "https://github.com/ark-electronics/tracktor-beam/blob/main/install_opencv.sh"
    click RM "https://github.com/ark-electronics/tracktor-beam/blob/main/README.md"

    %% Styles
    classDef sim fill:#C3DDF9,stroke:#3270B4,color:#000;
    classDef per fill:#C8F7C5,stroke:#2E8B57,color:#000;
    classDef ctrl fill:#F9E2C5,stroke:#D2691E,color:#000;
    classDef ext fill:#E0E0E0,stroke:#666,color:#000;
    classDef data fill:#FFF5BA,stroke:#DAA520,color:#000;
    classDef lib fill:#F0F0F0,stroke:#8B8B8B,color:#000;
    classDef deploy fill:#F5F5F5,stroke:#A9A9A9,color:#000;
```
