Diff: pixy2.h

Revision:

1:dd81f4065b6b

Parent:

0:dde1b9d6c9d6

Child:

2:5281a6289e8b

--- a/pixy2.h	Thu Feb 28 08:34:15 2019 +0000
+++ b/pixy2.h	Thu Feb 28 11:13:47 2019 +0000
@@ -65,7 +65,15 @@
 #define PIXY2_SET_DEFTURN   60
 #define PIXY2_SET_REVERSE   62
 #define PIXY2_ASK_VIDEO     112
- 
+
+
+/**************** STATE MACHINE ****************/
+
+typedef enum {idle, messageSent, receivingHeader, headerReceived, receivingData, dataReceived} T_Pixy2State;
+
+
+/**************** UTILS ****************/
+
 /**
  *  \struct Byte    ->      Short hand for unsigned char
  *  \struct Word    ->      Short hand for unsigned short
@@ -75,35 +83,76 @@
 typedef unsigned short  Word;
 typedef unsigned long   lWord;
 
-typedef enum {idle, messageSent, receivingHeader, headerReceived, receivingData, dataReceived} T_Pixy2State;
-
+/**
+ *  \union T_Word
+ *  \brief  Structured type to switch from word to bytes
+ *  \param  mot (Word)   : 16 bits word
+ *  \param  octet (Byte) : 2 bytes that overlap mot (byte access)
+ */
 typedef union {
     Word    mot;
     Byte    octet[2];
 }T_Word;
 
+/**
+ *  \union T_lWord
+ *  \brief  Structured type to switch from lword to word or bytes
+ *  \param  motLong (lWord) : 32 bits word
+ *  \param  mot (Word)      : 2 x 16 bits words that overlap motLong (word access)
+ *  \param  octet (Byte)    : 4 bytes that overlap motLong (byte access)
+ */
 typedef union {
     lWord   motLong;
     Word    mot[2];
     Byte    octet[4];
 }T_lWord;
 
+
+/**************** HEADERS ****************/
+
+/**
+ *  \struct T_pixy2Header
+ *  \brief  Structured type that match pixy2 header without checksum (send message)
+ *  \param  pixSync   (Word) : 16 bits synchro word - could be 0xc1ae (PIXY2_SYNC) or 0xc1af (PIXY2_CSSYNC)
+ *  \param  pixType   (Byte) : 8 bits message type identifier
+ *  \param  pixLength (Byte) : 8 bits message payload length (payload doesn't include checksum) 
+ */
 typedef struct {
     Word                pixSync;
     Byte                pixType;
     Byte                pixLength;
 }T_pixy2Header;
 
+/**
+ *  \struct T_pixy2sendFrame
+ *  \brief  Structured type that match frame definition for all kind of message to send to a pixy2 
+ *  \param  header (T_pixy2Header) : 4 bytes classical header starting with PIXY2_SYNC
+ *  \param  data   (Byte)          : 5 bytes payload (to match all usage, not all byte must be used)
+ */
 typedef struct {
     T_pixy2Header       header;
     Byte                data[5];
 }T_pixy2sendFrame;
 
+/**
+ *  \union  T_pixy2sendBuffer
+ *  \brief  Structured type to switch between structured type T_pixy2sendFrame and bytes 
+ *  \param  frame (T_pixy2sendFrame) : classical frame (header + payload) starting with PIXY2_SYNC
+ *  \param  data  (Byte)             : 9 bytes that overlap frame (byte access)
+ */
 typedef union {
     T_pixy2sendFrame    frame;
     Byte                data[9];
 }T_pixy2sendBuffer;
 
+/**
+ *  \struct T_pixy2RcvHeader
+ *  \brief  Structured type that match pixy2 header with checksum (received message)
+ *  \param  pixSync   (Word) : 16 bits synchro word - could be 0xc1ae (PIXY2_SYNC) or 0xc1af (PIXY2_CSSYNC)
+ *  \param  pixType   (Byte) : 8 bits message type identifier
+ *  \param  pixLength (Byte) : 8 bits message payload length (payload doesn't include checksum) 
+ *  \param  pixSync   (Word) : 16 bits checksum (sum of all bytes of the payload)
+ */
 typedef struct {
     Word                pixSync;
     Byte                pixType;
@@ -111,10 +160,27 @@
     Word                pixChecksum;
 }T_pixy2RcvHeader;
 
+
+/**************** PAYLOADS ****************/
+
+/**
+ *  \struct T_pixy2returnCode
+ *  \brief  Structured type that match pixy2 error/acknowledge/reply frame (type = 1 or 3) message payload
+ *  \param  pixReturn (lWord) : 32 bits returned value
+ */
 typedef struct {
-    lWord               pixAck;
-}T_pixy2AckCode;
+    lWord               pixReturn;
+}T_pixy2returnCode;
 
