Diff: Pixy.h

Revision:

2:90355c600404

Parent:

1:183ebbbc9c2e

Child:

3:1e4c6d7a0053

diff -r 183ebbbc9c2e -r 90355c600404 Pixy.h
--- a/Pixy.h	Mon May 21 16:14:19 2018 +0000
+++ b/Pixy.h	Tue May 22 17:15:30 2018 +0000
@@ -34,7 +34,7 @@
 #define PIXY_H
 
 /**
- * Includes
+ * Include : Mbed Library
  */
 #include "mbed.h"
 
@@ -48,12 +48,24 @@
 #define CC_BLOCCODE         0xAA56
 
     /**
-     * Types
+     *  \struct Byte    ->      Short hand for unsigned char
+     *  \struct Word    ->      Short hand for unsigned short
+     *  \struct lWord   ->      Short hand for unsigned long
      */
     typedef unsigned char   Byte;
     typedef unsigned short  Word;
     typedef unsigned long   lWord;
-    
+    /**
+     *  \struct T_pixyCCBloc
+     *  \brief Structured type to match pixy Color Code bloc organisation
+     *  \param Checksum (Word) : modulus sum of all words of the message
+     *  \param signature (Word) : identity (ie : numbers associated with colors) of the detected color code bloc
+     *  \param x (Word) : X coordinate (in pixel) of the center of the color code bloc
+     *  \param y (Word) : Y coordinate (in pixel) of the center of the color code bloc
+     *  \param width (Word) : Width (in pixel) of the color code bloc
+     *  \param height (Word) : Height (in pixel) of the color code bloc
+     *  \param angle (Word) : Angle (in degree, referenced to horizontal) of the color code bloc  
+     */
     typedef struct {
         Word    checksum;
         Word    signature;
@@ -64,6 +76,16 @@
         Word    angle;
     } T_pixyCCBloc;
     
+    /**
+     *  \struct T_pixyNMBloc
+     *  \brief Structured type to match pixy normal bloc organisation
+     *  \param Checksum (Word) : modulus sum of all words of the message
+     *  \param signature (Word) : identity (ie : number associated with the color) of the detected bloc
+     *  \param x (Word) : X coordinate (in pixel) of the center of the color code bloc
+     *  \param y (Word) : Y coordinate (in pixel) of the center of the color code bloc
+     *  \param width (Word) : Width (in pixel) of the color code bloc
+     *  \param height (Word) : Height (in pixel) of the color code bloc
+     */
     typedef struct {
         Word    checksum;
         Word    signature;
@@ -73,11 +95,23 @@
         Word    height;
     } T_pixyNMBloc;
     
+    /**
+     *  \union T_pixyCCData
+     *  \brief Structured type to match pixy Color Code bloc organisation
+     *  \param CCBloc (T_pixyCCBloc) : Color Code bloc structured element
+     *  \param tab[14] (Byte) : Byte access to the Color Code bloc 
+     */
     typedef union {
         Byte            tab[14];
         T_pixyCCBloc    CCbloc;
     } T_pixyCCData;
     
