# mourams/livox_ros_driver2 architecture

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

- Interactive diagram: https://gitdiagram.com/mourams/livox_ros_driver2
- Repository: https://github.com/mourams/livox_ros_driver2

## Overview

##### Project Type and Purpose
- This is a full-stack robotics driver package (“Livox ROS Driver 2”), providing a bridge between Livox LiDAR hardware and ROS/ROS2.
- It configures LiDAR devices over the network, ingests raw data packets, parses and queues them, then publishes point-cloud messages to ROS topics for visualization or recording.

##### File Structure
- Top-level directories:
- 3rdparty/rapidjson  → JSON parser library for config files
- config/             → JSON config templates for HAP, MID360, mixed setups
- launch_ROS1/launch_ROS2 → ROS1 XML launch files and ROS2 Python launch scripts
- msg/                → Custom ROS message definitions
- src/parse_cfg_file  → Code to read and interpret JSON configs
- src/comm/           → Communication utilities (queues, semaphores, packet handlers)
- src/call_back/      → Callbacks for different LiDAR models
- src/… .cpp/.h       → Driver node entrypoint, util modules, SDK integration

##### README for Additional Insights
- Core flow:
1) Read JSON config (via rapidjson)
2) Use Livox-SDK2 to send configuration commands
3) Open UDP ports to receive point and IMU data
4) Parse raw packets → CustomMsg/CustomPoint or standard PointCloud2
5) Publish to ROS topics
6) Optionally launch RViz or rosbag record

##### Main Components & Interactions
a. Hardware & External Services
- LiDAR devices (HAP, MID360) on network
- ROS1/ROS2 middleware (roscore or ROS2 DDS)
- RViz visualization
- rosbag (optional)
b. Internal Driver Components
- Config Parser (src/parse_cfg_file + rapidjson)
- Network Interface (Livox-SDK2 + sockets)
- Comm Layer (src/comm: cache_index, data_queue, pub_handler)
- Callback Layer (src/call_back: model-specific packet handlers)
- Driver Node (livox_ros_driver2_node entrypoint)
- Message Definitions (msg/CustomMsg.msg, CustomPoint.msg)
c. Data Flows & Relationships
1) Launch file passes parameters → Driver Node
2) Driver Node loads JSON via Config Parser
3) Driver Node calls Livox-SDK2 to configure devices
4) Driver Node opens UDP sockets to receive data
5) Raw packets → Comm Layer → Callback Layer
6) Processed point clouds → ROS topics
7) Topics → RViz / rosbag
8) Optionally multiple instances (multi-topic)

##### Architectural Patterns & Design Principles
- Publisher–Subscriber (ROS topics)
- Modular layering:
- Separation of concerns (config, network, parsing, publishing)
- Extensibility (callback modules per LiDAR type)
- Use of industry libraries: rapidjson for config, Livox-SDK2 for low-level comms, PCL for optional data types

