Revision 8:5ce5fe1ce503, committed 2018-03-28

Comitter:

dzoni

Date:

Wed Mar 28 13:18:59 2018 +0000

Parent:

7:1aba48efb1c3

Child:

9:486eeba3950f

Commit message:

Doxygen comments added. Ready for function test.

Changed in this revision

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doxy_templates.txt	Wed Mar 28 13:18:59 2018 +0000
@@ -0,0 +1,77 @@
+Dokumentace souborů
+
+V hlavičkových souborech a main.c pište plnou dokumentaci funkcí, struktur atd., ve všech souborech navíc pište tagy @author a @file. V textu dokumentace používejte angličtinu.
+
+Ukázka hlavičkového souboru
+#ifndef MY_AWESOME_LIBRARY_H
+#define MY_AWESOME_LIBRARY_H
+ 
+/**
+ * @brief   [OPTIONAL] Brief file description.
+ * @file    my_awesome_library.h
+ * @author  John Doe <john.doe@example.com>
+ *
+ * [OPTIONAL] Detailed file description.
+ */
+ 
+#include <stdlib.h>
+// ...
+ 
+#endif // MY_AWESOME_LIBRARY_H
+Ukázka jiného (nehlavičkového) souboru
+/**
+ * @author John Doe <john.doe@example.com>
+ * @file   list.c
+ */
+ 
+...
+
+Dokumentace struktur a výčtových typů
+/**
+ * @brief Doubly linked list node.
+ *
+ * [OPTIONAL] Detailed description.
+ */
+typedef struct node
+{
+    struct node *prev; /**< previous node        */
+    struct node *next; /**< next node            */
+    void        *data; /**< pointer to node data */
+} node_t;
+ 
+/**
+ * @brief UNIX file system permissions.
+ *
+ * [OPTIONAL] Detailed description.
+ */
+typedef enum mode
+{
+    Read    = 1, /**< read a file or list contents of a directory */
+    Write   = 2, /**< modify a file or directory entries          */
+    Execute = 4  /**< execute a file or enter a directory         */
+} mode_t;
+
+
+Dokumentace funkcí
+Pokud chcete v textu odkazovat parametr funkce, použijte značku @a parametr, hodnoty můžete značit např. značkou @c true. Funkce, které nic nevrací (mají návratový typ void) pochopitelně nemusí mít značku @return.
+
+/**
+ * @brief   Halting problem solver.
+ * @param   tm      Turing machine to simulate
+ * @param   input   input to simulate the @a tm with
+ * @return  @c true if the machine @a tm will halt with the tape @a input, @c false otherwise
+ * @note    [OPTIONAL] The content of the @a input tape will remain unchanged.
+ * @warning [OPTIONAL] Still under development.
+ * @bug     [OPTIONAL] This function can run indefinitely for some inputs.
+ *
+ * [OPTIONAL] Detailed information on how awesome this function is.
+ */
+bool halts(machine_t *tm, tape_t *input);
+Navíc, pokud je argument funkce ukazatel, přidejte za param položku [in], [out] nebo [in,out] pokud je to vstupní, výstupní resp. vstupno-výstupní argument:
+
+/**
+ * @param[in]     ro   memory to be read
+ * @param[out]    wo   memory to be filled
+ * @param[in,out] rw   memory to be read and written
+ */
+void foo(const void *ro, size_t *wo, char *rw);

--- a/main.cpp	Wed Mar 28 09:32:05 2018 +0000
+++ b/main.cpp	Wed Mar 28 13:18:59 2018 +0000
@@ -1,21 +1,35 @@
+/**
+ * @brief   Basic DC motor control test, rpm feedback by simple impulse signal, PID speed control.
+ * @file    main.cpp
+ * @author  Jan Tetour <jan.tetour@gmail.com>
+ *
+ * Test application for STM32F4 for small DC motor control. Main specifications:
+ *    - DC motor controlled by PWM
+ *    - Motor driver used L298N 
+ *    - RPM evaluated via simple impulse sensor
+ *    - Speed (RPM) controlled by PID controller
+ */
+ 
 #include "mbed.h"
+
 #include "FastPWM.h"
 #include "FastIO.h"
+
 #include "PID.h"
 
+// Define MODSERIAL buffer sizes
 #define MODSERIAL_DEFAULT_RX_BUFFER_SIZE 16
 #define MODSERIAL_DEFAULT_TX_BUFFER_SIZE 64 
 #include "MODSERIAL.h"
 
-#define IMPULSE_SENSOR_R_PIN (PA_9)
-#define PWM_OUT_R_PIN (PA_6)
+// Pin defintions
+#define IMPULSE_SENSOR_R_PIN    (PA_9)
+#define PWM_OUT_R_PIN           (PA_6)
 
-//------------------------------------
-// Hyperterminal configuration
-// 9600 bauds, 8-bit data, no parity
-//------------------------------------
+// Serial port definitions
 MODSERIAL pcLink(SERIAL_TX, SERIAL_RX);
 
