deploy: 8197af8

versions/main/md__2github_2workspace_2source_2modulo__controllers_2_r_e_a_d_m_e.html

@@ -72,7 +72,7 @@
   <div class="headertitle"><div class="title">modulo-controllers</div></div>
 </div><!--header-->
 <div class="contents">
-<div class="textblock"><p>ROS2 control interface class for controllers based on the control libraries stack.</p>
+<div class="textblock"><p>ROS 2 control interface classes for controllers in the AICA framework.</p>
 <h1>ControllerInterface</h1>
 <p>This C++ class derives from ros2_control <code>ControllerInterface</code> and incorporates <code>modulo</code> concepts like inputs, outputs, parameters, predicates, and services.</p>
 <p>It supports the following parameters:</p>
@@ -87,7 +87,32 @@ <h2>General behavior</h2>
 <p>The controller will claim either all or individually added state interfaces and individually added command interfaces. The class is intended to be used as a base class to implement any kind of controller.</p>
 <p>The <code>activation_timeout</code> parameter gives the controller plugin and hardware interface additional time to read the initial states to prevent any NaN data from propagating through to the control logic.</p>
 <h1>RobotControllerInterface</h1>
-<p>The <code>RobotControllerInterface</code> is derived from the <code>ControllerInterface</code>. It incorporates <code>JointState</code> and <code>CartesianState</code> classes to leverage the <code>robot_model::Model</code> class for forward and inverse kinematics, and supports force-torque sensor data in <code>CartesianWrench</code> format. </p>
+<p>The <code>RobotControllerInterface</code> is derived from the <code>ControllerInterface</code>. It incorporates <code>JointState</code> and <code>CartesianState</code> classes to leverage the <code>robot_model::Model</code> class for forward and inverse kinematics, and supports force-torque sensor data in <code>CartesianWrench</code> format.</p>
+<h2>Joints and control type</h2>
+<p>On top of any other individually added state interfaces, the controller will claim state interfaces matching the named <code>joints</code>, and read this state data into a JointState object.</p>
+<p>It will claim individual command interfaces from the hardware interface according to the named <code>joints</code> and the specified <code>control_type</code> given to the class at construction. The <code>hardware_name</code> parameter determines the name of the JointState object.</p>
+<p>This class is intended to be used as a base class to implement joint and task space controllers. They can set the joint command or access the joint state using the <code>set_joint_command()</code> and <code>get_joint_state()</code> methods, respectively.</p>
+<h2>Robot model and URDF</h2>
+<p>If a controller needs a robot model, a <code>robot_model::Model</code> will be configured from URDF information. To support this, the <code>robot_description</code> must be specified.</p>
+<p>The robot model is used to calculate the CartesianState of a task frame from the JointState using forward kinematics, which is available to derived classes using the <code>get_cartesian_state()</code> method.</p>
+<p>The task frame can be specified using the <code>task_space_frame</code> parameter. If left empty, the final link of the robot model will be used.</p>
+<p>In certain cases, the <code>joints</code> parameter might not be in a physically correct order; for example, they might be sorted alphabetically, which makes the corresponding JointState incompatible with the actual order of joints in a robot system. If set to true, the <code>sort_joints</code> parameter orders the joint names to be physically correct using the robot model data.</p>
+<p>Derived controllers can also access and leverage the robot model for more advanced behaviors such as inverse kinematics.</p>
+<h2>Force-Torque Sensor</h2>
+<p>If the <code>ft_sensor_name</code> and <code>ft_sensor_reference_frame</code> parameters are set, the controller will look for a matching sensor with the following state interfaces:</p>
+<ul>
+<li><code>force.x</code></li>
+<li><code>force.y</code></li>
+<li><code>force.z</code></li>
+<li><code>torque.x</code></li>
+<li><code>torque.y</code></li>
+<li><code>torque.z</code></li>
+</ul>
+<p>Derived controllers can use <code>get_ft_sensor()</code> to access a CartesianWrench object of the sensor data. If the <code>ft_sensor_reference_frame</code> matches the <code>task_space_frame</code>, the measured wrench will additionally be transformed to the robot base frame and applied to the Cartesian state of the robot that is available through <code>get_cartesian_state()</code>.</p>
+<h2>General behavior</h2>
+<p>The <code>command_half_life</code> parameter is used to attenuate any dynamic commands (velocities, accelerations or torques) in case no new commands are received (i.e. if <code>set_joint_command()</code> was not called since the last controller update).</p>
+<p>At each control step, the last command is scaled by a decay factor to cause an exponential fall-off towards zero. The decay factor is calculated in terms of the desired command half-life based on the control frequency. At the half-life time, the command value will be reduced by half. For example, a controller with a command half-life of 0.1 seconds will have the output command reduced by 50%, 25%, 12.5% and 6.25% at 0.1, 0.2, 0.3 and 0.4 seconds respectively.</p>
+<p>The <code>command_rate_limit</code> parameter sets an upper bound on how much a command interface value can change at each control step. It is expressed in units per second. For example, a controller with a rate limit of 5.0 commanding the joint velocity interface at 100Hz (a control period of 0.01 seconds) will only allow the joint velocity to change by up to 0.05 radians per second at each control step, or at 5.0 radians per second, per second. </p>
 </div></div><!-- contents -->
 </div><!-- PageDoc -->
 <!-- start footer part -->