Installation and usage

This guide applies to tags 8.0.0 onward, as the ROS driver underwent significant changes. For prior versions, please refer to (DEPRECATED) Installation and usage.

Environment setup

Before building or configuring the Fixposition ROS driver, the user must ensure that their local environment is supported. There are two methods available: manually installing all the driver dependencies or using one of the provided docker images.

a) Manual setup with dependencies

Note: The following installation steps assume an Ubuntu system.

ROS1 Noetic

Assuming that an installation similar to 'ros:noetic-ros-base' is already available:

sudo apt update
sudo apt install git python3-catkin-tools
sudo apt install libyaml-cpp-dev libboost-all-dev zlib1g-dev libeigen3-dev linux-libc-dev
sudo apt install ros-noetic-eigen-conversions ros-noetic-tf ros-noetic-tf-conversions ros-noetic-tf2-ros ros-noetic-tf2-tools ros-noetic-tf2-geometry-msgs

ROS2 Humble

Assuming that an installation similar to 'ros:humble-ros-base' is already available:

sudo apt update
sudo apt install libyaml-cpp-dev libboost-all-dev zlib1g-dev libeigen3-dev linux-libc-dev

In addition, it is necessary to download, build and install googletest:

curl -L https://github.com/google/googletest/archive/refs/tags/v1.13.0.tar.gz -o /tmp/gtest.tar.gz
echo "bfa4b5131b6eaac06962c251742c96aab3f7aa78 /tmp/gtest.tar.gz" | sha1sum --check

mkdir /tmp/gtest
cd /tmp/gtest
tar --strip-components=1 -xzvf ../gtest.tar.gz
cmake -B build -S . \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=/usr/local \
    -DBUILD_SHARED_LIBS=ON
cmake --build build --parallel 4
cmake --install build
cd /
rm -rf /tmp/gtest.tar.gz /tmp/gtest

You can skip the GTest update by running colcon build --cmake-args -DBUILD_TESTING=OFF.

ROS2 Jazzy

Assuming that an installation similar to 'ros:jazzy-ros-base' is already available:

sudo apt update
sudo apt install git libyaml-cpp-dev libboost-all-dev zlib1g-dev libeigen3-dev linux-libc-dev

b) Docker setup

Alternatively, the user can employ our Fixposition Docker images to build the Fixposition ROS driver, as these images are guaranteed to correctly compile the libraries and have been thoroughly tested. You can find the supported ROS1 and ROS2 images in the following repository: Fixposition Docker Repository.

Currently supported versions:

• Noetic

• Humble

• Jazzy

We recommend using the *-dev images, as they are the most complete.

In the Fixposition ROS driver, you will find a .devcontainer folder with examples on how to pull and configure these Docker images. Alternatively, you can simply execute ‘docker pull' and 'docker run' on the desired image path, and download the driver repository inside.

In addition, to compose the Docker containers present in the Fixposition ROS driver, the user can employ the Docker extension in VSCode. Then, open the folder in VSCode and execute the command 'Dev Container: Rebuild and Reopen in Container' (press Ctrl+Shift+P to open the command console). Afterward, select the desired ROS version to compile.

The compilation using VSCode is meant as a reference only and is currently being improved.

Repository setup

This driver operates as a ROS node, connecting to either a TCP or serial stream of the Fixposition Vision-RTK output data (see Fixposition ASCII messages and the Integration Manual for more information).

If using the previous ROS driver, you must remove and install the new repository from scratch.

To install the Fixposition ROS driver on your machine, extract / clone the repository and select one of the following installation methods:

• Set up driver for an existing ROS workspace

• Set up driver as a new ROS workspace

• Manual setup

The following bash scripts must be executed inside the repository folder (where the .git resides).

a) Set up driver for an existing ROS workspace

To adapt the Fixposition ROS driver to work with an existing ROS1|2 workspace, use the ‘setup_ros_ws.sh' script. This script sets up the Fixposition driver repository to be used in a existing ROS workspace. It assumes that you cloned the fixposition_driver repository to the src directory of your ROS workspace.

