==========================================
QGen Model Debugger: Step by Step Tutorial
==========================================

General comments
================

For installation and general documentation please refer to :ref:`debugger_doc`.
This tutorial assumes QGen and QGen debugger have been setup succesfully,
see :ref:`qgen-installation` for more details.

Create a Debugging project from MATLAB
======================================

Open the model that you want to debug in MATLAB, in this example we will be
using the model available `QGEN_INSTALL/share/qgen/examples/speedometer/speedometer.mdl`,
and click on `QGen > Create Debug session`.
This will create a new harness model in the same directory called `<model_name>_sim.slx`.

.. image:: img/DebuggerTuto1.png

This model references the original model and logs the signals connect to its
input and outputs ports. Additionally, it creates an `inputs` subsystem that you can use to
generate an appropriate test case.
Click `OK` on the dialog window that appeared, and proceed by updating the
signals within the `Signal Builder` window. Please refer to the signal builder
`documentation <https://www.mathworks.com/help/simulink/ug/working-with-signal-groups.html>`_
for more detail.

.. image:: img/DebuggerTuto2.png

Feel free to replace the signal builder block by any combination of blocks or
model references if desired.

.. image:: img/DebuggerTuto3.png

Once the test case is ready, run the simulation on your model by clicking on
the icon highlighted in red below.

.. image:: img/DebuggerTuto4.png

Start Debugging the model in GPS
================================

Once you can simulate the model successfully, click on
`QGen > Start QGen Debugger in GPS`.

.. image:: img/DebuggerTuto5.png

Two dialog windows will appear to define the debugging environment. The first will ask you
whether you want to use the test case created previously, click on `Yes`.

.. image:: img/DebuggerTuto6.png

If you model is using workspace variables click on `Yes` in the next dialog.

.. image:: img/DebuggerTuto7.png

GPS will then open and ask you to choose a target language for code generation,
pick `Ada` or `C` and click on `OK`.

.. image:: img/DebuggerTuto8.png

The next pop-up will ask you about a tolerance value that can be used to
consider the simulation correct or false.
All values output values coming from the generated code will have to be inside
the range [simulated-value - tolerance, simulated-value + tolerance] to be
considered correct.
Choose a value suiting you needs or leave it empty to use 0.0 as default.

.. image:: img/DebuggerTuto9.png

You can then generate code, build the executable and start the debugger by
clicking on the right icon in the image below or by clicking on
`Build > MDL generate, build & debug > main.adb`

.. image:: img/GPS_Toolbar.png

.. image:: img/GPS_MDL_Menu.png

After the generation and build process complete a `Debugger Console` Panel will
appear. Double click on your original model in the project view to display it
in a new GPS view.

Once the model is open browse to the desired subsystem by double clicking on a
subsystem or by using the outline view on the left. Set a breakpoint on a block
by right clicking on it and clicking on `Debug > Break on <block_name>`.

.. image:: img/DebuggerTuto10.png

Click on `Debug > Run...`, uncheck `Stop at beginning of main subprogram` and
click on `OK` to start debugging.

.. image:: img/DebuggerTuto11.png

Execution will reach the breakpoint on the block defined earlier and you can
examine the values and execute step by step, please refer to
:ref:`debugger_doc` for all the functionalities available to you at that
stage.

.. image:: img/DebuggerTuto12.png