Lifecycle Node
=============

*Advanced state management for safety-critical applications*

The lifecycle node is designed for applications that require strong safety requirements and controlled state management. Perfect for production environments where precise control over node initialization, activation, and shutdown is essential.

**Learn more:** `Lifecycle design documentation <https://design.ros2.org/articles/node_lifecycle.html>`_ | `Lifecycle example <https://github.com/ros2/demos/blob/humble/lifecycle/README.rst>`_

----

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

The standard node requires the following parameters:

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

   * - Parameter
     - Description
   * - ``config_file``
     - Path to the JSON configuration file
   * - ``output_rate``
     - Controls reading mechanism (see details below)
   * - ``bota_ft_sensor_link_name``
     - Prefix used to name the published topics. It must match the name provided to the XACRO.

**Understanding output_rate behavior:**

.. important::
   The **output_rate** parameter controls if the reading mechanism is **from the buffer** or **from the stream**:

   * **Positive value** - Reading from the buffer timed by ROS2. Topic publishing rate matches the set output rate. 
     The sensor update rate should be set higher than the desired output rate (``sinc_length`` in Gen 0 and ``app_submode`` in Gen A).
   
   * **Zero (0)** - Reading from the stream. Topic publishing will be timed by the sensor update rate.

----

Lifecycle State Management
---------------------------

The lifecycle node follows the ROS2 lifecycle state machine. Use the following services to manage transitions:

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

   * - Transition
     - ID
     - Service Call
   * - **configure()**
     - 1
     - .. code-block:: bash
     
          ros2 service call /bota_driver_lcnode/change_state \
            lifecycle_msgs/srv/ChangeState "{transition: {id: 1}}"
   * - **cleanup()**
     - 2
     - .. code-block:: bash
     
          ros2 service call /bota_driver_lcnode/change_state \
            lifecycle_msgs/srv/ChangeState "{transition: {id: 2}}"
   * - **activate()**
     - 3
     - .. code-block:: bash
     
          ros2 service call /bota_driver_lcnode/change_state \
            lifecycle_msgs/srv/ChangeState "{transition: {id: 3}}"
   * - **deactivate()**
     - 4
     - .. code-block:: bash
     
          ros2 service call /bota_driver_lcnode/change_state \
            lifecycle_msgs/srv/ChangeState "{transition: {id: 4}}"
   * - **shutdown()**
     - 6
     - .. code-block:: bash
     
          ros2 service call /bota_driver_lcnode/change_state \
            lifecycle_msgs/srv/ChangeState "{transition: {id: 6}}"

----

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

Once running, the node publishes the following topics:

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

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

.. important::
   **Topic Usage Recommendations:**
   
   * **For control applications:** Use ``/bota_frame`` as it contains all sensor data from the same sampling time in a single message, ensuring temporal consistency.
   
   * **For visualization and monitoring:** The individual topics (``/bota_wrench``, ``/bota_imu``) are provided for convenience with standard message types, making them easily compatible with tools like PlotJuggler and RViz.
   
   **Warning:** Using data from multiple individual topics simultaneously may lead to temporal inconsistencies, as there's no guarantee of synchronization between different topic subscriptions. The data points might come from different sampling times.

.. _bota-frame-msg:

.. note:: 
   **Custom Message Type:** ``BotaFrame`` (*) is a custom message type defined in the ``bota_driver`` package. 
   This message type will be available in your workspace as long as the ``bota_driver`` package is properly installed and sourced.
   
   **BotaFrame Definition:**
   
   .. code-block:: yaml
   
      # Status information
      bool throttled
      bool overrange
      bool invalid
      bool raw
      
      # Force and torque values in I.S. (same as /bota_wrench)
      geometry_msgs/WrenchStamped wrench
      
      # Imu values in I.S. (same as /bota_imu)
      sensor_msgs/Imu imu

      # Temperature in Celsius
      float32 temperature
      
      # Sensor timestamp in microseconds
      uint32 timestamp

.. note:: 
   **Timestamp Information:** All messages are stamped in the header with the ROS2 publishing time for precise temporal coordination. 
   This is different from the sensor's internal timestamp included in ``/bota_frame``, which corresponds to the actual sampling time on the sensor.

----

Available Services
------------------

The node exposes the following service:

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

   * - Service
     - Service Type
     - Description
   * - ``/bota_driver_lcnode/tare``
     - ``std_srvs/srv/Trigger``
     - Zeros out the wrench output of the sensor, setting current state as new reference

.. important::
   The **tare** service can only be called when the node is in **INACTIVE** state.

----

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

**Launch the node from the console:**

.. code-block:: bash
  
   ros2 run bota_driver bota_driver_lcnode \
     --ros-args \
     -p config_file:=<PATH_TO_JSON> \
     -p output_rate:=<VALUE> \
     -p bota_ft_sensor_link_name:=<BOTA_FT_SENSOR_LINK_NAME>

**Manage lifecycle states:**

.. code-block:: bash

   # Configure the node
   ros2 service call /bota_driver_lcnode/change_state lifecycle_msgs/srv/ChangeState "{transition: {id: 1}}"
   
   # Activate the node (starts publishing topics)
   ros2 service call /bota_driver_lcnode/change_state lifecycle_msgs/srv/ChangeState "{transition: {id: 3}}"

**Call the tare service from console:**

.. code-block:: bash

   # Note: Only works when node is in INACTIVE state
   ros2 service call /bota_driver_lcnode/tare std_srvs/srv/Trigger {}

**Complete Example:**

.. 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: 8px; box-shadow: 0 2px 10px rgba(0,0,0,0.1);">
    <h4 style="color: rgb(218, 101, 39); margin-top: 0; font-size: 1.2em;">Ready to try it out?</h4>
    <p style="margin-bottom: 20px; color: #495057;">A detailed example for the lifecycle node is coming soon. For now, you can follow the example for the standard node and adapt it for the lifecycle managed node youself.</p>
    <div style="display: flex; gap: 15px; flex-wrap: wrap;">
      <a href="https://gitlab.com/botasys/drivers/bota_driver_ros2_example" target="_blank" style="background: rgb(218, 101, 39); color: white; padding: 12px 25px; text-decoration: none; border-radius: 8px; 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)'">
         Standard Node Example on GitLab
      </a>
    </div>
  </div>