COLA2 CONVENTIONS

Here you can find a compendium of the naming conventions that have been followed throughout the implementation of COLA2.

Names and namespaces

• When naming packages, nodes, topics and messages inside COLA2, the general ROS conventions are used.

• The name for device driver packages follow the pattern manufacturer_[model]_device (i.e. imagenex_deltat_multibeam)

• If a message definition contains, for some reason, fields that are not in the international system of units (SI), the field specifies the units explicitly after a trailing underscore (i.e. rotation_degrees). Otherwise it is understood that the units are the SI ones.

• All nodes that are launched from COLA2 main launch files (in the vehicle package), are launched under the vehicle namespace (i.e. /sparus2/)

• Private node handlers are used in the majority of nodes. Therefore, topics, services and parameters related to a given node are declared inside it using:

  • Python: the ∼/topic_name, ∼/service_name or ∼/param_name

  • C++: ros::NodeHandle("~") and names as topic_name, service_name or param_name

  and they automatically resolve to the absolute names /sparus2/node_name/topic_name, /sparus2/node_name/service_name and /sparus2/node_name/param_name.

• Exceptions to the above are:

  • Topics that refer to the vehicle in general and not to a particular module or component (i.e. /sparus2/vehicle_status)

  • Sensor topics that are remapped in the launch files to be the input to the navigator node although they are published from a device driver node (i.e. /sparus2/teledyne_explorer_dvl/dvl is remapped to /sparus2/navigator/dvl)

Robot frames and coordinate systems

All frames in the vehicle are related in COLA2 using the standard ROS TF library. This library internally maintains a time buffered tree of transformations and eases the task of computing the transformation between any two frames.

The COLA2 world reference frame corresponds to the /world_ned. To allow proper visualization in the RViz a frame named /world is also created. This helper frame is rotated 180 degrees in the x axis with respect to the /world_ned and it is configured as a fixed frame in RViz. This effectively rotates the visualization so that the NED frame is properly represented.

Finally, the COG of the vehicle is always represented using the name <vehicle_name>/base_link, so in this case it is sparus2/base_link (notice that frame names do not start with /). The remaining frames of the robot sensors and actuators are also located inside its namespace and defined with respect to the this vehicle_namespace/base_link. All these transformations are defined with the help of xacro macros in the <vehicle_name>_description package.

Package structure

COLA2 C++ packages follow the structure:

pkg_name/
|-- config/
|   |-- pkg_name.yaml
|-- include/
|   |-- pkg_name.h
|   |-- ...(other header files)
|-- launch/
|   |-- pkg_name.launch
|-- msg/
|   |-- MsgName.msg
|-- src/
|   |-- pkg_name/
|   |   |-- pkg_name.cpp
|   |   |-- ...(other source files)
|   |-- pkg_name_node.cpp
|-- CMakeLists.txt
|-- package.xml

Basic code, uncoupled from the ROS, is found in the include/ (for headers) and src/ (for source) folders, inside pkg_name/ subfolders. The ROS nodes using these code are found directly in src/ folder, and identified by the trailing _node.

Whenever the node requires to load parameters from the ROS Param Server, specially in device driver packages, an example configuration YAML is provided in the config/ folder. Similarly, a basic launch file to load the required parameters and launch the node is provided in the launch/ folder. Note that these are just config and launch files accompanying the package for example purposes. When executing COLA2 on the real vehicle or simulating it, the config files that are actually used are the ones residing in the vehicle package (i.e. cola2_sparus2).

If the node requires custom ROS messages, for instance for storing a set of raw data from a sensor, the corresponding message definitions are found inside the msg/ folder. In case the message definition is needed by other COLA2 nodes, the .msg file should be placed in the cola2_msgs package.

Python packages follow a similar structure, although typically they just contain the ROS nodes inside the src folder.

Coding conventions

When developing code for COLA2, these are some guidelines to take into account:

• COLA2 c++ packages follow c++11 standard.

• When possible, try to follow the ROS Style guide for C++ (clang-format) and Python.

• Functions from cola2_lib should be employed for tasks that are common across COLA2 nodes (i.e. reading parameters from the ROS param server, setting up diagnostics, converting coordinates, etc.). Have a look on what is available inside io, utils and rosutils libraries of cola2_lib package.