+// Tasks timming definitions
 static const us_timestamp_t periodImpSens  =      125000; // 125 msec
 static const us_timestamp_t periodLEDBlink =      100000; // 100 msec
 static const us_timestamp_t periodPWMWrite =      250000; // 250 msec
@@ -28,31 +42,41 @@
 
 static us_timestamp_t tStamp = 0;
 
+static Timer myTimer;
+
+// RPM Sensor module level variables
 static unsigned int uiImpSens = 0U;
 static unsigned int uiImpSensTemp = 0U;
 static int          iImpSensLastState = 0;
-static float       fPwmDuty = 0.0;
+
+// PWM Generator module level variables
+static float fPwmDuty = 0.0f;
+
+// RPM Controller module level variables
 static float fRPMSetpoint = 0.0f;
 
-static void setup(void);
+// LOCAL MODULE VARIABLES
+// I/O pins related
+FastPWM mypwm(PWM_OUT_R_PIN);
+FastIn<IMPULSE_SENSOR_R_PIN> pinImpulseSensorIn;
+FastIn<USER_BUTTON> pinUserButtonIn;
+DigitalOut myled(LED1);
+
+// Controllers
+PID pid_RPM_Right_motor(1.0f, 0.0f, 0.0f, (((float)periodPWMWrite)/1000000.0f));
+
+// LOCAL FUNCTION DECLARATIONS
+// Task worker functions
 static void tskImpSens(void);
 static void tskLEDBlink(void);
 static void tskPWMWrite(void);
 static void tskRPMSetpoint(void);
 static void tskBackground(void);
 
-FastPWM mypwm(PWM_OUT_R_PIN);
-
-FastIn<IMPULSE_SENSOR_R_PIN> pinImpulseSensorIn;
-FastIn<USER_BUTTON> pinUserButtonIn;
+// Inititalization
+static void setup(void);
 
-PID pid_RPM_Right_motor(1.0f, 0.0f, 0.0f, (((float)periodPWMWrite)/1000000.0f));
-
-DigitalOut myled(LED1);
-
-Timer   myTimer;
-
-
+// Task management functions
 static inline void DO_TASK(us_timestamp_t tskPeriod, us_timestamp_t &tskTimer, us_timestamp_t timeStamp, void (*tskFunction)(void))
 {
     if (tskPeriod < (timeStamp - tskTimer))
@@ -67,7 +91,7 @@
     (*tskFunction)();
 }
 
-
+// Main function definition
 int main(void)
 {
     setup();
@@ -86,6 +110,8 @@
 }
 
 
+// LOCAL MODULE DEFINITIONS
+// Initialization
 void setup(void)
 {
     pcLink.baud(115200);
@@ -110,19 +136,38 @@
     pid_RPM_Right_motor.setSetPoint(0.0f);
 }
 
+// Task worker functions definitions
+/**
+ * @brief   RPM calculation.
+ * @note    Needs refactoring to implement #ifdef for 2 different implementation (with/without PID).
+ *
+ * Stores impulse count per measurement period and clears impulse counter.
+ */
 void tskImpSens(void)
 {
     uiImpSens = uiImpSensTemp;
     uiImpSensTemp = 0U;
 
-    pcLink.printf("IMP: %u imp.     \r", uiImpSens);
+ //   pcLink.printf("IMP: %u imp.     \r", uiImpSens);
 }
 
+/**
+ * @brief   User LED flashing.
+ *
+ * Implements User LED flashing.
+ */
 void tskLEDBlink(void)
 {
     myled = !myled;
 }
 
+/**
+ * @brief   Writes new duty cycle value into PWM generator.
+ * @note    Needs refactoring to implement #ifdef for 2 different implementation (with/without PID).
+ * @warning Not finished.
+ *
+ * Calculates new dyty cycle and writes the value into PWM generator.
+  */
 void tskPWMWrite(void)
 {
 //    fPwmDuty = fPwmDuty + 0.1;
@@ -145,6 +190,12 @@
 //    pcLink.printf("\r\nPWM: %.2f %%     \r\n", mypwm.read() * 100);
 }
 
+/**
+ * @brief   Implementation of periodic change of RPM Setpoint. Simulates setpoint changes to asses dynamic behaviour.
+ * @note    For test purposes.
+ *
+ * Increases Setpoint value step by step with every invocation.
+ */
 void tskRPMSetpoint(void)
 {
     fRPMSetpoint += 10.0f;
@@ -156,6 +207,14 @@
     pid_RPM_Right_motor.setSetPoint(fRPMSetpoint);
 }
 
+/**
+ * @brief   Implementation of background task. Periodically called from main loop without delay.
+ * @note    These actions are candidates for refactoring to event based implementation.
+ * @warning Initial implementation. Simple and easy.
+ *
+ * This function implements actions, which needs to be processed with high priority.
+ * Is intended to be called in every pass of main loop.
+ */
 void tskBackground(void)
 {
     // Impulse sensor - pulse counting
@@ -165,4 +224,4 @@
         iImpSensLastState = iTemp;
         uiImpSensTemp++;
     }
-}
\ No newline at end of file
+}