Note that this script automatically detects the ROS version enabled on your local machine using the ROS_DISTRO environment variable and adapts the repository respectively. Alternatively, you can force the ROS1|2 compilation using the ‘-r' flag. Lastly, you can use the '-s' flag to skip checking whether the Fixposition SDK is located inside the driver package.

The folder structure using this method should look like this:

ros_ws
├── src
│   ├── other_package                 # optional: other...
│   ├── ...                           #    ... ROS packages
│   ├── fixposition_driver
│   │   ├── fixposition_driver_lib
│   │   ├── fixposition_driver_msgs
│   │   ├── fixposition_driver_ros1   # if using ROS1
│   │   ├── fixposition_driver_ros2   # if using ROS2
│   │   ├── fixposition_sdk           # git submodule for fixposition SDK
│   ├── nmea_msgs                     # optional: if streaming RTCM3 messages
│   ├── ntrip_client                  # optional: if streaming RTCM3 messages

b) Set up driver as a new ROS workspace

To create a new ROS workspace for the Fixposition ROS driver, use the 'create_ros_ws.sh' script. This script creates symlinks from the downloaded repository into the new workspace in the selected <path> location. Note that this method is meant to be used in Fixposition driver development. To use the driver in your existing ROS workspace, use the 'setup_ros_ws.sh' script described above.

To use this script, the user must choose the desired path for the new ROS workspace. This path can be absolute or relative to ${SCRIPTDIR}. The default compilation mode is ‘release', which makes the output of the compiler less verbose. Alternatively, the user can set the compilation as ‘debug' using the '-d’ flag.

Note that this script automatically detects the ROS version enabled on your local machine using the ROS_DISTRO environment variable and adapts the repository respectively. Alternatively, you can force the ROS1|2 compilation using the ‘-r' flag. Lastly, you can use the '-s' flag to skip checking whether the Fixposition SDK is located inside the driver package.

The ‘create_ros_ws.sh' script generated a ROS workspace using symlinks. Thus, the original repository must not be deleted! Additionally, you cannot move the original folder unless using absolute paths, and the full repository cannot be located inside an existing ROS workspace.

The folder structure using this method should look like this:

<path>/ros_ws
├── src
│   ├── fixposition_driver
│   │   ├── fixposition_driver_lib
│   │   ├── fixposition_driver_msgs
│   │   ├── fixposition_driver_ros1   # if using ROS1
│   │   ├── fixposition_driver_ros2   # if using ROS2
│   │   ├── fixposition_sdk           # git submodule for fixposition SDK

c) Manual setup

If you decide to configure the repository manually (i.e., without using the provided scripts), then you must add a file named 'CATKIN_IGNORE' in the 'fixposition_driver_ros2' package when using a ROS1 environment. Similarly, you must add a file named 'COLCON_IGNORE' in the 'fixposition_driver_ros1' package when using a ROS2 environment. In a ROS 2 colcon workspace you additionally have to remove the fixposition-sdk/CMakeLists.txt file as colcon otherwise mistakes the entire fixposition-sdk directory as a package instead of using the the packages contained within this directory (fpsdk_common, fpsdk_ros2, fpsdk_apps).

The folder structure should look like this:

ros_ws
├── src
│   ├── other_package                 # optional: other...
│   ├── ...                           #    ... ROS packages
│   ├── fixposition_driver
│   │   ├── fixposition_driver_lib
│   │   ├── fixposition_driver_msgs
│   │   ├── fixposition_driver_ros1/COLCON_IGNORE   # if using ROS2
│   │   ├── fixposition_driver_ros2/CATKIN_IGNORE   # if using ROS1
│   │   ├── fixposition_sdk           # git submodule for fixposition SDK
│   │       ├── ~~CMakeLists.txt~~    # file must be removed if using ROS2
│   │       ├── fpsdk_ros1/COLCON_IGNORE            # if using ROS2
│   │       ├── fpsdk_ros2/CATKIN_IGNORE            # if using ROS1
│   │       ├── fpsdk_common
│   │       ├── ...
│   ├── ...

