Add documentation on how to integrate transmission parameters into th…

…e CIA402 generic driver (#117)

* Add doc for transmission. Torque not handled. Check torque before PR.

* Add force/torque aka effort example into the case study.

* Correct language mistakes (turn vs. revolution and reduction absolute value) spotted by tpoignonec.

---------

Co-authored-by: Manuel YGUEL <yguel@unistra.fr>

ethercat_driver_ros2/requirements.txt

@@ -3,3 +3,5 @@ sphinxcontrib-plantuml
 sphinx-mdinclude
 breathe
 exhale
+sphinx-copybutton
+sphinx-tabs

ethercat_driver_ros2/sphinx/_static/css/custom.css

@@ -1,7 +1,6 @@
-
 .wy-table-responsive table td,
 .wy-table-responsive table th {
- white-space:normal;
+    white-space: normal;
 }
 
 tr {
@@ -15,3 +14,8 @@ thead {
 table {
     white-space: normal;
 }
+
+pre {
+    white-space: pre-wrap !important;
+    word-break: break-all;
+}

ethercat_driver_ros2/sphinx/conf.py

@@ -44,10 +44,12 @@
 extensions = [
     "sphinx_rtd_theme",
     "sphinx_mdinclude",
-    "sphinx.ext.imgmath",
+    "sphinx.ext.mathjax",
     "sphinx.ext.todo",
     "sphinx.ext.graphviz",
     "sphinxcontrib.plantuml",
+    "sphinx_copybutton",
+    "sphinx_tabs.tabs",
     "breathe",
 ]
 

ethercat_driver_ros2/sphinx/index.rst

@@ -21,6 +21,7 @@ EtherCAT Driver ROS2 Stack
 
   user_guide/config_generic_slave
   user_guide/config_cia402_drive
+  user_guide/config_use_case_motor_with_gear_box
   user_guide/sdo_async_com
 
 .. toctree::

ethercat_driver_ros2/sphinx/user_guide/config_cia402_drive.rst

@@ -41,6 +41,7 @@ Usage
 Example configuration for the Maxon EPOS3 motor dive:
 
 ..  code-block:: yaml
+  :linenos:
 
   # Configuration file for Maxon EPOS3 drive
   vendor_id: 0x000000fb
@@ -54,7 +55,12 @@ Example configuration for the Maxon EPOS3 motor dive:
     - index: 0x1603
       channels:
         - {index: 0x6040, sub_index: 0, type: uint16, default: 0}  # Control word
-        - {index: 0x607a, sub_index: 0, type: int32, command_interface: position, default: .nan}  # Target position
+        - {
+            index: 0x607a,
+            sub_index: 0,
+            type: int32,
+            command_interface: position,
+            default: .nan}  # Target position
         - {index: 0x60ff, sub_index: 0, type: int32, default: 0}  # Target velocity
         - {index: 0x6071, sub_index: 0, type: int16, default: 0}  # Target torque
         - {index: 0x60b0, sub_index: 0, type: int32, default: 0}  # Offset position
@@ -67,9 +73,24 @@ Example configuration for the Maxon EPOS3 motor dive:
     - index: 0x1a03
       channels:
         - {index: 0x6041, sub_index: 0, type: uint16}  # Status word
-        - {index: 0x6064, sub_index: 0, type: int32, state_interface: position}  # Position actual value
-        - {index: 0x606c, sub_index: 0, type: int32, state_interface: velocity}  # Velocity actual value
-        - {index: 0x6077, sub_index: 0, type: int16, state_interface: effort}  # Torque actual value
+        - {
+            index: 0x6064,
+            sub_index: 0,
+            type: int32,
+            state_interface: position
+          }  # Position actual value
+        - {
+            index: 0x606c,
+            sub_index: 0,
+            type: int32,
+            state_interface: velocity
+          }  # Velocity actual value
+        - {
+            index: 0x6077,
+            sub_index: 0,
+            type: int16,
+            state_interface: effort
+          }  # Torque actual value
         - {index: 0x6061, sub_index: 0, type: int8}  # Mode of operation display
         - {index: 0x2071, sub_index: 1, type: int16}  # Digital Input Functionalities State
         - {index: 0x60b9, sub_index: 0, type: int16}  # Touch Probe Status

ethercat_driver_ros2/sphinx/user_guide/config_generic_slave.rst

@@ -76,19 +76,28 @@ Each PDO Channel has the following configuration flags:
   * - :code:`state_interface`
     - **Only for** :code:`tpdo`. Name of the state interface to be used inside :code:`ros2_control`.
   * - :code:`default`
-    - **Only for** :code:`rpdo`. Default value to be send to the drive if data received on the command interface is :code:`NaN`.
+    - **Only for** :code:`rpdo`. Default value to be sent if data received on the command interface is :code:`NaN`.
   * - :code:`mask`
     - Data mask, to be used with :code:`type` = :code:`bool`.
   * - :code:`factor`
-    - Data conversion factor.
+    - Data conversion factor/scale (:code:`type` : :code:`double`).
   * - :code:`offset`
-    - Data offset term.
+    - Data offset term (:code:`type` : :code:`double`).
 
 
 .. warning:: For each channel, tags :code:`index`, :code:`sub_index` and :code:`type` are **mandatory** even if the channel is not used in order to fill the data layout expected by the module. All other tags can remain unset.
 .. note:: Data type :code:`bitN` is used for gaps in the config. Refer to module manual if required.
 .. note:: Data type :code:`bool` requires the use of the :code:`mask` option as the registers can only be read as a multiple of 8 bits.
 
+.. note::
+
+   Data (d) can be modified using the optional :code:`factor` (f) and :code:`offset` (o) parameters following a linear relation: :math:`d \longrightarrow f\times d + o`. Default value are :math:`f=1` and :math:`o=0`. It is particularly useful for:
+
+  - scaling analog values to physical units,
+  - take into account calibration offsets,
+  - convert between different units,
+  - take into account transmission parameters like gear reduction or screw lead for motor control.
+
 Sync Manager Configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -134,11 +143,23 @@ Example configuration for the Beckhoff EL3104 analog input module:
     - index: 0x1a00
       channels:
         - {index: 0x3101, sub_index: 1, type: uint8}
-        - {index: 0x3101, sub_index: 2, type: int16, state_interface: analog_input.1, factor: 0.000305185}
+        - {
+            index: 0x3101,
+            sub_index: 2,
+            type: int16,
+            state_interface: analog_input.1,
+            factor: 0.000305185
+          }
     - index: 0x1a01
       channels:
         - {index: 0x3102, sub_index: 1, type: uint8}
-        - {index: 0x3102, sub_index: 2, type: int16, state_interface: analog_input.2, factor: 0.000305185}
+        - {
+            index: 0x3102,
+            sub_index: 2,
+            type: int16,
+            state_interface: analog_input.2,
+            factor: 0.000305185
+          }
   sm:  # Sync Manager
     - {index: 0, type: output, pdo: ~, watchdog: disable}
     - {index: 1, type: input, pdo: ~, watchdog: disable}