[telemetry] add documentation to telemetry system

sw/airborne/arch/lpc21/mcu_periph/sys_time_arch.c

@@ -120,6 +120,13 @@ void sys_time_arch_init( void ) {
   T0EMR = 0;
 
   /* set first sys tick interrupt    */
+  /* We need to wait long enough to be sure
+   * that all the init part is finished before
+   * the first interrupt. Since the global
+   * interrupts are enable at the end of the init
+   * phase, if we miss the first one, the
+   * sys_tick_handler is not called afterward
+   */
   T0MR0 = 4*sys_time.resolution_cpu_ticks;
 
   /* enable timer 0                  */

sw/airborne/subsystems/datalink/telemetry.c

@@ -20,14 +20,21 @@
  *
  */
 
+/**
+ * @file subsystems/datalink/telemetry.c
+ *
+ * Periodic telemetry system utility function.
+ *
+ */
+
 #include "subsystems/datalink/telemetry_common.h"
 
-//struct pprz_telemetry telemetry[PERIODIC_TELEMETRY_NB];
-
-//void periodic_telemetry_init(void) {
-//  telemetry = PERIODIC_TELEMETRY_MESSAGES;
-//}
-
+/** Register a telemetry callback function.
+ * @param _pt periodic telemetry structure to register
+ * @param _msg message name (string) as defined in telemetry xml file
+ * @param _cb callback function, called according to telemetry mode and specified period
+ * @return TRUE if message registered with success, FALSE otherwise
+ */
 bool_t register_periodic_telemetry(struct pprz_telemetry * _pt, char * _msg, telemetry_cb _cb) {
   // look for message name
   uint8_t i;

sw/airborne/subsystems/datalink/telemetry.h

@@ -25,9 +25,27 @@
 /**
  * @file subsystems/datalink/telemetry.h
  *
- * Periodic telemetry system header.
+ * Periodic telemetry system header (includes downlink utility and generated code).
  *
- * include downlink utility and generated code
+ * In order to use it a subsystem/module:
+ * - include this header:
+ *
+ *    #include "susystems/datalink/telemetry.h"
+ *
+ * - write a callback function:
+ *
+ *    void your_callback(void) {
+ *      // your code to send a telemetry message goes here
+ *    }
+ *
+ * - register your callback function (if the message name doesn't match
+ *   one of the names in your telemetry xml file or is already registered,
+ *   the function return FALSE)
+ *
+ *    register_periodic_telemetry(&your_telemetry_struct, "YOUR_MESSAGE_NAME", your_callback);
+ *
+ * In most cases, the default telemetry structure should be used
+ * (replace &your_telemetry_struct by DefaultPeriodic in the register function).
  */
 
 #include "std.h"

sw/airborne/subsystems/datalink/telemetry_common.h

@@ -32,7 +32,8 @@
 #include <inttypes.h>
 #include "std.h"
 
-/** Telemetry callback definition */
+/** Telemetry callback definition
+ */
 typedef void (*telemetry_cb)(void);
 
 /** Telemetry header
@@ -42,16 +43,16 @@ struct telemetry_msg {
   telemetry_cb cb;  ///< callback funtion
 };
 
+/** Telemetry structure.
+ *  Contains the total number of messages (from generated telemetry file)
+ *  and the list of registered callbacks
+ */
 struct pprz_telemetry {
-  uint8_t nb;       ///< number of messages
+  uint8_t nb;                 ///< number of messages
   struct telemetry_msg* msgs; ///< the list of (msg name, callbacks)
 };
 
-/** Telemetry init function
- */
-//void periodic_telemetry_init(void);
-
-/** Register function
+/** Register a telemetry callback function.
  * @param _pt periodic telemetry structure to register
  * @param _msg message name (string) as defined in telemetry xml file
  * @param _cb callback function, called according to telemetry mode and specified period