# ouster-ros
**Repository Path**: light169/ouster-ros
## Basic Information
- **Project Name**: ouster-ros
- **Description**: Official ROS driver for Ouster sensors
- **Primary Language**: Unknown
- **License**: BSL-1.0
- **Default Branch**: ros2
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-19
- **Last Updated**: 2025-05-19
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Official ROS driver for Ouster sensors
[ROS1 (melodic/noetic)](https://github.com/ouster-lidar/ouster-ros/tree/master) |
[ROS2 (rolling/humble)](https://github.com/ouster-lidar/ouster-ros/tree/ros2) |
[ROS2 (foxy)](https://github.com/ouster-lidar/ouster-ros/tree/ros2-foxy)
| ROS Version | Build Status (Linux) |
|:-----------:|:------:|
| ROS1 (melodic/noetic) | [](https://github.com/ouster-lidar/ouster-ros/actions/workflows/docker-image.yml)
| ROS2 (rolling/humble) | [](https://github.com/ouster-lidar/ouster-ros/actions/workflows/docker-image.yml)
| ROS2 (foxy) | [](https://github.com/ouster-lidar/ouster-ros/actions/workflows/docker-image.yml)
- [Overview](#overview)
- [Requirements](#requirements)
- [Getting Started](#getting-started)
- [Usage](#usage)
- [Launching Nodes](#launching-nodes)
- [Sensor Mode](#sensor-mode)
- [Recording Mode](#recording-mode)
- [Replay Mode](#replay-mode)
- [Multicast Mode (experimental)](#multicast-mode-experimental)
- [Invoking Services](#invoking-services)
- [GetMetadata](#getmetadata)
- [GetConfig](#getconfig)
- [SetConfig (experimental)](#setconfig-experimental)
- [License](#license)
## Overview
This ROS package provide support for all Ouster sensors with FW v2.0 or later targeting ros2 distros.
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 under the
name `/ouster/points2` which corresponds to the second point cloud.
## Requirements
This driver only supports **Rolling** and **Humble** ROS 2 distros. Please refer to ROS 2 online
documentation on how to setup ros on your machine before proceeding with the remainder of this guide.
> **Note**
> If you have _rosdep_ tool installed on your system you can then use the following command to get all
required dependencies:
```
rosdep install -y --from-paths $OUSTER_ROS_PATH -r
```
### Linux
In addition to the base ROS installation, the following ROS packages are required:
```bash
sudo apt install -y \
ros-$ROS_DISTRO-pcl-ros \
ros-$ROS_DISTRO-tf2-eigen \
ros-$ROS_DISTRO-rviz2
```
where `$ROS_DISTRO` is either ``rolling`` or ``humble``.
> **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`.
The following packages are also required
```bash
sudo apt install -y \
build-essential \
libeigen3-dev \
libjsoncpp-dev \
libspdlog-dev \
libcurl4-openssl-dev \
cmake \
python3-colcon-common-extensions
```
> **Note**
> You may choose a different _ssl_ backend for the _curl_ library such as `libcurl4-gnutls-dev` or
> `libcurl4-nss-dev`
### Windows
TBD
### Mac
TBD
## Getting Started
To build the driver using ROS2 you need to clone the project into the `src` folder of a ros2
workspace as shown below:
```bash
mkdir -p ros2_ws/src && cd ros2_ws/src
git clone -b ros2 --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:
```bash
source /opt/ros//setup.bash # replace ros-distro with 'rolling' or 'humble'
```
Finally, invoke `colcon build` command from within the catkin workspace as shown below:
```bash
cd ros2_ws
colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release
```
> **Note**
> Specifying `Release` as the build type is important to have a reasonable performance of the driver.
Once the build succeeds, you must source the _install_ folder of your ros2 workspace to add launch
commands to your environment:
```bash
source ros2_ws/install/setup.bash
```
## Usage
### 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
```bash
ros2 launch ouster_ros sensor.launch.xml \
sensor_hostname:=
```
#### Recording Mode
> Note
> As of package version 8.1, specifiying metadata file is optional since the introduction of the
> metadata topic
```bash
ros2 launch ouster_ros record.launch.xml \
sensor_hostname:= \
bag_file:= \
metadata:= # optional
```
#### 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
```bash
ros2 launch ouster_ros replay.launch.xml \
bag_file:= \
metadata:= # optional if bag file has /metadata topic
```
#### 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.xml`
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 as follows:
```bash
roslaunch ouster_ros sensor_mtp.launch.xml \
sensor_hostname:= \
udp_dest:= \
mtp_main:=true \
mtp_dest:= # 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**):
```bash
roslaunch ouster_ros sensor_mtp.launch.xml \
sensor_hostname:= \
udp_dest:= \
mtp_main:=false \
mtp_dest:= # 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.
### Invoking Services
To execute any of the following service, first you need to open a new terminal
and source the ros2 workspace again by running the command
`source ros2_ws/install/setup.bash`
#### GetMetadata
To get metadata while connected to a live sensor or during a replay session invoke
the following command:
```bash
ros2 service call /ouster/get_metadata ouster_srvs/srv/GetMetadata
```
#### GetConfig
To get the current config of a live sensor, invoke the command:
```bash
ros2 service call /ouster/get_config ouster_srvs/srv/GetConfig
```
#### SetConfig (experimental)
To change config via a file while connected to a live sensor, invoke the command:
```bash
ros2 service call /ouster/set_config ouster_srvs/srv/SetConfig \
"{config_file: 'some_config.json'}"
```
#### Reset (experimental)
To reset the new reset service, execute the following commnad:
```bash
ros2 service call /ouster/reset std_srvs/srv/Empty
```
When this service is invoked the client should stop streaming, dispose current
connection, reset the sensor and reconnect again.
> **Note**
> Changing settings is not yet fully support during a reset operation (more on this)
TBD: For further detailed instructions refer to the [main guide](./docs/index.rst)
## License
[License File](./LICENSE)