You're reading the documentation for a development version. For the latest released version, please have a look at Kilted.

Details about parameters

This controller uses the generate_parameter_library to handle its parameters. The parameter definition file located in the src folder contains descriptions for all the parameters used by the controller.

List of parameters

joints (string_array)

Joint names of the system

Read only: True

Default: {}

Constraints:

  • contains no duplicates

  • length is greater than 0

command_joints (string_array)

Joint names to control. If left empty, joints will be used. This parameters can be used if:

  • JTC is used in a controller chain where command and state interfaces don’t have same names.

  • If the number of command joints is smaller than the degrees-of-freedom. For example to track the state and error of passive joints. command_joints must then be a subset of joints.

Read only: True

Default: {}

Constraints:

  • contains no duplicates

command_interfaces (string_array)

Command interfaces provided by the hardware interface for all joints

Read only: True

Default: {}

Constraints:

  • contains no duplicates

  • length is greater than 0

  • every element is one of the list [‘position’, ‘velocity’, ‘acceleration’, ‘effort’]

  • Custom validator: joint_trajectory_controller::command_interface_type_combinations

state_interfaces (string_array)

State interfaces provided by the hardware for all joints.

Read only: True

Default: {}

Constraints:

  • contains no duplicates

  • length is greater than 0

  • every element is one of the list [‘position’, ‘velocity’, ‘acceleration’]

  • Custom validator: joint_trajectory_controller::state_interface_type_combinations

speed_scaling.initial_scaling_factor (double)

The initial value of the scaling factor if no exchange with hardware takes place.

Read only: True

Default: 1.0

Constraints:

  • greater than or equal to 0.0

speed_scaling.state_interface (string)

Fully qualified name of the speed scaling state interface name

Read only: True

Default: “”

speed_scaling.command_interface (string)

Command interface name used for setting the speed scaling factor on the hardware.

Read only: True

Default: “”

allow_partial_joints_goal (bool)

Allow joint goals defining trajectory for only some joints.

Default: false

allow_trajectory_replacement (bool)

When a new trajectory arrives while one is still executing, blend with the old one instead of hard-replacing it: joints not commanded by the new trajectory keep following the old trajectory (instead of holding at the current position), and the transition uses the existing bridge so it stays smooth even under speed scaling. Set to false to keep the legacy behavior.

Default: true

interpolate_from_desired_state (bool)

Interpolate from the current desired state when receiving a new trajectory.

The controller ignores the states provided by hardware interface but using last commands as states for starting the trajectory interpolation.

This is useful if hardware states are not following commands, i.e., an offset between those (typical for hydraulic manipulators). Furthermore, it is necessary if you have a reference trajectory that you send over multiple messages (e.g. for MPC-style trajectory planning).

If this flag is set, the controller tries to read the values from the command interfaces on activation. If they have real numeric values, those will be used instead of state interfaces. Therefore it is important set command interfaces to NaN (i.e., std::numeric_limits<double>::quiet_NaN()) or state values when the hardware is started.

Read only: True

Default: false

allow_integration_in_goal_trajectories (bool)

Allow integration in goal trajectories to accept goals without position or velocity specified

Default: false

set_last_command_interface_value_as_state_on_activation (bool)

When set to true, the last command interface value is used as both the current state and the last commanded state upon activation. If an interface (e.g. velocity) is available only as state and not command, the state is used. Use this to prevent sagging/jumps on activation when using soft or compliant hardware. When set to false, the current state is used for both.

Default: true

action_monitor_rate (double)

Rate to monitor status changes when the controller is executing action (control_msgs::action::FollowJointTrajectory)

Read only: True

Default: 20.0

Constraints:

  • greater than or equal to 0.1

interpolation_method (string)

The type of interpolation to use, if any

Read only: True

Default: “splines”

Constraints:

  • one of the specified values: [‘splines’, ‘none’]

positions_upsampling.enable (bool)

Upsample positions-only messages on ~/joint_trajectory into a smooth global C2 cubic spline by synthesizing knot velocities (a global tridiagonal solve with rest boundary conditions v0 = v_{N-1} = 0). Messages that already carry velocities are passed through unchanged. Has no effect when interpolation_method is none.

Read only: True

Default: false

positions_upsampling.policy_frequency (double)

Frequency in Hz at which an AI policy emits action-chunk waypoints. When greater than zero, time_from_start = (i + 1) / policy_frequency is synthesized for positions-only chunks that arrive without timing. When zero, incoming chunks must already carry strictly-increasing time_from_start. Only used when positions_upsampling.enable is true.

Default: 0.0

Constraints:

  • greater than or equal to 0.0

allow_nonzero_velocity_at_trajectory_end (bool)

If false, the last velocity point has to be zero or the goal will be rejected

Default: false

cmd_timeout (double)

Timeout after which the input command is considered stale. Timeout is counted from the end of the trajectory (the last point). cmd_timeout must be greater than constraints.goal_time, otherwise ignored. If zero, timeout is deactivated

Default: 0.0

constraints

Default values for tolerances if no explicit values are set in the JointTrajectory message. Also contains the decelerate_on_cancel option and per-joint max_deceleration_on_cancel values for smooth stopping behavior (see Decelerate on cancel).

constraints.stopped_velocity_tolerance (double)

Velocity tolerance for at the end of the trajectory that indicates that controlled system is stopped.

Default: 0.01

constraints.goal_time (double)

