C++ Parameters
==============
.. highlight:: cpp

.. default-domain:: cpp

Parameters allow to view and modify data from running programs. They consist of an input and output signal
where the output signal can be overridden either from the ln manager or from python clients.

Creating C++ Parameters is a two-step process. You first need to instantiate a parameter block

.. cpp:function:: ln::parameters::parameter_block(ln::client *clnt_, std::string parameter_group_name_, bool always_publish_ = false, std::string topic_name_ = "")

and then register parameters to it using

.. cpp:function:: template<typename... Types> ln::parameters::parameter_block::register_parameters(port_description<Types>... port_descriptions)

Note that this function can only be called once, you cannot register more than one set of parameters to a `parameter_block`.
It is easiest to supply brace-enclosed initializer lists to this functions, e.g. `{"sig_name", &sig_in, &sig_out, before_update_callback, after_update_callback}`.
The callbacks can also be omitted and are explained in the next section. Please see the following code example for details. Inside your main loop, you then have to cyclically call

.. cpp:function:: ln::parameters::parameter_block::update()

to allow overriding parameters.

.. sourcecode:: c++

        #include <chrono>
        #include <thread>
        #include <iostream>

        #include <ln/ln.h>
        #include <ln/parameters.h>
        #include <ln/parameters_eigen.h>

        int main(void) {
            // Init the client
            ln::client clnt("ln_parameters_example");

            // Create parameter block
            ln::parameters::parameter_block params(&clnt, "ln.parameters.example.cpp");

            // Signal
            double sig_in = 0, sig_out = 0;

            params.register_parameters<double>({"sig", "human-readable sig description", &sig_in, &sig_out});

            // Loop
            while (true) {
                std::this_thread::sleep_for(std::chrono::seconds(5));
                sig_in += 1;
                params.update();

                std::cout << "sig input: " << sig_in << ", sig output: " << sig_out << std::endl;
            }
        }


Parameter Callbacks
^^^^^^^^^^^^^^^^^^^
As mentioned above, you can supply the two callbacks

.. cpp:struct:: ln::parameters::port_description

   .. cpp:member:: std::function<bool(void *)> before_update_callback
   .. cpp:member:: std::function<void(void *)> after_update_callback


where the function `before_update_callback` is called from the service handler when a new override arrives. This function can be used to check the parameter value for validity,
if the value is e.g. out of range it can `return false;` and the update is rejected. Otherwise it has to `return true;` to accept the update.

The function `after_update_callback` is called within your main loop's call to `update()` after a parameter has been updated. It can be used to recompute dependant values.

Debugging Parameters
^^^^^^^^^^^^^^^^^^^^
The env variable `LN_PARAMETER_DEBUG` can be set to enable some debug output when using ln parameters (also for Simulink models).

Manager and Web UI Usage
^^^^^^^^^^^^^^^^^^^^^^^^

When a client registers a parameter block, it provides manager-visible
``ln/parameters/*`` services. The LN manager GTK UI and web UI use these
services to query parameter values, set or clear overrides, and request
temporary publication of a parameter as a topic for plotting.

In the browser UI, open ``/lnm/parameters`` or select the ``parameters`` tab.
Use the pattern field and ``refresh`` button to query providers. Selecting a
parameter shows its input, override, and output values. Scalars, vectors, and
matrices get editable layouts suited to their shape. ``set override`` fixes the
parameter output to the entered value; ``reset override`` returns it to normal
provider behavior. ``open scope`` requests topic publication for that parameter
and opens ``ln_scope`` for the parameter's ``.output`` field.

For scripted access, use the web UI protocol messages documented in
:doc:`reference_webui_protocol` or the helper methods on
``links_and_nodes_manager_client.ManagerClient``:

.. code-block:: python

   parameters = await client.get_parameters("*")
   await client.set_parameter_override(
       service,
       parameter_name,
       True,
       "42.0",
       provider_id=provider_id,
   )
   await client.open_parameter_scope(
       service,
       parameter_name,
       provider_id=provider_id,
   )