# livox-sdk/livox_apollo_driver architecture

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

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

## Overview

1. This repo is a Livox LiDAR adapter for Apollo, located as a self-contained module under `apollo/modules/drivers/livox`. Its job is to turn Livox raw sensor data into Apollo-standard point cloud messages.

2. The architectural boundary is between the Livox hardware/software stack and Apollo Cyber RT. Livox-specific communication stays inside this module; everything Apollo downstream sees is a standard `apollo::drivers::PointCloud` published on Apollo channels.

3. Runtime startup is Apollo-native: `launch/livox.launch` and `dag/livox.dag` define how the driver component is launched inside Cyber. The README shows it is started with `cyber_launch`, which means this module runs as part of the Apollo cyber runtime rather than as a standalone daemon.

4. The main control/config layer is `conf/livox_conf.pb.txt` plus `proto/config.proto`. That config describes whether the system uses a hub, the per-LiDAR `frame_id`, hub port, output channel name, fan setting, return mode, and optional broadcast code/SN. This config is what binds physical sensors to logical Apollo topics.

5. The core processing is in `driver/driver.cc`, `driver/hub_driver.cc`, and their headers. From the names and README, the driver layer encapsulates Livox SDK interaction and likely hides device-specific details behind a common driver interface.

6. `driver/driver_factory.h` suggests a factory/abstraction boundary for selecting driver implementations. In practice, the repo’s README says it currently only supports Livox Hub mode, so the hub-oriented driver path is the active architecture.

7. `driver/livox_driver_component.cc` is the Apollo Cyber component bridge. This is the integration point that connects the Livox driver to Apollo message publishing, so it is the key runtime boundary between sensor I/O and Apollo dataflow.

8. The data path is: Livox LiDAR(s) -> Livox Hub -> Livox SDK/driver -> Apollo point cloud conversion -> per-LiDAR point cloud channel. The output topics are explicitly per sensor, for example `/apollo/sensor/livox/front/center/PointCloud2`, `/apollo/sensor/livox/front/left/PointCloud2`, and similar channels for each configured lidar.

9. `params/livox_horizon_novatel_extrinsics_front_center.yaml` indicates calibration/extrinsic alignment is part of the module’s deployment model. That file is the boundary between raw sensor geometry and Apollo’s vehicle/world coordinate usage.

10. The install path is also part of the architecture: `apollo/docker/build/installers/install_livox_sdk.sh` installs the Livox SDK into Apollo’s docker environment before building. So the repo depends on Apollo’s dockerized dev environment and an external Livox SDK shared library.

11. `driver/driver_test.cc` provides a local verification path for the driver logic, while the Bazel `BUILD` files define how the module is compiled inside Apollo. That means the repo has both a runtime integration path and a lower-level driver test path.

12. In short, the repo is a thin Apollo integration layer around Livox hardware: configuration and calibration feed a hub-based driver, the driver converts Livox data into Apollo point clouds, and the Cyber component publishes those messages onto per-sensor Apollo topics.

