feat: add extension descriptions

.vscode/settings.json

@@ -28,4 +28,9 @@
     "editor.rulers": [
         120
     ],
+    "yaml.schemas": {
+        "https://raw.githubusercontent.com/aica-technology/api/731960c66a8fb9b29620a9f79baaa935818ab1db/docs/static/schemas/1-0-2/extension.schema.json": [
+            "extension_descriptions/*.yaml"
+        ]
+    }
 }

CHANGELOG.md

@@ -26,7 +26,10 @@ Release Versions:
 
 ## Upcoming changes
 
+- feat(interfaces): add assignment message definition (#220)
+- feat(components): add assignment methods (#224, #227)
 - fix(controllers): safe interface map check (#233)
+- feat: add extension descriptions (#225)
 
 ## 5.3.0
 
@@ -40,8 +43,6 @@ computations, without blocking the control loop.
 - fix(controllers): check for finite wrench values (#216)
 - feat(controllers): allow control type change after construction (#217)
 - feat(controllers): implement lock-free service wrappers for demanding callbacks (#218)
-- feat(interfaces): add assignment message definition (#220)
-- feat(components): add assignment methods (#224, #227)
 
 ## 5.2.3
 

aica-package.toml

@@ -9,7 +9,7 @@ name = "modulo"
 
 [build]
 type = "ros"
-image = "v2.0.5-jazzy"
+image = "v2.0.6-jazzy"
 
 [build.dependencies]
 "@aica/foss/control-libraries" = "v9.0.0"

source/modulo_components/CMakeLists.txt

@@ -19,6 +19,8 @@ endif()
 find_package(ament_cmake_auto REQUIRED)
 find_package(ament_cmake_python REQUIRED)
 
+include(InstallAicaDescriptions)
+
 ament_auto_find_build_dependencies()
 
 include_directories(include)
@@ -32,8 +34,8 @@ ament_auto_add_library(${PROJECT_NAME} SHARED
 ament_python_install_package(${PROJECT_NAME} SCRIPTS_DESTINATION lib/${PROJECT_NAME})
 
 # Install descriptions
-install(DIRECTORY ./component_descriptions
-        DESTINATION .)
+install_aica_descriptions(./component_descriptions ${CMAKE_INSTALL_PREFIX}/component_descriptions)
+install_aica_descriptions(./extension_descriptions ${CMAKE_INSTALL_PREFIX}/extension_descriptions)
 
 if(BUILD_TESTING)
   find_package(ament_cmake_gtest REQUIRED)

source/modulo_components/extension_descriptions/modulo_component.yaml

@@ -0,0 +1,27 @@
+schema: 1-0-2
+name: Component
+description:
+  brief: A wrapper for rclcpp::Node to simplify application composition through unified component interfaces.
+  details:
+    This class is intended for direct inheritance to implement custom components that perform one-shot or externally
+    triggered operations.
+virtual: true
+inherits: "rclcpp::Node"
+class: modulo_components::Component
+type: component
+parameters:
+  - display_name: Rate
+    description: The frequency in Hertz for all periodic callbacks
+    parameter_name: rate
+    parameter_type: double
+    default_value: 10.0
+    validation:
+      range:
+        exclusive_minimum: 0
+predicates:
+  - display_name: In error state
+    description: True if the component is in error state
+    predicate_name: in_error_state
+  - display_name: Is finished
+    description: True if the on_execute_callback() method of one-shot components successfully finished
+    predicate_name: is_finished

source/modulo_components/extension_descriptions/modulo_lifecycle_component.yaml

@@ -0,0 +1,22 @@
+schema: 1-0-2
+name: Lifecycle Component
+description:
+  brief:
+    A wrapper for rclcpp_lifecycle::LifecycleNode to simplify application composition through unified component
+    interfaces while supporting lifecycle states and transitions.
+  details:
+    This class is intended for direct inheritance to implement custom state-based components that perform different
+    behaviors based on their state and on state transitions.
+virtual: true
+inherits: "rclcpp_lifecycle::LifecycleNode"
+class: modulo_components::LifecycleComponent
+type: lifecycle_component
+parameters:
+  - display_name: Rate
+    description: The frequency in Hertz for all periodic callbacks
+    parameter_name: rate
+    parameter_type: double
+    default_value: 10.0
+    validation:
+      range:
+        exclusive_minimum: 0

source/modulo_controllers/CMakeLists.txt

@@ -23,6 +23,8 @@ endif()
 find_package(ament_cmake_auto REQUIRED)
 find_package(control_libraries 9.0.0 CONFIG REQUIRED COMPONENTS state_representation robot_model controllers)
 
+include(InstallAicaDescriptions)
+
 ament_auto_find_build_dependencies()
 
 include_directories(include)
@@ -34,8 +36,8 @@ ament_auto_add_library(${PROJECT_NAME} SHARED
 
 target_link_libraries(${PROJECT_NAME} ${control_libraries_LIBRARIES})
 
-install(DIRECTORY ./controller_descriptions
-        DESTINATION .)
+install_aica_descriptions(./controller_descriptions ${CMAKE_INSTALL_PREFIX}/controller_descriptions)
+install_aica_descriptions(./extension_descriptions ${CMAKE_INSTALL_PREFIX}/extension_descriptions)
 
 ament_auto_package()
 

source/modulo_controllers/extension_descriptions/modulo_controllers_base_controller_interface.yaml

@@ -0,0 +1,43 @@
+schema: 1-0-2
+name: Base Controller Interface
+description:
+  brief: Base controller class to combine ros2_control, control libraries and modulo
+virtual: true
+inherits: "controller_interface::ControllerInterface"
+class: modulo_controllers/BaseControllerInterface
+type: controller
+parameters:
+  - display_name: Input validity period
+    description: The maximum age of an input state before discarding it as expired (in seconds)
+    parameter_name: input_validity_period
+    parameter_type: double
+    default_value: 1.0
+    validation:
+      range:
+        exclusive_minimum: 0
+  - display_name: Predicate publishing rate
+    description: The rate at which to publish controller predicates (in Hertz)
+    parameter_name: predicate_publishing_rate
+    parameter_type: double
+    default_value: 10.0
+    internal: true
+    validation:
+      range:
+        exclusive_minimum: 0
+  - display_name: Update rate
+    description:
+      The rate at which to evaluate the controller (in Hertz). Defaults to the controller manager rate if not set.
+    parameter_name: update_rate
+    parameter_type: int
+    default_value: null
+    optional: true
+    internal: true
+    validation:
+      range:
+        exclusive_minimum: 0
+  - display_name: Is Async
+    description: Whether the controller should be evaluated asynchronously
+    parameter_name: is_async
+    parameter_type: bool
+    default_value: false
+    internal: true

source/modulo_controllers/extension_descriptions/modulo_controllers_controller_interface.yaml

@@ -0,0 +1,39 @@
+schema: 1-0-2
+name: Controller Interface
+description:
+  brief: Controller interface class that includes custom parameters for derived controllers
+virtual: true
+inherits: modulo_controllers/BaseControllerInterface
+class: modulo_controllers/ControllerInterface
+type: controller
+parameters:
+  - display_name: Hardware name
+    description: The name of the hardware interface
+    parameter_name: hardware_name
+    parameter_type: string
+    default_value: null
+    optional: true
+    internal: true
+  - display_name: Joints
+    description: A vector of joint names that the controller will claim
+    parameter_name: joints
+    parameter_type: string_array
+    default_value: null
+    optional: true
+    internal: true
+  - display_name: Robot description
+    description: The string formatted content of the controller's URDF description
+    parameter_name: robot_description
+    parameter_type: string
+    default_value: null
+    optional: true
+    internal: true
+  - display_name: Activation timeout
+    description: The seconds to wait for valid data on the state interfaces before activating (in seconds)
+    parameter_name: activation_timeout
+    parameter_type: double
+    default_value: 1.0
+    internal: true
+    validation:
+      range:
+        exclusive_minimum: 0

source/modulo_controllers/extension_descriptions/modulo_controllers_robot_controller_interface.yaml

@@ -0,0 +1,54 @@
+schema: 1-0-2
+name: Robot Controller Interface
+description:
+  brief: Base controller class that automatically associates joints with a JointState object
+virtual: true
+inherits: modulo_controllers/ControllerInterface
+class: modulo_controllers/RobotControllerInterface
+type: controller
+parameters:
+  - display_name: FT sensor name
+    description: Optionally, the name of a force-torque sensor in the hardware interface
+    parameter_name: ft_sensor_name
+    parameter_type: string
+    default_value: null
+    optional: true
+  - display_name: FT sensor reference frame
+    description: The reference frame of the force-torque sensor in the robot model
+    parameter_name: ft_sensor_reference_frame
+    parameter_type: string
+    default_value: null
+    optional: true
+  - display_name: Command half life
+    description:
+      A time constant for the exponential decay of the commanded velocity, acceleration or torque if no new command is
+      set
+    parameter_name: command_half_life
+    parameter_type: double
+    default_value: 0.1
+    validation:
+      range:
+        minimum: 0
+  - display_name: Command rate limit
+    description: The maximum allowable change in command on any interface expressed in command units / second
+    parameter_name: command_rate_limit
+    parameter_type: double
+    default_value: null
+    optional: true
+    validation:
+      range:
+        minimum: 0
+  - display_name: Task-space frame
+    description:
+      The frame name in the robot model to use for kinematics calculations (defaults to the last frame in the model)
+    parameter_name: task_space_frame
+    parameter_type: string
+    default_value: null
+    optional: true
+    internal: true
+  - display_name: Sort joints
+    description: If true, re-arrange the 'joints' parameter into a physically correct order according to the robot model
+    parameter_name: joints
+    parameter_type: bool
+    default_value: true
+    internal: true

source/modulo_controllers/src/BaseControllerInterface.cpp

@@ -159,6 +159,7 @@ BaseControllerInterface::on_set_parameters_callback(const std::vector<rclcpp::Pa
 bool BaseControllerInterface::validate_parameter(const std::shared_ptr<ParameterInterface>& parameter) {
   if (parameter->get_name() == "predicate_publishing_rate" || parameter->get_name() == "input_validity_period") {
     auto value = parameter->get_parameter_value<double>();
+    // FIXME: don't allow zero
     if (value < 0.0 || value > std::numeric_limits<double>::max()) {
       RCLCPP_ERROR(
           get_node()->get_logger(), "Parameter value of parameter '%s' should be a positive finite number",

source/modulo_controllers/src/ControllerInterface.cpp

@@ -169,6 +169,7 @@ ControllerInterface::on_activate(const rclcpp_lifecycle::State&) {
   }
 
   auto start_time = get_node()->get_clock()->now();
+  // FIXME: validate activation timeout parameter
   auto activation_timeout = rclcpp::Duration::from_seconds(get_parameter_value<double>("activation_timeout"));
   while (read_state_interfaces() != controller_interface::return_type::OK) {
     RCLCPP_DEBUG_THROTTLE(