[doc] Add a Debug section. (#2968)

doc/sphinx/source/developer_guide/debug.rst

@@ -0,0 +1,150 @@
+.. developer_guide debug
+
+=========
+Debugging
+=========
+
+Debugging can be essential when developing your own module. Here are some ways to help debug your code.
+
+Messages
+--------
+
+There are a few messages that you can use to debug over telemetry.
+You then can see the result with the **Messages** tool.
+
+INFO_MSG
+________
+
+**INFO_MSG** allows you to send a char array. It is defined as:
+
+.. code-block:: xml
+
+    <message name="INFO_MSG" id="215">
+        <field name="msg" type="char[]"/>
+    </message>
+
+
+Example:
+
+.. code-block:: C
+
+    #include <string.h>
+    #include "modules/datalink/telemetry.h"
+    ...
+    void my_function() {
+      char msg[] = "It works!";
+      DOWNLINK_SEND_INFO_MSG(DefaultChannel, DefaultDevice, strlen(msg), msg);
+    }
+
+PAYLOAD_FLOAT
+_____________
+
+**PAYLOAD_FLOAT** allows you to send an array of floats. It is defined as:
+
+.. code-block:: xml
+
+    <message name="PAYLOAD_FLOAT" id="237">
+        <field name="values" type="float[]"/>
+    </message>
+
+
+Example:
+
+.. code-block:: C
+
+    #include "modules/datalink/telemetry.h"
+    ...
+    void my_function() {
+      char buf[] = {42.2, 12.5, 8};
+      DOWNLINK_SEND_PAYLOAD_FLOAT(DefaultChannel, DefaultDevice, 3, buf);
+    }
+
+
+Shell
+-----
+
+When using **ChibiOS**, you can use the **shell** module to have a shell-like interface on the autopilot.
+
+Setup shell
+___________
+
+In your airframe, add the *shell* module:
+
+.. code-block:: xml
+
+    <module name="shell">
+        <configure name="SHELL_PORT" value="uart6"/>
+        <configure name="SHELL_BAUD" value="B115200"/>
+        <configure name="SHELL_DYNAMIC_ENTRIES_NUMBER" value="5"/>
+    </module>
+
+Connect your PC to the UART through a *serial to USB convertor*, and open the serial port with e.g. minicom or GtkTerm. Hit *ENTER* to be welcomed by a nice ``pprz >`` prompt !
+
+To test it, type ``info`` in the prompt, then hit *ENTER*. Various info about the autopilot should be printed.
+
+
+Add your own commands
+_____________________
+
+You can add your own commands to the shell.
+
+.. note::
+    
+    You can define up to ``SHELL_DYNAMIC_ENTRIES_NUMBER`` commands. This number default to 5, but you can increase it with a *configure* in your airframe.
+
+This example shows how to define your own commands in your module:
+
+.. code-block:: C
+    
+    #if USE_SHELL
+    #include "modules/core/shell.h"     // include this file
+    
+    // implement your command in a function with this prototype:
+    static void cmd_mycommand(shell_stream_t *sh, int argc, const char *const argv[]) {
+        // print to the shell with chprintf
+        chprintf(sh, "My amazing command got %d args!\r\n", argc);
+    }
+    #endif
+    
+    ...
+    
+    void mymodule_init(void) {
+    #if USE_SHELL
+        // register your command
+        shell_add_entry("mycmd", cmd_mycommand)
+    #endif
+    }
+
+
+.. note::
+
+    + Unlike what is usually done, the ``argc`` is the number of arguments *excluding* the command invocation. When no parameters is given to the command, *argc == 0*.
+    + As done in this example, you can put all your shell related code behind a ``#if USE_SHELL ... #endif`` for your module to work regardless if the shell module is loaded or not.
+
+.. admonition:: Using the serial over USB
+
+    If you are using the serial over USB, you can use ``usb_serial`` or ``usb_serial_debug`` as the SHELL_PORT.
+
+Debugger
+--------
+
+You can debug your code using GDB.
+
+Build the firmware with debug symbols enabled. In the firmware section of the airframe, add:
+
+.. code-block:: C
+
+    <configure name="RTOS_DEBUG" value="1"/>
+
+The ELF file is located in ``var/aircrafts/<$AIRCRAFT>/ap/obj/ap.elf``.
+
+You can then debug the firmware using any SWD or JTAG probe.
+
+coming soon™: how to debug using VsCode !
+
+Log
+---
+
+You can use logs to help you debug your code. See the :ref:`logging` page.
+
+

doc/sphinx/source/developer_guide/index_developer.rst

@@ -14,4 +14,5 @@ TBD
     modules
     abi
     logging
+    debug
 

doc/sphinx/source/developer_guide/logging.rst

@@ -1,5 +1,7 @@
 .. developer_guide logging
 
+.. _logging:
+
 =============
 Logging
 =============