Basilisk-ROS 2 Bridge

A lightweight, open-source communication bridge between the Basilisk astrodynamics simulation framework and ROS 2, enabling real-time, bidirectional data exchange.

This repository provides a ROS 2 interface for the Basilisk astrodynamics framework that enables spacecraft simulations to interact directly with ROS 2 nodes without requiring any modifications to Basilisk's core. The bridge connects Basilisk's high-fidelity spacecraft dynamics and simulation timing with ROS 2's distributed middleware.

Spacecraft states generated in Basilisk are published as ROS 2 topics, while commands such as forces, torques, or thruster states can be sent from ROS 2 back into the simulation. This allows standard ROS 2 tools and workflows (e.g., rosbag, RViz, PlotJuggler) to be applied directly to spacecraft simulations, and supports modular autonomy, estimation, control, and monitoring software running externally in ROS 2.

The bridge supports single- and multi-spacecraft scenarios using namespace-aware topic conventions, enabling scalable setups such as formation flying and coordinated control.

Citation

If you use this package in academic work, please cite:

E. Krantz, N. N. Chan, G. Tibert, H. Mao and C. Fuglesang, "Bridging the Basilisk Astrodynamics Framework with ROS 2 for Modular Spacecraft Simulation and Hardware Integration," 2025 International Conference on Space Robotics (iSpaRo), Sendai, Japan, 2025, doi: 10.1109/iSpaRo66239.2025.11437323.

IEEE Xplore | arXiv

BibTeX

@inproceedings{krantz2025bridging,
  title={Bridging the Basilisk Astrodynamics Framework with ROS 2 for Modular Spacecraft Simulation and Hardware Integration},
  author={Krantz, Elias and Chan, Ngai Nam and Tibert, Gunnar and Mao, Huina and Fuglesang, Christer},
  booktitle={2025 International Conference on Space Robotics (iSpaRo)},
  year={2025},
  organization={IEEE},
  doi={10.1109/iSpaRo66239.2025.11437323}
}

Quick Start

Prerequisites

• Basilisk

pip install bsk

• ROS 2 (e.g. Humble, Rolling)

MuJoCo scenario: pip install bsk does not currently include MuJoCo support. To run the MuJoCo examples in examples/mujoco/, build Basilisk from source with MuJoCo enabled instead:

python3 conanfile.py --mujoco True

export the user path of Basilisk to .bashrc as:

export BSK_PATH=<your-BSK-path>

and activate that Basilisk environment in the terminal running the MuJoCo scenario:

source $BSK_PATH/.venv/bin/activate

In order to visualize the results of the simulations make sure you install Vizard.

Install

1. Clone the repos:

cd <your-ros2-workspace>/src
git clone https://github.com/DISCOWER/bsk-msgs.git
git clone https://github.com/DISCOWER/bsk-ros2-bridge.git

2. Install the Basilisk bridge handler module rosBridgeHandler:

# Navigate to the bridge directory
cd <your-ros2-workspace>/src/bsk-ros2-bridge
# Install the bridge handler module
pip install -e .

If running basilisk with MuJoCo (Basilisk built from source), activate your Basilisk environment (source $BSK_PATH/.venv/bin/activate) before this step instead, and deactivate it before step 3.

3. Install the ROS 2 bridge package:

# Navigate to your ROS 2 workspace
cd <your-ros2-workspace>
# Install required python packages
pip install -r src/bsk-ros2-bridge/requirements.txt
# Build the ROS 2 bridge package and its dependencies
colcon build --packages-up-to bsk-ros2-bridge
source install/setup.bash

Run an Example

Terminal 1: Start the bridge

ros2 launch bsk-ros2-bridge bridge.launch.py

Terminal 2: Start a Basilisk scenario

python examples/scenarioRosOrbit_wrench.py

For the MuJoCo examples, activate your source-built Basilisk environment first: source $BSK_PATH/.venv/bin/activate.

Terminal 3: Verify topics

ros2 topic list

Closed-Loop Control Example