Time tolerance for achieving trajectory goal before or after commanded time. Positive values set a finite grace period in seconds. If set to a negative value, the controller will wait a potentially infinite amount of time. If set to zero, no grace period is allowed, the goal must be reached on time.

Default: 10.0

constraints.decelerate_on_cancel (bool)

If true and each joints max_deceleration_on_cancel is greater than 0, decelerate to a stop when the request is canceled or the goal constraints are violated. Requires velocity state interface from all joints in the controller.

Read only: True

Default: false

constraints.<joints>.trajectory (double)

Per-joint trajectory offset tolerance during movement.

Default: 0.0

constraints.<joints>.goal (double)

Per-joint trajectory offset tolerance at the goal position.

Default: 0.0

constraints.<joints>.max_deceleration_on_cancel (double)

Per-joint max acceleration used to calculate the stopping position when a request is canceled or preempted.

Read only: True

Default: 0.0

Constraints:

  • greater than or equal to 0.0

gains

The parameters are used to configure PID loops for the velocity or effort-only command interfaces. This structure contains the controller gains for every joint with following the control laws

  • If velocity is the only command interface:

    \[u = k_{ff} v_d + k_p e + k_i \sum e dt + k_d (v_d - v)\]

    with the desired velocity \(v_d\), the measured velocity \(v\), the position error \(e\) (definition see below), the controller period \(dt\), and the velocity manipulated variable (control variable) \(u\), respectively.

  • If effort is the only command interface:

    \[u = k_{ff} v_d + \delta_d + k_p e + k_i \sum e dt + k_d (v_d - v)\]

    with the desired velocity \(v_d\), the desired effort \(\delta_d\) if provided in the trajectory (or 0 otherwise), the measured velocity \(v\), the position error \(e\) (definition see below), the controller period \(dt\), and the effort manipulated variable (control variable) \(u\), respectively.

If the joint is of continuous type, the position error \(e = normalize(s_d - s)\) is normalized between \(-\pi, \pi\), i.e., the shortest rotation to the target position is the desired motion. Otherwise \(e = s_d - s\) is used, with the desired position \(s_d\) and the measured position \(s\) from the state interface.

If you want to turn off the PIDs (open loop control), set the feedback gains to zero and an appropriate value for feed-forward gain \(k_{ff}\).

gains.<joints>.p (double)

Proportional gain \(k_p\) for PID

Default: 0.0

gains.<joints>.i (double)

Integral gain \(k_i\) for PID

Default: 0.0

gains.<joints>.d (double)

Derivative gain \(k_d\) for PID

Default: 0.0

gains.<joints>.ff_velocity_scale (double)

Feed-forward scaling \(k_{ff}\) of velocity

Default: 0.0

gains.<joints>.u_clamp_max (double)

Upper output clamp.

Default: std::numeric_limits<double>::infinity()

gains.<joints>.u_clamp_min (double)

Lower output clamp.

Default: -std::numeric_limits<double>::infinity()

gains.<joints>.i_clamp_max (double)

Upper integral clamp.

Default: std::numeric_limits<double>::infinity()

gains.<joints>.i_clamp_min (double)

Lower integral clamp.

Default: -std::numeric_limits<double>::infinity()

gains.<joints>.antiwindup_strategy (string)

Specifies the anti-windup strategy. Options: ‘back_calculation’, ‘conditional_integration’ or ‘none’. Note that the ‘back_calculation’ strategy use the tracking_time_constant parameter to tune the anti-windup behavior.

Default: “none”

Constraints:

  • one of the specified values: [‘back_calculation’, ‘conditional_integration’, ‘none’]

gains.<joints>.tracking_time_constant (double)

Specifies the tracking time constant for the ‘back_calculation’ strategy. If set to 0.0 when this strategy is selected, a recommended default value will be applied.

Default: 0.0

gains.<joints>.error_deadband (double)

Is used to stop integration when the error is within the given range.

Default: 0.0

An example parameter file

joint_trajectory_controller:
  ros__parameters:
    action_monitor_rate: 20.0
    allow_integration_in_goal_trajectories: false
    allow_nonzero_velocity_at_trajectory_end: false
    allow_partial_joints_goal: false
    allow_trajectory_replacement: true
    cmd_timeout: 0.0
    command_interfaces: '{}'
    command_joints: '{}'
    constraints:
      <joints>:
        goal: 0.0
        max_deceleration_on_cancel: 0.0
        trajectory: 0.0
      decelerate_on_cancel: false
      goal_time: 10.0
      stopped_velocity_tolerance: 0.01
    gains:
      <joints>:
        antiwindup_strategy: none
        d: 0.0
        error_deadband: 0.0
        ff_velocity_scale: 0.0
        i: 0.0
        i_clamp_max: std::numeric_limits<double>::infinity()
        i_clamp_min: -std::numeric_limits<double>::infinity()
        p: 0.0
        tracking_time_constant: 0.0
        u_clamp_max: std::numeric_limits<double>::infinity()
        u_clamp_min: -std::numeric_limits<double>::infinity()
    interpolate_from_desired_state: false
    interpolation_method: splines
    joints: '{}'
    positions_upsampling:
      enable: false
      policy_frequency: 0.0
    set_last_command_interface_value_as_state_on_activation: true
    speed_scaling:
      command_interface: ''
      initial_scaling_factor: 1.0
      state_interface: ''
    state_interfaces: '{}'