You're reading the documentation for an older, but still supported, version of ROS 2. For information on the latest version, please have a look at Kilted.

Humble to Jazzy

General

A version.h file will be generated per package using the ament_generate_version_header (#1449). For example, you can include the version of the package in the logs.
```
#include <controller_manager/version.h>
...
RCLCPP_INFO(get_logger(), "controller_manager version: %s", CONTROLLER_MANAGER_VERSION_STR);
```

controller_interface

For details see the controller_manager section.

Pass URDF to controllers on init (#1088).
Pass controller manager update rate on the init of the controller interface (#1141)
A method to get node options to setup the controller node #api-breaking (#1169)
Export state interfaces from the chainable controller #api-breaking (#1021)
All chainable controllers must implement the method export_state_interfaces to export the state interfaces, similar to export_reference_interfaces method that is exporting the reference interfaces.
The controllers will now set use_global_arguments from NodeOptions to false, to avoid getting influenced by global arguments (Issue : #1684) (#1694). From now on, in order to set the parameters to the controller, the --param-file option from spawner should be used.
With (#1683) the rclcpp_lifecycle::State & get_state() and void set_state(const rclcpp_lifecycle::State & new_state) are replaced by rclcpp_lifecycle::State & get_lifecycle_state() and void set_lifecycle_state(const rclcpp_lifecycle::State & new_state). This change affects controllers and hardware. This is related to (#1240) as variant support introduces get_state and set_state methods for setting/getting state of handles.
The assign_interfaces and release_interfaces methods are now virtual, so that the user can override them to store the interfaces into custom variable types, so that the user can have the flexibility to take the ownership of the loaned interfaces to the controller (#1743)
The new PoseSensor semantic component provides a standard interface for hardware providing cartesian poses (#1775)
The controllers now support the fallback controllers (a list of controllers that will be activated, when the spawned controllers fails by throwing an exception or returning return_type::ERROR during the update cycle) (#1789)
The controllers can be easily introspect the internal member variables using the macro REGISTER_ROS2_CONTROL_INTROSPECTION (#1918)
A new SemanticComponentCommandInterface semantic component provides capabilities analogous to the SemanticComponentInterface, but for write-only devices (#1945)
The new semantic command interface LedRgbDevice provides standard (command) interfaces for 3-channel LED devices (#1945)
The new MagneticFieldSensor semantic component provides an interface for reading data from magnetometers. (#2627)
The controller_manager will now deactivate the entire controller chain if a controller in the chain fails during the update cycle. (#2681)
The update rate of the controller will now be approximated to a closer achievable frequency, when its frequency is not achievable with the current controller manager update rate. (#2828)
The lifecycle ID is cached internally in the controller to avoid calls to get_lifecycle_state() in the real-time control loop. (#2884)

controller_manager

URDF is now passed to controllers on init (#1088) This should help avoiding extra legwork in controllers to get access to the /robot_description.
Pass controller manager update rate on the init of the controller interface (#1141)
Report inactive controllers as a diagnostics ok instead of an error (#1184)
Set chained controller interfaces ‘available’ for activated controllers (#1098)
- Configured chainable controller: Listed exported interfaces are unavailable and unclaimed
- Active chainable controller (not in chained mode): Listed exported interfaces are available but unclaimed
- Active chainable controller (in chained mode): Listed exported interfaces are available and claimed
Try using SCHED_FIFO on any kernel (#1142)
A method to get node options to setup the controller node was added (#1169): get_node_options can be overridden by controllers, this would make it easy for other controllers to be able to setup their own custom node options
CM now subscribes to robot_description topic instead of ~/robot_description (#1410).
Change the controller sorting with an approach similar to directed acyclic graphs (#1384)

Changes from (PR #1256)

All joints defined in the <ros2_control>-tag have to be present in the URDF received by the controller manager, otherwise the following error is shown:

The published robot description file (URDF) seems not to be genuine. The following error was caught: <unknown_joint> not found in URDF.

This is to ensure that the URDF and the <ros2_control>-tag are consistent. E.g., for configuration ports use gpio interface types instead.

The syntax for mimic joints is changed to the official URDF specification.

<joint name="right_finger_joint" type="prismatic">
  <axis xyz="0 1 0"/>
  <origin xyz="0.0 -0.48 1" rpy="0.0 0.0 0.0"/>
  <parent link="base"/>
  <child link="finger_right"/>
  <limit effort="1000.0" lower="0" upper="0.38" velocity="10"/>
</joint>
<joint name="left_finger_joint" type="prismatic">
  <mimic joint="right_finger_joint" multiplier="1" offset="0"/>
  <axis xyz="0 1 0"/>
  <origin xyz="0.0 0.48 1" rpy="0.0 0.0 3.1415926535"/>
  <parent link="base"/>
  <child link="finger_left"/>
  <limit effort="1000.0" lower="0" upper="0.38" velocity="10"/>
</joint>

The parameters within the ros2_control tag are not supported any more.

The support for the description parameter for loading the URDF was removed (#1358).
The --controller-type or -t spawner arg is removed. Now the controller type is defined in the controller configuration file with type field (#1639).
The --namespace or -n spawner arg is deprecated. Now the spawner namespace can be defined using the ROS 2 standard way (#1640).
Added support for the wildcard entries for the controller configuration files (#1724).
The spawner now supports the --controller-ros-args argument to pass the ROS 2 node arguments to the controller node to be able to remap topics, services and etc (#1713).
The spawner now supports parsing multiple -p or --param-file arguments, this should help in loading multiple parameter files for a controller or for multiple controllers (#1805).
--switch-timeout was added as parameter to the helper scripts spawner.py and unspawner.py. Useful if controllers cannot be switched immediately, e.g., paused simulations at startup (#1790).
ros2_control_node can now handle the sim time used by different simulators, when use_sim_time is set to true (#1810).
The ros2_control_node node now accepts the thread_priority parameter to set the scheduler priority of the controller_manager’s RT thread (#1820).
The ros2_control_node node has a new lock_memory parameter to lock memory at startup to physical RAM in order to avoid page faults (#1822).
The ros2_control_node node has a new cpu_affinity parameter to bind the process to a specific CPU core. By default, this is not enabled. (#1852).
The --service-call-timeout was added as parameter to the helper scripts spawner.py. Useful when the CPU load is high at startup and the service call does not return immediately (#1808).
The cpu_affinity parameter can now be of type int or int_array to bind the process to a specific CPU core or multiple CPU cores. (#1915).
The pal_statistics is now integrated into the controller_manager, so that the controllers, hardware components and the controller_manager can be easily introspected and monitored using the topics ~/introspection_data/names and ~/introspection_data/values (#1918).
A python module test_utils was added to the controller_manager package to help with integration testing (#1955).
A new parameter enforce_command_limits is introduced to be able to enable and disable the enforcement of the command limits (#1989).
A latched topic ~/activity has been added to the controller_manager to publish the activity of the controller_manager, where the change in states of the controllers and the hardware components are published. (#2006).
The controller manager will use a monotonic clock for triggering read-update-write cycles, but when the use_sim_time parameter is set to true, it will use the ROS Clock for triggering. When monotonic clock is being used, all the hardware components will receive the monotonic time in their read and write method, instead the controllers will always receive the ROS time in their update method irrespective of the clock being used. (#2046).
The default strictness of the switch_controllers can now we be chosen using ROS 2 parameters. The default behaviour is still left to BEST_EFFORT (#2168).
Parameter shutdown_on_initial_state_failure was added to avoid shutting down on hardware initial state failure (#2230).
The controller manager now publishes ~/statistics/names and ~/statistics/values topics to introspect the execution time and periodicity of the different entities running in the realtime loop (#2449).
The controller manager now supports switching (activating and deactivating) controllers in both realtime and non-realtime modes. This is controlled by the parameter activate_asap of the switch_controllers service (#2452).
The spawner now supports two new arguments --switch-asap and --no-switch-asap to control the behaviour of the spawner when switching controllers to be in realtime loop (or) non-realtime loop. By default, it is set to --switch-asap to keep the earlier behavior (#2610).
New parameters overruns.manage and overruns.print_warnings were added to control the behavior of the controller manager/ros2_control_node when overruns occur (#2546).
The bcolors class now respects the RCUTILS_COLORIZED_OUTPUT environment variable to automatically disable colors in non-TTY and CI environments.
A new parameter handle_exceptions is added to the controller manager to control whether exceptions thrown by controllers during update are caught and handled internally or propagated. (#2807)

hardware_interface

A portable version for string-to-double conversion was added: hardware_interface::stod (#1257)
test_components was moved to its own package (#1325)

The ros2_control tag now supports parsing of the limits from the URDF into the HardwareInfo structure. More conservative limits can be defined using the min and max attributes per interface (#1472)

<ros2_control name="RRBotSystemMutipleGPIOs" type="system">
  <hardware>
    <plugin>ros2_control_demo_hardware/RRBotSystemPositionOnlyHardware</plugin>
    <param name="example_param_hw_start_duration_sec">2.0</param>
    <param name="example_param_hw_stop_duration_sec">3.0</param>
    <param name="example_param_hw_slowdown">2.0</param>
  </hardware>
  <joint name="joint1">
    <command_interface name="position">
      <param name="min">-1</param>
      <param name="max">1</param>
    </command_interface>
    <command_interface name="velocity">
      <limits enable="false"/>
    </command_interface>
    <state_interface name="position"/>
  </joint>
</ros2_control>

Soft limits are also parsed from the URDF into the HardwareInfo structure for the defined joints (#1488)
Access to logger and clock through get_logger and get_clock methods in ResourceManager and HardwareComponents Actuator, Sensor and System (#1585)

The ros2_control tag now supports parsing read/write rate rw_rate for the each hardware component parsed through the URDF (#1570)

<ros2_control name="RRBotSystemMutipleGPIOs" type="system" rw_rate="500">
  <hardware>
    <plugin>ros2_control_demo_hardware/RRBotSystemPositionOnlyHardware</plugin>
    <param name="example_param_hw_start_duration_sec">2.0</param>
    <param name="example_param_hw_stop_duration_sec">3.0</param>
    <param name="example_param_hw_slowdown">2.0</param>
  </hardware>
  <joint name="joint1">
    <command_interface name="position"/>
    <command_interface name="velocity"/>
    <state_interface name="position"/>
  </joint>
  <joint name="joint2">
    <command_interface name="position"/>
    <state_interface name="position"/>
  </joint>
</ros2_control>
<ros2_control name="MultimodalGripper" type="actuator" rw_rate="200">
  <hardware>
    <plugin>ros2_control_demo_hardware/MultimodalGripper</plugin>
  </hardware>
  <joint name="parallel_fingers">
    <command_interface name="position">
      <param name="min">0</param>
      <param name="max">100</param>
    </command_interface>
    <state_interface name="position"/>
  </joint>
  <gpio name="suction">
    <command_interface name="suction"/>
    <state_interface name="suction"/>
  </gpio>
</ros2_control>

Added get_hardware_info method to the hardware components interface to access the HardwareInfo instead of accessing the variable info_ directly (#1643)
With (#1683) the rclcpp_lifecycle::State & get_state() and void set_state(const rclcpp_lifecycle::State & new_state) are replaced by rclcpp_lifecycle::State & get_lifecycle_state() and void set_lifecycle_state(const rclcpp_lifecycle::State & new_state). This change affects controllers and hardware. This is related to (#1240) as variant support introduces get_state and set_state methods for setting/getting state of handles.
With (#1421) a key-value storage is added to InterfaceInfo. This allows to define extra params with per Command-/StateInterface in the .ros2_control.xacro file.
With (#1763) parsing for SDF published to robot_description topic is now also supported.
With (#1567) all the Hardware components now have a fully functional asynchronous functionality, by simply adding is_async tag to the ros2_control tag in the URDF. This will allow the hardware components to run in a separate thread, and the controller manager will be able to run the controllers in parallel with the hardware components.
The hardware components can be easily introspect the internal member variables using the macro REGISTER_ROS2_CONTROL_INTROSPECTION (#1918)
Added new get_optional method that returns std::optional of the templated type, and this can be used to check if the value is available or not (#1976 and #2061)
Added hardware components execution time and periodicity statistics diagnostics (#2086)
Changes from (PR #1688) for an overview of related changes and discussion refer to (PR #1240):
- Command-/StateInterfaces are now created and exported automatically by the framework via the on_export_command_interfaces() or on_export_state_interfaces() methods based on the interfaces defined in the ros2_control XML-tag, which gets parsed and the InterfaceDescription is created accordingly (check the hardware_info.hpp).
- The memory for storing the value of a Command-/StateInterfaces is no longer allocated in the hardware but instead in the Command-/StateInterfaces itself.
- To access the automatically created Command-/StateInterfaces we provide the std::unordered_map<std::string, InterfaceDescription>, where the string is the fully qualified name of the interface and the InterfaceDescription is the configuration of the interface. The std::unordered_map<> are divided into type_state_interfaces_ and type_command_interfaces_ where type can be: joint, sensor, gpio and unlisted. E.g. the CommandInterfaces for all joints can be found in the joint_command_interfaces_ map. The unlisted includes all interfaces not listed in the ros2_control XML-tag but were created by overriding the export_unlisted_command_interfaces() or export_unlisted_state_interfaces() function by creating some custom Command-/StateInterfaces.
The prepare_command_mode_switch and perform_command_mode_switch methods will now only receive the start/stop interfaces that belong to the hardware component instead of everything (#2120)
The asynchronous components now support two scheduling policies: synchronized and detached and other properties to configure them (#2477).
The hardware interface is now treated similarly as ERROR, when a hardware component returns ERROR on the read cycle (#2334).
The controllers are now deactivated when a hardware component returns DEACTIVATE on the write cycle. The parameter deactivate_controllers_on_hardware_self_deactivate is added to control this behavior temporarily. It is recommended to set this parameter to true in order to avoid controllers to use inactive hardware components and to avoid any unexpected behavior. This feature parameter will be removed in future releases and will be defaulted to true (#2334 & #2501).
The controllers are not allowed to be activated when the hardware component is in INACTIVE state. The parameter allow_controller_activation_with_inactive_hardware is added to control this behavior temporarily. It is recommended to set this parameter to false in order to avoid controllers to use inactive hardware components and to avoid any unexpected behavior. This feature parameter will be removed in future releases and will be defaulted to false (#2347).
The lifecycle ID is cached internally in the controller to avoid calls to get_lifecycle_state() in the real-time control loop. (#2884)
Handles now also support float32, uint8, int8, uint16, int16, uint32, int32 data types in addition to double and bool. (#2879)

joint_limits

Add header to import limits from standard URDF definition (#1298)

ros2controlcli

Spawner colours were added to list_controllers depending upon active or inactive (#1409)
The set_hardware_component_state verb was added (#1248). Use the following command to set the state of a hardware component
```
ros2 control set_hardware_component_state <hardware_component_name> <state>
```

The load_controller now supports parsing of the params file (#1703).

ros2 control load_controller <controller_name> <realtive_or_absolute_file_path>

All the ros2controlcli verbs now support the namespacing through the ROS 2 standard way (#1703).
```
ros2 control <verb> <arguments> --ros-args -r __ns:=<namespace>
```
The CLI verbs list_hardware_components and list_hardware_interfaces will now show the data type used by the internal Command and State interfaces (#2204).

transmission_interface

The simple_transmission and differential_transmission now also support the force interface (#2588).