# livox-sdk/livox_ros_driver architecture

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

- Interactive diagram: https://gitdiagram.com/livox-sdk/livox_ros_driver
- Repository: https://github.com/livox-sdk/livox_ros_driver

## Overview

##### Project type and purpose
- This is a ROS (Robot Operating System) driver package (“livox_ros_driver”) for Livox LiDAR devices (single‐unit LiDAR or multi‐port Hub).
- Purpose: establish communication with Livox hardware (via Livox‐SDK), parse raw LiDAR packets or files (LVX), publish point clouds and custom messages on ROS topics, and optionally synchronize timestamps via GPS.

##### File structure
- Top‐level: .gitignore, LICENSE, README.md, CMakeLists.txt, package.xml → standard ROS/Catkin package.
- livox_ros_driver/common → third‐party libraries (FastCRC for checksums; RapidJSON/RapidXML for config and XML parsing).
- livox_ros_driver/config → JSON configuration files (livox_lidar_config.json, livox_hub_config.json) and RViz view presets.
- livox_ros_driver/launch → ROS launch files orchestrating nodes, passing parameters, autoloading RViz or rosbag conversion.
- livox_ros_driver/livox_ros_driver → core C++ implementation: communication layers (comm_protocol, lds*, ldq, lddc), LVX file handling, node main entry point.
- livox_ros_driver/msg → ROS message definitions (CustomMsg, CustomPoint).
- livox_ros_driver/timesync → GPS‐based timestamp synchronization module (serial port interface).

##### Extract architecture insights from README
- The driver is a single ROS node (can be run in multiple instances via different launch files).
- It depends on Livox-SDK for low‐level device communication.
- Configuration is supplied via JSON files, loaded at startup by launch files.
- Publishes multiple topic types: standard sensor_msgs/PointCloud2, custom liveox formats, and can record to rosbag or feed RViz.

a. Main components
- Hardware layer:
– Livox LiDAR devices (over Ethernet or USB)
– Livox Hub (aggregates multiple LiDARs)
– GPS receiver + PPS signal (for timesync)
- Driver layer (livox_ros_driver node):
– Comm module (comm_protocol)
– Data unpackers (lds_lidar, lds_hub, lvx_file)
– Timestamp sync (timesync module)
– JSON/XML parser (RapidJSON/RapidXML)
– CRC checker (FastCRC)
– ROS publishers (PointCloud2, CustomPoint, CustomMsg)
- ROS core/services:
– Parameter server (for configs)
– Topics and message bus
- Client layer:
– rviz (visualization)
– rosbag (record/playback)
– Other ROS nodes subscribing to LiDAR data

b. Relationships and interactions
1. Launch file → loads parameters from JSON → ROS parameter server
2. livox_ros_driver node reads parameters → initializes Livox‐SDK
3. Comm module connects to devices (LiDAR/Hub) → receives raw packets
4. Raw data passes through CRC → protocol parser → data queues
5. timesync module optionally reads GPS serial → adjusts packet timestamps
6. Data converters produce ROS messages → publish on topics
7. Clients (rviz, rosbag recorders, downstream nodes) subscribe to topics

c. Architectural patterns & principles
- Modular separation: communication, parsing, publishing, timesync
- Dependency injection via launch-file and config parameters
- Single‐responsibility nodes (one livox_ros_driver instance per device type or conversion use case)
- Plugin-free but layered code organization under livox_ros_driver/

d. Key technologies & libraries
- ROS (catkin, topic/launch/parameter server)
- Livox-SDK (device API)
- C++17 (or C++11)
- RapidJSON / RapidXML for config parsing
- FastCRC for integrity checks
- PCL / sensor_msgs/PointCloud2 for cloud formats

