Introduction

This package is a ROS Wrapper for the Modular and Robust State-Estimation (MaRS) Library, which can be found here, with the technology described by this publication. The wrapper defines simple nodes for direct use. Additional sensors can be added to pre-existing nodes, or a dedicated ROS node can be designed for a specific application.

Please note that the general definition of a sensor module is defined within the MaRS library. The sensor modules defined by the MaRS Library can then be used within the ROS wrapper by instantiating the corresponding sensor module class and the definition of corresponding callbacks.

The setup of new, dedicated ROS nodes and the implementation of new sensor modules to the MaRS Library is described in the Tutorial section, and by the MaRS library itself.

The MaRS ROS wrapper uses the MaRS library as a submodule. After cloning the mars_ros node, no additional download is needed (except of initializing the submodule).

Austrian Patent Application Pending

Features

ROS Wrapper

• Ready to use ROS nodes for common setups (Position, Pose, and GNSS sensor with IMU)
• Predefined sensor update modules (Plug and Play)
• Predefined RQT views
• Docker test environment

The MaRS Framework

• Truly-Modular decoupling of Sensor-States from the essential Navigation-States
• Generalized covariance segmentation for Plug and Play state and covariance blocks
• Minimal State-Representation at any point in time
• Integration and removal of sensor modules during runtime
• Out of sequence sensor measurement handling
• Developed for computationally constrained platforms
• Efficient handling of asynchronous and multi-rate sensor information
• Separation between simple user interaction and the complexity of information handling

Getting Started

Setup and Building the Project

# Generate a catkin workspace (optional)
$ mkdir -p catkin_ws/src
$ cd catkin_ws
$ catkin init
$ catkin config --cmake-args -DCMAKE_BUILD_TYPE=Release
$ cd src

# Get the mars_ros package
$ git clone https://github.com/aau-cns/mars_ros.git mars_ros
$ cd mars_ros
$ git submodule update --init --recursive

# Build the project and run tests
$ cd ../../
$ catkin build

Isolated Build with Docker

The docker image is published regularly with updates to Dockerhub. If you want to build the image yourself, you can do so with

$ cd mars_ros # Enter the source directory
$ docker build --network=host -t aaucns/mars_ros_test_env:latest . # Build the Docker image

Either way, you can then test your MaRS ROS wrapper by executing the following.

# The following runs the container, maps the source code (read only)
# and executes the script in 'docker/docker_application_test.sh'
$ docker run -it --rm \
  --network=host \
  -v "$(pwd)":/source:ro \
  aaucns/mars_ros_test_env:latest

Usage

Modules

Parameter

The MaRS nodes define a set of standard parameters which are useful in paxis. The current set of parameters is stated below:

Service

Topics

