ATMOS CW Emulation

A dual-actuation control stack that physically emulates relative orbital dynamics, expressed by the linearized Clohessy-Wiltshire (CW) equations, on the ATMOS free-flyer. Two Model Predictive Controllers (MPC) run in parallel: a spacecraft MPC drives the solenoid thrusters and represents the spacecraft under test, while a CW dynamics MPC drives the bidirectional propellers to physically apply the scaled orbital accelerations. A dynamic similitude maps the orbital scenario onto the testbed, letting the spacecraft controller run directly at orbital scale.

The stack contains three controllers:

• CW dynamics MPC: applies the scaled CW accelerations with the propeller module.
• Spacecraft MPC (ATMOS): the spacecraft's onboard controller, commanding the solenoid thrusters via PX4 messages.
• Spacecraft MPC (Basilisk): the identical spacecraft controller, interfaced to the Basilisk astrodynamics framework for high-fidelity orbital validation.

The two spacecraft MPCs differ only in their message interface (PX4 or Basilisk), so the identical controller can be validated on the free-flyer and in high-fidelity simulation without modification. The MPCs are based on px4-mpc.

Quick Start

Prerequisites

• acados

For the CW dynamics MPC and spacecraft MPC (ATMOS):

• px4_msgs
• ATMOS Propeller Plate Interface

For the spacecraft MPC (Basilisk):

• Basilisk, Basilisk-ROS 2 Bridge and Basilisk-ROS 2 Messages

Install

cd <your-ros2-workspace>/src
git clone https://github.com/DISCOWER/atmos_cw_emulation.git
cd ..
colcon build --packages-up-to atmos_cw_emulation
source install/setup.bash

Usage

Emulation on ATMOS

The CW dynamics MPC and the spacecraft MPC run together. They can run against either PX4 SITL with the gz_atmos_dual airframe, or the real ATMOS hardware. See atmos.discower.io for platform setup and the propeller module documentation.

Terminal 1: Launch the CW dynamics MPC, and let it converge on a starting position

ros2 launch atmos_cw_emulation atmos_cw_dynamics.launch.py

Terminal 2: Once still at starting position, launch the spacecraft MPC

ros2 launch atmos_cw_emulation sc_mpc_atmos.launch.py

Validation in Basilisk

In Basilisk, the orbital accelerations arise naturally from the simulated dynamics, so no CW dynamics MPC is required and the spacecraft controller runs alone.

Terminal 1: Start the bridge (see bridge Quick Start)

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

Terminal 2: Start the Basilisk scenario

python bsk_scenario/bsk_scenario.py

Terminal 3: Launch the spacecraft MPC

ros2 launch atmos_cw_emulation sc_mpc_bsk.launch.py

Launch Options

atmos_cw_dynamics.launch.py

Argument	Default	Description
namespace	crackle	ROS 2 namespace for all nodes
skip_build	False	Skip acados solver codegen/build and reuse an existing compiled solver
orbit_period	100.0	Period of the represented orbit in minutes
lambda_t	1.0	Time scaling factor

sc_mpc_atmos.launch.py and sc_mpc_bsk.launch.py

Argument	Default	Description
namespace	crackle	ROS 2 namespace for all nodes
skip_build	False	Skip acados solver codegen/build and reuse an existing compiled solver
orbit_period	100.0	Period of the represented orbit in minutes
lambda_t	50.0	Time scaling factor
lambda_l	100.0	Length scaling factor
lambda_m	8.0	Mass scaling factor
lambda_J	80.0	Inertia scaling factor

sc_mpc_bsk.launch.py additionally accepts use_sim_time (default True) to synchronize with the /clock topic.

Notes:

• The time and length factors map the orbital scenario onto the laboratory duration and floor area, while the mass and inertia factors are the spacecraft-to-platform ratios. The defaults reproduce the scenario in the paper (100 min orbit mapped onto a 2 min laboratory period).
• Use the same orbit_period and scaling factors for both controllers so they emulate the same orbit.
• skip_build:=True is useful for faster startup when the solver has already been generated for the same controller/model configuration.

Troubleshooting

Missing acados dependencies: If the launch fails during solver generation, ensure the Python package acados_template is installed and that $ACADOS_SOURCE_DIR is correctly exported in your .bashrc.

Shared library error: If you encounter ImportError: libacados.so: cannot open shared object file, ensure your $LD_LIBRARY_PATH includes $ACADOS_SOURCE_DIR/lib.

Missing message types: If you receive errors about unknown types, ensure px4_msgs (ATMOS) or bsk_msgs (Basilisk) are built and your workspace is fully sourced.

Missing propeller plate interface: If the CW dynamics launch fails to find propeller_plate_iface, ensure the ATMOS Propeller Plate Interface is cloned into your workspace and built.

References

• ATMOS platform
• ATMOS Propeller Plate Interface
• px4-mpc
• PX4 Autopilot
• Basilisk Astrodynamics Simulation
• Basilisk-ROS 2 Bridge
• Basilisk-ROS 2 Messages
• acados
• ROS 2 Documentation