# fontainebleau2021/agv_2023 architecture

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

- Interactive diagram: https://gitdiagram.com/fontainebleau2021/agv_2023
- Repository: https://github.com/fontainebleau2021/agv_2023

## Overview

##### Project type and purpose
- This is a ROS‐based AGV (automated guided vehicle) integration framework (`agv_2023_pkg`), organized as a catkin workspace with multiple ROS packages.
- It brings together sensor drivers (`sensor_pkg`), SLAM/localization (`SLAM_pkg`), mapping (`map_pkg`), navigation planning (`navigation_pkg`), control and actuation (`control_pkg` + `motor_control`), network/cloud connectivity (`networksocket_pkg`), orchestration services (`service_pkg`), and shell scripts to launch sensors (`sensor_run_sh`).

##### High-level package breakdown
- sensor_pkg: IMU, GPS, LiDAR (Livox/Ouster), camera (ZED, USB), Marvelmind, NMEA driver
- SLAM_pkg: LIO‐SAM SLAM algorithm (with relocalization)
- map_pkg: static map loaders & pointcloud publishers for RViz
- navigation_pkg: costmaps, global planner, TEB local planner, “navi_master” orchestration
- control_pkg: UGV SDK (bunker, hunter, scout, tracer demos), ROS control nodes, motor_control for servos
- networksocket_pkg: ROS socket clients and web UI (robot_html) for remote visualization/control
- service_pkg: RPC servers (agr_service) exposing services for starting/stopping nodes, SLAM service
- sensor_run_sh: convenience shell scripts to bring up each sensor

##### Key architectural patterns
- ROS pub/sub: sensors → topic streams → SLAM/localization → odometry (`/tf`), pointclouds, images → navigation nodes → velocity commands → control nodes → hardware/SDK
- ROS services/actions: `agr_service`, save_map service, network socket RPC
- Parameterization & launch: each package has dedicated `launch/` folder, YAML parameter files under `config/`
- Modularity: each functional domain in its own package; common messages under `msg/`, service definitions under `srv/`

##### Main components
A. ROS Master (central graph manager)
B. Sensor Layer (sensor_pkg + sensor_run_sh)
- IMU node(s) (openzen_sensor, imu_integrator)
- GPS node(s) (nmea_navsat_driver, imu_gps_localization)
- LiDAR nodes (livox_ros_driver, ouster_ros)
- Camera nodes (zed-open-capture, usb_cam)
- Marvelmind beacon node
C. SLAM/Localization Layer (SLAM_pkg/lio_sam_devel)
- Input: `/imu/data`, `/velodyne_points`, `/livox/lidar`
- Output: optimized pose (`/aft_mapped_to_init`), `cloud_info` topic
D. Mapping & Visualization Layer (map_pkg)
- map_load publishes static occupancy map & RViz config
- pcd_to_rviz and publish_pointcloud nodes publish demo point clouds
E. Navigation & Planning Layer (navigation_pkg)
- Costmap generator → local & global planners → TEB planner
- navi_master orchestrates state machine, subscribes odometry, publishes `/cmd_vel` or `/ackermann_drive`
F. Control & Actuation Layer (control_pkg + motor_control)
- UGV SDK library wraps CAN/serial ports → `bunker_base_node` etc.
- motor_control node exposes TCP/ROS interface, subscribes velocity commands, drives servo motors
G. Service & Orchestration Layer (service_pkg)
- agr_service node provides ROS service `/agr_service` to start SLAM/navigation clients
H. Network & Web UI Layer (networksocket_pkg)
- robotsocket C++ node provides TCP/UDP socket interfaces, publishes/subscribes ROS topics remotely
- robot_html web client (JavaScript) connects to robotsocket, visualizes map & robot pose

##### Interactions and data flows
- Sensors publish raw data streams → SLAM & mapping nodes consume them
- SLAM outputs pose & pointcloud info → navigation nodes read pose for planning
- Navigation publishes velocity commands → control nodes translate to motor driver messages
- Service nodes allow on‐demand start/stop via ROS services
- Network socket nodes mirror selected topics to remote client; web UI subscribes to these via WebSockets

