Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add GPIO tag description to docs #1109

Merged
merged 3 commits into from
Sep 23, 2023
Merged

Add GPIO tag description to docs #1109

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1a81d0d
Reformat hardware_components docs
christophfroehlich Sep 5, 2023
84a2034
Copy info from roadmap
christophfroehlich Sep 6, 2023
1471772
Add info on broadcasters
christophfroehlich Sep 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 21 additions & 11 deletions hardware_interface/doc/hardware_components_userdoc.rst
View file
Open in desktop
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
Open in desktop
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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Parsing of ``<gpio>``-tag is similar to this of a ``<joint>``-tag having command and state interfaces.
Parsing of ``<gpio>``-tag is similar to that of a ``<joint>``-tag having command and state interfaces.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Merged without this 🤦

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
Open in desktop
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
Loading