##### Final Checklist
- All src subdirectories represented (parse_cfg_file, comm, call_back)
- JSON config files feeding into parser
- Launch file layer feeding parameters
- Network flow from devices to node
- ROS topics as central bus
- Visualization & recording as sinks

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Hardware
    subgraph "External Hardware" 
        LiDAR["LiDAR Devices (HAP, MID360)"]:::external
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        Templates["Config Templates"]:::config
        Rapidjson["rapidjson Library"]:::library
        Parser["Config Parser"]:::internal
    end

    %% Launch Layer
    subgraph "Launch Layer"
        ROS1Launch["ROS1 Launch Scripts"]:::config
        ROS2Launch["ROS2 Launch Scripts"]:::config
    end

    %% Core Driver
    subgraph "Core Driver Logic"
        DriverNode["Driver Node"]:::internal
        Network["Network Interface & SDK"]:::sdk
        CommLayer["Comm Layer"]:::comm
        CallbackLayer["Callback Layer"]:::callback
    end

    %% ROS Middleware
    subgraph "ROS Middleware"
        ROSCore["ROS1/ROS2 Middleware"]:::middleware
    end

    %% Consumers
    subgraph "Consumers"
        RViz["RViz Visualization"]:::consumer
        Rosbag["rosbag Recording"]:::consumer
    end

    %% Flows
    Templates -->|provide JSON| Parser
    Rapidjson --> Parser
    ROS1Launch -->|pass params| DriverNode
    ROS2Launch -->|pass params| DriverNode

    DriverNode -->|"configure devices"| Network
    LiDAR -->|"UDP packets"| Network
    Network -->|"raw data"| CommLayer
    CommLayer -->|"parsed packets"| CallbackLayer
    CallbackLayer -->|"point clouds"| DriverNode

    DriverNode -->|"publish PointCloud2"| ROSCore
    ROSCore --> RViz
    ROSCore --> Rosbag

    %% Click Events
    click Parser "https://github.com/mourams/livox_ros_driver2/blob/master/src/parse_cfg_file/parse_cfg_file.cpp"
    click Parser "https://github.com/mourams/livox_ros_driver2/blob/master/src/parse_cfg_file/parse_cfg_file.h"
    click Parser "https://github.com/mourams/livox_ros_driver2/blob/master/src/parse_cfg_file/parse_livox_lidar_cfg.cpp"
    click Parser "https://github.com/mourams/livox_ros_driver2/blob/master/src/parse_cfg_file/parse_livox_lidar_cfg.h"

    click Rapidjson "https://github.com/mourams/livox_ros_driver2/tree/master/3rdparty/rapidjson/"

    click Templates "https://github.com/mourams/livox_ros_driver2/blob/master/config/HAP_config.json"
    click Templates "https://github.com/mourams/livox_ros_driver2/blob/master/config/MID360_config.json"
    click Templates "https://github.com/mourams/livox_ros_driver2/blob/master/config/mixed_HAP_MID360_config.json"

    click ROS1Launch "https://github.com/mourams/livox_ros_driver2/blob/master/launch_ROS1/msg_HAP.launch"
    click ROS1Launch "https://github.com/mourams/livox_ros_driver2/blob/master/launch_ROS1/msg_MID360.launch"
    click ROS1Launch "https://github.com/mourams/livox_ros_driver2/blob/master/launch_ROS1/msg_mixed.launch"
    click ROS1Launch "https://github.com/mourams/livox_ros_driver2/blob/master/launch_ROS1/rviz_HAP.launch"
    click ROS1Launch "https://github.com/mourams/livox_ros_driver2/blob/master/launch_ROS1/rviz_MID360.launch"
    click ROS1Launch "https://github.com/mourams/livox_ros_driver2/blob/master/launch_ROS1/rviz_mixed.launch"

    click ROS2Launch "https://github.com/mourams/livox_ros_driver2/blob/master/launch_ROS2/msg_HAP_launch.py"
    click ROS2Launch "https://github.com/mourams/livox_ros_driver2/blob/master/launch_ROS2/msg_MID360_launch.py"
    click ROS2Launch "https://github.com/mourams/livox_ros_driver2/blob/master/launch_ROS2/rviz_HAP_launch.py"
    click ROS2Launch "https://github.com/mourams/livox_ros_driver2/blob/master/launch_ROS2/rviz_MID360_launch.py"
    click ROS2Launch "https://github.com/mourams/livox_ros_driver2/blob/master/launch_ROS2/rviz_mixed.py"

    click DriverNode "https://github.com/mourams/livox_ros_driver2/blob/master/src/driver_node.cpp"
    click DriverNode "https://github.com/mourams/livox_ros_driver2/blob/master/src/driver_node.h"
    click DriverNode "https://github.com/mourams/livox_ros_driver2/blob/master/src/livox_ros_driver2.cpp"
    click DriverNode "https://github.com/mourams/livox_ros_driver2/blob/master/src/lds.cpp"
    click DriverNode "https://github.com/mourams/livox_ros_driver2/blob/master/src/lds.h"
    click DriverNode "https://github.com/mourams/livox_ros_driver2/blob/master/src/lds_lidar.cpp"
    click DriverNode "https://github.com/mourams/livox_ros_driver2/blob/master/src/lds_lidar.h"
    click DriverNode "https://github.com/mourams/livox_ros_driver2/blob/master/src/lddc.cpp"
    click DriverNode "https://github.com/mourams/livox_ros_driver2/blob/master/src/lddc.h"

    click Network "https://github.com/mourams/livox_ros_driver2/blob/master/src/lds.cpp"
    click Network "https://github.com/mourams/livox_ros_driver2/blob/master/src/lds.h"
    click Network "https://github.com/mourams/livox_ros_driver2/blob/master/src/lds_lidar.cpp"
    click Network "https://github.com/mourams/livox_ros_driver2/blob/master/src/lds_lidar.h"
    click Network "https://github.com/mourams/livox_ros_driver2/blob/master/src/lddc.cpp"
    click Network "https://github.com/mourams/livox_ros_driver2/blob/master/src/lddc.h"

    click CommLayer "https://github.com/mourams/livox_ros_driver2/blob/master/src/comm/comm.cpp"
    click CommLayer "https://github.com/mourams/livox_ros_driver2/blob/master/src/comm/comm.h"
    click CommLayer "https://github.com/mourams/livox_ros_driver2/blob/master/src/comm/cache_index.cpp"
    click CommLayer "https://github.com/mourams/livox_ros_driver2/blob/master/src/comm/cache_index.h"
    click CommLayer "https://github.com/mourams/livox_ros_driver2/blob/master/src/comm/ldq.cpp"
    click CommLayer "https://github.com/mourams/livox_ros_driver2/blob/master/src/comm/ldq.h"
    click CommLayer "https://github.com/mourams/livox_ros_driver2/blob/master/src/comm/lidar_imu_data_queue.cpp"
    click CommLayer "https://github.com/mourams/livox_ros_driver2/blob/master/src/comm/lidar_imu_data_queue.h"
    click CommLayer "https://github.com/mourams/livox_ros_driver2/blob/master/src/comm/pub_handler.cpp"
    click CommLayer "https://github.com/mourams/livox_ros_driver2/blob/master/src/comm/pub_handler.h"
    click CommLayer "https://github.com/mourams/livox_ros_driver2/blob/master/src/comm/semaphore.cpp"
    click CommLayer "https://github.com/mourams/livox_ros_driver2/blob/master/src/comm/semaphore.h"

    click CallbackLayer "https://github.com/mourams/livox_ros_driver2/blob/master/src/call_back/lidar_common_callback.cpp"
    click CallbackLayer "https://github.com/mourams/livox_ros_driver2/blob/master/src/call_back/lidar_common_callback.h"
    click CallbackLayer "https://github.com/mourams/livox_ros_driver2/blob/master/src/call_back/livox_lidar_callback.cpp"
    click CallbackLayer "https://github.com/mourams/livox_ros_driver2/blob/master/src/call_back/livox_lidar_callback.h"

    click RViz "https://github.com/mourams/livox_ros_driver2/blob/master/package.xml"
    click Rosbag "https://github.com/mourams/livox_ros_driver2/blob/master/CMakeLists.txt"

    %% Styles
    classDef external fill:#9f6,stroke:#333,stroke-width:1px
    classDef config fill:#f96,stroke:#333,stroke-width:1px
    classDef internal fill:#6cf,stroke:#333,stroke-width:1px
    classDef library fill:#ccf,stroke:#333,stroke-width:1px
    classDef sdk fill:#c9f,stroke:#333,stroke-width:1px
    classDef comm fill:#8fd,stroke:#333,stroke-width:1px
    classDef callback fill:#add8e6,stroke:#333,stroke-width:1px
    classDef middleware fill:#fcf,stroke:#333,stroke-width:1px
    classDef consumer fill:#f9c,stroke:#333,stroke-width:1px
```
