pixy2 smart camera library www.pixycam.com
Pixy2 Library project (using UART interface)
pixy2.h
- Committer:
- haarkon
- Date:
- 2019-03-11
- Revision:
- 7:1163b9c3274b
- Parent:
- 6:e9e3aa6f1a55
- Child:
- 8:c93e1d706c0e
File content as of revision 7:1163b9c3274b:
/** * @author Hugues Angelis * * @section LICENSE * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal * in the Software without restriction, including without limitation the rights * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell * copies of the Software, and to permit persons to whom the Software is * furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included in * all copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN * THE SOFTWARE. * * @section DESCRIPTION * * CMUCAM 5 - Pixy2 * * Datasheet, FAQ and PC drivers : * * http://www.pixycam.com/ */ #ifndef _PIXY2_ #define _PIXY2_ /** * Include : Mbed Library */ #include "mbed.h" /** * Defines */ #define PIXY2_NCSHEADERSIZE 4 #define PIXY2_CSHEADERSIZE 4 #define PIXY2_SYNC 0xC1AE #define PIXY2_CSSYNC 0xC1AF #define PIXY2_ACK 1 #define PIXY2_ASK_RESOL 12 #define PIXY2_REP_RESOL 13 #define PIXY2_ASK_VERS 14 #define PIXY2_REP_VERS 15 #define PIXY2_SET_BRIGHT 16 #define PIXY2_SET_SERVOS 18 #define PIXY2_SET_LED 20 #define PIXY2_SET_LAMP 22 #define PIXY2_ASK_FPS 24 #define PIXY2_ASK_BLOC 32 #define PIXY2_REP_BLOC 33 #define PIXY2_ASK_LINE 48 #define PIXY2_REP_LINE 49 #define PIXY2_SET_MODE 54 #define PIXY2_SET_TURN 58 #define PIXY2_SET_VECTOR 56 #define PIXY2_SET_DEFTURN 60 #define PIXY2_SET_REVERSE 62 #define PIXY2_ASK_VIDEO 112 /**************** ERRORS ****************/ /** * \struct Pixy2ErrorCode * \brief Explicit error code list : * \param PIXY2_OK : No error * \param PIXY2_MISC_ERROR : Unknown error * \param PIXY2_BUSY : Pixy hasn't finish yet * \param PIXY2_BAD_CHECKSUM : Checksum is wrong * \param PIXY2_TYPE_ERROR : unexpected type message * @note More documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:general_api#error-codes */ typedef int Pixy2ErrorCode; #define PIXY2_OK 0 #define PIXY2_MISC_ERROR -1 #define PIXY2_BUSY -2 #define PIXY2_BAD_CHECKSUM -3 #define PIXY2_TYPE_ERROR -7 /**************** STATE MACHINE ****************/ typedef enum {idle, messageSent, receivingHeader, headerReceived, receivingData, dataReceived} T_Pixy2State; /**************** UTILS ****************/ /** * \struct Byte -> Short hand for unsigned char * \struct sByte -> Short hand for char * \struct Word -> Short hand for unsigned short * \struct sWord -> Short hand for short * \struct lWord -> Short hand for unsigned long * \struct slWord -> Short hand for long */ typedef unsigned char Byte; typedef char sByte; typedef unsigned short Word; typedef short sWord; typedef unsigned long lWord; typedef long slWord; /** * \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; Byte pixLength; 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 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; Byte pixFWVersionMin; Word pixFWBuild; 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 pixFrameHeight (Word) : 16 bits height (in pixel) of an image */ typedef struct { Word pixFrameWidth; Word pixFrameHeight; }T_Pixy2Resolution; /** * \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 (sWord) : 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; Word pixY; Word pixWidth; Word pixHeight; sWord pixAngle; Byte pixIndex; 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 the tail of the vector (number between 0 and 78) * \param pixY0 (Byte) : 8 bits Y (vertical, relative to the top of image) position of the tail of the vector (number between 0 and 51) * \param pixX1 (Byte) : 8 bits X (horizontal, relative to the left of image) position of the head of the vector (number between 0 and 78) * \param pixY1 (Byte) : 8 bits Y (vertical, relative to the top of image) position of the head of the vector (number between 0 and 51) * \param pixIndex (Byte) : 8 bits tracking identification of the vector (set by pixy2 to ease a vector identification in case of multiple vector in a line following program) * \param pixFlags (Byte) : 8 bits flag containing possible usefull informations (see notes) * @note This structure is a feature of Line API, packed as a feature in a Line Frame, documented here : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:protocol_reference * @note More info can be found here : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:line_api * @note or here : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:line_tracking */ typedef struct { Byte pixX0; Byte pixY0; Byte pixX1; Byte pixY1; Byte pixIndex; Byte pixFlags; }T_Pixy2Vector; /** * \struct T_Pixy2InterLine * \brief Structured type that match pixy2 intersection line definition - used in Line frame (type 48/49) - message payload * \param pixIndex (Byte) : 8 bits tracking identification of the intersection line (set by pixy2 to ease a line following program) * \param pixReserved (Byte) : Not documented by manufacturer * \param pixAngle (sWord) : 16 bits angle (in degree, between -180.0 and +180.0) of the intersection line * @note This structure is a sub feature of Line API, packed as a sub feature of intersection feature in a Line Frame, documented here : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:protocol_reference * @note More info can be found here : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:line_api * @note or here : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:line_tracking */ typedef struct { Byte pixIndex; Byte pixReserved; sWord pixAngle; }T_Pixy2InterLine; /** * \struct T_pixy2Intersection * \brief Structured type that match pixy2 intersection definition - used in Line frame (type 48/49) - message payload * \param pixX (Byte) : X axis coordinate of the intersection (in pixel, between 0 and 78) * \param pixY (Byte) : Y axis coordinate of the intersection (in pixel, between 0 and 51) * \param pixN (Byte) : Number of lines connected to the intersection (between 3 and 5) * \param pixReserved (Byte) : Not documented by manufacturer * @note This structure is a feature of Line API, packed as a feature in a Line Frame, documented here : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:protocol_reference * @note More info can be found here : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:line_api * @note or here : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:line_tracking */ typedef struct { Byte pixX; Byte pixY; Byte pixN; Byte pixReserved; }T_pixy2Intersection; /** * \struct T_pixy2BarCode * \brief Structured type that match pixy2 barcode definition - used in Line frame (type 48/49) - message payload * \param pixX (Byte) : X axis coordinate of the barcode (in pixel, between 0 and 78) * \param pixY (Byte) : Y axis coordinate of the barcode (in pixel, between 0 and 51) * \param pixFlag (Byte) : Flag to indicate if barcode met filtering constraint * \param pixCode (Byte) : Indicate the numeric value associated with the barcode (between 0 and 15) * @note This structure is a feature of Line API, packed as a feature in a Line Frame, documented here : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:protocol_reference * @note More info can be found here : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:line_api * @note or here : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:line_tracking */ typedef struct { Byte pixX; Byte pixY; Byte pixFlag; Byte pixCode; }T_pixy2BarCode; /** * \struct T_pixy2LineFeature * \brief Structured type that match pixy2 feature header for Line API - used in Line frame (type 48/49) - message payload * \param pixType (Byte) : Type of the feature (can be 1 -> Vector, 2 -> Intersection or 4 -> Barcode) * \param pixLength (Byte) : Number of Bytes for this feature * @note This structure is the header of features of Line API in Line Frames. Ther can be up to 4 features in a frame. Documented here : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:protocol_reference * @note More info can be found here : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:line_api * @note or here : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:line_tracking */ typedef struct { Byte pixType; Byte pixLength; }T_pixy2LineFeature; /** * \struct T_pixy2Pixel * \brief Structured type that match pixy2 video API - used in Video frame (type 112/1) - message payload * \param pixBlue (Byte) : Blue RGB value of the average blue component of the 5x5 pixels square centered on X param passes to the function (value between 0 and 255) * \param pixGreen (Byte) : Green RGB value of the average blue component of the 5x5 pixels square centered on X param passes to the function (value between 0 and 255) * \param pixRed (Byte) : Red RGB value of the average blue component of the 5x5 pixels square centered on X param passes to the function (value between 0 and 255) * @note More info can be found here : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:video_api * @note or here : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:video */ typedef struct { Byte pixBlue; Byte pixGreen; Byte pixRed; }T_pixy2Pixel; /** * Pixy2 : CMU CAM 5 - Smart camera * More informations at http://www.pixycam.com/ */ class PIXY2 { protected : Serial* _Pixy2; public : /** * Constructor of pixy2 object. * * @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) */ PIXY2(PinName tx, PinName rx, int debit = 230400); // Fonctions publiques /** * Queries and receives the firmware and hardware version of Pixy2, which is put in the version member variable. * @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 version (T_Pixy2Version - passed by reference) : pointer to the version data structure * @return Pixy2ErrorCode : error code. */ Pixy2ErrorCode pixy2_getVersion (T_Pixy2Version *version); /** * Gets the width and height of the frames used by the current program. * @note After calling this function, the width and height can be found in the frameWidth and frameHeight member variables. * @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 resolution (T_Pixy2Resolution - passed by reference) : pointer to the resolution data structure * @return Pixy2ErrorCode : error code. */ Pixy2ErrorCode pixy2_getResolution (T_Pixy2Resolution *resolution); /** * Sets the relative exposure level of Pixy2's image sensor. Higher values result in a brighter (more exposed) image. * @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 Pixy2ErrorCode : error code. */ Pixy2ErrorCode pixy2_setCameraBrightness (Byte brightness); /** * sets the servo positions of servos plugged into Pixy2's two RC servo connectors. * @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 Pixy2ErrorCode : error code. */ Pixy2ErrorCode pixy2_setServos (Word s0, Word s1); Pixy2ErrorCode pixy2_setLED (Byte red, Byte green, Byte blue); Pixy2ErrorCode pixy2_setLamp (Byte upper, Byte lower); Pixy2ErrorCode pixy2_getFPS (T_pixy2returnCode *framerate); Pixy2ErrorCode pixy2_getBlocks (Byte sigmap, Byte maxBloc); Pixy2ErrorCode pixy2_getMainFeature (Byte type, Byte features); Pixy2ErrorCode pixy2_getAllFeature (Byte features); Pixy2ErrorCode pixy2_setMode (Byte mode); Pixy2ErrorCode pixy2_setNexTurn (Word angle); Pixy2ErrorCode pixy2_setDefaultTurn (Word angle); Pixy2ErrorCode pixy2_setVector (Byte vectorIndex); Pixy2ErrorCode pixy2_ReverseVector (void); Pixy2ErrorCode pixy2_getRGB (Word x, Word y, Byte saturate, T_pixy2Pixel *pixel); // Variables globales Publiques Byte Pixy2_numBlocks; T_pixy2Bloc Pixy2_blocks[]; Byte Pixy2_numVectors; T_Pixy2Vector Pixy2_vectors[]; Byte Pixy2_numIntersections; T_pixy2Intersection Pixy2_intersections[]; T_Pixy2InterLine Pixy2_intLines[]; Byte Pixy2_numBarcodes; T_pixy2BarCode Pixy2_barcodes[]; private : // Variables globales Privées T_Pixy2State etat; Byte* Pixy2_buffer; Byte wPointer, rPointer, dataSize; Byte frameContainChecksum; // Fonctions privées Pixy2ErrorCode pixy2_sndGetVersion (void); Pixy2ErrorCode pixy2_sndGetResolution (void); Pixy2ErrorCode pixy2_sndSetCameraBrightness (Byte brightness); Pixy2ErrorCode pixy2_sndSetServo (Word s0, Word s1); Pixy2ErrorCode pixy2_sndSetLED (Byte red, Byte green, Byte blue); Pixy2ErrorCode pixy2_sndSetLamp (Byte upper, Byte lower); Pixy2ErrorCode pixy2_sndGetFPS (void); Pixy2ErrorCode pixy2_sndGetBlocks (Byte sigmap, Byte maxBloc); Pixy2ErrorCode pixy2_sndGetMainFeature (Byte type, Byte feature); Pixy2ErrorCode pixy2_sndSetMode (Byte mode); Pixy2ErrorCode pixy2_sndSetNexTurn (Word angle); Pixy2ErrorCode pixy2_sndSetDefaultTurn (Word angle); Pixy2ErrorCode pixy2_sndSetVector (Byte vectorIndex); Pixy2ErrorCode pixy2_sndReverseVector (void); Pixy2ErrorCode pixy2_sndGetRGB (Word x, Word y, Byte saturate); void pixy2_getByte (); Pixy2ErrorCode pixy2_validateChecksum (Byte* tab); }; #endif