# Constellation lab specifications and interfacing This guide details the ATMOS free-flyer, its ROS 2 interface, coordinate frames, dynamics, and lab constraints. Continue with [Find your way around My Experiments](/docs/guide-1/) and [Build and submit your first dockerized experiment](/docs/guide-2/), then [Test a controller in the Gazebo simulation](/docs/guide-3/) before developing [your own experiment](/docs/guide-4/). ATMOS is an open-source, air-bearing free-flyer for space robotics research. For further platform details, see the [ATMOS project site](https://atmos.discower.io/) and the paper [Towards Open-Source and Modular Space Systems with ATMOS](https://arxiv.org/abs/2501.16973). The onboard computer uses an ARM64 processor, so images submitted for deployment must target `linux/arm64`. The [first experiment guide](/docs/guide-2/) shows the deployment build step; [the custom experiment guide](/docs/guide-4/) explains how to test and submit your own code. ## ATMOS Platform Specifications and Experiment Constraints | Component | ATMOS details | | --- | --- | | Size and mass | 0.4 m in diameter and about 0.5 m tall. Mass is approximately 17 kg. The moment of inertia about the z-axis is approximately 0.3 kg m^2. The center of mass is close to the geometric center. | | Thrusters | Eight thrusters, each producing about 1.4 N. They are driven by 10 Hz PWM. | | Flight controller | PX4 Autopilot handles low-level control, actuator allocation, sensor fusion, and vehicle modes. | | Onboard computer | NVIDIA Jetson Orin NX with an ARM64 processor, running Ubuntu 22.04 and ROS 2 Humble. High-level autonomy runs on this computer. Submitted images must target `linux/arm64`. | | Sensors | An IMU connected to the flight controller and laboratory motion-capture (MoCap) tracking. The onboard estimator fuses the available measurements. | | Air supply | 4.5 L, 300 bar compressed-air tank. | | Battery | 10 Ah, 6S LiPo. The air supply normally limits experiment time before the battery does. | Plan for no more than 10 minutes when the robot is actuated; aggressive use of the thrusters can shorten this further. When floating passively without actuation, an experiment can last up to about 1 hour. Account for these limits when planning your experiment. The usable motion area is limited to: $$ \begin{aligned} 0.00\,\text{m} &\le x \le 4.10\,\text{m} \\ -1.55\,\text{m} &\le y \le 1.75\,\text{m} \end{aligned} $$ The thrusters use 10 Hz PWM. Do not command actuator updates faster than 10 Hz. Plan trajectories and recovery behavior so the entire experiment stays inside these bounds. Avoid collisions with the lab boundary; do not plan to use contact as a stopping strategy. Remember that the robot has momentum and that the available braking force depends on its orientation and thruster commands. Three equivalent robots are available: `snap`, `crackle`, and `pop`. The service currently supports one robot per experiment. Multi-robot experiments are planned, but are not yet available through the Constellation service. ## ROS 2 Interface PX4 does not run ROS 2. A micro-DDS agent bridges selected messages between the flight controller and the ROS 2 network. In ROS 2, state topics use the `//fmu/out/` namespace, and commands use `//fmu/in/`. Here, `` is the selected robot name, such as `snap`, `crackle`, or `pop`. The available messages are configured on the flight-controller side. The list below covers commonly used topics; the full set can be larger or depend on the experiment configuration. In the simulation or experiment environment, inspect what is actually available: ```bash ros2 topic list ros2 topic info /snap/fmu/out/vehicle_odometry ros2 interface show px4_msgs/msg/VehicleOdometry ``` The `ros2 topic info` command uses `snap` as its example robot. Replace it with the selected robot name (`snap`, `crackle`, or `pop`). All flight-controller topics include that namespace; use `ros2 topic list` to check their full names. The full list of available ATMOS topics is published in [`dds_topics.yaml`](https://atmos.discower.io/assets/px4_autopilot/dds_topics.yaml). For PX4 message definitions and field details, see the [PX4 message reference](https://docs.px4.io/main/en/msg_docs/). | Topic | Description | | --- | --- | | `//fmu/out/vehicle_odometry` | Estimated position, velocity, attitude quaternion, and angular velocity. The estimate uses the available sensor fusion, including MoCap and the IMU. | | `//fmu/out/vehicle_status` | Vehicle state, including whether it is armed and the current control mode. ROS 2 control requires the vehicle to be armed and in Offboard mode. | | `//fmu/in/offboard_control_mode` | Continuously selects the Offboard control layer used by the controller. Send it at least 5 Hz while using Offboard control. | | `//fmu/in/vehicle_rates_setpoint` | Body angular-rate and normalized force command for the body-rate mode. | | `//fmu/in/vehicle_thrust_setpoint` and `//fmu/in/vehicle_torque_setpoint` | Normalized force and torque commands used together in the thrust-and-torque (wrench) mode. | | `//fmu/in/actuator_motors` | Per-thruster duty-cycle commands for direct allocation. This bypasses the flight controller's control allocation. | ### ATMOS Control Modes Three control modes are available: | Mode | Command from ROS 2 | What the flight controller does | | --- | --- | --- | | Body rate (`body_rate`) | Body angular velocity and normalized body force | Allocates the requested control to the thrusters. | | Wrench (`thrust_and_torque`) | Normalized body force and torque | Allocates the requested force and torque to the thrusters. | | Direct allocation (`direct_allocation`) | A normalized duty-cycle command for each of the eight thrusters, from 0 to 1 | Sends the per-thruster commands without flight-controller allocation. | Select the control layer by setting its corresponding flag in `//fmu/in/offboard_control_mode`: `body_rate` for body-rate control, `thrust_and_torque` for wrench control, or `direct_actuator` for direct allocation. Set the selected flag to true and leave the other Offboard mode flags false. ## Coordinate Frames and Transformations ATMOS and PX4 use different coordinate conventions: - **ATMOS world frame: ENU**: x points East, y points North, and z points Up. - **ATMOS body frame: FLU**: x points Forward, y points Left, and z points Up. - **PX4 world frame: NED**: x points North, y points East, and z points Down. - **PX4 body frame: FRD**: x points Forward, y points Right, and z points Down. The flight-controller-to-ATMOS frame conversions are: | Quantity | Conversion | | --- | --- | | Position and velocity | $(\text{north}, \text{east}, \text{down})_{\text{NED}} \to (\text{east}, \text{north}, -\text{down})_{\text{ENU}}$ | | Body angular velocity | $(\text{forward}, \text{right}, \text{down})_{\text{FRD}} \to (\text{forward}, -\text{right}, -\text{down})_{\text{FLU}}$ | | Attitude quaternion | For PX4 components $q_{\text{PX4}} = (q_w, q_x, q_y, q_z)$:
$q_{\text{ATMOS}} = {\frac{1}{\sqrt{2}} (q_w + q_z,\ q_x + q_y,\ q_x - q_y,\ q_w - q_z)}$ | These conversions are self-inverse and apply in either direction. Apply the corresponding conversion to frame-dependent values sent on `//fmu/in/`, from ATMOS ENU/FLU to NED/FRD. ## ATMOS Motion Model A basic model treats ATMOS as an actuated, frictionless rigid body. Let $p$ and $v$ be position and velocity in ENU, $q$ the FLU-to-ENU attitude quaternion, and $\omega$ angular velocity in FLU. $F$ and $T$ are the applied force and torque in the body frame; $m$ is mass; $J$ is body inertia; $R(q)$ maps body-frame vectors into ENU; $\Omega(\omega)$ is the quaternion-rate operator; and $\times$ denotes the vector cross product. The rigid-body equations are: $$ \begin{aligned} \dot{p} &= v \\ \dot{v} &= \frac{1}{m} R(q) F \\ \dot{q} &= \frac{1}{2} \Omega(\omega) q \\ \dot{\omega} &= J^{-1} \left( T - \omega \times J \omega \right) \end{aligned} \label{eq:rigid-body} $$ In the lab, the robot is constrained to x-y translation and z-axis rotation. ### Thruster Force and Torque Allocation The fixed thruster geometry maps physical thruster forces $u$ to body-frame force and z-axis torque. Each $u_i$ is between $0$ and $1.4\,\text{N}$; these are physical forces, not the normalized duty-cycle commands used in `direct_allocation` mode: $$ F_{xy} = \begin{bmatrix} 1 & -1 & 1 & -1 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & -1 & 1 & -1 & 1 \end{bmatrix} u \label{eq:force-allocation} $$ $$ T_z = r \begin{bmatrix} -1 & 1 & 1 & -1 & -1 & 1 & 1 & -1 \end{bmatrix} u \label{eq:torque-allocation} $$ Here, $r = 0.12\,\text{m}$ is the thruster torque arm. The maximum magnitude of each body-force component is $F_{\max} = 2 \cdot 1.4\,\text{N} = 2.8\,\text{N}$; the maximum yaw torque is $T_{\max} = 4 \cdot 1.4\,\text{N} \cdot 0.12\,\text{m} \approx 0.67\,\text{N\,m}$. For normalized setpoints, divide commanded body-force by $F_{\max}$ and body-torque by $T_{\max}$. ## Continue Continue to [Find your way around My Experiments](/docs/guide-1/) for a tour of the pages where you manage your experiments, then [Build and submit your first dockerized experiment](/docs/guide-2/). It introduces the container and service workflow before you move on to simulation and your own experiment.