ros2_control hardware interface
===============================

*For applications with strong real-time and safety requirements*

The hardware interface variant is designed for applications within the ros2_control framework that require strong real-time and safety requirements. This variant always uses the reading from the buffer mechanism, timed by the **ros2_control** master clock.

**Learn more:** `ros2_control official documentation <https://control.ros.org/jazzy/doc/ros2_control/doc/index.html>`_

----

ROS2 Control Tags in URDF
--------------------------

To use the sensor hardware interface, the following block must be included in your URDF file:

**Required Parameters:**

.. list-table:: 
   :widths: 20 60
   :header-rows: 1
   :class: highlight

   * - Parameter
     - Description
   * - ``config_file``
     - Path to the JSON configuration file
   * - ``tare_on_activation``
     - Whether to tare the sensor on HW interface activation

**URDF Configuration:**

.. code-block:: xml

   <ros2_control name="<SENSOR_LINK_NAME>" type="sensor">
      <hardware>
        <plugin>bota_driver/BotaFTSensor</plugin>
        <param name="config_file">PATH_TO_JSON</param>
        <param name="tare_on_activation">true|false</param>
      </hardware>
    </ros2_control>

.. note::
   **XACRO Integration:** It is advisable to include sensor links and joints leveraging the XACRO macros provided in the ``bota-driver`` package.  See the :doc:`driver_ros2` driver documentation for more details about the XACROs included in the ``bota-driver`` package.

----

Available State Interfaces
---------------------------

Once the hardare interface is loaded by the ``controller_manager`` the following state interfaces are available:

.. list-table:: 
   :widths: 25 19 40
   :header-rows: 1
   :class: highlight

   * - Interface Name
     - Type
     - Description
   * - ``hardware_interface_active``
     - Status
     - Indicates if the hardware interface is active
   * - ``status.throttled``
     - Status
     - Sensor throttling status flag
   * - ``status.overrange``
     - Status
     - Sensor overrange status flag
   * - ``status.invalid``
     - Status
     - Sensor invalid data status flag
   * - ``status.raw``
     - Status
     - Raw data status flag
   * - ``status``
     - Status
     - Indicates if any of the status flags are set, acting as a general summary status flag
   * - ``force.x/y/z``
     - Measurement
     - Force measurements in X, Y, Z axes
   * - ``torque.x/y/z``
     - Measurement
     - Torque measurements in X, Y, Z axes
   * - ``lin_acc.x/y/z``
     - Measurement
     - Acceleration measurements in X, Y, Z axes
   * - ``ang_vel.x/y/z``
     - Measurement
     - Angular rate measurements in X, Y, Z axes
   * - ``temperature``
     - Measurement
     - Temperature reading in Celsius
   * - ``timestamp``
     - Timing
     - Sensor timestamp in microseconds

----

Taring procedure
-----------------

.. important::
  The sensor is always zeroed during **activation** of the hardware interface if the parameter ``tare_on_activation`` is set to ``true`` in the URDF configuration.

To perform a taring procedure, the hardware interface needs to be **deactivated** and then **re-activated**. 

It is important to ensure that no controller is actively using the sensor data during this process, 
as the state interface data will not be updated while the hardware inteface is deactivated. 
The ``hardware_interface_active`` will turn ``false`` during this period, indicating that the sensor data is not being updated.

An example how to do this is shown in the example repository linked below.


----

Safety Guidelines
-----------------

A proper use of the Bota FT sensor hardware interface requires monitoring two distinct safety aspects:

1. **Hardware Interface Status**
  Due to **ros2_control** implementation, sensor interfaces can be exposed even when hardware is disconnected. 
  Always check ``hardware_interface_active`` before using any sensor data. 
  If this flag turns ``false``, the state interfaces are not being updated with sensor data, and you must not use them in your control logic.

2. **Sensor Status Flags**
  The sensor provides status flags that indicate data quality and operational conditions. 
  Always monitor these flags in your control logic and react accordingly to ensure safe operation.

----

Getting Started
---------------
Bota Systems provides an example including a full **ros2_control setup with a Bota FT sensor**.  
It demonstrates how to integrate the sensor into a ROS2 control system, including the necessary 
configuration and usage patterns.

.. raw:: html

  <div style="background: linear-gradient(135deg, #f8f9fa, #e9ecef); border-left: 5px solid rgb(218, 101, 39); padding: 25px; margin: 25px 0; border-radius: 6px; box-shadow: 0 2px 10px rgba(0,0,0,0.1);">
    <p style="margin-bottom: 20px; color: #495057;">Found the packages implementation in our official GitLab repository.</p>
    <a href="https://gitlab.com/botasys/drivers/bota_driver_ros2_control_example" target="_blank" style="background: rgb(218, 101, 39); color: white; padding: 12px 25px; text-decoration: none; border-radius: 10px; font-weight: bold; display: inline-block; box-shadow: 0 3px 10px rgba(218, 101, 39, 0.3); transition: all 0.3s ease;" onmouseover="this.style.background='#b8541f'; this.style.transform='translateY(-3px) scale(1.05)'; this.style.boxShadow='0 8px 25px rgba(218, 101, 39, 0.3)'" onmouseout="this.style.background='rgb(218, 101, 39)'; this.style.transform='translateY(0) scale(1)'; this.style.boxShadow='0 3px 10px rgba(218, 101, 39, 0.3)'">
      <code style="background: #ffffff; color: #b8541f; padding: 1px 6px; border-radius: 2px; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, 'Roboto Mono', 'Courier New', monospace; font-weight: 700; font-size: 0.72em; display: inline-block; vertical-align: middle;">bota_example_ros2_control</code>
      <span style="margin-left:10px; color: #ffffff; font-weight:700; vertical-align: middle;">on GitLab</span>
    </a>
  </div>