##### Technologies & frameworks
- ROS Melodic (nodes in C++/Python)
- LIO‐SAM (GTSAM, PCL, Eigen)
- Livox & Ouster SDKs
- ZED Open Capture (C++ + ROS API)
- Web UI: roslibjs, ros2djs, eventemitter2
- UGV SDK: C++ async ports, protocol parsers
- Dockerfile (SLAM_pkg) for reproducible container
- CMake / catkin build system; parameters in YAML; RViz configs

- Clear labels: component names, topic/service names
- External dependencies (e.g., Livox/Ouster hardware, Web browser)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "ROS Core"
        ROS_MASTER["ROS Master"]:::rosmaster
    end

    subgraph "Sensor Layer" 
        direction TB
        IMU["IMU Nodes"]:::sensor
        GPS1["nmea_navsat_driver"]:::sensor
        GPS2["imu_gps_localization"]:::sensor
        LIVOX["livox_ros_driver"]:::sensor
        OUSTER["ouster_ros"]:::sensor
        ZED_OPEN["zed-open-capture"]:::sensor
        USB_CAM["usb_cam"]:::sensor
        MARVELMIND["Marvelmind Beacon"]:::sensor
        SENSOR_LAUNCH["Sensor Launch Scripts"]:::sensor
    end

    subgraph "SLAM/Localization Layer"
        SLAM_NODE["LIO-SAM SLAM"]:::slam
    end

    subgraph "Service & Orchestration Layer"
        AGR_SERVICE["agr_service RPC Server"]:::service
    end

    subgraph "Mapping & Visualization Layer"
        MAP_LOAD["Static Map Loader"]:::mapping
        PCD2RVIZ["pcd_to_rviz"]:::mapping
        PUBLISH_PC["publish_pointcloud"]:::mapping
    end

    subgraph "Navigation & Planning Layer"
        NAV_CORE["Navigation Core & navi_master"]:::navigation
        BUNKER_DESC["bunker_description"]:::navigation
    end

    subgraph "Network & Web UI Layer"
        ROBOTSOCKET["robotsocket Server"]:::network
        ROBOT_HTML["robot_html Web Client"]:::network
    end

    subgraph "Control & Actuation Layer"
        UGV_SDK["UGV SDK Nodes"]:::control
        BUNKER_ROS["bunker_ros Nodes"]:::control
        MOTOR_CTRL["motor_control Node"]:::control
    end

    subgraph "Hardware"
        ACTUATORS["CAN/Servo Actuators"]:::hardware
    end

    %% Flows
    ROS_MASTER -->|manages| IMU
    ROS_MASTER --> GPS1
    ROS_MASTER --> GPS2
    ROS_MASTER --> LIVOX
    ROS_MASTER --> OUSTER
    ROS_MASTER --> ZED_OPEN
    ROS_MASTER --> USB_CAM
    ROS_MASTER --> MARVELMIND
    ROS_MASTER --> SENSOR_LAUNCH

    IMU & GPS1 & GPS2 & LIVOX & OUSTER & ZED_OPEN & USB_CAM & MARVELMIND -->|"/imu/data,/velodyne_points,/livox/lidar"/etc| SLAM_NODE

    SLAM_NODE -->|"pose,/tf,cloud_info"| NAV_CORE

    SLAM_NODE -->|'bidir: /agr_service'| AGR_SERVICE
    AGR_SERVICE -->|'bidir: /agr_service'| NAV_CORE

    MAP_LOAD & PCD2RVIZ & PUBLISH_PC -->|publish static map & pointclouds| ROBOTSOCKET
    SLAM_NODE -->|cloud_info| ROBOTSOCKET
    NAV_CORE -->|odom,cmd_vel| ROBOTSOCKET
    ROBOTSOCKET -->|WebSockets| ROBOT_HTML

    NAV_CORE -->|"/cmd_vel,/ackermann_drive"| MOTOR_CTRL
    MOTOR_CTRL -->|drives| ACTUATORS
    UGV_SDK & BUNKER_ROS -->|control messages| ACTUATORS

    %% Click Events
    click IMU "https://github.com/fontainebleau2021/agv_2023/tree/master/sensor_pkg/imu_pkg/imu_integrator"
    click GPS1 "https://github.com/fontainebleau2021/agv_2023/tree/master/sensor_pkg/GPS_pkg/nmea_navsat_driver"
    click GPS2 "https://github.com/fontainebleau2021/agv_2023/tree/master/sensor_pkg/GPS_pkg/imu_gps_localization"
    click LIVOX "https://github.com/fontainebleau2021/agv_2023/tree/master/sensor_pkg/livox_pkg/livox_ros_driver"
    click OUSTER "https://github.com/fontainebleau2021/agv_2023/tree/master/sensor_pkg/ouster_pkg/ouster_lidar/ouster_ros"
    click ZED_OPEN "https://github.com/fontainebleau2021/agv_2023/tree/master/sensor_pkg/camera_pkg/zed-open-capture"
    click USB_CAM "https://github.com/fontainebleau2021/agv_2023/tree/master/sensor_pkg/camera_pkg/camera"
    click MARVELMIND "https://github.com/fontainebleau2021/agv_2023/tree/master/sensor_pkg/marvelmind_pkg/ros_marvelmind_package"
    click SENSOR_LAUNCH "https://github.com/fontainebleau2021/agv_2023/tree/master/sensor_run_sh/"
    click SLAM_NODE "https://github.com/fontainebleau2021/agv_2023/tree/master/SLAM_pkg/lio_sam_devel"
    click MAP_LOAD "https://github.com/fontainebleau2021/agv_2023/tree/master/map_pkg/map_load"
    click PCD2RVIZ "https://github.com/fontainebleau2021/agv_2023/tree/master/map_pkg/pcd_to_rviz"
    click PUBLISH_PC "https://github.com/fontainebleau2021/agv_2023/tree/master/map_pkg/publish_pointcloud"
    click NAV_CORE "https://github.com/fontainebleau2021/agv_2023/tree/master/navigation_pkg/navigation"
    click BUNKER_DESC "https://github.com/fontainebleau2021/agv_2023/tree/master/navigation_pkg/bunker_description"
    click UGV_SDK "https://github.com/fontainebleau2021/agv_2023/tree/master/control_pkg/bunker_pkg/ugv_sdk"
    click BUNKER_ROS "https://github.com/fontainebleau2021/agv_2023/tree/master/control_pkg/bunker_pkg/bunker_ros"
    click MOTOR_CTRL "https://github.com/fontainebleau2021/agv_2023/tree/master/control_pkg/motor_control"
    click AGR_SERVICE "https://github.com/fontainebleau2021/agv_2023/tree/master/service_pkg/agr_service"
    click ROBOTSOCKET "https://github.com/fontainebleau2021/agv_2023/tree/master/networksocket_pkg/robotsocket"
    click ROBOT_HTML "https://github.com/fontainebleau2021/agv_2023/tree/master/networksocket_pkg/robot_html"

    %% Styles
    classDef rosmaster fill:#f6e58d,stroke:#d35400,stroke-width:2px
    classDef sensor fill:#74b9ff,stroke:#0984e3,color:#ffffff
    classDef slam fill:#55efc4,stroke:#00b894
    classDef mapping fill:#81ecec,stroke:#00cec9
    classDef navigation fill:#fdcb6e,stroke:#e17055
    classDef control fill:#e17055,stroke:#d63031
    classDef service fill:#b2bec3,stroke:#636e72
    classDef network fill:#a29bfe,stroke:#6c5ce7
    classDef hardware fill:#dfe6e9,stroke:#b2bec3,stroke-dasharray: 5 5
```
