Diff: pixy2.h

Revision:

19:007d361c8d66

Parent:

18:190e3987e274

Child:

20:8e3adcaab290

--- a/pixy2.h	Wed Mar 13 16:27:14 2019 +0000
+++ b/pixy2.h	Mon Apr 01 12:34:14 2019 +0000
@@ -67,6 +67,10 @@
 #define PIXY2_SET_DEFTURN   60
 #define PIXY2_SET_REVERSE   62
 #define PIXY2_ASK_VIDEO     112
+#define PIXY2_VECTOR        1
+#define PIXY2_INTERSECTION  2
+#define PIXY2_BARCODE       4
+#define PIXY2_MAX_INT_LINE  6
 
 /**************** ERRORS ****************/
 
@@ -312,6 +316,7 @@
     Byte                pixY;
     Byte                pixN;
     Byte                pixReserved;
+    T_pixy2InterLine    PixintLines[PIXY2_MAX_INT_LINE];
 }T_pixy2Intersection;
 
 /**
@@ -342,8 +347,8 @@
  *  @note or here : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:line_tracking
  */
 typedef struct {
-    Byte                pixType;
-    Byte                pixLength;
+    Byte                fType;
+    Byte                fLength;
 }T_pixy2LineFeature;
 
 /**
@@ -381,6 +386,11 @@
  */
 PIXY2(PinName tx, PinName rx, int debit = 230400);
 
+/**
+ * Destructor of pixy2 object.
+ */
+~PIXY2();
+
 // Fonctions publiques
 
 /**
@@ -435,7 +445,7 @@
 T_pixy2ErrorCode pixy2_setLED (Byte red, Byte green, Byte blue);
 
 /**
- * Turns on/off Pixy2's integrated light source.
+ * Sets on/off Pixy2's integrated light source.
  * The upper argument controls the two white LEDs along the top edge of Pixy2's PCB. The lower argument sets the RGB LED, causing it to turn on all three color channels at full brightness, resulting in white light.
  * It will override Pixy2's own setting of the RGB LED. 
  * @note Frame Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:porting_guide
@@ -473,7 +483,7 @@
 T_pixy2ErrorCode pixy2_getBlocks (Byte sigmap, Byte maxBloc);
 
 /**
- * This function gets the latest main features of Line tracking.
+ * Gets the latest main features of Line tracking in the most recent frame.
  * The results are returned in the variables vectors, intersections, and barcodes, respectively.
  * The main feature is the feature that is the most likely to be relevant for line traking.
  * In case of multiple vector (for example 2 lines unconnected), the function will return only the vector of the line you are the most likely to follow.
@@ -489,7 +499,7 @@
 T_pixy2ErrorCode pixy2_getMainFeature (Byte features);
 
 /**
- * This function gets all the latest features of Line tracking.
+ * Gets all the latest features of Line tracking in the most recent frame.
  * The results are returned in the variables vectors, intersections, and barcodes, respectively.
  * @note General description : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:line_tracking
  * @note Frame Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:porting_guide
@@ -504,7 +514,7 @@
 T_pixy2ErrorCode pixy2_getAllFeature (Byte features);
 
 /**
- * This function sets various modes in the line tracking algorithm.
+ * Sets various modes in the line tracking algorithm.
  * @note General description : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:line_tracking
  * @note Frame Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:porting_guide
  * @note Function Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:pixy2_full_api#plugin_include__wiki__v2__line_api
@@ -518,7 +528,7 @@
 T_pixy2ErrorCode pixy2_setMode (Byte mode);
 
 /**
- * This function tells the line tracking algorithm which path it should take at the next intersection.
+ * Tells the line tracking algorithm which path it should take at the next intersection.
  * @note General description : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:line_tracking
  * @note Frame Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:porting_guide
  * @note Function Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:pixy2_full_api#plugin_include__wiki__v2__line_api
@@ -528,10 +538,10 @@
  * @note setNextTurn() will remember the turn angle you give it, and execute it at the next intersection. The line tracking algorithm will then go back to the default turn angle for subsequent intersections.
  * @note Upon encountering an intersection, the line tracking algorithm will find the path in the intersection that matches the turn angle most closely. 
  */
