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

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

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

The methods used to send and received messages (:cpp:func:`MAVLINK_UTILS::sendMessage`, :cpp:func:`MAVLINK_UTILS::sendMessages`,
:cpp:func:`MAVLINK_UTILS::updateMonitoredMessages`) include logging mecanism that can be used to log the mavlink sent or
received messages.

Activation
----------

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

.. code-block:: cpp

    MAVLINK_UTILS mavlink(&streamObj);
    mavlink.initiateLogging();

.. warning::

    As mentionned in the API documentation, this function should be called after all messages to monitor and send have been added!
    So it should be called after all :cpp:func:`MAVLINK_UTILS::addMsgToMonitor` and :cpp:func:`MAVLINK_UTILS::addMsgToSendingList`.

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>`_

Header
~~~~~~

For informations, a header field inside LoggerFrame is giving mavlink messages Names and ID. The completion of this
header is done by :cpp:func:`MAVLINK_UTILS::initiateLogging`. It is given just as a indication as the log decoding tools will extract
the informations directly from generated code and ID encoded inside the mavlink frame payload.

.. code-block:: json

    {
        "mavlinkHeader": "ATTITUDE_QUATERNION,LOCAL_POSITION_NED,GLOBAL_POSITION_INT,HIGHRES_IMU,SYSROX_INS_GENERIC_CALIBRATION_BARO_SENSOR_CORRECTION,SYSROX_INS_GENERIC_CALIBRATION_IMU_SENSOR_CORRECTION_ACC,SYSROX_INS_GENERIC_CALIBRATION_IMU_SENSOR_CORRECTION_GYRO,SYSROX_INS_GENERIC_CALIBRATION_IMU_SENSOR_CORRECTION_MAG,SYSROX_INS_GENERIC_CALIBRATION_MAG_SENSOR_CORRECTION",
        "timestamp": 5811387
    },
    {
        "mavlinkID": "31,32,33,105,50005,50001,50002,50003,50004",
        "timestamp": 5811387
    },

Body
~~~~

Inside the |loggerframe| structure, a field containing the mavlink events exists and is populated when a mavlink event is sent or received.

- The logged mavlink frame follows mavlink structure with the addition of direction.

.. |loggerframe| raw:: html

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

.. admonition:: Message structure

    =========  ===============
    Direction  Mavlink message
    =========  ===============

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

Decoding
--------

A general logging file handle the decoding of all the enclosed information, including protobuf events.
The script is located in the protobuf repo, inside 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 ``mavlinkEventsLog_decoded.json`` inside the output folder, with the
messages sent or received presented with json format, for example:

.. code-block:: json

    {
        "mavlinkData": {
        "mavpackettype": "ATTITUDE_QUATERNION",
        "time_boot_ms": 11770,
        "q1": 0.8999999761581421,
        "q2": 0.10000000149011612,
        "q3": 0.20000000298023224,
        "q4": 0.30000001192092896,
        "rollspeed": 0.0,
        "pitchspeed": 0.0,
        "yawspeed": 0.0,
        "repr_offset_q": [
            0.0,
            0.0,
            0.0,
            0.0
        ]
        },
        "mavlinkDirection": "TX",
        "mavlinkID": 31,
        "timestamp": 11770214
    },