File content as of revision 3:6ba43af28440:

/**
 * @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


/**************** 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  pixFrameHeigth  (Word) : 16 bits height (in pixel) of an image
 */
typedef struct {
    Word                pixFrameWidth;
    Word                pixFrameHeigth;
}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 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 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 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 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;

typedef struct {
    Byte                pixType;
    Byte                pixLength;
}T_pixy2LineFeature;

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

/**
 * Gives information about Pixy2 version and Firmware
 * @note according to documentation : https://docs.pixycam.com/wiki/doku.php?id=wiki:v2:porting_guide
 * @param version (T_Pixy2Version - passed by reference) : pointer to the version data
 * @return  0 if OK
 * @return -2 if Busy
 * @return -3 if Checksum error
 * @return -7 if Type Error
 */
int pixy2_getVersion (T_Pixy2Version *version);
int pixy2_getResolution (T_Pixy2Resolution *resolution);
int pixy2_setCameraBrightness (Byte brightness);
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_pixy2returnCode *framerate);
int pixy2_getBlocks (Byte sigmap, Byte maxBloc);
int pixy2_getMainFeature (Byte type, Byte features);
int pixy2_getAllFeature (Byte features);
int pixy2_setMode (Byte mode);
int pixy2_setNexTurn (Word angle);
int pixy2_setDefaultTurn (Word angle);
int pixy2_setVector (Byte vectorIndex);
int pixy2_ReverseVector (void);
int 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
int pixy2_sndGetVersion (void);
int pixy2_sndGetResolution (void);
int pixy2_sndSetCameraBrightness (Byte brightness);
int pixy2_sndSetServo (Word s0, Word s1);
int pixy2_sndSetLED (Byte red, Byte green, Byte blue);
int pixy2_sndSetLamp (Byte upper, Byte lower);
int pixy2_sndGetFPS (void);
int pixy2_sndGetBlocks (Byte sigmap, Byte maxBloc);
int pixy2_sndGetMainFeature (Byte type, Byte feature);
int pixy2_sndSetMode (Byte mode);
int pixy2_sndSetNexTurn (Word angle);
int pixy2_sndSetDefaultTurn (Word angle);
int pixy2_sndSetVector (Byte vectorIndex);
int pixy2_sndReverseVector (void);
int pixy2_sndGetRGB (Word x, Word y, Byte saturate);

void pixy2_getByte ();
int pixy2_validateChecksum (Byte* tab);
};

#endif