+/**
+ *  \struct T_Pixy2Version
+ *  \brief  Structured type that match pixy2 version frame (type = 14/15) message payload
+ *  \param  pixHWVersion    (Word)   : 16 bits hardWare Version of pixy2
+ *  \param  pixFWVersionMaj (Byte)   : 8 bits upper part of firmware (before the dot) 
+ *  \param  pixFWVersionMin (Byte)   : 8 bits lower part of firmware (after the dot)
+ *  \param  pixFWBuild      (Word)   : 16 bits firmware build information
+ *  \param  pixHFString     (String) : 10 bytes user friendly pixy2 firmware type
+ */
 typedef struct {
     Word                pixHWVersion;
     Byte                pixFWVersionMaj;
@@ -123,15 +189,31 @@
     char                pixHFString[10];
 }T_Pixy2Version;
 
+/**
+ *  \struct T_Pixy2Resolution
+ *  \brief  Structured type that match pixy2 resolution frame (type = 12/13) message payload
+ *  \param  pixFrameWidth   (Word) : 16 bits width (in pixel) of an image
+ *  \param  pixFrameHeigth  (Word) : 16 bits height (in pixel) of an image
+ */
 typedef struct {
     Word                pixFrameWidth;
     Word                pixFrameHeigth;
 }T_Pixy2Resolution;
 
-typedef struct {
-    lWord               pixFps;
-}T_pixy2Framerate;
-
+/**
+ *  \struct T_pixy2Bloc
+ *  \brief  Structured type that match pixy2 blocks frame (type = 32/33) message payload
+ *  \param  pixSignature (Word)   : 16 bits signature or color code of the color bloc (signature are between 1 and 7, color code are composed of signature of 2, up to 5, tags so over 10)
+ *  \param  pixX         (Word)   : 16 bits X (horizontal axis) position of color bloc center, relative to the left of the image (in pixels, between 0 and 315)
+ *  \param  pixY         (Word)   : 16 bits Y (vertical axis) position of color bloc center, relative to the top of the image (in pixels, between 0 and 207)
+ *  \param  pixWidth     (Word)   : 16 bits width (in pixels, between 0 and 316) of color bloc
+ *  \param  pixHeight    (Word)   : 16 bits height (in pixels, between 0 and 208) of color bloc
+ *  \param  pixAngle     (Word)   : 16 bits angle (in degree, between -180.0 and +180.0) of a color code bloc
+ *  \param  pixIndex     (Byte)   : 8 bits tracking identification of the color code bloc (set by pixy2 to ease a bloc position following program)
+ *  \param  pixAge       (Byte)   : 8 bits age (in number of frame) of a bloc (doesn't wrap around).
+ *  @note More info can be found here : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:ccc_api
+ *  @note or here : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:color_connected_components
+ */
 typedef struct {
     Word                pixSignature;
     Word                pixX;
@@ -143,6 +225,16 @@
     Byte                pixAge;
 }T_pixy2Bloc;
 
+/**
+ *  \struct T_Pixy2Vector
+ *  \brief  Structured type that match pixy2 vector definition - used in Line frame (type 48/49) - message payload
+ *  \param  pixX0     (Byte)   : 8 bits X (horizontal, relative to the left of image) position of color bloc center
+ *  \param  pixY0     (Byte)   : 8 bits Y (vertical, relative to the top of image) position of color bloc center
+ *  \param  pixX1     (Byte)   : 8 bits width (in pixels) of color bloc
+ *  \param  pixY1     (Byte)   : 8 bits height (in pixels) of color bloc
+ *  \param  pixIndex  (Byte)   : 8 bits identification of the color code bloc (used to follow a bloc position)
+ *  \param  pixAge    (Byte)   : 8 bits age (in number of frame) of a bloc (doesn't wrap around) (used to follow a bloc position)
+ */
 typedef struct {
     Byte                pixX0;
     Byte                pixY0;
@@ -210,7 +302,7 @@
 int pixy2_setServos (Word s0, Word s1); 
 int pixy2_setLED (Byte red, Byte green, Byte blue);
 int pixy2_setLamp (Byte upper, Byte lower);
-int pixy2_getFPS (T_pixy2Framerate framerate);
+int pixy2_getFPS (T_pixy2returnCode *framerate);
 int pixy2_getBlocks (Byte sigmap, Byte maxBloc);
 int pixy2_getMainFeature (Byte type, Byte features);
 int pixy2_getAllFeature (Byte features);