From a3d27889cb0bc9a58ce2e5e79720b12325b47f19 Mon Sep 17 00:00:00 2001 From: David Wong <33114676+drwnz@users.noreply.github.com> Date: Tue, 11 Jul 2023 12:05:35 +0900 Subject: [PATCH] docs: readme update (#28) * docs: update README * docs: make return mode table consistent * style(pre-commit): autofix * add 128E4X|40P|QT64 config file * fix README * Add Intro to README * docs: edit README * docs: README minor changes * docs: fix typo * docs: improvements to README * fix: spelling for ROS 2 --------- Co-authored-by: drwnz Co-authored-by: tokuda99 Co-authored-by: Abraham Monrroy Cano --- README.md | 267 ++++++++++++---------- nebula_ros/config/hesai/Pandar128E4X.yaml | 19 ++ nebula_ros/config/hesai/Pandar40P.yaml | 19 ++ nebula_ros/config/hesai/PandarQT64.yaml | 19 ++ 4 files changed, 198 insertions(+), 126 deletions(-) create mode 100644 nebula_ros/config/hesai/Pandar128E4X.yaml create mode 100644 nebula_ros/config/hesai/Pandar40P.yaml create mode 100644 nebula_ros/config/hesai/PandarQT64.yaml diff --git a/README.md b/README.md index 103294d2c..7a70659e9 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,39 @@ -# Nebula Lidar Driver +# Nebula Sensor Driver -## How to build - -Builds on ROS Galactic and Humble. - -A [TCP enabled version of ROS' Transport Driver](https://github.com/MapIV/transport_drivers/tree/tcp) is required to use Nebula. You can install it manually or pull it inside this repository using vcs: - -`vcs import . < build_depends.repos` +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: +- ROS 2 interface implementations +- Abstraction of sensor decoders and hardware interfaces available as libraries +- TCP/IP and UDP communication implementations -Once you have either installed or added the source of the above Transport Drivers package to your workspace, be sure to install dependencies using `rosdep`: +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. -`rosdep install --from-paths src --ignore-src -y -r` -Then compile with colcon, optionally enabling symlink: +## How to build -`colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release` +Nebula builds on ROS Galactic and Humble. + +> **Note** +> +> A [TCP enabled version of ROS' Transport Driver](https://github.com/MapIV/transport_drivers/tree/tcp) 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: + +```bash +# 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 +## How to run tests Run tests: @@ -30,42 +47,74 @@ Show results: colcon test-result --all ``` -## Generic Launch File +## 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` +``` +ros2 launch nebula_ros nebula_launch.py sensor_model:=Pandar64 +``` -If you don't want to launch the hardware (i.e. working on rosbag) set the `launch_hw` flag to false: +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` +``` +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` +``` +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` +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` +``` +ros2 launch nebula_ros nebula_launch.py sensor_model:=Pandar64 config_file:=your_sensor.yaml +``` -## Hesai LiDARs +## Supported sensors Supported models, where sensor_model is the ROS param to be used at launch: -| Model | sensor_model | -| ------------- | ------------ | -| Pandar 64 | Pandar64 | -| Pandar 40P | Pandar40P | -| Pandar XT32 | PandarXT32 | -| Pandar XT32M | PandarXT32M | -| Pandar QT64 | PandarQT64 | -| Pandar QT128 | PandarQT128 | -| Pandar AT128 | PandarAT128 | -| Pandar 128E4X | Pandar128E4X | +| Manufacturer | Model | sensor_model | Configuration file | Test status | +| ------------ | ------------- | ------------ | ------------------ | ----------- | +| HESAI | Pandar 64 | Pandar64 | Pandar64.yaml | :heavy_check_mark: | +| HESAI | Pandar 40P | Pandar40P | Pandar40P.yaml | :heavy_check_mark: | +| HESAI | Pandar XT32 | PandarXT32 | PandarXT32.yaml | :heavy_check_mark: | +| HESAI | Pandar XT32M | PandarXT32M | PandarXT32M.yaml | :warning: | +| HESAI | Pandar QT64 | PandarQT64 | PandarQT64.yaml | :heavy_check_mark: | +| HESAI | Pandar QT128 | PandarQT128 | PandarQT128.yaml | :warning: | +| HESAI | Pandar AT128 | PandarAT128 | PandarAT128.yaml | :heavy_check_mark: | +| HESAI | Pandar 128E4X | Pandar128E4X | Pandar128E4X.yaml | :warning: | +| Velodyne | VLP-16 | VLP16 | VLP16.yaml | :warning: | +| Velodyne | VLP-16-HiRes | VLP16 | | :x: | +| Velodyne | VLP-32 | VLP32 | VLP32.yaml | :warning: | +| Velodyne | VLS-128 | VLS128 | VLS128.yaml | :warning: | -Supported return modes per model: +Test status:\ +:heavy_check_mark:: complete\ +:warning:: some functionality yet to be tested\ +:x: : untested -| Sensor Model | return_mode | type | +## 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 | @@ -103,100 +152,66 @@ Supported return modes per model: | Pandar 64 | Strongest | Single | | Pandar 64 | Dual | Dual | -Common ROS params: - -| Parameter | Type | Default | Accepted Values | Description | -| ------------ | ------ | ------- | -------------------------- | ---------------- | -| sensor_model | string | | See supported models | | -| return_mode | string | | See supported return modes | | -| frame_id | string | pandar | | ROS frame ID | -| scan_phase | double | 0 | degrees [0, 360[ | Scan start angle | - -### Hesai Hardware Interface - -Launches the UDP hardware connection to a live sensor and publishes HesaiScan messages. E.g.: -`ros2 launch nebula_ros hesai_hw_interface.xml sensor_model:=Pandar40P return_mode:=Dual` -Unique params: - -| Parameter | Type | Default | Accepted Values | Description | -| --------------- | ------ | ----------- | ----------------- | --------------- | -| sensor_ip | string | 192.168.0.1 | | Sensor IP | -| host_ip | string | 192.168.0.1 | | 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 | - -### Hesai Driver - -Launches the hesai driver which subscribes to HesaiScan messages and converts them to PointCloud2. E.g.: -`ros2 launch nebula_ros hesai_driver.xml sensor_model:=Pandar40P return_mode:=Dual` -Unique params: - -| Parameter | Type | Default | Accepted Values | Description | +#### 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 | +| rotation_speed | uint16 | 600 | | Rotation speed | +| cloud_min_angle | uint16 | 0 | degrees [0, 360] | FoV start angle | +| cloud_max_angle | uint16 | 360 | 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 | - -## Velodyne LiDARs - -| Model | sensor_model | Config | -| --------------------- | ------------ | ------------------ | -| VLP-16 | VLP16 | VLP16.yaml | -| VLP-16-HiRes | VLP16 | VLP16_hires.yaml | -| VLP-32 | VLP32 | VLP32.yaml | -| VLS-128 (Alpha Prime) | HDL64 | VLS128.yaml | -| | | | -| Untested: | | | -| HDL-32 | PandarQT64 | HDL32.yaml | -| HDL-64E (default) | HDL64 | HDL64e_utexas.yaml | -| HDL-64E S2 | HDL64 | HDL64e_s2.yaml | -| HDL-64E S3 | HDL64 | HDL64e_s3.yaml | - -Supported return modes: - -| Mode | return_mode | -| ------------------ | --------------- | -| Single (First) | SingleFirst | -| Single (Strongest) | SingleStrongest | -| Single (Last) | SingleLast | -| Dual | Dual | - -Common ROS params: - -| Parameter | Type | Default | Accepted Values | Description | -| ------------ | ------ | ------- | -------------------------- | ---------------- | -| sensor_model | string | | See supported models | | -| return_mode | string | | See supported return modes | | -| frame_id | string | pandar | | ROS frame ID | -| scan_phase | double | 0 | degrees [0, 360[ | Scan start angle | - -### Velodyne Hardware Interface - -Launches the UDP hardware connection to a live sensor and publishes VelodyneScan messages. E.g.: -`ros2 launch nebula_ros velodyne_hw_interface.xml sensor_model:=VLS128 return_mode:=Dual` -Unique params: - -| Parameter | Type | Default | Accepted Values | Description | -| --------------- | ------ | ----------- | --------------- | --------------- | -| sensor_ip | string | 192.168.0.1 | | Sensor IP | -| data_port | uint16 | 2368 | | Sensor port | -| gnss_port | uint16 | 2369 | | GNSS port | -| frequency_ms | uint16 | 100 | ms, > 0 | Time per scan | -| packet_mtu_size | uint16 | 1500 | | Packet MTU size | - -### Velodyne Driver - -Launches the Velodyne driver which subscribes to VelodyneScan messages and converts them to PointCloud2. E.g.: -`ros2 launch nebula_ros velodyne_driver.xml sensor_model:=VLS128 return_mode:=Dual` -Unique params: - -| Parameter | Type | Default | Accepted Values | Description | -| ---------------- | ------ | ------- | ---------------- | --------------------------------------- | -| calibration_file | string | | | LiDAR calibration file | -| min_range | double | 0.3 | meters, >= 0.3 | Minimum point range published | -| max_range | double | 300 | meters, <= 300 | Maximum point range published | -| view_width | double | 360 | degrees ]0, 360] | Horizontal FOV centered at `scan_phase` | - -## Diagrams +| 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 | + +#### 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 | +| view_width | double | 360.0 | degrees [0.0, 360.0] | Horizontal FOV centered at `scan_phase` | + +## Software design overview ![DriverOrganization](docs/diagram.png) diff --git a/nebula_ros/config/hesai/Pandar128E4X.yaml b/nebula_ros/config/hesai/Pandar128E4X.yaml new file mode 100644 index 000000000..b4f5df758 --- /dev/null +++ b/nebula_ros/config/hesai/Pandar128E4X.yaml @@ -0,0 +1,19 @@ +/**: + ros__parameters: + sensor_model: "Pandar128E4X" # See readme for supported models + sensor_ip: "192.168.1.201" # Lidar Sensor IP + host_ip: "255.255.255.255" # Broadcast IP from Sensor + frame_id: "hesai" + data_port: 2368 # LiDAR Data Port + gnss_port: 10110 # LiDAR GNSS Port + return_mode: "Dual" # See readme for supported return modes + scan_phase: 0.0 # Angle where scans begin (degrees, [0.,360.] + packet_mtu_size: 1500 # Packet MTU size + rotation_speed: 600 # Motor RPM, the sensor's internal spin rate. + cloud_min_angle: 0 # Field of View, start degrees. + cloud_max_angle: 360 # Field of View, end degrees. + diag_span: 1000 # milliseconds + calibration_file: "./install/nebula_decoders/share/nebula_decoders/calibration/hesai/Pandar128E4X.csv" + setup_sensor: True + + online: True \ No newline at end of file diff --git a/nebula_ros/config/hesai/Pandar40P.yaml b/nebula_ros/config/hesai/Pandar40P.yaml new file mode 100644 index 000000000..3b457f573 --- /dev/null +++ b/nebula_ros/config/hesai/Pandar40P.yaml @@ -0,0 +1,19 @@ +/**: + ros__parameters: + sensor_model: "Pandar40P" # See readme for supported models + sensor_ip: "192.168.1.201" # Lidar Sensor IP + host_ip: "255.255.255.255" # Broadcast IP from Sensor + frame_id: "hesai" + data_port: 2368 # LiDAR Data Port + gnss_port: 10110 # LiDAR GNSS Port + return_mode: "Dual" # See readme for supported return modes + scan_phase: 0.0 # Angle where scans begin (degrees, [0.,360.] + packet_mtu_size: 1500 # Packet MTU size + rotation_speed: 600 # Motor RPM, the sensor's internal spin rate. + cloud_min_angle: 0 # Field of View, start degrees. + cloud_max_angle: 360 # Field of View, end degrees. + diag_span: 1000 # milliseconds + calibration_file: "./install/nebula_decoders/share/nebula_decoders/calibration/hesai/Pandar40P.csv" + setup_sensor: True + + online: True diff --git a/nebula_ros/config/hesai/PandarQT64.yaml b/nebula_ros/config/hesai/PandarQT64.yaml new file mode 100644 index 000000000..b2caccca8 --- /dev/null +++ b/nebula_ros/config/hesai/PandarQT64.yaml @@ -0,0 +1,19 @@ +/**: + ros__parameters: + sensor_model: "PandarQT64" # See readme for supported models + sensor_ip: "192.168.1.201" # Lidar Sensor IP + host_ip: "255.255.255.255" # Broadcast IP from Sensor + frame_id: "hesai" + data_port: 2368 # LiDAR Data Port + gnss_port: 10110 # LiDAR GNSS Port + return_mode: "Dual" # See readme for supported return modes + scan_phase: 0.0 # Angle where scans begin (degrees, [0.,360.] + packet_mtu_size: 1500 # Packet MTU size + rotation_speed: 600 # Motor RPM, the sensor's internal spin rate. + cloud_min_angle: 0 # Field of View, start degrees. + cloud_max_angle: 360 # Field of View, end degrees. + diag_span: 1000 # milliseconds + calibration_file: "./install/nebula_decoders/share/nebula_decoders/calibration/hesai/PandarQT64.csv" + setup_sensor: True + + online: True \ No newline at end of file