/nebula

Primary LanguageC++Apache License 2.0Apache-2.0

Nebula Sensor Driver

Nebula is a sensor driver platform that is designed to provide a unified framework for as wide a variety of devices as possible. While it primarily targets Ethernet-based LiDAR sensors, it aims to be easily extendable to support new sensors and interfaces. Nebula provides the following features:

  • Support for Velodyne and Hesai sensors, with other LiDAR vendor support under development
  • ROS 2 interface implementations
  • TCP/IP and UDP communication implementations
  • Abstraction of sensor decoders and hardware interfaces available as libraries
  • Handling of standard LiDAR functionality, including but not limited to:
    • Configuration of communication settings such as sensor and host IP addresses and communication ports
    • Configuration of scan speed, synchronization settings, scan phase, and field of view
    • Receiving and conversion of UDP packet data into point clouds in Cartesian co-ordinates
    • Receiving and interpretation of diagnostics information from the sensor
    • Support for multiple return modes and labelling of return types for each point

With a rapidly increasing number of sensor types and models becoming available, and varying levels of vendor and third-party driver support, Nebula creates a centralized driver methodology. We hope that this project will be used to facilitate active collaboration and efficiency in development projects by providing a platform that reduces the need to re-implement and maintain many different sensor drivers. Contributions to extend the supported devices and features of Nebula are always welcome.

How to build

Nebula builds on ROS Galactic and Humble.

Note

A TCP enabled version of ROS' Transport Driver is required to use Nebula. It is installed automatically into your workspace using the below commands. However, if you already have ROS transport driver binaries installed, you will have to uninstall them to avoid conflicts (replace humble with your ROS distribution): sudo apt remove ros-humble-udp-driver ros-humble-io-context

To build Nebula run the following commands in your workspace:

# In workspace
mkdir src
git clone https://github.com/tier4/nebula.git src
# Import dependencies
vcs import src < src/build_depends.repos
rosdep install --from-paths src --ignore-src -y -r
# Build Nebula
colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release

How to run tests

Run tests:

colcon test --event-handlers console_cohesion+ --packages-above nebula_common

Show results:

colcon test-result --all

Generic launch file

You can easily run the sensor hardware interface, the sensor hardware monitor and sensor driver using (e.g. Pandar64):

ros2 launch nebula_ros nebula_launch.py sensor_model:=Pandar64

If you don't want to launch the hardware (i.e. when you are working from a rosbag), set the launch_hw flag to false:

ros2 launch nebula_ros nebula_launch.py sensor_model:=Pandar64 launch_hw:=false

If you don't want the hardware driver to perform the sensor configuration communication (i.e. limited number of connections) set the setup_sensor flag to false:

ros2 launch nebula_ros nebula_launch.py sensor_model:=Pandar64 setup_sensor:=false

You should ideally provide a config file for your specific sensor, but default ones are provided nebula_drivers/config:

ros2 launch nebula_ros nebula_launch.py sensor_model:=Pandar64 config_file:=your_sensor.yaml

Supported sensors

Supported models, where sensor_model is the ROS param to be used at launch:

Manufacturer Model sensor_model Configuration file Test status
HESAI Pandar 64 Pandar64 Pandar64.yaml ✔️
HESAI Pandar 40P Pandar40P Pandar40P.yaml ✔️
HESAI Pandar XT32 PandarXT32 PandarXT32.yaml ✔️
HESAI Pandar XT32M PandarXT32M PandarXT32M.yaml ⚠️
HESAI Pandar QT64 PandarQT64 PandarQT64.yaml ✔️
HESAI Pandar QT128 PandarQT128 PandarQT128.yaml ⚠️
HESAI Pandar AT128 PandarAT128 PandarAT128.yaml ✔️*
HESAI Pandar 128E4X Pandar128E4X Pandar128E4X.yaml ⚠️
Velodyne VLP-16 VLP16 VLP16.yaml ⚠️
Velodyne VLP-16-HiRes VLP16
Velodyne VLP-32 VLP32 VLP32.yaml ⚠️
Velodyne VLS-128 VLS128 VLS128.yaml ⚠️
Continental ARS548 ARS548 ARS548.yaml ⚠️

Test status:
✔️: complete
⚠️: some functionality yet to be tested
❌: untested
*: AT128 needs software version 3.50.8 or newer for the scan_angle setting to work correctly.

ROS parameters

Common ROS parameters

Parameters shared by all supported models:

Parameter Type Default Accepted values Description
sensor_model string See supported models
return_mode string See supported return modes
frame_id string Sensor dependent ROS frame ID
scan_phase double 0.0 degrees [0.0, 360.0] Scan start angle

Hesai specific parameters

Supported return modes per model