To run the scenario with closed-loop control, you can use the Basilisk-ROS 2 MPC.

Once the MPC controller is installed and sourced in your workspace, start it in a new terminal:

ros2 launch bsk-ros2-mpc mpc.launch.py namespace:=bskSat0

Example Scenarios

Scenario	Description	Control Mode
scenarioRosBasic_da.py	Single spacecraft (no Earth)	da
scenarioRosBasic_wrench.py	Single spacecraft (no Earth)	wrench
scenarioRosOrbit_da.py	Spacecraft orbiting Earth	da
scenarioRosOrbit_wrench.py	Spacecraft orbiting Earth	wrench
scenarioRosLeaderFollowerBasic_wrench.py	1 leader + 2 followers (no Earth)	wrench
scenarioRosLeaderFollowerOrbit_wrench.py	1 leader + 2 followers (orbit)	wrench
mujoco/scenarioRosMujoco_wrench.py	Two satellites on a collision course with MuJoCo multibody dynamics	wrench

Notes:

da (direct allocation) commands individual thrusters via /<ns>/bsk/in/thr_array_cmd_force. wrench commands 3D forces and torques via /<ns>/bsk/in/cmd_force and /<ns>/bsk/in/cmd_torque, mapped to thrusters by Basilisk.

The orbit scenarios support any number of spacecraft. Launch one controller per namespace (e.g., /bskSat0, /bskSat1).

All spacecraft models used in the scenarios are based on ATMOS in terms of size, thruster configuration, and inertia properties.

Development Guide

Integrating RosBridgeHandler in a Scenario

A minimal setup looks like:

# Add RosBridgeHandler module
from bsk_ros2_bridge import RosBridgeHandler
ros_bridge = RosBridgeHandler()

# Add publisher (Basilisk → ROS 2)
ros_bridge.add_ros_publisher('SCStatesMsgPayload', 'SCStatesMsgIn', 'sc_states', 'bskSat', max_rate=50.0)

# Add subscriber (ROS 2 → Basilisk)  
ros_bridge.add_ros_subscriber('CmdForceBodyMsgPayload', 'CmdForceBodyMsgOut', 'cmd_force', 'bskSat')

# Connect messages to Basilisk modules
ros_bridge.bskSat.SCStatesMsgIn.subscribeTo(scObject.scStateOutMsg)
thrForceMapping.cmdForceInMsg.subscribeTo(ros_bridge.CmdForceBodyMsgOut)

# Add the module to a simulation task
scSim.AddModelToTask(simTaskName, ros_bridge)

This would result in the following ROS 2 publisher and subscriber:
/bskSat/bsk/out/sc_states
/bskSat/bsk/in/cmd_force

Registering ROS 2 Publishers and Subscribers

# Publisher: Sends Basilisk data to ROS 2
ros_bridge.add_ros_publisher(msg_type_name, handler_name, topic_name, namespace, max_rate=None, rate_is_real_time=False)

# Subscriber: Receives ROS 2 commands in Basilisk
ros_bridge.add_ros_subscriber(msg_type_name, handler_name, topic_name, namespace)

Parameters:

• msg_type_name - Basilisk message type (e.g., 'SCStatesMsgPayload', 'CmdForceBodyMsgPayload')
• handler_name - Internal message handler (e.g., 'SCStatesMsgIn', 'CmdForceBodyMsgOut')
• topic_name - ROS 2 topic name (e.g., 'sc_states', 'cmd_force')
• namespace - Spacecraft identifier (e.g., 'bskSat', 'bskSat0')
• max_rate - (Publishers only) optional maximum publishing rate (Hz). If not specified, publishes at the task rate.
• rate_is_real_time - (Publishers only) if True, max_rate is a real-world (wall-clock) Hz even if accelFactor changes at runtime. If False (default), max_rate is a simulated-time Hz, so the effective real-world publish rate scales with accelFactor.

Topic Structure

Topics follow the pattern: /<namespace>/bsk/<in|out>/<topic_name>

