Skip to content

Commit

Permalink
docs: readme update (#28)
Browse files Browse the repository at this point in the history 
* 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 <drwnz@users.noreply.github.com>
Co-authored-by: tokuda99 <kosuke.tokuda@tier4.jp>
Co-authored-by: Abraham Monrroy Cano <abraham.monrroy@gmail.com>
  • Loading branch information
@drwnz @tokuda99 @amc-nu
4 people authored Jul 11, 2023
1 parent c90e808 commit a3d2788
Show file tree
Hide file tree
Showing 4 changed files with 198 additions and 126 deletions.
267 changes: 141 additions & 126 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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:

Expand All @@ -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 |
Expand Down Expand Up @@ -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)
19 changes: 19 additions & 0 deletions nebula_ros/config/hesai/Pandar128E4X.yaml
View file
Original file line number Diff line number Diff line change
@@ -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
19 changes: 19 additions & 0 deletions nebula_ros/config/hesai/Pandar40P.yaml
View file
Original file line number Diff line number Diff line change
@@ -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
19 changes: 19 additions & 0 deletions nebula_ros/config/hesai/PandarQT64.yaml
View file
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit a3d2788

Please sign in to comment.