Skip to content

Commit

Permalink
Add GPIO tag description to docs (#1109)
Browse files Browse the repository at this point in the history
  • Loading branch information
@christophfroehlich
christophfroehlich authored Sep 23, 2023
1 parent d77f6f1 commit 8141212
Show file tree
Hide file tree
Showing 3 changed files with 175 additions and 15 deletions.
32 changes: 21 additions & 11 deletions hardware_interface/doc/hardware_components_userdoc.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,20 +14,21 @@ Guidelines and Best Practices
.. toctree::
:titlesonly:

Writing a Hardware Interface <writing_new_hardware_interface.rst>
Hardware Interface Types <hardware_interface_types_userdoc.rst>
Writing a Hardware Component <writing_new_hardware_component.rst>


Handling of errors that happen during read() and write() calls
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If ``hardware_interface::return_type::ERROR`` is returned from ``read()`` or ``write()`` methods of a hardware interface, ``on_error(previous_state)`` method will be called to handle any error that happened.
If ``hardware_interface::return_type::ERROR`` is returned from ``read()`` or ``write()`` methods of a hardware_interface class, ``on_error(previous_state)`` method will be called to handle any error that happened.

Error handling follows the `node lifecycle <https://design.ros2.org/articles/node_lifecycle.html>`_.
If successful ``CallbackReturn::SUCCESS`` is returned and hardware is again in ``UNCONFIGURED`` state, if any ``ERROR`` or ``FAILURE`` happens the hardware ends in ``FINALIZED`` state and can not be recovered.
The only option is to reload the complete plugin, but there is currently no service for this in the Controller Manager.

Migration from Foxy to Galactic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Migration from Foxy to newer versions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Between Foxy and Galactic we made substantial changes to the interface of hardware components to enable management of their lifecycle.
The following list shows a set of quick changes to port existing hardware components to Galactic:
Expand All @@ -36,20 +37,29 @@ The following list shows a set of quick changes to port existing hardware compon

2. If using BaseInterface as base class then you should remove it. Specifically, change:

hardware_interface::BaseInterface<hardware_interface::[Actuator|Sensor|System]Interface> to hardware_interface::[Actuator|Sensor|System]Interface
.. code-block:: c++

hardware_interface::BaseInterface<hardware_interface::[Actuator|Sensor|System]Interface>

to

.. code-block:: c++

hardware_interface::[Actuator|Sensor|System]Interface

3. Remove include of headers ``base_interface.hpp`` and ``hardware_interface_status_values.hpp``

4. Add include of header ``rclcpp_lifecycle/state.hpp`` although this may not be strictly necessary

5. replace first three lines in ``on_init`` to:
5. replace first three lines in ``on_init`` to

.. code-block:: c++

.. code-block:: c++
if (hardware_interface::[Actuator|Sensor|System]Interface::on_init(info) != CallbackReturn::SUCCESS)
{
return CallbackReturn::ERROR;
}

if (hardware_interface::[Actuator|Sensor|System]Interface::on_init(info) != CallbackReturn::SUCCESS)
{
return CallbackReturn::ERROR;
}

6. Change last return of ``on_init`` to ``return CallbackReturn::SUCCESS;``

Expand Down
150 changes: 150 additions & 0 deletions hardware_interface/doc/hardware_interface_types_userdoc.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,150 @@
:github_url: https://github.com/ros-controls/ros2_control/blob/{REPOS_FILE_BRANCH}/hardware_interface/doc/hardware_interface_types_userdoc.rst

.. _hardware_interface_types_userdoc:

``ros2_control`` hardware interface types
---------------------------------------------------------

The ``ros2_control`` framework provides a set of hardware interface types that can be used to implement
a hardware component for a specific robot or device.
The following sections describe the different hardware interface types and their usage.

Joints
*****************************
``<joint>``-tag groups the interfaces associated with the joints of physical robots and actuators.
They have command and state interfaces to set the goal values for hardware and read its current state.

State interfaces of joints can be published as a ROS topic by means of the :ref:`joint_state_broadcaster <joint_state_broadcaster_userdoc>`

Sensors
*****************************
``<sensor>``-tag groups multiple state interfaces describing, e.g., internal states of hardware.

Depending on the type of sensor, there exist a couple of specific semantic components with broadcasters shipped with ros2_controllers, e.g.

- :ref:`Imu Sensor Broadcaster <imu_sensor_broadcaster_userdoc>`
- :ref:`Force Torque Sensor Broadcaster <force_torque_sensor_broadcaster_userdoc>`

GPIOs
*****************************
The ``<gpio>``-tag is used for describing input and output ports of a robotic device that cannot be associated with any joint or sensor.
Parsing of ``<gpio>``-tag is similar to this of a ``<joint>``-tag having command and state interfaces.
The tag must have at least one ``<command>``- or ``<state>``-tag as a child.

The keyword "gpio" is chosen for its generality.
Although strictly used for digital signals, it describes any electrical analog, digital signal, or physical value.

The ``<gpio>`` tag can be used as a child of all three types of hardware components, i.e., system, sensor, or actuator.

Because ports implemented as ``<gpio>``-tag are typically very application-specific, there exists no generic publisher
within the ros2_control framework. A custom gpio-controller has to be implemented for each application. As an example, see :ref:`the GPIO controller example <ros2_control_demos_example_10_userdoc>` as part of the demo repository.

Examples
*****************************
The following examples show how to use the different hardware interface types in a ``ros2_control`` URDF.
They can be combined together within the different hardware component types (system, actuator, sensor) (:ref:`see detailed documentation <overview_hardware_components>`) as follows

1. Robot with multiple GPIO interfaces

- RRBot System
- Digital: 4 inputs and 2 outputs
- Analog: 2 inputs and 1 output
- Vacuum valve at the flange (on/off)


.. code:: xml
<ros2_control name="RRBotSystemMutipleGPIOs" type="system">
<hardware>
<plugin>ros2_control_demo_hardware/RRBotSystemPositionOnlyHardware</plugin>
<param name="example_param_hw_start_duration_sec">2.0</param>
<param name="example_param_hw_stop_duration_sec">3.0</param>
<param name="example_param_hw_slowdown">2.0</param>
</hardware>
<joint name="joint1">
<command_interface name="position">
<param name="min">-1</param>
<param name="max">1</param>
</command_interface>
<state_interface name="position"/>
</joint>
<joint name="joint2">
<command_interface name="position">
<param name="min">-1</param>
<param name="max">1</param>
</command_interface>
<state_interface name="position"/>
</joint>
<gpio name="flange_digital_IOs">
<command_interface name="digital_output1"/>
<state_interface name="digital_output1"/> <!-- Needed to know current state of the output -->
<command_interface name="digital_output2"/>
<state_interface name="digital_output2"/>
<state_interface name="digital_input1"/>
<state_interface name="digital_input2"/>
</gpio>
<gpio name="flange_analog_IOs">
<command_interface name="analog_output1"/>
<state_interface name="analog_output1"/> <!-- Needed to know current state of the output -->
<state_interface name="analog_input1"/>
<state_interface name="analog_input2"/>
</gpio>
<gpio name="flange_vacuum">
<command_interface name="vacuum"/>
<state_interface name="vacuum"/> <!-- Needed to know current state of the output -->
</gpio>
</ros2_control>
2. Gripper with electrical and suction grasping possibilities

- Multimodal gripper
- 1-DoF parallel gripper
- suction on/off

.. code:: xml
<ros2_control name="MultimodalGripper" type="actuator">
<hardware>
<plugin>ros2_control_demo_hardware/MultimodalGripper</plugin>
</hardware>
<joint name="parallel_fingers">
<command_interface name="position">
<param name="min">0</param>
<param name="max">100</param>
</command_interface>
<state_interface name="position"/>
</joint>
<gpio name="suction">
<command_interface name="suction"/>
<state_interface name="suction"/> <!-- Needed to know current state of the output -->
</gpio>
</ros2_control>
3. Force-Torque-Sensor with temperature feedback and adjustable calibration

- 2D FTS
- Temperature feedback in °C
- Choice between 3 calibration matrices, i.e., calibration ranges

.. code:: xml
<ros2_control name="RRBotForceTorqueSensor2D" type="sensor">
<hardware>
<plugin>ros2_control_demo_hardware/ForceTorqueSensor2DHardware</plugin>
<param name="example_param_read_for_sec">0.43</param>
</hardware>
<sensor name="tcp_fts_sensor">
<state_interface name="fx"/>
<state_interface name="tz"/>
<param name="frame_id">kuka_tcp</param>
<param name="fx_range">100</param>
<param name="tz_range">100</param>
</sensor>
<sensor name="temp_feedback">
<state_interface name="temperature"/>
</sensor>
<gpio name="calibration">
<command_interface name="calibration_matrix_nr"/>
<state_interface name="calibration_matrix_nr"/>
</gpio>
</ros2_control>
8 changes: 4 additions & 4 deletions ...ce/doc/writing_new_hardware_interface.rst → ...ce/doc/writing_new_hardware_component.rst
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
:github_url: https://github.com/ros-controls/ros2_control/blob/{REPOS_FILE_BRANCH}/hardware_interface/doc/writing_new_hardware_interface.rst
:github_url: https://github.com/ros-controls/ros2_control/blob/{REPOS_FILE_BRANCH}/hardware_interface/doc/writing_new_hardware_component.rst

.. _writing_new_hardware_interface:
.. _writing_new_hardware_component:

Writing a new hardware interface
=================================
Writing a Hardware Component
============================

In ros2_control hardware system components are libraries, dynamically loaded by the controller manager using the `pluginlib <https://ros.org/wiki/pluginlib>`_ interface.
The following is a step-by-step guide to create source files, basic tests, and compile rules for a new hardware interface.
Expand Down

0 comments on commit 8141212

Please sign in to comment.