From 284ba9df8196382056806b356b666304cff566d4 Mon Sep 17 00:00:00 2001 From: Felix Kloss Date: Tue, 25 Jun 2024 11:03:08 +0200 Subject: [PATCH] doc: Document robot configuration options Add a page to the documentation which lists all the options of the robot configuration files. This is currently mostly copied from the doxygen of the Config class. --- doc/configuration.rst | 184 ++++++++++++++++++++++++++++++++++++++++++ doc_mainpage.rst | 1 + 2 files changed, 185 insertions(+) create mode 100644 doc/configuration.rst diff --git a/doc/configuration.rst b/doc/configuration.rst new file mode 100644 index 0000000..c93922b --- /dev/null +++ b/doc/configuration.rst @@ -0,0 +1,184 @@ +******************* +Robot Configuration +******************* + +Configuration File +================== + +The robot drivers based on :cpp:class:`~robot_fingers::NJointBlmcRobotDriver` are +configured via YAML files, which has to be passed to the function that creates the +backend (for example, see demo_single_finger_position_control_). + +Default configurations for the different (Tri-)Finger robots can be found in the +``config/`` folder of the robot_fingers package. + + +Options +======= + +.. note:: + + Some of the options below expect a list with one value for each joint. They are + annotated with the type ``list[N_joints]``. The actual length of the list depends on + the number of joints of the robot. The order of the joints is implicitly defined by + :confval:`can_ports`. + + +.. confval:: can_ports: list + + List of the CAN interface names to which the robot is connected. Example: + ``["can0", "can1", "can2"]``. + + The joints will be ordered accordingly (e.g. in actions and observations), i.e. for + the above example, the joint order will be + ``[can0-motorA, can0-motorB, can1-motorA, ...]`` + + +.. confval:: max_current_A: float = 0.0 + + Maximum current [in Ampere] that can be sent to the motor. Commands that result in + higher torques will be clipped to the maximum. + +.. confval:: has_endstop: bool = false + + Specify whether the joints have physical end stops or not. + + This is, for example, relevant for homing, where the end stop can be used to + determine the absolute joint positions. See also :confval:`homing_method`. + + Note that not having end stops does not mean that the joint can rotate freely in + general. + + +.. confval:: homing_method: str = "NONE" + + Which method to use for homing. See :doc:`homing` for possible values. + + +.. confval:: calibration + + Map with parameters related to homing and initialisation. + + .. confval:: calibration.endstop_search_torques_Nm: list[N_Joints] = [0, ...] + + Torque that is used to find the end stop. + + .. confval:: move_steps: int = 0 + + Number of time steps for reaching the initial position (see + :confval:`initial_position_rad`) after homing. + + +.. confval:: move_to_position_tolerance_rad: float = 0.0 + + Tolerance [in radian] for reaching the target with + :cpp:func:`robot_fingers::NJointBlmcRobotDriver::move_to_position` (used during + initialization and shutdown). + + +.. confval:: safety_kd: list[N_Joints] = [0.1, ...] + + D-gain to dampen velocity. + The default value is rather high to be on the safe side. Depending in the + application you may want to reduce it, to allow faster motions. + + Set to zero to completely disable damping. + + +.. confval:: position_control_gains + + Map with default control gains for the position PD controller. + + .. confval:: kp: list[N_joints] = [0, ...] + + Default P-gain for the position controller. + + .. confval:: kd: list[N_joints] = [0, ...] + + Default D-gain for the position controller. + +.. confval:: hard_position_limits_lower: list[N_joints] = [0, ...] + + Hard lower limits for joint position. Exceeding the limit with any joint results in + an error and robot shutdown. + +.. confval:: hard_position_limits_upper: list[N_joints] = [0, ...] + + Hard upper limits for joint position. Exceeding the limit with any joint results in + an error and robot shutdown. + + +.. confval:: soft_position_limits_lower: list[N_joints] = [-inf, ...] + + Soft lower limits for joint position. + + Exceeding this limit with some joints results in the action for that joint being + adjusted to move the joint back inside the limits. + +.. confval:: soft_position_limits_upper: list[N_joints] = [inf, ...] + + Soft upper limits for joint position. See :confval:`soft_position_limits_lower`. + + +.. confval:: home_offset_rad: list[N_joints] = [0, ...] + + Offset between home position and zero. See :doc:`homing`. + + +.. confval:: initial_position_rad: list[N_joints] = [0, ...] + + Initial position to which the robot moves during initialization. + +.. confval:: shutdown_trajectory + + **Optional** + + Trajectory which is executed in the shutdown method. Use this to move the robot to a + "rest position" during shutdown of the robot driver. It can consist of arbitrarily + many steps. Leave it empty to not move during shutdown. + + The trajectory is specified as a list of steps, each step consisting of the following + values: + + .. confval:: shutdown_trajectory.target_position_rad: list[N_joints] + + Target positions for the joints in radian. + + .. confval:: shutdown_trajectory.move_steps: int + + Number of time steps for reaching the target position. + + Example: + + .. code-block:: yaml + + # first move slowly back to initial position + - target_position_rad: [0, 0.9, -1.7, 0, 0.9, -1.7, 0, 0.9, -1.7] + move_steps: 3000 + # then move faster to the actual rest position. + - target_position_rad: [1.57, 1.8, -2.5, 1.57, 1.8, -2.5, 1.57, 1.8, -2.5] + move_steps: 1000 + + +.. confval:: run_duration_logfiles: list + + **Optional** + + List of file to which run duration logs are written. + + You can specify multiple files here if you want to log the runtime of different + independent components separately. For example on a robot with multiple + manipulators, you can have a separate log for each manipulator, so if one of them is + replaced, only the log file of this manipulator needs to be changed. + + + +Example +======= + +As a complete example, this is the configuration file used for the TriFingerPro robots: + +.. literalinclude:: /PKG/config/trifingerpro.yml + + +.. _demo_single_finger_position_control: https://github.com/open-dynamic-robot-initiative/robot_fingers/blob/master/demos/demo_single_finger_position_control.py diff --git a/doc_mainpage.rst b/doc_mainpage.rst index 8cf2dbb..afafe1b 100644 --- a/doc_mainpage.rst +++ b/doc_mainpage.rst @@ -18,6 +18,7 @@ software, see also our paper_ on the open-source version of the TriFinger robot. doc/installation.rst doc/getting_started.rst doc/singularity.rst + doc/configuration.rst doc/homing.rst doc/simulation_backend.rst doc/hardware_testing.rst