Trickle configuration (ITk)
===========================

This section describes the API to interface ``felix-trickle`` to set the trickle memory and settings.
It is only relevant for systems using a firmware that supports trickle configuration (ITk).

For all functions except :cpp:func:`append_trickle_config<FelixClientThreadExtension520::append_trickle_config>`,
the FID is the virtual FID of ``felix-trickle``.


Setting the trickle memory
--------------------------

1. Create a new trickle configuration using the
   :cpp:func:`create_trickle_config<FelixClientThreadExtension520::create_trickle_config>` function.

.. doxygenfunction:: FelixClientThreadExtension520::create_trickle_config
  :no-link:

2. Append the configuration for each frontend using the
   :cpp:func:`append_trickle_config<FelixClientThreadExtension520::append_trickle_config>` function.

.. doxygenfunction:: FelixClientThreadExtension520::append_trickle_config
  :no-link:

3. Send the configuration to the firmware using the
   :cpp:func:`send_trickle_config<FelixClientThreadExtension520::send_trickle_config>` function.

.. doxygenfunction:: FelixClientThreadExtension520::send_trickle_config
  :no-link:

Controlling trickle configuration
---------------------------------

The trickle configuration can be started and stopped using the
:cpp:func:`start_trickle<FelixClientThreadExtension520::start_trickle>` and
:cpp:func:`stop_trickle<FelixClientThreadExtension520::stop_trickle>` functions.

.. doxygenfunction:: FelixClientThreadExtension520::start_trickle
  :no-link:

.. doxygenfunction:: FelixClientThreadExtension520::stop_trickle
  :no-link:

The BCIDs between which the trickle configuration is active can be selected using the
:cpp:func:`select_trickle_bcids<FelixClientThreadExtension520::select_trickle_bcids>`
function and the speed can be throttled using the
:cpp:func:`throttle_trickle<FelixClientThreadExtension520::throttle_trickle>` function.

.. doxygenfunction:: FelixClientThreadExtension520::select_trickle_bcids
  :no-link:

.. doxygenfunction:: FelixClientThreadExtension520::throttle_trickle
  :no-link:

.. caution::
  The functionality for both functions is not implemented in the firmware yet.

.. note::
  A throttle factor of 1 means no throttling, 2 means half speed, etc.

.. important::

   - ``create_trickle_config()`` always resets the client-side state.
   - ``send_trickle_config()`` always overwrites the server-side configuration.
   - While trickle is running, only ``stop_trickle()`` is allowed.

Code Example
------------

.. code-block:: cpp
  :linenos:

  fct.create_trickle_config();

  for (const auto& [frontend_fid, config] : trickle_config) {
    fct.append_trickle_config(frontend_fid, config);
  }

  fct.send_trickle_config(trickle_fid);

  fct.select_trickle_bcids(trickle_fid, 0, 100);
  fct.throttle_trickle(trickle_fid, 2);

  fct.start_trickle(trickle_fid);
  fct.stop_trickle(trickle_fid);