Messages logging
================

.. toctree::
   :maxdepth: 3
   :caption: Contents:

Introduction
------------

The methods used to send and received messages (:cpp:func:`PROTOBUF_UTILS::sendMessages`,
:cpp:func:`PROTOBUF_UTILS::updateReceivedMessages`) include logging mecanism that can be used to log the protobuf sent or
received messages.

Activation
----------

The only method that has to be called is :cpp:func:`PROTOBUF_UTILS::initiateLogging` :

.. code-block:: cpp
    :linenos:

    PROTOBUF_UTILS protobuf(&streamObj, &myTimer);
    protobuf.initiateLogging();

The use of `libDM_msg_center <../libdm_msg_center/index.html>`_ does call this method automatically.


Location and structure of the logging file
------------------------------------------

From June 2024, the protobuf events are logged inside the unique protobuf encoded binary file. The file is located in the SD card in
``local_folder/log.binDM``.

- The logging binary file is located in the SD card in ``local_folder/log.binDM``.

More information about the general logging mechanism at `libDM_stream_logger <../libdm_stream_logger/index.html>`_

Body
~~~~

Inside the |loggerframe| structure, a field containing the protobuf events exists, encoded as a |protoframe|.

- The logged frame the common structure of |protoframe| with the addition of direction and frame size.

.. |loggerframe| raw:: html

   <a href="_static/protofiles/protobuf.html#.LoggerFrame" target="_blank">LoggerFrame</a>

.. |protoframe| raw:: html

   <a href="_static/protofiles/protobuf.html#.ProtoFrame" target="_blank">ProtoFrame</a>

.. admonition:: Message structure

    =========  ==========  ================
    Direction  Frame size  Protobuf message
    =========  ==========  ================

With direction being 0 for messages received and 1 for messages sent.

Decoding the logging file
-------------------------

A general logging file handle the decoding of all the enclosed information, including protobuf events.
The script is located in the folder tools/decode_protobuf.py.

The script can be used as follow:

- Install the requirements:

.. code-block:: bash

    pip install -r requirements.txt

- Run the script:

.. code-block:: bash

    python decode_protobuf.py log.binDM

The script will read and extract the data from the logging file and create a new file ``protobufEventsLog_decoded.json.json`` inside the output folder, with the
messages sent or received presented with json format, for example:

.. code-block:: json
    :linenos:

    [
        {
            "startByte": 1437226410,
            "timestamp": "1333291054",
            "attitude": {
                "attitudeLocal": {
                    "ypr": {
                        "pitch": 0.2,
                        "yaw": 0.1
                    }
                }
            },
            "endByte": 2857740885,
            "direction": "RX"
        },
        {
            "startByte": 1437226410,
            "timestamp": "1333341049",
            "attitude": {
                "attitudeLocal": {
                    "ypr": {
                        "pitch": 0.2,
                        "yaw": 0.1
                    }
                }
            },
            "endByte": 2857740885,
            "direction": "RX"
        }
    ]