Quick Start: Using the Driver
To start the Oculus M3000d driver, different launch files are available for basic functionality or more “advanced” features.
Important
You cannot start the ROS2 driver while Oculus ViewPoint is running. If you launch any of the ROS2 driver scripts while ViewPoint is running, it will not work.
Important
Make sure no firewall is active on your device. A firewall can cause connection problems both in ViewPoint and with the ROS2 driver. You can disable it from a terminal with:
sudo ufw disable
0) Define the initial configuration
If you run one of the launch files, you can set the initial node parameter configuration in a .yaml
file. Navigate to the
oculus_ros2/oculus_ros2/cfg
directory, where you can find the configuration file used by each node.
Setting up the driver and processing nodes in advance is not crucial, since dynamic parameter reconfiguration is handled by the nodes, as described below.
1) Start the driver and optional sonar processing nodes
Sonar driver
To run only the driver node (handling the ROS2 interface with the low-level sonar driver library):
ros2 run oculus_ros2 oculus_sonar_node
Exposed topics
If the driver runs without any topic or namespace remapping (as in the command above), it exposes:
/status: high-level status information about the sensor state, device ID, IP and other information, remapped to other topics for easy access./ping: encodes the overall ping return in a readable way, including processed sound received, timestamp, etc./oculus_ping: encodes the overall ping return./temperature: internal electronics temperature. Used to enter protection mode when the temperature is too high./pressure: pressure to which the sensor is subjected. Used to retrieve depth for sound speed computation.
Additionally, the reconfigurable ROS2 node parameters are exposed to change the sonar configuration (frequency mode, gain, etc.). See Reconfiguring the sonar below.
Sonar driver + image formation
ros2 launch oculus_ros2 oculus_ros2_basic.launch.py
This runs the oculus_sonar_node and the sonar_viewer_node.
Sonar driver + image formation + point cloud + rviz2
ros2 launch oculus_ros2 oculus_ros2_full.launch.py
2) Reconfiguring the sonar and the processing nodes
Most of the configuration of the sonar driver and the processing nodes (such as the viewer and the point cloud publisher) is handled by ROS2 node parameters. This allows reconfiguration during sensor usage, without restarting the process (using the parameter reconfiguration callback).
You can reconfigure the parameters with the ROS2 CLI tools, but it is more comfortable to use the
rqt Dynamic Reconfigure plugin. Start it with:
rqt
Then open Plugins > Configuration > Dynamic Reconfigure.
From there, select the oculus_sonar driver node to see all the reconfigurable sonar parameters
(frequency mode, gain, range, etc.). In the same way, to change the polar-to-cartesian conversion
resolution or other aspects of the viewer, select the sonar_viewer node. This holds for any node
that exposes ROS2 parameters and implements the parameter callback.
The configuration .yaml files are extensively commented to explain what each parameter refers to,
the accepted values, and how they map to the sonar behavior.
Bonus: other useful commands and tools
Recording ROS2 bags
To record a specific subset of topics, run in another terminal:
ros2 bag record /topic1 /topic2
Caution
If the full Oculus stack is running, including the point cloud and high-resolution cartesian images, bag files can be extremely heavy if all messages are stored.
The most important data published during sonar usage is stored in the /ping message. This
topic stores all the acoustic echo recorded by the Oculus receiver, which can then be processed with
the sonar_viewer node. If the oculus_sonar_node is running in the sonar namespace, you can
store the ping messages with:
ros2 bag record /sonar/ping
Replaying this bag with the sonar_viewer_node running gives you access to all the visualization
functionality of the driver library. The same applies to the other sonar nodes that process the raw
ping data or the cartesian/polar images.
A useful tutorial on working with ROS2 bags is available here.
Converting ROS2 bags to images
Once you have recorded a ROS2 bag, you may want to save the polar/cartesian sonar frames in a local
directory as .png images. The sonar_saver_node has been implemented for exactly this.
Note
The code is not yet optimized to be device-agnostic in handling absolute/relative paths, so you need to make a minor modification to configure the save path. Additionally, some subscriber and publisher topic names are hardcoded in the nodes used in the steps above, so take care to remap topic names and namespaces if needed.
Open
sonar_saver.yaml(in thecfgdirectory of theoculus_ros2package) and update theoutput_dirandbag_nameparameters with your desired absolute save directory. The polar and cartesian images are saved inoutput_dir/bag_name/.Since you changed the configuration, rebuild the workspace and source it.
Start the sonar saver node:
ros2 run oculus_ros2 sonar_saver_node --ros-args --params-file </path/to/sonar_saver>.yaml
If the bag only stores the ping messages (raw sonar echo readings), start the viewer node for image formation (polar and cartesian):
ros2 run oculus_ros2 sonar_viewer_node
Play the bag file of interest:
ros2 bag play <bag_name>
You can perform all the steps above with a single launch file, taking care to update the bag path, topic names and possible node namespaces:
ros2 launch oculus_ros2 oculus_ros2_bag_saver.launch.py bag_path:=<path/to/bag>
Post-process and inspect ROS2 bag messages
The oculus_ros2_bag launch file is a good template for any sonar data processing based on a recorded
bag. It automatically plays the specified bag in loop mode and starts the viewer node for image
processing, rviz2 for visualization, and some other utility nodes.
Note
Some topics are remapped because of timestamp warnings. There is probably a better way to handle the different timestamps between the running nodes and the messages broadcast by the bag file.
ros2 launch oculus_ros2 oculus_ros2_bag.launch.py bag_path:=<absolute_path_to_bag>