docs: document common parameters

docs/parameters.md

@@ -1,7 +1,96 @@
 # Common Parameters
 
-Parameters common to all or most sensors, regardless of vendor, are explained on this page.
+- 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.
 
-Vendor-specific parameters can be found on the vendor pages in this tab.
+## Connection Mode Settings
 
-Sensor-specific parameters are defined in `nebua_ros/schema/<sensor_model>.schema.json` and are described in the sensor-specific parameter pages in this tab.
+### `launch_hw`
+
+Whether to connect to a real sensor or to accept replayed packets from a topic like `/<vendor>_packets` or `/nebula_packets`.
+Both 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 and 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`
+
+Sensors for which Nebula supports IP multicast, `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 info on syntax.
+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 supported ranges or options supported by specific sensor models can vary. Refer to the sensor's parameter page for details.
+
+### `rotation_speed`
+
+The rotations per minute (RPM) the sensor's motor should spin at (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).

docs/parameters/vendors/hesai/common.md

@@ -1 +1,61 @@
 # Hesai-Specific Parameters
+
+## PTP Settings
+
+Support varies from sensor to sensor, so check the sensor's parameter page for allowed values.
+
+### `ptp_profile`
+
+The PTP version or profile to use. The supported profiles are `1588v2`, `802.1as` (gPTP), and `automotive` (AutoSAR Time Synchronization Protocol).
+
+### `ptp_domain`
+
+The domain to separate multiple PTP connections over the same link.
+
+### `ptp_transport_type`
+
+Whether to use `UDP` or `L2`. For `802.1as` and `automotive`, only `L2` is allowed.
+
+### `ptp_switch_type`
+
+While this is not found in the PTP standards, this influences how often the sensor performs delay measurements.
+Set this to `TSN` if your switch supports gPTP or the AutoSAR protocol, and `NON_TSN` if the switch does not.
+In the latter case, the sensor will measure more often.
+
+## Scan Cutting and Field of View
+
+Scan cutting influences the time stamps of points and the point cloud headers.
+The point cloud header time stamp is always the absolute time of the earliest (theoretical) point in the cloud.
+This means that for different parameter combinations, different timing behaviors are observed:
+
+- `cut_angle` is in `(cloud_min_angle, cloud_max_angle)` (both bounds exclusive): the earliest point is the one directly after `cut_angle`
+- `cut_angle = cloud_max_angle` and the FoV is not 360 deg: the earliest point is at `cloud_min_angle`
+
+Depending on whether `cut_angle` and `sync_angle` are aligned, the point cloud time stamp will be somewhere in `[ToS, ToS + 100 ms)` assuming a `10 Hz` LiDAR.
+
+**Examples:**
+
+| `cloud_min_angle` | `cloud_max_angle` | `cut_angle` | `sync_angle` | Resulting cloud timestamp |
+| ----------------: | ----------------: | ----------: | -----------: | ------------------------: |
+|                 0 |               360 |           0 |            0 |                       ToS |
+|                 0 |               180 |           0 |            0 |                       ToS |
+|                 0 |               360 |         180 |            0 |               ToS + 50 ms |
+|                90 |               360 |         360 |            0 |               ToS + 25 ms |
+
+### `cloud_min_angle` and `cloud_max_angle`
+
+The start and end angle of the desired field of view (FoV), in degrees. For the full FoV for 360 deg LiDARs, set these to `0` and `360`.
+The angles can also be set such that the 360->0 bound is crossed, e.g. `270` and `90`.
+
+Internally, the sensor handles angle correction effects and sets the hardware parameters with a computed margin to account for them.
+The output pointcloud will have exactly the FoV angles set in these parameters.
+
+### `sync_angle`
+
+The encoder angle of the sensor which will be passed at top-of-second (ToS). This is the time where the timestamp will roll over to `0`,
+e.g. `X.X0000... s` for a `10 Hz` frame rate.
+
+### `cut_angle`
+
+The corrected angle at which one point cloud ends and the next one starts.
+This angle has to be in the range `(cloud_min_angle, cloud_max_angle]`, except for a 360 deg FoV, where the angle has to be `[0, 360)`.