On top of that, the user must adapt the CMake files to correctly link and compile the packages in the repository. You can use the provided scripts as reference for which files need to be adapted. However, we highly recommend sticking to the provided scripts as they have been thoroughly tested and we can guarantee their functionality in the supported environments.

Note that the fixposition-sdk submodule in the Fixposition ROS driver must be made available using either an initial git clone --recursive on the ROS driver repository or, for an existing repository, using git submodule update --init. This step is performed automatically when using either of the provided scripts detailed in (a) or (b).

Driver compilation

a) ROS1 steps

Source the setup.bash from the ROS1 distro repository (/opt/ros/{ROS_DISTRO}/setup.bash). For example:

source /opt/ros/melodic/setup.bash

Then, build the ROS1 driver node and all its dependencies with:

catkin build

Lastly, source the development environment:

source devel/setup.bash

b) ROS2 steps

Source the setup.bash from the ROS2 distro repository (/opt/ros/{ROS_DISTRO}/setup.bash). For example:

source /opt/ros/$ROS_DISTRO/setup.bash

Then, build the ROS2 driver node and all its dependencies with:

colcon build

Lastly, source the development environment:

source install/setup.bash

ROS2, unlike ROS1, by default uses a install directory in the workspace. So when you do ros2 launch *, the configuration and launch files are taken from the install directory instead of src.

If you want to modify the parameters in the YAML files. You can:

• Modify the YAML file in the src directory and then re-run colcon build to update them into the install directory.

• Modify the YAML file in install. However, the next time you do colcon build they will be overridden by the files in src.

Launch the Driver

ROS1 steps

• To launch the node (serial or TCP mode), run:

roslaunch fixposition_driver_ros1 node.launch

• The user can also enable a verbose mode using the dev node as:

roslaunch fixposition_driver_ros1 dev.launch

ROS2 steps

• To launch the node (serial or TCP mode), run:

ros2 launch fixposition_driver_ros2 node.launch

• The user can also enable a verbose mode using the dev node as:

ros2 launch fixposition_driver_ros2 dev.launch

Driver configuration

To change the settings of the ROS driver, the user must adapt the launch/config.yaml file accordingly.

Some of the available options include:

• Configuring the TCP client or serial connection.

  • Serial (<device>:<baudrate>). E.g., stream: serial:///dev/ttyUSB0:115200.

  • TCP client (<ip_address>:<port>). E.g., stream: tcpcli://10.0.2.1:21000.

The performance of the serial driver is highly dependent on the configured baudrate and is not meant to handle high output rates or multiple simultaneous messages.

• Reconnect time tolerance (in seconds).

• Driver delay warning threshold (in seconds). Note that this warning only works if your system time is synced to the Vision-RTK2.

• Messages that should be used by the driver (e.g., FP_A-ODOMETRY, NMEA-GP-GGA, NOV_B-INSPVAX). Note that the sensor must be configured with the messages enabled in the correct port.

• Driver behavior:

  • fusion_epoch: Enable fusion epoch output.

    nmea_epoch: Enable NMEA epoch output and choose NMEA collector trigger.

    raw_output: Enable raw messages output.

    cov_warning: Enable covariance warnings. If the position change is bigger than the reported covariance, it will issue a warning.

    nav2_mode: Enable nav2 mode. Expands the TF tree to provide the necessary transformations.

• Namespace for output topics.

• Wheelspeed input topic (see Fixposition ROS Driver | Input-Wheelspeed-through-the-driver).

• Correction data input topic (see Fixposition ROS Driver | Streaming-RTCM3-messages-/-RTK-corrections).

• Wheelspeed odometry converter: Choose whether to enable this method, the input topic and message type, the scale factor of the measurements, and the enabled dimensions (see Fixposition ROS Driver | Fixposition-Odometry-Converter).