docs: add parameter tables generated from schemas per vendor and sens…

…or model (#195) * docs: create API reference page, link class/namespace/... references in navigation (#194) * docs: add API reference page and add things like class references to nav * Apply suggestions from code review Co-authored-by: David Wong <[email protected]> * docs: fix case style of API reference heading Signed-off-by: Max SCHMELLER <[email protected]> --------- Signed-off-by: Max SCHMELLER <[email protected]> Co-authored-by: David Wong <[email protected]> * chore(docs): add `mkdocs_macros.py` for schema table rendering * docs: add vendor pages for parameters * docs: add parameter pages for all sensors * chore(schema): restrict `sensor_model` parameter to only the sensor model in the current schema file * chore(docs): update requirements.txt to match Autoware * docs: add docs build instructions to readme * ci(pre-commit): autofix * chore(docs): make `include_refs` default * ci(pre-commit): autofix * chore(docs): remove empty about page as the index page already contains an about section * docs: deprecate old point types * docs: update support status for sensors * docs: re-arrange nav to reflect user needs better * docs: document common parameters * docs: revert status of currently not fully tested sensors * docs: add figures and more detailed explanation to the scan angle section for Hesai * English lesson Co-authored-by: David Wong <[email protected]> * chore: apply suggested phrasing changes Signed-off-by: Max SCHMELLER <[email protected]> * chore: move Hesai-specific parameters to Hesai schema Signed-off-by: Max SCHMELLER <[email protected]> * docs: add parameter table for Hesai Signed-off-by: Max SCHMELLER <[email protected]> --------- Signed-off-by: Max SCHMELLER <[email protected]> Co-authored-by: David Wong <[email protected]> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
tier4 · Nov 11, 2024 · 7c2f90b · 7c2f90b
1 parent 949ab05
commit 7c2f90b
Show file tree

Hide file tree

Showing 47 changed files with 570 additions and 257 deletions.
diff --git a/README.md b/README.md
@@ -15,7 +15,6 @@ Nebula works with ROS 2 and is the recommended sensor driver for the [Autoware](
 We recommend you get started with the [Nebula Documention](https://tier4.github.io/nebula/).
 Here you will find information about the background of the project, how to install and use with ROS 2, and also how to add new sensors to the Nebula driver.
 
-- [About Nebula](https://tier4.github.io/nebula)
 - [Design](https://tier4.github.io/nebula/design)
 - [Supported Sensors](https://tier4.github.io/nebula/supported_sensors)
 - [Installation](https://tier4.github.io/nebula/installation)
@@ -25,6 +24,8 @@ Here you will find information about the background of the project, how to insta
 - [Contributing](https://tier4.github.io/nebula/contribute)
 - [Tutorials](https://tier4.github.io/nebula/tutorials)
 
+To build and serve the documentation locally, see the build steps further below.
+
 ## Quick start
 
 Nebula builds with ROS 2 Galactic and Humble.
@@ -46,6 +47,14 @@ rosdep install --from-paths . --ignore-src -y -r
 colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release -DCMAKE_EXPORT_COMPILE_COMMANDS=1
 ```
 
+_(optional)_ To build and serve the documentation, run the following commands in your workspace:
+
+```shell
+cd src
+pip3 install -r docs/requirements.txt
+mkdocs serve
+```
+
 To launch Nebula as a ROS 2 node with default parameters for your sensor model:
 
 ```bash

diff --git a/docs/about.md b/docs/about.md
diff --git a/docs/index.md b/docs/index.md
@@ -15,8 +15,6 @@ Nebula works with ROS 2 and is the recommended sensor driver for the [Autoware](
 - A driver solution to suit current Autoware requirements
   - Interfaces and pointcloud type updates made in unison with Autoware developments
 
-For more information, please refer to [About Nebula](about.md).
-
 ## Getting started
 
 - [Installation](installation.md)

diff --git a/docs/parameters.md b/docs/parameters.md
@@ -1,123 +1,96 @@
-# ROS parameters for supported sensors
-
-> **Note**
->
-> The information on this page may be out of date.
-> Please refer to the configuration in the relevant `*sensor_model*.param.yaml` file for you sensor, to confirm what parameters are available,
-
-## 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                                                                |
-| udp_only                       | bool   | False           | True, False       | Use UDP protocol only (settings synchronization and diagnostics publishing are disabled) |
-
-### 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                                                                            |
-| udp_only        | bool   | False           | True, False       | Use UDP protocol only (settings synchronization and diagnostics publishing are disabled) |
-
-### 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                 |
+# Common Parameters
+
+- Sensor-specific parameters are defined in `nebula_ros/schema/<sensor_model>.schema.json` and are described in the sensor-specific parameter pages in this tab.
+- Vendor-specific parameters can be found on the vendor pages in this tab.
+- Parameters common to all or most sensors, regardless of vendor, are explained on this page.
+
+## Connection Mode Settings
+
+### `launch_hw`
+
+Whether to connect to a real sensor or to accept replayed packets from a topic like `/<vendor>_packets` or `/nebula_packets`.
+These behaviors are mutually exclusive: replayed packets are only accepted if no sensor is connected, and packets are only published on the above topics if a sensor is connected.
+If enabled, Nebula connects to the sensor over UDP/TCP/CAN/etc. and publishes packets on the above topics but does not subscribe to them.
+If disabled, Nebula subscribes to packets on `/<vendor>_packets` or `/nebula_packets` but does not publish packets on these topics.
+
+### `setup_sensor`
+
+_Only applies if `launch_hw = true`_
+
+Whether to set up the sensor with the values from Nebula's parameters or to just check and warn if they are different.
+If enabled, Nebula checks current sensor configuration state, and updates the sensor's parameters where they differ from Nebula's.
+If disabled, the current configuration state is downloaded from the sensor, and Nebula warns if its parameters are different than the ones from the sensor but no sensor settings are changed.
+
+## Network Settings
+
+### IP-Based Sensors
+
+#### `sensor_ip`
+
+This parameter is mainly used for TCP communication, such as diagnostics and for setting parameters.
+TCP connections will be made to `sensor_ip`, and if `multicast_ip` is supported and set to a multicast group,
+Nebula will drop all UDP traffic received via multicast that was not sent from `sensor_ip`.
+
+#### `host_ip`
+
+UDP sockets are bound to this IP, and for sensors supporting it, Nebula will change the sensor's host IP setting to this address.
+Set this parameter to the IP address of your host.
+
+!!! warning
+
+    This parameter can be set to `255.255.255.255` to receive packets on any interface. However, this will set the sensor to use IP broadcast.
+    IP multicast may also break with this setting, as the UDP socket cannot determine the correct network interface.
+
+#### `multicast_ip`
+
+For sensors with IP multicast support in Nebula, `multicast_ip` can be set to an address in `224.0.0.0/28` (the range from `224.0.0.0` to `239.255.255.255`).
+Nebula will then configure the sensor to send its data to that group, and Nebula will join that group and accept only data sent by `sensor_ip`.
+Set this parameter to `""` to disable multicast.
+
+#### `data_port`, `gnss_port`, etc
+
+The ports at which data streams from the sensor arrive. If multiple sensors are connected to one machine, make sure that sensor data streams are separated by setting these ports to different values for each sensor.
+These settings have to be mirrored in the sensor's settings for sensors where Nebula cannot set them automatically (e.g. Robosense).
+
+### CAN-FD-Based Sensors
+
+#### `interface`
+
+The name of the CAN interface the sensor is connected to. Find available interfaces via `ip link show type can`.
+
+#### `filters`
+
+A string expressing the filters used to accept/reject arriving CAN frames. See [man candump](https://manpages.ubuntu.com/manpages/jammy/man1/candump.1.html) for syntax information.
+You can install `candump` via `apt install can-utils`.
+
+## ROS-Specific Settings
+
+### `frame_id`
+
+The TF2 frame ID used for the published point clouds, objects, etc.
+
+## LiDAR-Specific Settings
+
+These settings are common to most LiDARs, but the ranges or options supported by specific sensor models can vary. Please refer to the individual sensor parameter pages for details.
+
+### `rotation_speed`
+
+The revolutions per minute (RPM) setting for the sensor's motor (mechanical LiDARs only). To calculate the resulting frame rate in frames per second (FPS), use `FPS = RPM / 60`.
+
+### `min_range`
+
+The minimum distance in meters for any point. Points closer than this are filtered out.
+
+### `max_range`
+
+The maximum distance in meters for any point. Points farther away than this are filtered out.
+
+### `return_mode`
+
+Each laser beam can result in multiple returns: if there is a semi-transparent object in front of a solid one, a first weak return, and a strong last return will be reported.
+Depending on perception requirements, one might be interested in specific returns, e.g. the strongest and last returns, or only the first return.
+This parameter is used to set this preference.
+
+### `dual_return_distance_threshold`
+
+For multiple returns that are close together, the points will be fused into one if they are below this threshold (in meters).
diff --git a/docs/parameters/vendors/continental/ars548.md b/docs/parameters/vendors/continental/ars548.md
@@ -0,0 +1 @@
+{{ json_to_markdown("nebula_ros/schema/ARS548.schema.json") }}
diff --git a/docs/parameters/vendors/continental/common.md b/docs/parameters/vendors/continental/common.md
@@ -0,0 +1 @@
+{{ json_to_markdown("nebula_ros/schema/sub/radar_continental.json", ["definitions"], True) }}
diff --git a/docs/parameters/vendors/continental/srr520.md b/docs/parameters/vendors/continental/srr520.md
@@ -0,0 +1 @@
+{{ json_to_markdown("nebula_ros/schema/SRR520.schema.json") }}
diff --git a/docs/parameters/vendors/hesai/at128.md b/docs/parameters/vendors/hesai/at128.md
@@ -0,0 +1 @@
+{{ json_to_markdown("nebula_ros/schema/PandarAT128.schema.json") }}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		{{ json_to_markdown("nebula_ros/schema/ARS548.schema.json") }}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		{{ json_to_markdown("nebula_ros/schema/sub/radar_continental.json", ["definitions"], True) }}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		{{ json_to_markdown("nebula_ros/schema/PandarAT128.schema.json") }}