+    /**
+     *  \union T_pixyNMData
+     *  \brief Structured type to match pixy normal bloc organisation
+     *  \param CCBloc (T_pixyCCBloc) : Normal bloc structured element
+     *  \param tab[12] (Byte) : Byte access to the normal bloc 
+     */
     typedef union {
         Byte            tab[12];
         T_pixyNMBloc    NMbloc;
@@ -98,7 +132,8 @@
 
 
 /**
- * Pixy
+ * Pixy : CMU CAM 5 - Smart camera
+ * More informations at http://cmucam.org/projects/cmucam5
  */
 class PIXY {
 
@@ -108,22 +143,29 @@
 
 public :
 
-    /**
-     * Variables globales
-     *
-     * @note
-     *  A FIFO is a circular buffer where data are stored in the order in witch
-     *  they arrive. You need 2 variables to point both read and write registers.
-     *  The library manage both pointers, but access to the FIFO is allowed from
-     *  outside of the library, so you can manage your own read pointers.
-     *  Write pointers are strictly private.   
-     *
-     * @section DESCRIPTION
-     *  Pixy_CCFIFO is a FIFO where the Color Code objects are stored
-     *  Pixy_NMFIFO is a FIFO where the Normal objects are stored
-     *  Pixy_CCObjet is the number of CC object read from the CAM during the last frame
-     *  Pixy_NMObjet is the number of normal object read from the CAM during the last frame
-     */
+/** Direct access to the CC FIFO
+ * @note A FIFO is a circular buffer where data are stored in the order in witch they arrive and can be read in the same order. A FIFO need 2 variables (call read and write pointers) to point both read and write registers.
+ * @note The library manage both read and write pointers with FIFO functions, but users can access the FIFO with their own code, users must then manage their own read pointers while write pointers (that are strictly private) can only be managed by the library functions.   
+ *
+ *  \var Pixy_CCFIFO[20]
+ *  \brief is a FIFO where the Color Code objects are stored. FIFO can store up to 20 objects
+ */
+
+/** Direct access to the NM FIFO
+ * @note A FIFO is a circular buffer where data are stored in the order in witch they arrive and can be read in the same order. A FIFO need 2 variables (call read and write pointers) to point both read and write registers.
+ * @note The library manage both read and write pointers with FIFO functions, but users can access the FIFO with their own code, users must then manage their own read pointers while write pointers (that are strictly private) can only be managed by the library functions.   
+ *  \var Pixy_NMFIFO[20]
+ *  \brief is a FIFO where the Normal objects are stored. FIFO can store up to 20 objects
+ */
+ 
+/** 
+ *  \var Pixy_CCObjet
+ *  \brief is the number of CC object read by the library ISR from the CAM during the last frame
+ *  @note not Thread Safe
+ *  \var Pixy_NMObjet
+ *  \brief is the number of normal object read by the library ISR from the CAM during the last frame
+ *  @note not Thread Safe
+ */
     T_pixyCCData        Pixy_CCFIFO[20];    // FIFO des objets ColorCode
     T_pixyNMData        Pixy_NMFIFO[20];    // FIFO des objets Normaux
     Byte                Pixy_CCObjet;       // Nombre d'objets de type Color Code
@@ -132,25 +174,28 @@
     Byte                Pixy_FirstNMObjet;  // Position dans la FIFO du premier objet de la trame suivante
     
     
-    /** Liste des Sémaphores
+    /** A new frame as been read
      *
-     * @note
-     *  Semaphore are global variable used to communicate from ISR with main routine
-     *  All semaphores must be cleared by user.
+     * @note Semaphore are global variable used to communicate from ISR with main routine. All semaphores must be cleared by user.
+     *  \var FlagPixy
+     *  \brief is automaticly set after each received image frame
+     */
+
+    /** Data have been lost
      *
-     * @section DESCRIPTION
-     *  FlagPixy is automaticly set after each received image frame
-     *  FlagPixyOverflow is automaticly set if any FIFO oveflows (more than 20 obj). 
+     * @note Semaphore are global variable used to communicate from ISR with main routine. All semaphores must be cleared by user.
+     *  \var FlagPixyOverflow
+     *  \brief is automaticly set if any FIFO oveflows (more than 20 obj of a kind). 
      */
     int                 FlagPixy, FlagPixyOverflow;
     int                 Pixy_check;
 
     /**
-     * Constructor.
+     * Constructor of pixy object.
      *
-     * @param tx is the Mbed pin used as TX
-     * @param rx is the Mbed pin used as RX
-     * @param debit is the bitrate of the serial (max value is 230400 b/s)
+     * @param tx : the Mbed pin used as TX
+     * @param rx : the Mbed pin used as RX
+     * @param debit : the bitrate of the serial (max value is 230400 b/s)
      */
     PIXY(PinName tx, PinName rx, int debit =230400);
 
@@ -158,18 +203,18 @@
      * Return the number of objects (normal and ColorCode) that have been
      * received from the PIXY during the last frame
      *
-     * @param nbNormal (passed by reference) number of normal object detected
-     * @param nbCC (passed by reference) number of color code object detected
-     * @return : 0 if sucessfull,
+     * @param nbNM (passed by reference) : number of normal object detected
+     * @param nbCC (passed by reference) : number of color code object detected
+     * @return   0 if sucessfull,
      *          -1 if no PIXY is talking,
      *          -2 if object(s) have been lost (from previous frame or from actual) 
      */
-    int detectedObject (int* nbNormal, int* nbCC);
+    int detectedObject (int* nbNM, int* nbCC);
 
     /**
      * Reads the oldest Color Code object from the last frame received 
      *
-     * @note : also manage the Color Code FIFO
+     * @note this function also manage the read pointer of the Color Code FIFO (ie : after use function point the next object to be read)
      *
      * @return a T_PixyCCBloc (see .h for details)
      */
@@ -178,7 +223,7 @@
     /**
      * Reads the oldest Normal object from the last frame received 
      *
-     * @note : also manage the Normal FIFO
+     * @note this function also manage the read pointer of the Normal FIFO (ie : after use function point the next object to be read)
      *
      * @return a T_PixyNMBloc (see .h for details)
      */