##### Elements
- Components: LiDAR, Hub, GPS, livox_ros_driver node (with sub‐components), ROS Core, clients
- Hardware (green)
- Driver internals (blue)
- ROS infrastructure (orange)
- Clients (purple)
- From hardware → comm module → parser → publishers → clients
- From GPS → timesync → timestamp adjuster
- From JSON files → parameter server → driver
- Clear labels for message types (PointCloud2, CustomPoint), topic names, ports/protocols

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Hardware Layer"
        LiDAR["Livox LiDAR"]:::hardware
        Hub["Livox Hub"]:::hardware
        GPS["GPS Receiver"]:::hardware
    end

    subgraph "Configuration Files"
        LivoxConfig["livox_lidar_config.json"]:::driver
        HubConfig["livox_hub_config.json"]:::driver
        RVizLidar["display_lidar_points.rviz"]:::driver
        RVizHub["display_hub_points.rviz"]:::driver
    end

    subgraph "Launch Files"
        LaunchLidar["livox_lidar.launch"]:::driver
        LaunchHub["livox_hub.launch"]:::driver
        LaunchLVX["lvx_to_rosbag.launch"]:::driver
    end

    ParamServer["ROS Parameter Server"]:::ros
    LivoxDriver["livox_ros_driver Node"]:::driver

    subgraph "Driver Internals"
        Comm["Comm Module"]:::driver
        CRC["CRC Checker"]:::driver
        ParserJSON["JSON Parser"]:::driver
        ParserXML["XML Parser"]:::driver
        UnpackerLidar["lds_lidar"]:::driver
        UnpackerHub["lds_hub"]:::driver
        UnpackerLVX["lds_lvx"]:::driver
        DataQueue["Data Queue Module"]:::driver
        DevControl["Device Control Module"]:::driver
        LVXHandler["LVX File Handler"]:::driver
        TimeSync["Timesync Module"]:::driver
        GPSIF["GPS Serial Interface"]:::driver
        ROSPub["ROS Publishers"]:::driver
        SDK["Livox-SDK"]:::external
    end

    subgraph "ROS Core"
        Topics["Topics & Message Bus"]:::ros
    end

    subgraph "Client Layer"
        RViz["RViz"]:::client
        Rosbag["rosbag record/playback"]:::client
        OtherNodes["Other ROS Nodes"]:::client
    end

    %% Relationships
    LivoxConfig -->|loads| ParamServer
    HubConfig -->|loads| ParamServer
    LaunchLidar -->|sets params| ParamServer
    LaunchHub -->|sets params| ParamServer
    LaunchLVX -->|sets params| ParamServer

    ParamServer -->|configures| LivoxDriver
    LivoxDriver -->|uses| SDK

    LiDAR -->|Ethernet/USB| Comm
    Hub -->|Ethernet| Comm
    Comm -->|raw data| CRC
    CRC -->|validated data| UnpackerLidar
    CRC -->|validated data| UnpackerHub
    DataQueue -->|queues| DevControl
    UnpackerLidar -->|frames| DataQueue
    UnpackerHub -->|frames| DataQueue
    LVXHandler -->|file data| UnpackerLVX
    UnpackerLVX -->|frames| DataQueue

    GPS -->|PPS/serial| GPSIF
    GPSIF -->|serial data| TimeSync
    TimeSync -->|timestamps| DataQueue

    DataQueue -->|packets| ROSPub
    ParserJSON -->|parses config| LivoxDriver
    ParserXML -->|parses config| LivoxDriver

    ROSPub -->|publishes PointCloud2/CustomMsg| Topics
    Topics --> RViz
    Topics --> Rosbag
    Topics --> OtherNodes

    %% Click Events
    click Comm "https://github.com/livox-sdk/livox_ros_driver/blob/master/livox_ros_driver/common/comm/comm_protocol.h"
    click CRC "https://github.com/livox-sdk/livox_ros_driver/blob/master/livox_ros_driver/common/FastCRC/FastCRC.h"
    click ParserJSON "https://github.com/livox-sdk/livox_ros_driver/tree/master/livox_ros_driver/common/rapidjson/"
    click ParserXML "https://github.com/livox-sdk/livox_ros_driver/tree/master/livox_ros_driver/common/rapidxml/"
    click LivoxConfig "https://github.com/livox-sdk/livox_ros_driver/blob/master/livox_ros_driver/config/livox_lidar_config.json"
    click HubConfig "https://github.com/livox-sdk/livox_ros_driver/blob/master/livox_ros_driver/config/livox_hub_config.json"
    click RVizLidar "https://github.com/livox-sdk/livox_ros_driver/blob/master/livox_ros_driver/config/display_lidar_points.rviz"
    click RVizHub "https://github.com/livox-sdk/livox_ros_driver/blob/master/livox_ros_driver/config/display_hub_points.rviz"
    click LaunchLidar "https://github.com/livox-sdk/livox_ros_driver/blob/master/livox_ros_driver/launch/livox_lidar.launch"
    click LaunchHub "https://github.com/livox-sdk/livox_ros_driver/blob/master/livox_ros_driver/launch/livox_hub.launch"
    click LaunchLVX "https://github.com/livox-sdk/livox_ros_driver/blob/master/livox_ros_driver/launch/lvx_to_rosbag.launch"
    click LivoxDriver "https://github.com/livox-sdk/livox_ros_driver/blob/master/livox_ros_driver/livox_ros_driver/livox_ros_driver.cpp"
    click UnpackerLidar "https://github.com/livox-sdk/livox_ros_driver/blob/master/livox_ros_driver/livox_ros_driver/lds_lidar.cpp"
    click UnpackerHub "https://github.com/livox-sdk/livox_ros_driver/blob/master/livox_ros_driver/livox_ros_driver/lds_hub.cpp"
    click UnpackerLVX "https://github.com/livox-sdk/livox_ros_driver/blob/master/livox_ros_driver/livox_ros_driver/lds_lvx.cpp"
    click DataQueue "https://github.com/livox-sdk/livox_ros_driver/blob/master/livox_ros_driver/livox_ros_driver/ldq.cpp"
    click DevControl "https://github.com/livox-sdk/livox_ros_driver/blob/master/livox_ros_driver/livox_ros_driver/lddc.cpp"
    click LVXHandler "https://github.com/livox-sdk/livox_ros_driver/blob/master/livox_ros_driver/livox_ros_driver/lvx_file.cpp"
    click TimeSync "https://github.com/livox-sdk/livox_ros_driver/blob/master/livox_ros_driver/timesync/timesync.cpp"
    click GPSIF "https://github.com/livox-sdk/livox_ros_driver/blob/master/livox_ros_driver/timesync/user_uart/user_uart.cpp"
    click Topics "https://github.com/livox-sdk/livox_ros_driver/blob/master/livox_ros_driver/msg/CustomMsg.msg"
    click Topics "https://github.com/livox-sdk/livox_ros_driver/blob/master/livox_ros_driver/msg/CustomPoint.msg"
    click SDK "https://github.com/livox-sdk/livox_ros_driver/blob/master/CMakeLists.txt"

    %% Styles
    classDef hardware fill:#aaffaa,stroke:#333,stroke-width:1px
    classDef driver fill:#aad4ff,stroke:#333,stroke-width:1px
    classDef ros fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef client fill:#e0aaff,stroke:#333,stroke-width:1px
    classDef external fill:#dddddd,stroke:#333,stroke-width:1px
```
