ros2_control in MoveIt Pro
MoveIt Pro's robot controllers run within ros2_control, the standard ROS 2 framework for real-time hardware control. They keep their real-time control logic in framework-agnostic libraries, with ros2_control as the integration layer, not the implementation.
This page explains how that stack is put together, which controllers MoveIt Pro ships, the safety checks each controller performs while the robot is moving, and where safety remains the responsibility of the robot hardware and the system integrator.
It assumes you have completed the beginner tutorials and understand Objectives and motion planning at a high level.
For configuring the ros2_control section of a robot configuration package, see the ros2_control configuration reference.
The control stack
MoveIt Pro is layered. The task and planning layers decide what the robot should do; the control layer turns that decision into a hardware command every control cycle.
The boundary between non-real-time and real-time work is the controller_manager.
A controller's update() method and the hardware interface's read() and write() run synchronously inside the controller_manager's real-time loop. Everything above it (Behavior Tree ticks, planning, ROS service and action callbacks) runs in non-real-time threads and hands data to the real-time loop through lock-free buffers.
The real-time loop rate is set once for the whole controller_manager at startup, not per controller. The authoritative rate for a given robot is its controller_manager configuration.
Every runtime safety check described below runs inside a controller's update(). If the real-time loop itself stops running, those checks cannot fire, because the controllers are not executing. Detecting a stalled real-time loop is the responsibility of the hardware and the surrounding system, not of any single controller. See Safety responsibilities outside MoveIt Pro.
Controllers in MoveIt Pro
MoveIt Pro ships several first-party ros2_control controllers and also supports the upstream joint_trajectory_controller. Only one controller can command a given hardware interface at a time, so MoveIt Pro switches controllers to move between tasks, for example from executing a planned trajectory to teleoperating.
| Controller | Role | Typical use |
|---|---|---|
| Joint Trajectory Admittance Controller (JTAC) | Executes joint-space trajectories, with optional Cartesian compliance driven by a force/torque sensor. | Planned motions, including force-compliant ones such as insertions and surface following. |
| Joint Velocity Controller (JVC) | Follows streamed joint-velocity commands. | Teleoperation and closed-loop velocity streaming (visual servoing, learned policies). |
| Velocity Force Controller (VFC) | Follows streamed Cartesian velocity commands, optionally augmented by a force setpoint. | Cartesian teleoperation and hybrid velocity/force tasks. |
io_controller | Triggers digital I/O (GPIO) outputs. | Grippers, suction, and other tools. |
Upstream joint_trajectory_controller (JTC) | Executes joint-space trajectories without admittance. | Planned motions when Cartesian compliance is not needed. |
JTAC consumes trajectories through a ROS 2 action; JVC and VFC consume streamed commands from topics. The how-to guides walk through using them: executing position trajectories with admittance and streaming velocities and force.
Runtime safety
MoveIt Pro's controllers are not just command followers. Each one runs safety checks every control cycle and, depending on the check, either clamps the command back within limits or brings the robot to a controlled stop rather than continuing blindly or releasing the joints.
Trajectory tracking (JTAC)
While executing a trajectory, JTAC compares the commanded joint positions (the trajectory sampled at the current time) against the measured joint positions every cycle:
- Path tolerance. If any joint deviates from its commanded position by more than
path_tolerance(default 0.05 rad), JTAC aborts and brakes to a stop. - Goal tolerance. At the end of the trajectory, JTAC verifies that every joint is within
goal_tolerance(default 0.05 rad) of its target, and aborts if not.
Force and torque limit (JTAC)
When admittance is active, JTAC compares the filtered measured wrench against absolute_force_torque_threshold per axis every cycle. The default is 45 N of force along the X, Y, Z axes and 10 Nm of torque about each. Exceeding it on any axis aborts the motion and brakes to a stop; this force limit is separate from the spring-mass-damper compliance.
Streamed-command safety (JVC and VFC)
The velocity controllers do not track a pre-planned trajectory, so they enforce safety on the commands they receive and the motion they generate:
- Command timeout. If no new command arrives within
command_timeout(default 0.2 s), the controller stops. For streamed control this means the robot stops on its own when commands stop arriving. - Joint position-limit prediction. Each cycle, the controller asks whether a maximum-deceleration stop, started now, would carry a joint past its soft position limit (with a
joint_limit_position_tolerancemargin, default 0.02 rad). If so, it stops before the limit is reached. - Velocity and acceleration clamping. Commanded velocities and accelerations that exceed the configured per-joint limits (and, for VFC, the per-Cartesian-axis limits) are scaled down uniformly so the direction of motion is preserved.
Controlled stops
Every first-party controller stops by braking along a deceleration profile, not by cutting the command to zero or releasing the joints. JTAC uses the configured stop_accelerations; JVC and VFC use the configured joint acceleration limits. JTAC additionally reports a trajectory action as finished only once the robot has fully stopped.
Non-finite value rejection
The controllers check for non-finite values (NaN and ±Inf) at every boundary: commanded inputs, sensor and joint-state readings, generated setpoints, and the final hardware command. On detection the controller stops the robot (or refuses to start if idle) and logs the offending value instead of forwarding it to hardware. Each controller's README covers its specific checks.
Summary of runtime checks
The set of runtime guarantees you get depends on which controller is driving the robot.
| Runtime check | JTAC | JVC | VFC |
|---|---|---|---|
| Measured-vs-commanded tracking (path / goal tolerance) | Yes | No | No |
| Command-stream timeout stop | Action-based, n/a | Yes (0.2 s) | Yes (0.2 s) |
| Joint position-limit prediction | No | Yes | Yes |
| Velocity / acceleration clamp | Stop trajectory only | Yes | Yes (joint and Cartesian) |
| Absolute force/torque abort | Yes | n/a | No |
| Non-finite (NaN/Inf) rejection (9.4+) | Yes | Yes | Yes |
| Controlled deceleration stop on abort | Yes | Yes | Yes |
Each controller's API documentation, linked from the controllers table above, lists its full parameter set and defaults.
Safety responsibilities outside MoveIt Pro
MoveIt Pro's software checks reduce risk during normal operation, but they are not a substitute for functional safety. MoveIt Pro is not a safety-rated system, and the following must be provided by the robot, its driver, and the surrounding installation.
- Emergency stop. There is no software emergency-stop path in MoveIt Pro. A safety-rated stop must be a physical chain (emergency-stop circuit, safety relay or safety PLC, contactor) that removes drive power independently of the software. The WebUI "stop" is a cooperative stop handled at the next Behavior Tree tick; it is not an emergency stop.
- Safe state on fault. When a controller is deactivated it releases its hardware interfaces without commanding a hold or zero. Reaching a safe state is left to the robot driver and the physical safety chain. See Configure Hardware Protective Stop for integrating a vendor protective stop with MoveIt Pro.
- Real-time loop health. The runtime checks above only run while the real-time loop is running. Monitoring that the loop is alive and meeting its deadline is a responsibility of the hardware and the surrounding system.
- Direct control access. A process that drives a controller directly over ROS 2 (streaming to a topic or sending an action goal) bypasses the task and planning layers, and with them the pre-execution collision and validity checks. The safety floor in that case is whatever the chosen controller enforces, as summarized above.