Standard Node
=============

The ``bota_payload_utils`` package implements two standard ROS2 nodes:

- **bota_payload_compensator_node** (:ref:`see below <bota-payload-compensator-node>`)
- **bota_payload_estimator_node** (:ref:`see below <bota-payload-estimator-node>`)

These nodes follow the `Bota Control Toolkit architecture <../bota_control_toolkit/bota_control_toolkit.html>`__, allowing them to be easily integrated into processing
chains with other `ROS2 Bota Control Nodes <../bota_control_toolkit/bota_control_toolkit_ros2.html>`__, such as the `Bota Driver Node <../driver/driver_ros2_standard_node.html>`__.

----

.. _bota-payload-compensator-node:

Bota Payload Compensator Node
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Configuration Parameters
-------------------------

The node requires the following parameters:

.. list-table:: 
   :widths: 15 35 
   :header-rows: 1
   :class: highlight

   * - Parameter
     - Description
   * - ``node_name``
     - Name assigned to the node, as well as the prefix for topics and services. 
   * - ``config_file``
     - Path to the JSON configuration file
   * - ``input_node_name``
     - Name of the node that provides input data to this node in the processing chain.
   * - ``imu_offset``
     - Offset between the Wrench frame and the IMU frame.

.. note::
  The ``input_node_name`` parameter should match the ``node_name`` of the previous node in the processing chain.

.. warning::
   The ``imu_offset`` parameter will be deprecated in future releases as the IMU data will be published by the driver in the same frame as the wrench.  

Published Topics
----------------

Once running, the node publishes the following topics:

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

  * - Topic
    - Message Type
    - Description
  * - ``<NODE_NAME>/bota_frame``
    - :ref:`BotaFrame <bota-frame-msg>` (see below)
    - Complete sensor data including status, wrench, IMU, temperature and timestamp
  * - ``<NODE_NAME>/bota_wrench``
    - `WrenchStamped <https://docs.ros.org/en/jazzy/p/geometry_msgs/msg/WrenchStamped.html>`_
    - Force and torque measurements from the sensor
  * - ``<NODE_NAME>/bota_imu``
    - `Imu <https://docs.ros.org/en/ros2_packages/jazzy/api/sensor_msgs/msg/Imu.html>`_
    - Imu measurements from the sensor

The published topics follow the same structure as the ones described in the `Bota Driver Node documentation <../driver/driver_ros2_standard_node.html#published-topics>`__. 
For this reason, the **same usage recommendations apply here** as well.

Since this node is not a starting block in the processing chain (it only processes a signal), **the published topics are defined in the same frame as the one of source node**.

Services
------------------

The node exposes the following service:

.. list-table:: 
   :widths: 55 30 45
   :header-rows: 1
   :class: highlight

   * - Service
     - Service Type
     - Description
   * - ``/<NODE_NAME>/tare_compensated_wrench``
     - ``std_srvs/srv/Trigger``
     - Zeros out the wrench output of this block, setting current state as new reference

.. important::
  Calling the **tare** service from the **driver node** will **only zero out the input** raw signal, 
  which is not desired behavior when using the compensator node in a processing chain. For this reason, the **tare service provided by 
  the compensator node should be used instead**.

Getting Started
---------------

**Launch the node from the console:**

.. code-block:: bash
  
   ros2 run bota_payload_utils bota_payload_compensator_node \
     --ros-args \
     -p node_name:=<NODE_NAME>
     -p config_file:=<PATH_TO_JSON> \
     -p input_node_name:=<INPUT_NODE_NAME> \
     -p imu_offset:=<IMU_OFFSET> \

**Call the tare service from console:**

.. code-block:: bash

   ros2 service call /<NODE_NAME>/tare_compensated_wrench std_srvs/srv/Trigger {}

----------------------

.. _bota-payload-estimator-node:

Bota Payload Estimator Node
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Configuration Parameters
-------------------------

The node requires the following parameters:

.. list-table:: 
   :widths: 15 35 
   :header-rows: 1
   :class: highlight

   * - Parameter
     - Description
   * - ``node_name``
     - Name assigned to the node, as well as the prefix for topics and services. 
   * - ``config_file``
     - Path to the JSON configuration file
   * - ``input_node_name``
     - Name of the node that provides input data to this node in the processing chain.
   * - ``imu_offset``
     - Offset between the Wrench frame and the IMU frame.

.. note::
  The ``input_node_name`` parameter should match the ``node_name`` of the previous node in the processing chain.

.. warning::
   The ``imu_offset`` parameter will be deprecated in future releases as the IMU data will be published in the same frame as the wrench by the driver.  

Published Topics
----------------

Once running, the node publishes the following topics:

.. list-table:: 
  :widths: 37 16 40
  :header-rows: 1
  :class: highlight

  * - Topic
    - Message Type
    - Description
  * - ``<NODE_NAME>/is_estimator_running``
    - `Bool <https://docs.ros.org/en/jazzy/p/std_msgs/msg/Bool.html>`_
    - Indicates whether the payload estimator is currently running.
  * - ``<NODE_NAME>/is_estimation_successful``
    - `Bool <https://docs.ros.org/en/jazzy/p/std_msgs/msg/Bool.html>`_
    - Indicates whether the payload estimation algorithm has successfully converged to a solution.

These topics should be monitoried after starting the estimation routine (:ref:`see below <bota-payload-estimator-node-services>`) to check its status and decide on further actions.

.. _bota-payload-estimator-node-services:
Services
------------------

The node exposes the following service:

.. list-table:: 
   :widths: 55 30 45
   :header-rows: 1
   :class: highlight

   * - Service
     - Service Type
     - Description
   * - ``/<NODE_NAME>/start_payload_estimation``
     - ``std_srvs/srv/Trigger``
     - Start the payload estimation routine


Getting Started
---------------

**Launch the node from the console:**

.. code-block:: bash
  
   ros2 run bota_payload_utils bota_payload_estimator_node \
     --ros-args \
     -p node_name:=<NODE_NAME>
     -p config_file:=<PATH_TO_JSON> \
     -p input_node_name:=<INPUT_NODE_NAME> \
     -p imu_offset:=<IMU_OFFSET> \

**Call the start estimation service from console:**

.. code-block:: bash

   ros2 service call /<NODE_NAME>/start_payload_estimation std_srvs/srv/Trigger {}

**Monitor the estimation status topics:**

.. code-block:: bash

    ros2 topic echo /<NODE_NAME>/is_estimator_running
    ros2 topic echo /<NODE_NAME>/is_estimation_successful

////////////////////////////


Complete Usage Example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Bota Systems provides a ROS2 demo package ``bota_demo_ros2`` to get yourself started with the **Bota Payload Utilities for ROS2 nodes**.

.. 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 package implementation in our official GitLab repository.</p>
    <a href="https://gitlab.com/botasys/control_toolkit/bota_demo_ros2" 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_demo_ros2</code>
      <span style="margin-left:10px; color: #ffffff; font-weight:700; vertical-align: middle;">on GitLab</span>
    </a>
  </div>