Main entry points: [`apollo/modules/drivers/livox/driver/livox_driver_component.cc`](https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/driver/livox_driver_component.cc) (Driver component), [`apollo/modules/drivers/livox/driver/driver.cc`](https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/driver/driver.cc) (Base driver), [`apollo/modules/drivers/livox/driver/hub_driver.cc`](https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/driver/hub_driver.cc) (Hub driver), [`apollo/modules/drivers/livox/conf/livox_conf.pb.txt`](https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/conf/livox_conf.pb.txt) (Livox config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_runtime["Apollo runtime"]
  node_n_launch["Livox launch<br/>Apollo launch<br/>[livox.launch]"]
  node_n_dag["Livox DAG<br/>Cyber DAG<br/>[livox.dag]"]
  node_n_component["Driver component<br/>Cyber component"]
  node_n_component_header["Component API<br/>Component headers"]
end

subgraph group_g_driver["Driver core"]
  node_n_driver["Base driver<br/>Driver interface<br/>[driver.cc]"]
  node_n_hub_driver["Hub driver<br/>Hub-mode driver<br/>[hub_driver.cc]"]
  node_n_factory["Driver factory<br/>Driver selector<br/>[driver_factory.h]"]
  node_n_driver_header["Driver API<br/>Driver headers<br/>[driver.h]"]
  node_n_hub_header["Hub API<br/>Hub headers<br/>[hub_driver.h]"]
  node_n_build["Driver BUILD<br/>Bazel build"]
  node_n_test["Driver test<br/>Unit test<br/>[driver_test.cc]"]
end

subgraph group_g_config["Configuration"]
  node_n_conf["Livox config<br/>Runtime config<br/>[livox_conf.pb.txt]"]
  node_n_proto["Config proto<br/>Config schema<br/>[config.proto]"]
  node_n_proto_build["Proto BUILD<br/>Bazel build"]
end

subgraph group_g_deploy["Deployment"]
  node_n_install["SDK installer<br/>Docker install"]
end

subgraph group_g_calib["Calibration"]
  node_n_extrinsics["Front-center extrinsics<br/>Calibration yaml"]
end

node_n_launch -->|"starts"| node_n_dag
node_n_dag -->|"runs"| node_n_component
node_n_component -->|"uses"| node_n_driver
node_n_component -->|"binds"| node_n_hub_driver
node_n_driver -->|"selects"| node_n_factory
node_n_driver -->|"implements"| node_n_hub_driver
node_n_driver -->|"declares"| node_n_driver_header
node_n_hub_driver -->|"declares"| node_n_hub_header
node_n_component -->|"declares"| node_n_component_header
node_n_conf -->|"schema"| node_n_proto
node_n_conf -->|"configures"| node_n_component
node_n_conf -->|"configures"| node_n_hub_driver
node_n_component -->|"reads"| node_n_proto
node_n_install -->|"supplies SDK"| node_n_driver
node_n_build -->|"builds"| node_n_driver
node_n_build -->|"builds"| node_n_component
node_n_proto_build -->|"builds"| node_n_proto
node_n_extrinsics -->|"calibrates"| node_n_component
node_n_test -->|"verifies"| node_n_driver

click node_n_launch "https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/launch/livox.launch"
click node_n_dag "https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/dag/livox.dag"
click node_n_component "https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/driver/livox_driver_component.cc"
click node_n_driver "https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/driver/driver.cc"
click node_n_hub_driver "https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/driver/hub_driver.cc"
click node_n_factory "https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/driver/driver_factory.h"
click node_n_driver_header "https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/driver/driver.h"
click node_n_hub_header "https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/driver/hub_driver.h"
click node_n_component_header "https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/driver/livox_driver_component.h"
click node_n_conf "https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/conf/livox_conf.pb.txt"
click node_n_proto "https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/proto/config.proto"
click node_n_extrinsics "https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/params/livox_horizon_novatel_extrinsics_front_center.yaml"
click node_n_install "https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/docker/build/installers/install_livox_sdk.sh"
click node_n_build "https://github.com/livox-sdk/livox_apollo_driver/tree/master/apollo/modules/drivers/livox/driver/BUILD"
click node_n_proto_build "https://github.com/livox-sdk/livox_apollo_driver/tree/master/apollo/modules/drivers/livox/proto/BUILD"
click node_n_test "https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/driver/driver_test.cc"

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_n_launch,node_n_dag,node_n_component,node_n_component_header toneBlue
class node_n_driver,node_n_hub_driver,node_n_factory,node_n_driver_header,node_n_hub_header,node_n_build,node_n_test toneAmber
class node_n_conf,node_n_proto,node_n_proto_build toneMint
class node_n_install toneRose
class node_n_extrinsics toneIndigo
```

## Components

### Apollo runtime

Cyber launch and component wiring for the Livox adapter.

- [Livox launch](https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/launch/livox.launch): Apollo launch · Cyber launch entrypoint for starting the Livox module. · `apollo/modules/drivers/livox/launch/livox.launch`
- [Livox DAG](https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/dag/livox.dag): Cyber DAG · Component graph used by Apollo Cyber to run the driver. · `apollo/modules/drivers/livox/dag/livox.dag`
- [Driver component](https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/driver/livox_driver_component.cc): Cyber component · Apollo Cyber bridge between Livox driver logic and published point clouds. · `apollo/modules/drivers/livox/driver/livox_driver_component.cc`
- [Component API](https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/driver/livox_driver_component.h): Component headers · Cyber component declarations for the driver integration. · `apollo/modules/drivers/livox/driver/livox_driver_component.h`

### Driver core

Livox SDK interaction and point cloud translation logic.

- [Base driver](https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/driver/driver.cc): Driver interface · Common driver layer that wraps Livox SDK-facing behavior. · `apollo/modules/drivers/livox/driver/driver.cc`
- [Hub driver](https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/driver/hub_driver.cc): Hub-mode driver · Active Livox Hub-oriented implementation for sensor ingestion. · `apollo/modules/drivers/livox/driver/hub_driver.cc`
- [Driver factory](https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/driver/driver_factory.h): Driver selector · Abstraction boundary for choosing a driver implementation. · `apollo/modules/drivers/livox/driver/driver_factory.h`
- [Driver API](https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/driver/driver.h): Driver headers · Driver interfaces and declarations shared across implementations. · `apollo/modules/drivers/livox/driver/driver.h`
- [Hub API](https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/driver/hub_driver.h): Hub headers · Hub driver declarations and shared hub-specific structures. · `apollo/modules/drivers/livox/driver/hub_driver.h`
- [Driver BUILD](https://github.com/livox-sdk/livox_apollo_driver/tree/master/apollo/modules/drivers/livox/driver/BUILD): Bazel build · Build definition for compiling the Livox driver module in Apollo. · `apollo/modules/drivers/livox/driver/BUILD`
- [Driver test](https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/driver/driver_test.cc): Unit test · Local verification path for driver behavior. · `apollo/modules/drivers/livox/driver/driver_test.cc`

### Configuration

Runtime config and message schema that bind sensors to Apollo topics.

- [Livox config](https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/conf/livox_conf.pb.txt): Runtime config · Per-sensor and hub settings such as frame IDs, ports, return mode, and channel names. · `apollo/modules/drivers/livox/conf/livox_conf.pb.txt`
- [Config proto](https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/proto/config.proto): Config schema · Protobuf definition for Livox driver configuration. · `apollo/modules/drivers/livox/proto/config.proto`
- [Proto BUILD](https://github.com/livox-sdk/livox_apollo_driver/tree/master/apollo/modules/drivers/livox/proto/BUILD): Bazel build · Build definition for the configuration protobuf. · `apollo/modules/drivers/livox/proto/BUILD`

### Deployment

SDK installation into Apollo's docker build environment.

- [SDK installer](https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/docker/build/installers/install_livox_sdk.sh): Docker install · Build-time installer for the Livox SDK inside Apollo's docker environment. · `apollo/docker/build/installers/install_livox_sdk.sh`

### Calibration

Extrinsic alignment used to place sensor data in Apollo coordinates.

- [Front-center extrinsics](https://github.com/livox-sdk/livox_apollo_driver/blob/master/apollo/modules/drivers/livox/params/livox_horizon_novatel_extrinsics_front_center.yaml): Calibration yaml · Sensor-to-vehicle alignment used during deployment. · `apollo/modules/drivers/livox/params/livox_horizon_novatel_extrinsics_front_center.yaml`

## Connections

- Livox launch → Livox DAG: starts · Launch file activates the Cyber DAG.
- Livox DAG → Driver component: runs · DAG instantiates the Cyber component.
- Driver component → Base driver: uses · Component delegates sensor handling to the driver layer.
- Driver component → Hub driver: binds · Runtime path is hub-oriented in this repo.
- Base driver → Driver factory: selects · Factory boundary chooses driver implementation.
- Base driver → Hub driver: implements · Hub driver is the concrete driver path.
- Base driver → Driver API: declares · Header defines the driver interface.
- Hub driver → Hub API: declares · Header defines hub-driver specifics.
- Driver component → Component API: declares · Header defines the component interface.
- Livox config → Config proto: schema · Text config follows the protobuf schema.
- Livox config → Driver component: configures · Runtime settings drive publishing and sensor mapping.
- Livox config → Hub driver: configures · Hub mode, ports, return mode, and sensor binding are read here.
- Driver component → Config proto: reads · Component consumes structured configuration values.
- SDK installer → Base driver: supplies SDK · Installer makes the external Livox SDK available to the driver build/runtime.
- Driver BUILD → Base driver: builds · Bazel target compiles the driver module.
- Driver BUILD → Driver component: builds · Bazel target compiles the Cyber component.
- Proto BUILD → Config proto: builds · Bazel target compiles the config protobuf.
- Front-center extrinsics → Driver component: calibrates · Extrinsics align Livox points for Apollo usage.
- Driver test → Base driver: verifies · Unit tests cover core driver logic.