Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: readme update #28

Merged
merged 11 commits into from
Jul 11, 2023
Merged

docs: readme update #28

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
19a1053
docs: update README
drwnz Jun 14, 2023
14cd434
docs: make return mode table consistent
drwnz Jun 14, 2023
b1210e3
style(pre-commit): autofix
drwnz Jun 14, 2023
c3e8e29
add 128E4X|40P|QT64 config file
tokuda99 Jun 27, 2023
6869290
fix README
tokuda99 Jun 27, 2023
7f5c086
Add Intro to README
amc-nu Jun 28, 2023
5e82c3b
docs: edit README
drwnz Jul 5, 2023
3790310
docs: README minor changes
drwnz Jul 5, 2023
89449e8
docs: fix typo
drwnz Jul 10, 2023
92f7dc5
docs: improvements to README
drwnz Jul 10, 2023
0f604aa
fix: spelling for ROS 2
drwnz Jul 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
267 changes: 141 additions & 126 deletions README.md
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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