Merge pull request #178 from open-dynamic-robot-initiative/fkloss/doc…

…_joint_axes

Fkloss/doc joint axes

doc/actions_and_observations.rst

@@ -5,9 +5,7 @@ Actions and Observations
 This page describes the structure of actions and observations used by the robot drivers
 implemented in ``robot_fingers``.  The fields of both actions and observations are
 typically arrays with one element per robot joint.  The order of joints in the list
-depends on the robot.
-
-.. todo:: Add dedicated page about joint order
+depends on the robot (see :doc:`joint_order`).
 
 A simple but complete example, using actions and observations can be found in
 :doc:`examples/demo_single_finger_position_control`.

doc/configuration.rst

@@ -7,7 +7,7 @@ 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_).
+backend (for example, see :doc:`examples/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.
@@ -23,6 +23,9 @@ Options
    the number of joints of the robot.  The order of the joints is implicitly defined by
    :confval:`can_ports`.
 
+   For (Tri-)Finger robots, the order is expected to be as described in
+   :doc:`joint_order`.
+
 
 .. confval:: can_ports: list
 
@@ -33,6 +36,10 @@ Options
    the above example, the joint order will be
    ``[can0-motorA, can0-motorB, can1-motorA, ...]``
 
+   Note: For (Tri-)Finger robots, the order is expected to be as described in
+   :doc:`joint_order`.  So make sure to connect/configure the CAN interfaces
+   accordingly.
+
 
 .. confval:: max_current_A: float = 0.0
 

doc/joint_order.rst

@@ -0,0 +1,46 @@
+*************************
+Joint Order and Direction
+*************************
+
+The :doc:`action and observation structs <actions_and_observations>` contain arrays for
+joint positions, torques, etc.  Each entry in these arrays corresponds to one joint of
+the robot.
+
+Joint Order
+===========
+
+On the finger robots, joints for each finger are ordered from the base towards the tip:
+
+.. image:: ./images/fingerpro_joint_axes.png
+   :align: center
+   :alt: Image of a FingerPro model with annotations of the joints rotation axes.
+
+For TriFinger robots, the joints of the three fingers ("finger0", "finger120" and
+"finger240") are each ordered as shown above and then concatenated.  That is, the joint
+array is ordered like this:
+
+::
+
+    finger0_joint0, finger0_joint1, finger0_joint2, finger120_joint0, ..., finger240_joint2
+
+
+See :ref:`trifinger_docs:finger_and_camera_names` on how the three fingers are mounted
+for TriFingerPro.
+
+
+Joint Directions
+================
+
+For "FingerPro" and "FingerEdu" fingers, directions of rotation (i.e. which direction is
+positive and which is negative) is as depicted in the image above.
+For "FingerOne", joint 1 is inverted, the others are the same.
+
+
+Zero Position
+=============
+
+All joints are in zero-position when the finger is pointing straight down:
+
+.. image:: ./images/fingerpro_zero_position.png
+   :align: center
+   :alt: Image of a FingerPro model with the finger tip pointing straight down.

doc_mainpage.rst

@@ -14,10 +14,12 @@ software, see also our paper_ on the open-source version of the TriFinger robot.
 .. toctree::
    :caption: General Documentation
    :maxdepth: 1
+   :hidden:
 
    doc/installation.rst
    doc/getting_started.rst
    doc/actions_and_observations.rst
+   doc/joint_order.rst
    doc/singularity.rst
    doc/configuration.rst
    doc/homing.rst