Because applications might use different message types, the example ROS nodes provide different subscribers to feed position or pose information. Each topic essentially feeds to the same update routine after converting the ROS message to an internal MaRS measurement type. Note: Only use one of the input messages for the example nodes to prevent confusion. If you want to use multiple sensors, please follow the [Tutorial](# Tutorial).

Custom MaRS message types

Default Navigation State

The Navigation-States (core states) are the essential states to localize a robot in the world, given the fact that these states are propagated with IMU measurements.

General Nomenclature

The translation defines frame with respect to frame expressed in frame . The translation is expressed in frame if the subscript is not defined. The quaternion describes the rotation of frame with respect to frame . denotes the conversion of quaternion to its corresponding rotation matrix. Please note that this framework uses the Hamilton notation for the Quaternion representation.

Symbols

Symbol	Message name	Description
	p_wi	Translation of the robot IMU/body frame expressed w.r.t. the world frame
	v_wi	Velocity of the robot IMU/body frame expressed w.r.t. the world frame
	q_wi	Orientation of the robot IMU/body frame expressed w.r.t. the world frame (Hamiltonian)
	b_w	Gyroscopic bias
	b_a	Accelerometer bias
	cov	Navigation state covariance

The fields FRAME_TYPEand QUATERNION_TYPE are used for consecutive processing. The states of MaRS are expressed in ENU and Quaternions are Hamiltonian.

mars_ros::ExtCoreState

The ExtCoreState message contains the full set of information concerning the core navigation state. Definition of the message:

std_msgs/Header header
geometry_msgs/Vector3 p_wi
geometry_msgs/Vector3 v_wi
geometry_msgs/Quaternion q_wi
geometry_msgs/Vector3 b_w
geometry_msgs/Vector3 b_a
float64[225] cov
uint8 FRAME_TYPE
uint8 QUATERNION_TYPE

mars_ros::ExtCoreStateLite

The ExtCoreStateLite message contains only the essential state components for navigation. This message can be used if the bandwidth to e.g. a flight controller, is limited. Definition of the message:

std_msgs/Header header
geometry_msgs/Vector3 p_wi
geometry_msgs/Vector3 v_wi
geometry_msgs/Quaternion q_wi

uint8 FRAME_TYPE
uint8 QUATERNION_TYPE

Programming

The codebase is mostly C++ based and follows the C++ Google style convention. A C-Lang file with formatting definitions / for auto formatting can be found in the root directory of the project mars_ros/.clang-format.

Tutorial

As stated in the introduction, the ROS MaRS wrapper does not define the general sensor modules. Sensor modules are defined (ROS independent) by the MaRS Library. The usage of sensors within the ROS wrapper is done through the MaRS Library API. The definition and design of a new ROS node/middleware integration is described by the MaRS Lib Integration Tutorial.

Project Layout

Package Layout/Codebase

Generated with tree -a -L 3 --noreport --charset unicode > layout.md

.
|-- cfg
|   `-- mars.cfg
|-- .clang-format
|-- cmake
|   `-- mars_libConfig.cmake
|-- CMakeLists.txt
|-- docker
|   |-- docker_application_test.sh
|   `-- dockerfile
|-- .gitmodules
|-- include
|   |-- mars_msg_conv.h
|   |-- mars_wrapper_gps.h
|   |-- mars_wrapper_pose.h
|   `-- mars_wrapper_position.h
|-- launch
|   |-- config
|   |   |-- gps_config.yaml
|   |   |-- pose_config.yaml
|   |   `-- position_config.yaml
|   |-- mars_gps.launch
|   |-- mars_gps_template.launch
|   |-- mars_pose.launch
|   |-- mars_pose_template.launch
|   |-- mars_position.launch
|   |-- px4_sim.launch
|   `-- rqt_pose.launch
|-- LICENSE
|-- mars_lib
|       `-- <submodule>
|-- msg
|   |-- ExtCoreStateLite.msg
|   `-- ExtCoreState.msg
|-- package.xml
|-- README.md
|-- resources
|   |-- a-astro-space-font.zip
|   |-- cov_segmentation.png
|   |-- cov_segmentation.svg
|   |-- mars_ros_logo.png
|   `-- mars_ros_logo.svg
|-- rosdoc.yaml
|-- rqt_perspective
|   `-- mars_pose.perspective
`-- src
    |-- mars_node.cpp
    |-- mars_wrapper_gps.cpp
    |-- mars_wrapper_pose.cpp
    `-- mars_wrapper_position.cpp

Contact

For further information, please contact Christian Brommer

License

This software is made available to the public to use (source-available), licensed under the terms of the BSD-2-Clause-License with no commercial use allowed, the full terms of which are made available in the LICENSE file. No license in patents is granted.

Usage for academic purposes

If you use this software in an academic research setting, please cite the corresponding paper and consult the LICENSE file for a detailed explanation.

@inproceedings{brommer2020,
   author   = {Brommer, Christian and Jung, Roland and Steinbrener, Jan and Weiss, Stephan},
   doi      = {10.1109/LRA.2020.3043195},
   journal  = {IEEE Robotics and Automation Letters},
   title    = {{MaRS : A Modular and Robust Sensor-Fusion Framework}},
   year     = {2020}
}