Tutorials

Once all the previous components are installed and configured, you can start to use ROS applications with the DESERT middleware. Inside the framework different tutorial clients are available to test the system.

Basic network configuration

First of all you need to deploy a valid acoustic network configuration. Initially it is suggested to start with a simulated channel, that tries to reproduce a real underwater environment using only mathematical models for attenuation and noise computation. Then a SNR threshold is applied to decide if a packet was lost or not during the transmission.

In this case no real devices are employed so you can test the software using only your computers. The DESERT module implementing this mathematical channel is called UW/PHYSICAL and you can find a TCL script with this configuration inside the rmw_desert repository under the name test_uwApplicationTCP.tcl.

To let the middleware connect with the network it is always present the UW/APPLICATION module at the highest layer of the protocols stack. Basically it creates a TCP socket for each simulated underwater node that will be used as an interface to send and receive data in the user space through DESERT.

So move to the directory inside the workspace where you cloned the repository of rmw_desert and run the following command.

ns test_uwApplicationTCP.tcl

This script creates two nodes, and now you should be able to connect to each of them using a socket hosted on your machine through the TCP ports 4000 and 5000.

Allowed topics

Every time a ROS application is executed on the top of the DESERT middleware, a file called ros_allowed_topics.conf must be present in the current working directory. It contains a JSON dictionary of the topics which are allowed to send information and the identifier string is converted to an integer.

This mechanism is foundamental in underwater channels because the bandwidth is limited and so it should be prevented to send non-useful data. Each time you develop a client applicantion and you need to use a new topic, it must be added to this configuration file with an assigned integer, otherwise the middleware will block it.

For each topic you want to enable you have to choose a random number greater than zero and fill the JSON dictionary with the key containing the topic name string and the value containing the selected integer.

In the default configuration saved on this repository /discovery and /discovery_request are the first two enabled topics. Those ones are reserved in order to provide discovery functionalities to the application, allowing each node to know the network structure.

For this motivation client applications can not create entities with those stream names, so if you enable them the middleware will automatically send additional data in the underwater channel to achieve the goal explained above. Note that it is quite resource-consuming, so in most real cases scenarios you want to disable this feature to prevent saturating the acoustic transmission.

Turtlesim and teleop key

A valuable tool utilized for introducing the framework is Turtlesim, a lightweight simulator designed for educational purposes within ROS 2. Turtlesim serves as a fundamental demonstration of ROS 2 operations, offering insights into the activities one may engage in with an actual robot or a simulated robot in subsequent stages.

Essentially, the turtlesim_node showcases a graphical interface featuring a turtle that periodically transmits data regarding its position, color, and other attributes, while concurrently awaiting commands dictating its movement via topics and services.

By simulating the functionalities of an abstract robot, the turtle assumes the role of the target device necessitating control. Conversely, a program responsible for dispatching control commands, known as turtle_teleop_key, is also imperative for the interactive process.

Install the turtlesim package for your ROS 2 distro.

sudo apt update
sudo apt install ros-${ROS_DISTRO}-turtlesim

Before proceeding move to the root directory of the cloned rmw_desert repository and make sure that the file called ros_allowed_topics.conf is present as described in the previous section.

To start turtlesim, enter the following command in your terminal after making sure that the ns instance executed in the previous section is still running.

RMW_IMPLEMENTATION=rmw_desert DESERT_PORT=4000 ros2 run turtlesim turtlesim_node

At this point you connected a ROS client application to one of the two simulated DESERT nodes through the TCP port 4000. In order to control the turtle you need to connect with a different port using the middleware, and so you just need to open another terminal window, source the libraries as described before, and execute the client application called teleop key.

RMW_IMPLEMENTATION=rmw_desert DESERT_PORT=5000 ros2 run turtlesim turtle_teleop_key

Now you can use the arrows to move the turtle and some characters to perform absolute rotations by employing the DESERT underwater network infrastructure.

Change environment variables

The mathematical simulation of the underwater channel can be modeled by acting on different parameters representing the environmental characteristics of a specific setting.

Tunable values are:

• Transmission power
• Speed of the wind
• Shipping activity level
• Position of each node

It is possible to act also on other parameters, but they are considered the most realistic values for those type of communications and so you should prevent diverging from plausible conditions.

To modify the power of the acoustic transmission open the file test_uwApplicationTCP.tcl and edit the variable below. It is expressed in underwater dB, the relative unit used to specify the intensity of an underwater sound.

set opt(txpower) 180.0

The speed of the wind and the shipping activity level are tunable with the following variables. The first is expressed in meters per second, while the last is an absolute value ranging from zero to one, representing respectively no ships and high shipping activity.

MPropagation/Underwater set windspeed_ 10
MPropagation/Underwater set shipping_  0

Finally the position of nodes can be altered with a three-dimensional coordinate system using meters as the measurement unit. Each of them is set in this snippet.

for {set id1 0} {$id1 < $opt(nn)} {incr id1}  {
    $position($id1) setX_ 500
    $position($id1) setY_ 0
    $position($id1) setZ_ -1000
}

In this configuration all the nodes are communicating with a common sink which is connected to the TCP port 5000, located through another variable named $position_sink. To understand the behavior of the channel you can maintain its coordinates fixed and change only the position of the other nodes from the code block above.

Real network configuration

In order to test the middleware in a real scenario you will need acoustic underwater modems such as those manufactured by EvoLogics. In the DESERT stack a physical layer implementing the communication with those devices is available under the name UW/UwModem/EvoLogicsS2C.

They are connected through a standard network and an Ethernet cable, so each one has its own IP address that has to be defined inside the TCL script to allow NS finding those physical modems.

Open the test_uwEvologicsApplicationTCP_TDMA.tcl file and look for the following lines.

set address_node(0) "10.42.9.1:9200"
set address_sink    "10.42.9.2:9200"

Here you have to put the addresses of at least two EvoLogics devices followed by the 9200 port, or alternatively of the official EvoLogics emulators. Move to the rmw_desert directory and run the command below.

ns test_uwEvologicsApplicationTCP_TDMA.tcl

Make sure the modems are reachable from you station and then you should be able to run turtlesim with a real underwater transmission using the commands from the previous section.