Official ROS1/ROS2 drivers for Ouster sensors ============================================= ROS1 (melodic/noetic) | ROS2 (rolling/humble/iron/jazzy) | ROS2 (galactic/foxy) [](https://github.com/ouster-lidar/ouster-ros/blob/master/docs/images/logo.png) | ROS Version | Build Status (Linux) | | --- | --- | | ROS1 (melodic/noetic) | !melodic/noetic | | ROS2 (rolling/humble/iron/jazzy) | !rolling/humble/iron/jazzy | | ROS2 (galactic/foxy) | !galactic/foxy | * Official ROS1/ROS2 drivers for Ouster sensors * Overview * Supported Devices * Requirements * Getting Started * Usage * Launching Nodes * Sensor Mode * Recording Mode * Replay Mode * PCAP Replay Mode * Multicast Mode (experimental) * Launch Files Arguments * Invoking Services * GetMetadata * GetConfig * SetConfig * License Overview -------- [](https://github.com/ouster-lidar/ouster-ros?utm_source=chatgpt.com#overview) This ROS package provide support for all Ouster sensors with FW v2.0 or later. Upon launch the driver will configure and connect to the selected sensor device, once connected the driver will handle incoming IMU and lidar packets, decode lidar frames and publish corresponding ROS messages on the topics of `/ouster/imu` and `/ouster/points`. In the case the used sensor supports dual return and it was configured to use this capability, then another topic will published named `/ouster/points2` which corresponds to the second point cloud. Supported Devices ----------------- [](https://github.com/ouster-lidar/ouster-ros?utm_source=chatgpt.com#supported-devices) The driver supports the following list of Ouster sensors: * OS0 * OS1 * OS2 * OSDome You can obtain detailed specs sheet about the sensors and obtain updated FW through the website downloads section. Requirements ------------ [](https://github.com/ouster-lidar/ouster-ros?utm_source=chatgpt.com#requirements) This package only supports **Melodic** and **Noetic** ROS distros. Please refer to ROS online documentation on how to setup ros on your machine before proceeding with the remainder of this guide. In addition to the base ROS installation, the following ROS packages are required: ```shell sudo apt install -y \ ros-$ROS_DISTRO-pcl-ros \ ros-$ROS_DISTRO-rviz ``` where `$ROS-DISTRO` is either `melodic` or `noetic`. > **Note** > Installing `ros-$ROS_DISTRO-rviz` package is optional in case you didn't need to visualize the point cloud using rviz but remember to always set `viz` launch arg to `false`. Additional dependenices: ```shell sudo apt install -y \ build-essential \ libeigen3-dev \ libjsoncpp-dev \ libspdlog-dev \ libcurl4-openssl-dev \ cmake ``` > **Note** > You may choose a different ssl backend for the curl library such as `libcurl4-gnutls-dev` or `libcurl4-nss-dev` > **Note** > To use the PCAP replay mode you need to have `libpcap-dev` installed Getting Started --------------- [](https://github.com/ouster-lidar/ouster-ros?utm_source=chatgpt.com#getting-started) To build the driver using ROS you need to clone the project into the `src` folder of a catkin workspace as shown below: ```shell mkdir -p catkin_ws/src && cd catkin_ws/src git clone --recurse-submodules https://github.com/ouster-lidar/ouster-ros.git ``` Next to compile the driver you need to source the ROS environemt into the active termainl: ```shell source /opt/ros/<ros-distro>/setup.bash # replace ros-distro with 'melodic' or 'noetic' ``` Finally, invoke `catkin_make` command from within the catkin workspace as shown below: ```shell cd catkin_ws catkin_make --cmake-args -DCMAKE_BUILD_TYPE=Release ``` Specifying `Release` as the build type is important to have a reasonable performance of the driver. Usage ----- [](https://github.com/ouster-lidar/ouster-ros?utm_source=chatgpt.com#usage) ### Launching Nodes [](https://github.com/ouster-lidar/ouster-ros?utm_source=chatgpt.com#launching-nodes) The package supports three modes of interaction, you can connect to a _live sensor_, _replay_ a recorded bag or _record_ a new bag file using the corresponding launch files. Recently, we have added a new mode that supports multicast. The commands are listed below: #### Sensor Mode [](https://github.com/ouster-lidar/ouster-ros?utm_source=chatgpt.com#sensor-mode) The driver offers two launch files to connect to an Ouster sensor: `sensor.launch` and `driver.launch`; they differ in terms of how the processing of incoming packets is performed. `sensor.launch` spawns three nodelets, one to connect to the sensor and publishes raw packets to the two other nodelets which handles converting them into **Imu**, **Image** and **PointCloud2** messages. Meanwhile, `driver.launch` file spawn a single nodelet that handles all of these tasks. You can invoke the two files in the same way. The following line shows how to run the node using `driver.launch`: ```shell roslaunch ouster_ros driver.launch \ sensor_hostname:=<sensor host name> \ metadata:=<json file name> # optional ``` `driver.launch` offers better performance and reduced overhead on the ROS bus, thus it is preferred over `sensor.launch`. `sensor.launch` is mainly provided for backward compatibilty. > **Note**: If you observe parts of the scan missing is missing, this suggests having a lots of dropped packets It is recommended that you increase the maximum allowed size for receive memory buffers in network subsystem, you can do so by running the script `network-configure.bash` under `util`. #### Recording Mode [](https://github.com/ouster-lidar/ouster-ros?utm_source=chatgpt.com#recording-mode) > Note As of package version 8.1, specifiying metadata file is optional since the introduction of the metadata topic ```shell roslaunch ouster_ros record.launch \ sensor_hostname:=<sensor host name> \ bag_file:=<optional bag file name> \ metadata:=<json file name> # optional ``` #### Replay Mode [](https://github.com/ouster-lidar/ouster-ros?utm_source=chatgpt.com#replay-mode) > Note As of package version 8.1, specifiying metadata file is optional if the bag file being replayed already contains the metadata topic ```shell roslaunch ouster_ros replay.launch \ bag_file:=<path to rosbag file> \ metadata:=<json file name> # optional if bag file has /metadata topic ``` ##### PCAP Replay Mode [](https://github.com/ouster-lidar/ouster-ros?utm_source=chatgpt.com#pcap-replay-mode) > Note To use this feature you need to compile the driver with `BUILD_PCAP` option enabled ```shell roslaunch ouster_ros replay_pcap.launch \ pcap_file:=<path to ouster pcap file> \ metadata:=<json file name> # required ``` #### Multicast Mode (experimental) [](https://github.com/ouster-lidar/ouster-ros?utm_source=chatgpt.com#multicast-mode-experimental) The multicast launch mode supports configuring the sensor to broadcast lidar packets from the same sensor (live) to multiple active clients. You initiate this mode by using `sensor_mtp.launch` file to start the node. You will need to specify a valid multicast group for the **udp\_dest** argument which the sensor is going to broadcast data to it. You will also need to set **mtp\_main** argument to **true**, this is need to configure the sensor with the specified **udp\_dest** and any other sensor settings. You can control on which ip (IP4 only) you wish to receive the data on this machine from the multicast group using the **mtp\_dest** argument follows: ```shell roslaunch ouster_ros sensor_mtp.launch \ sensor_hostname:=<sensor host name> \ udp_dest:=<multicast group ip (ipv4)> \ mtp_main:=true \ mtp_dest:=<client ip to receive data> # mtp_dest is optional ``` Using a different machine that belongs to the same netwok subnet, you can start another instance of the client to start receiving sensor messages through the multicast group as shown below (note that **mtp\_main** is set to **false**): ```shell roslaunch ouster_ros sensor_mtp.launch \ sensor_hostname:=<sensor host name> \ udp_dest:=<multicast group ip (ipv4)> \ mtp_main:=false \ mtp_dest:=<client ip to receive data> # mtp_dest is optional ``` > **Note:** In both cases the **mtp\_dest** is optional and if left unset the client will utilize the first available interface.