-T_pixy2ErrorCode pixy2_setNexTurn (sWord angle);
+T_pixy2ErrorCode pixy2_setNextTurn (sWord angle);
 
 /**
- * This function tells the line tracking algorithm which path to choose by default upon encountering an intersection.
+ * Tells the line tracking algorithm which path to choose by default upon encountering an intersection.
  * @note General description : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:line_tracking
  * @note Frame Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:porting_guide
  * @note Function Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:pixy2_full_api#plugin_include__wiki__v2__line_api
@@ -544,7 +554,7 @@
 T_pixy2ErrorCode pixy2_setDefaultTurn (sWord angle);
 
 /**
- * This function tells witch vector the tracking algorithm must choose as default route upon encountering an intersection.
+ * Tells witch vector the tracking algorithm must choose as default route upon encountering an intersection.
  * @note General description : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:line_tracking
  * @note Frame Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:porting_guide
  * @note Function Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:pixy2_full_api#plugin_include__wiki__v2__line_api
@@ -555,7 +565,7 @@
 T_pixy2ErrorCode pixy2_setVector (Byte vectorIndex);
 
 /**
- * This function reverse the head and the tail of vectors
+ * Reverse the head and the tail of vectors
  * @note General description : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:line_tracking
  * @note Frame Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:porting_guide
  * @note Function Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:pixy2_full_api#plugin_include__wiki__v2__line_api
@@ -565,7 +575,7 @@
 T_pixy2ErrorCode pixy2_ReverseVector (void);
 
 /**
- * This function returns the average RGB components of a square of 5x5 pixels centered on the given pixel coordinate
+ * Returns the average RGB components of a square of 5x5 pixels centered on the given pixel coordinate
  * @note General description : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:video
  * @note Frame Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:porting_guide
  * @note Function Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:video_api
@@ -595,7 +605,6 @@
 T_pixy2Vector       *Pixy2_vectors;
 Byte                Pixy2_numIntersections;
 T_pixy2Intersection *Pixy2_intersections;
-T_pixy2InterLine    *Pixy2_intLines;
 Byte                Pixy2_numBarcodes;
 T_pixy2BarCode      *Pixy2_barcodes;
 
@@ -607,24 +616,198 @@
 Byte                frameContainChecksum;
 
 // Fonctions privées
+
+/**
+ * Queries the firmware and hardware version of Pixy2.
+ * This function is part of the pixy2_getVersion function who treat the reply to this query.
+ * @note Frame Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:porting_guide
+ * @note Function Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:general_api
+ * @return T_pixy2ErrorCode : error code.
+ */
 T_pixy2ErrorCode pixy2_sndGetVersion (void);
+
+/**
+ * Queries width and height of the frames used by the current program.
+ * This function is part of the pixy2_getResolution function who treat the reply to this query.
+ * @note Frame Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:porting_guide
+ * @note Function Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:general_api
+ * @return T_pixy2ErrorCode : error code.
+ */
 T_pixy2ErrorCode pixy2_sndGetResolution (void);
+
+/**
+ * Sends the relative exposure level of Pixy2's image sensor.
+ * Higher values result in a brighter (more exposed) image.
+ * This function is part of the pixy2_setCameraBrightness function who treat the acknowledge of this frame.
+ * @note Frame Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:porting_guide
+ * @note Function Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:general_api
+ * @param brightness (Byte - passed by value) : brightness level
+ * @return T_pixy2ErrorCode : error code.
+ */
 T_pixy2ErrorCode pixy2_sndSetCameraBrightness (Byte brightness);
+
+/**
+ * Sends the servo positions of servos plugged into Pixy2's two RC servo connectors.
+ * This function is part of the pixy2_setServo function who treat the acknowledge of this frame.
+ * @note Frame Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:porting_guide
+ * @note Function Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:general_api
+ * @param s0 (Word - passed by value) : value between 0 and 511
+ * @param s1 (Word - passed by value) : value between 0 and 511
+ * @return T_pixy2ErrorCode : error code.
+ */
 T_pixy2ErrorCode pixy2_sndSetServo (Word s0, Word s1);
+
+/**
+ * Sends Pixy2's RGB LED value. The three arguments sets the brightness of the red, green and blue sections of the LED.
+ * It will override Pixy2's own setting of the RGB LED.
+ * This function is part of the pixy2_setLED function who treat the acknowledge of this frame.
+ * @note Frame Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:porting_guide
+ * @note Function Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:general_api
+ * @param red (Byte - passed by value) : Red component value (between 0 and 255)
+ * @param green (Byte - passed by value) : Green component value (between 0 and 255)
+ * @param blue (Byte - passed by value) : Blue component value (between 0 and 255)
+ * @return T_pixy2ErrorCode : error code.
+ */
 T_pixy2ErrorCode pixy2_sndSetLED (Byte red, Byte green, Byte blue);
+
+/**
+ * Sends command that turns on/off Pixy2's integrated light source.
+ * The upper argument controls the two white LEDs along the top edge of Pixy2's PCB. The lower argument sets the RGB LED, causing it to turn on all three color channels at full brightness, resulting in white light.
+ * It will override Pixy2's own setting of the RGB LED.
+ * This function is part of the pixy2_setLamp function who treat the acknowledge of this frame.
+ * @note Frame Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:porting_guide
+ * @note Function Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:general_api
+ * @param upper (Byte - passed by value) : switch on or off the upper lamps (boolean : zero or non-zero)
+ * @param lower (Byte - passed by value) : switch on or off the lower lamp (boolean : zero or non-zero)
+ * @return T_pixy2ErrorCode : error code.
+ */
 T_pixy2ErrorCode pixy2_sndSetLamp (Byte upper, Byte lower);