Sensor model return_mode Mode
Pandar XT32M Last Single
Pandar XT32M Strongest Single
Pandar XT32M LastStrongest Dual
Pandar XT32M First Single
Pandar XT32M LastFirst Dual
Pandar XT32M FirstStrongest Dual
Pandar XT32M Dual Dual
--- --- ---
Pandar AT128 Last Single
Pandar AT128 Strongest Single
Pandar AT128 LastStrongest Dual
Pandar AT128 First Single
Pandar AT128 LastFirst Dual
Pandar AT128 FirstStrongest Dual
Pandar AT128 Dual Dual
--- --- ---
Pandar QT128 Last Single
Pandar QT128 Strongest Single
Pandar QT128 LastStrongest Dual
Pandar QT128 First Single
Pandar QT128 LastFirst Dual
Pandar QT128 FirstStrongest Dual
Pandar QT128 Dual Dual
--- --- ---
Pandar QT64 Last Single
Pandar QT64 Dual Dual
Pandar QT64 First Single
--- --- ---
Pandar 40P Last Single
Pandar 40P Strongest Single
Pandar 40P Dual Dual
--- --- ---
Pandar 64 Last Single
Pandar 64 Strongest Single
Pandar 64 Dual Dual

Hardware interface parameters

Parameter Type Default Accepted values Description
frame_id string hesai ROS frame ID
sensor_ip string 192.168.1.201 Sensor IP
host_ip string 255.255.255.255 Host IP
data_port uint16 2368 Sensor port
gnss_port uint16 2369 GNSS port
frequency_ms uint16 100 milliseconds, > 0 Time per scan
packet_mtu_size uint16 1500 Packet MTU size
rotation_speed uint16 600 Rotation speed
cloud_min_angle uint16 0 degrees [0, 360] FoV start angle
cloud_max_angle uint16 359 degrees [0, 360] FoV end angle
dual_return_distance_threshold double 0.1 Dual return distance threshold
diag_span uint16 1000 milliseconds, > 0 Diagnostic span
setup_sensor bool True True, False Configure sensor settings

Driver parameters

Parameter Type Default Accepted values Description
frame_id string hesai ROS frame ID
calibration_file string LiDAR calibration file
correction_file string LiDAR correction file

Velodyne specific parameters

Supported return modes

return_mode Mode
SingleFirst Single (First)
SingleStrongest Single (Strongest)
SingleLast Single (Last)
Dual Dual

Hardware interface parameters

Parameter Type Default Accepted values Description
frame_id string velodyne ROS frame ID
sensor_ip string 192.168.1.201 Sensor IP
host_ip string 255.255.255.255 Host IP
data_port uint16 2368 Sensor port
gnss_port uint16 2369 GNSS port
frequency_ms uint16 100 milliseconds, > 0 Time per scan
packet_mtu_size uint16 1500 Packet MTU size
cloud_min_angle uint16 0 degrees [0, 360] FoV start angle
cloud_max_angle uint16 359 degrees [0, 360] FoV end angle

Driver parameters

Parameter Type Default Accepted values Description
frame_id string velodyne ROS frame ID
calibration_file string LiDAR calibration file
min_range double 0.3 meters, >= 0.3 Minimum point range published
max_range double 300.0 meters, <= 300.0 Maximum point range published
cloud_min_angle uint16 0 degrees [0, 360] FoV start angle
cloud_max_angle uint16 359 degrees [0, 360] FoV end angle

Software design overview

DriverOrganization

Hesai Sensor Setup

New Hesai sensors do not provide a Web UI to verify and set up the sensor parameters. Instead, these offer a TCP-based protocol to obtain and set the configuration. Nebula sets these sensors at launch. However, settings such as Destination IP, Sensor IP, IP Mask, and Data Port might cause undesired sensor functioning if the driver gets mistakenly launched with inappropriate values. To overcome this problem, Nebula provides an additional setup script for these settings to avoid such scenarios.

The script requires the installation of dependencies via pip:

$ pip3 install scripts/requirements.txt # first-time setup

Once the dependencies are installed, the setup script can be invoked using the following command:

$ python3 scripts/hesai_config --sensor-ip X.X.X.X

To set the parameters, please use the corresponding arguments as defined below:

usage: hesai_config.py [-h] --sensor-ip SENSOR_IP [--destination-ip DESTINATION_IP]
                       [--data-port DATA_PORT] [--new-sensor-ip NEW_SENSOR_IP] [--mask MASK]

options:
  -h, --help            Show this help message and exit
  --sensor-ip SENSOR_IP
                        The current sensor IP address
  --destination-ip DESTINATION_IP
                        Change the current destination IP address to the given one
  --data-port DATA_PORT
                        Change the current destination LiDAR data port to the given one
  --new-sensor-ip NEW_SENSOR_IP
                        Change the current sensor IP address to the given one
  --mask MASK           Change the current net mask to the given one. You can pass it in either a
                        CIDR notation or dotted-decimal notation.

How to evaluate performance

You can evaluate Nebula performance on a given rosbag and sensor model using the below tools. The profiling runner is most accurate when assigning isolated cores via the -c <core_id>. CPU frequencies are locked/unlocked automatically by the runner to increase repeatability.

Run profiling for each version you want to compare:

./scripts/profiling_runner.bash baseline -m Pandar64 -b ~/my_rosbag -c 2 -t 20 -n 3
git checkout my_improved_branch
./scripts/profiling_runner.bash improved -m Pandar64 -b ~/my_rosbag -c 2 -t 20 -n 3

Show results:

pip3 install scripts/requirements.txt  # first-time setup
python3 scripts/plot_times.py baseline improved