cybership_common

This repository is the home of the CyberShip Software Suite - a collection of ROS 2 packages that together provide the tools to simulate, visualize, and control autonomous maritime vessels. The suite covers everything from the digital twin (URDF models and visualization) to real-time sensor integration (IMU, motion capture, etc.) and advanced control (dynamic positioning and thrust allocation).

What's Included

• cybership_bringup: Launch files to initialize all the necessary nodes for bringing up a vessel in a ROS 2 environment. This includes hardware drivers, localization, and sensor integration.
• cybership_simulator: Simple Python scripts for vessel simulation using basic physics. Use these scripts to test vessel behavior in simulation.
• cybership_viz: Nodes and configurations to visualize the vessel in RViz. This package provides a visual representation of the vessel using its URDF models.
• cybership_description: URDF models and coordinate frame definitions for accurate vessel representation.
• cybership_config: Centralized configuration files that are shared and used by various components in the suite.
• cybership_interfaces: Common message and service definitions to standardize communication across the suite.
• Other modules: Additional packages for utilities, thruster control, dynamic positioning, and sensor drivers like BNO055 and motion capture (mocap).

Installation

Follow these steps to set up your ROS 2 workspace with the CyberShip Software Suite:

Important

Make sure that you have sourced the ROS 2 installation

source /opt/ros/<distro>/setup.bash

Replace <distro> with your ROS 2 distribution (e.g., humble, jazzy, etc.).

Note

Guides assumes you have $ROS_WORKSPACE environment variable set to the root of your ROS 2 workspace. ROS workspace is usually is at ~/ros_ws or similar. You can set this variable

export ROS_WORKSPACE=~/ros_ws

or add it to your shell configuration file (e.g., ~/.bashrc) for persistence.

Note

The following instructions assume you have already set up a ROS 2 workspace. If you haven't done so, you can create one using the following commands:

mkdir -p $ROS_WORKSPACE/src
cd $ROS_WORKSPACE
colcon build
source install/setup.bash

For the lazy ones

You can use the provided installation script to automate the setup process:

curl -fsSL https://raw.githubusercontent.com/NTNU-MCS/cybership_software_suite/refs/heads/master/lazy_install.sh | bash

For the ones who like to read

1. Clone the Repository and Submodules

   cd $ROS_WORKSPACE/src
   git clone https://github.com/NTNU-MCS/cybership_software_suite
   cd cybership_software_suite
   git submodule update --init --recursive
   

2. Set Up a Python Virtual Environment

   cd $ROS_WORKSPACE
   python3 -m venv venv --system-site-packages --symlinks
   source venv/bin/activate
   touch venv/COLCON_IGNORE

3. Install Python Dependencies

   cd $ROS_WORKSPACE
   source venv/bin/activate
   find src/cybership_software_suite -name "requirements*txt" -exec pip install -r {} \;

4. Install ROS Dependencies and Build

   cd $ROS_WORKSPACE
   rosdep install --from-paths src -i
   colcon build --symlink-install

Warning

Make sure that you have initialized rosdep and sourced the ROS 2 environment before running the above command. You can do this by running:

source /opt/ros/<distro>/setup.bash
sudo rosdep init
rosdep update

Replace <distro> with your ROS 2 distribution (e.g., humble, jazzy, etc.). If you encounter any issues with dependencies, please refer to the documentation of the specific package for additional instructions.

1. Source the Environment

   source $ROS_WORKSPACE/venv/bin/activate
   source $ROS_WORKSPACE/install/setup.bash

Bringing Up a Vessel

There are two main modes to bring up a vessel: physical and simulation.

For a Physical Deployment: Use the cybership_bringup package. For example, to bring up the Voyager vessel, run:

ros2 launch cybership_bringup voyager.launch.py vessel_name:=voyager vessel_model:=voyager

You can similarly launch other vessel types like Enterprise or Drillship by choosing the corresponding launch file in cybership_bringup.

For Simulation: Use the cybership_simulator package. This runs simplified physics scripts:

Visualization

Visualize your vessel using the RViz visualization tools provided in the suite. The cybership_viz package sets up RViz with a preconfigured scene showing your vessel's URDF model and sensor data overlays. To launch visualization:

Additionally, the cybership_description package can publish the URDF model via:

Additional Notes

Dynamic Positioning: The cybership_dp package provides controllers for dynamic positioning. Launch the complete DP system or individual controllers as needed.

Sensor Integration & Drivers

The suite integrates various sensors such as the BNO055 IMU and motion capture systems. Please refer to corresponding packages (e.g., cybership_external/bno055 and cybership_mocap) for detailed instructions.

Utilities and Interfaces

Use the utility functions in cybership_utilities for standardized launch arguments and helper functions across your launch files. Common interfaces are provided in cybership_interfaces.

Docker

docker compose --profile voyager up

Documentation

The documentations is mostly done through readme files of the subpackages and inline comments. Operational manual is available here.