+
+/**
+ * Queries Pixy2's framerate.
+ * This function is part of the pixy2_getFPS function who treat the reply to this query.
+ * @note Frame Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:porting_guide
+ * @note Function Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:general_api
+ * @return T_pixy2ErrorCode : error code.
+ */
 T_pixy2ErrorCode pixy2_sndGetFPS (void);
+
+/**
+ * Queries all detected color blocks in the most recent frame.
+ * This function is part of the pixy2_getBlocks function who treat the reply to this query.
+ * @note General description : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:color_connected_components
+ * @note Frame Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:porting_guide
+ * @note Function Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:pixy2_full_api#plugin_include__wiki__v2__ccc_api
+ * @param sigmap (Byte - passed by value) : signature filtering
+ * @param maxBloc (Byte - passed by value) : maximum number of blocks to return
+ * @return T_pixy2ErrorCode : error code.
+ * @note There are 7 different signatures definition (sig1 to sig7). Color codes are made of a combination of signature and can be filtered as well.
+ * @note Filtering is based on ORing codes : 1 for sig1, 2 for sig2, 4 for sig3, 8 for sig4, 16 for sig5, 32 for sig6, 64 sor sig7 and 128 for color code.
+ * @note So sigmap = 255 means accept all and sigmap = 0 means reject all. For example filtering to get only sig1 and sig5 means using sigmap = 17 (16 + 1).
+ */
 T_pixy2ErrorCode pixy2_sndGetBlocks (Byte sigmap, Byte maxBloc);
-T_pixy2ErrorCode pixy2_sndGetMainFeature (Byte type, Byte feature);
+
+/**
+ * Queries the latest features of Line tracking in the most recent frame.
+ * The results are returned in the variables vectors, intersections, and barcodes, respectively.
+ * This function is part of the pixy2_getMainFeature or pixy2_getAllFeature function who treat the reply to this query.
+ * @note General description : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:line_tracking
+ * @note Frame Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:porting_guide
+ * @note Function Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:pixy2_full_api#plugin_include__wiki__v2__line_api
+ * @param type (Byte - passed by value) : select between Main or All features (0 for main feature only, 1 for all features)
+ * @param feature (Byte - passed by value) : feature filtering
+ * @return T_pixy2ErrorCode : error code (if negative) or ORing of feature detected (if positive).
+ * @note There are 3 possible features (vectors, intersections and barcodes).
+ * @note Filtering or detected feature are based on ORing codes : 1 for vectors, 2 for intersections, 4 for barcodes.
+ * @note So for filtering : 7 = accept all, 0 = reject all. For example filtering to get only vectors and barcode means using feature = 5 (1 + 4).
+ * @note So for return value : 1 means only vector(s) detected, 2 means only intersection(s) detected, 3 vector(s) and intersection(s) detected and so on.
+ */
+T_pixy2ErrorCode pixy2_sndGetLineFeature (Byte type, Byte feature);
+
+/**
+ * Sets various modes in the line tracking algorithm.
+ * This function is part of the pixy2_setMode function who treat the acknowledge of this frame.
+ * @note General description : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:line_tracking
+ * @note Frame Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:porting_guide
+ * @note Function Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:pixy2_full_api#plugin_include__wiki__v2__line_api
+ * @param mode (Byte - passed by value) : ORing of required feature
+ * @return T_pixy2ErrorCode : error code.
+ * @note There are 3 possible features :
+ * @note * LINE_MODE_TURN_DELAYED : Normally, the line tracking algorithm will choose the straightest path (branch) when encountering an intersection. Setting LINE_MODE_TURN_DELAYED will prevent the line tracking algorithm from choosing the path automatically. This is useful if your program doesn't know beforehand which path it wants to take at the next intersection.
+ * @note * LINE_MODE_MANUAL_SELECT_VECTOR : Normally, the line tracking algorithm will choose what it thinks is the best Vector line automatically. Setting LINE_MODE_MANUAL_SELECT_VECTOR will prevent the line tracking algorithm from choosing the Vector automatically. Instead, your program will need to set the Vector by calling setVector().
+ * @note * LINE_MODE_WHITE_LINE : Normally, the line tracking algorithm will try to find dark lines on a light background (black lines). Setting LINE_MODE_WHITE_LINE will instruct the line tracking algorithm to look for light lines on a dark background (white lines).
+ */
 T_pixy2ErrorCode pixy2_sndSetMode (Byte mode);