Common Topics:

• /clock - Simulation time synchronization (if publish_clock is enabled)
• /<namespace>/bsk/out/sc_states - Spacecraft states
• /<namespace>/bsk/in/thr_array_cmd_force - Thruster commands
• /<namespace>/bsk/in/cmd_force - Force commands
• /<namespace>/bsk/in/cmd_torque - Torque commands

Time Synchronization

If publish_clock is enabled (default: True), the bridge publishes /clock at a fixed real-world rate set by clock_rate, independent of accelFactor. ROS 2 nodes should use use_sim_time:=true to follow simulated time. Set publish_clock:=false to disable /clock entirely and have nodes use system time instead.

ros2 launch bsk-ros2-bridge bridge.launch.py publish_clock:=true clock_rate:=1000.0

QoS Settings

All topics use the following ROS 2 Quality of Service (QoS):

• Reliability: BEST_EFFORT
• Durability: VOLATILE
• History: KEEP_LAST
• Queue depth: 1

This configuration prioritizes low-latency communication and ensures that only the most recent message is delivered, suitable for high-rate spacecraft simulation data.

Port Configuration

Bridge launch arguments:

Argument	Default	Description
pub_port	5550	ZMQ port: Basilisk → Bridge
sub_port	5551	ZMQ port: Bridge → Basilisk
heartbeat_port	5552	ZMQ heartbeat port
publish_clock	True	Whether to publish /clock
clock_rate	1000.0	/clock publish rate (Hz, real/wall-clock time)
namespace	''	Bridge namespace

To set custom ports:

ros2 launch bsk-ros2-bridge bridge.launch.py pub_port:=6550 sub_port:=6551 heartbeat_port:=6552

ros_bridge = RosBridgeHandler(send_port=6550, receive_port=6551, heartbeat_port=6552)

RosBridgeHandler arguments:

Parameter	Default	Description
ModelTag	'ros_bridge'	Module identifier for logging
send_port	5550	ZMQ port for sending data to bridge (BSK → ROS 2)
receive_port	5551	ZMQ port for receiving data from bridge (ROS 2 → BSK)
heartbeat_port	5552	ZMQ port for heartbeat monitoring
accelFactor	1.0	Simulation speed factor, used to scale /clock time and rate_is_real_time publishers
requireBridge	False	If True, Basilisk waits for the bridge to be reachable before the simulation starts, and waits (blocks) whenever the connection is lost until it's restored
clockSync	None	Reference to the scenario's ClockSynch module. Only used when requireBridge=True, to keep simulation playback speed consistent after the bridge connection is restored.

Tested Configurations

Environment	ROS 2 Distro	Notes
Ubuntu 22.04 LTS	Humble	Full build, CLI tools, and launch files tested
Ubuntu 24.04 LTS	Jazzy	Full build, CLI tools, and launch files tested
Windows (WSL, Ubuntu 24.04)	Rolling	Build and topic communication verified

WSL note: Locale settings may need correction (see ROS 2 docs). Minor GUI latency (e.g., BSK-Vizard) is expected; CLI tools work normally.

Troubleshooting

Missing message types: ensure bsk_msgs is built and sourced.

Missing rosBridgeHandler: ensure you have installed the package (see Installation step 2).

Basilisk built from source: if you built Basilisk from source (e.g. for MuJoCo support) rather than via pip install bsk, activate its environment (source <your-basilisk-path>/.venv/bin/activate) in the terminal running the scenario.

Ctrl+C won't stop a scenario waiting for bridge connection: while waiting for the bridge connection, Ctrl+C may not respond. Restart the bridge to resume and exit normally, or run kill <pid>.

Port conflicts: check with lsof -i :5550 and kill any processes using the port if needed.

References

• Basilisk-ROS 2 Messages
• Basilisk-ROS 2 MPC
• Basilisk: an Astrodynamics Simulation Framework
• Basilisk GitHub
• ROS 2 Documentation
• ZeroMQ Documentation