-T_pixy2ErrorCode pixy2_sndSetNexTurn (Word angle);
+
+/**
+ * Tells the line tracking algorithm which path it should take at the next intersection.
+ * This function is part of the pixy2_setNextTurn function who treat the acknowledge of this frame.
+ * @note General description : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:line_tracking
+ * @note Frame Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:porting_guide
+ * @note Function Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:pixy2_full_api#plugin_include__wiki__v2__line_api
+ * @param angle (sWord - passed by value) : angle closest to the next turn (in degree, between -180 and 180)
+ * @return T_pixy2ErrorCode : error code.
+ * @note Turn angles are specified in degrees, with 0 being straight ahead, left being 90 and right being -90, although any valid angle value can be used.
+ * @note setNextTurn() will remember the turn angle you give it, and execute it at the next intersection. The line tracking algorithm will then go back to the default turn angle for subsequent intersections.
+ * @note Upon encountering an intersection, the line tracking algorithm will find the path in the intersection that matches the turn angle most closely.
+ */
+T_pixy2ErrorCode pixy2_sndSetNextTurn (Word angle);
+
+/**
+ * Tells the line tracking algorithm which path to choose by default upon encountering an intersection.
+ * This function is part of the pixy2_setDefaultTurn function who treat the acknowledge of this frame.
+ * @note General description : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:line_tracking
+ * @note Frame Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:porting_guide
+ * @note Function Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:pixy2_full_api#plugin_include__wiki__v2__line_api
+ * @param angle (sWord - passed by value) : angle closest to the default turn (in degree, between -180 and 180)
+ * @return T_pixy2ErrorCode : error code.
+ * @note Turn angles are specified in degrees, with 0 being straight ahead, left being 90 and right being -90, although any valid angle value can be used.
+ * @note The line tracking algorithm will find the path in the intersection that matches the default turn angle most closely.
+ * @note A call to setNextTurn() will supercede the default turn angle for the next intersection.
+ */
 T_pixy2ErrorCode pixy2_sndSetDefaultTurn (Word angle);
+
+/**
+ * Tells witch vector the tracking algorithm must choose as default route upon encountering an intersection.
+ * This function is part of the pixy2_setVector function who treat the acknowledge of this frame.
+ * @note General description : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:line_tracking
+ * @note Frame Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:porting_guide
+ * @note Function Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:pixy2_full_api#plugin_include__wiki__v2__line_api
+ * @param vectorindex (Byte - passed by value) : index of the vector to follow
+ * @return T_pixy2ErrorCode : error code.
+ * @note If the LINE_MODE_MANUAL_SELECT_VECTOR mode bit is set, the line tracking algorithm will no longer choose the Vector automatically. Instead, setVector() will set the Vector by providing the index of the line.
+ */
 T_pixy2ErrorCode pixy2_sndSetVector (Byte vectorIndex);
+
+/**
+ * Reverse the head and the tail of vectors
+ * This function is part of the pixy2_reverseVector function who treat the acknowledge of this frame.
+ * @note General description : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:line_tracking
+ * @note Frame Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:porting_guide
+ * @note Function Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:pixy2_full_api#plugin_include__wiki__v2__line_api
+ * @return T_pixy2ErrorCode : error code.
+ * @note The Vector has a direction. It normally points up, from the bottom of the camera frame to the top of the camera frame for a forward-moving robot. Calling reverseVector() will invert the vector. This will typically cause your robot to back-up and change directions.
+ */
 T_pixy2ErrorCode pixy2_sndReverseVector (void);
+
 T_pixy2ErrorCode pixy2_sndGetRGB (Word x, Word y, Byte saturate);
 
+/**
+ * Gets all the latest features of Line tracking in the most recent frame.
+ * The results are returned in the variables vectors, intersections, and barcodes, respectively.
+ * @note General description : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:line_tracking
+ * @note Frame Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:porting_guide
+ * @note Function Documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:pixy2_full_api#plugin_include__wiki__v2__line_api
+ * @param feature (Byte - passed by value) : feature filtering
+ * @return T_pixy2ErrorCode : error code.
+ * @note There are 3 possible features (vectors, intersections and barcodes).
+ * @note Filtering is based on ORing codes : 1 for vectors, 2 for intersections, 4 for barcodes.
+ * @note So 7 = accept all, 0 = reject all. For example filtering to get only vectors and barcode means using feature = 5 (1 + 4).
+ */
+T_pixy2ErrorCode pixy2_getFeatures (void);
+
 void pixy2_getByte ();
 T_pixy2ErrorCode pixy2_validateChecksum (Byte* tab);
-};
+}; // End Class
 
-#endif        
\ No newline at end of file
+#endif