FRC - Hackathon / Pixy

Library for Pixy - CMUCAM5 smart camera

Dependents:   TestPixy FRC_2018 FRC2018_Bis 0hackton_08_06_18 ... more

Fork of Pixy by FRC - Hackathon

Pixy.h@5:d395fe0fb0e0, 2018-05-31 (annotated)

Committer:
haarkon
Date:
Thu May 31 17:24:52 2018 +0000
Revision:
5:d395fe0fb0e0
Parent:
2:90355c600404
Child:
6:f16f250fe2cb
Tested Pixy library

Who changed what in which revision?

UserRevisionLine numberNew contents of line
haarkon 0:6f78c735f07c 1 /**
haarkon 0:6f78c735f07c 2 * @author Hugues Angelis
haarkon 0:6f78c735f07c 3 *
haarkon 0:6f78c735f07c 4 * @section LICENSE
haarkon 0:6f78c735f07c 5 *
haarkon 0:6f78c735f07c 6 * Permission is hereby granted, free of charge, to any person obtaining a copy
haarkon 0:6f78c735f07c 7 * of this software and associated documentation files (the "Software"), to deal
haarkon 0:6f78c735f07c 8 * in the Software without restriction, including without limitation the rights
haarkon 0:6f78c735f07c 9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
haarkon 0:6f78c735f07c 10 * copies of the Software, and to permit persons to whom the Software is
haarkon 0:6f78c735f07c 11 * furnished to do so, subject to the following conditions:
haarkon 0:6f78c735f07c 12 *
haarkon 0:6f78c735f07c 13 * The above copyright notice and this permission notice shall be included in
haarkon 0:6f78c735f07c 14 * all copies or substantial portions of the Software.
haarkon 0:6f78c735f07c 15 *
haarkon 0:6f78c735f07c 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
haarkon 0:6f78c735f07c 17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
haarkon 0:6f78c735f07c 18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
haarkon 0:6f78c735f07c 19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
haarkon 0:6f78c735f07c 20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
haarkon 0:6f78c735f07c 21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
haarkon 0:6f78c735f07c 22 * THE SOFTWARE.
haarkon 0:6f78c735f07c 23 *
haarkon 0:6f78c735f07c 24 * @section DESCRIPTION
haarkon 0:6f78c735f07c 25 *
haarkon 0:6f78c735f07c 26 * CMUCAM 5 - Pixy
haarkon 0:6f78c735f07c 27 *
haarkon 0:6f78c735f07c 28 * Datasheet, FAQ and PC drivers :
haarkon 0:6f78c735f07c 29 *
haarkon 0:6f78c735f07c 30 * http://www.cmucam.org/projects/cmucam5
haarkon 0:6f78c735f07c 31 */
haarkon 0:6f78c735f07c 32
haarkon 0:6f78c735f07c 33 #ifndef PIXY_H
haarkon 0:6f78c735f07c 34 #define PIXY_H
haarkon 0:6f78c735f07c 35
haarkon 0:6f78c735f07c 36 /**
haarkon 2:90355c600404 37 * Include : Mbed Library
haarkon 0:6f78c735f07c 38 */
haarkon 0:6f78c735f07c 39 #include "mbed.h"
haarkon 0:6f78c735f07c 40
haarkon 0:6f78c735f07c 41 /**
haarkon 0:6f78c735f07c 42 * Defines
haarkon 0:6f78c735f07c 43 */
haarkon 0:6f78c735f07c 44 #define CC_BLOCSIZE 14
haarkon 0:6f78c735f07c 45 #define N_BLOCSIZE 12
haarkon 0:6f78c735f07c 46
haarkon 0:6f78c735f07c 47 #define N_BLOCCODE 0xAA55
haarkon 0:6f78c735f07c 48 #define CC_BLOCCODE 0xAA56
haarkon 0:6f78c735f07c 49
haarkon 0:6f78c735f07c 50 /**
haarkon 2:90355c600404 51 * \struct Byte -> Short hand for unsigned char
haarkon 2:90355c600404 52 * \struct Word -> Short hand for unsigned short
haarkon 2:90355c600404 53 * \struct lWord -> Short hand for unsigned long
haarkon 0:6f78c735f07c 54 */
haarkon 0:6f78c735f07c 55 typedef unsigned char Byte;
haarkon 0:6f78c735f07c 56 typedef unsigned short Word;
haarkon 0:6f78c735f07c 57 typedef unsigned long lWord;
haarkon 2:90355c600404 58 /**
haarkon 2:90355c600404 59 * \struct T_pixyCCBloc
haarkon 2:90355c600404 60 * \brief Structured type to match pixy Color Code bloc organisation
haarkon 2:90355c600404 61 * \param Checksum (Word) : modulus sum of all words of the message
haarkon 2:90355c600404 62 * \param signature (Word) : identity (ie : numbers associated with colors) of the detected color code bloc
haarkon 2:90355c600404 63 * \param x (Word) : X coordinate (in pixel) of the center of the color code bloc
haarkon 2:90355c600404 64 * \param y (Word) : Y coordinate (in pixel) of the center of the color code bloc
haarkon 2:90355c600404 65 * \param width (Word) : Width (in pixel) of the color code bloc
haarkon 2:90355c600404 66 * \param height (Word) : Height (in pixel) of the color code bloc
haarkon 2:90355c600404 67 * \param angle (Word) : Angle (in degree, referenced to horizontal) of the color code bloc
haarkon 2:90355c600404 68 */
haarkon 0:6f78c735f07c 69 typedef struct {
haarkon 0:6f78c735f07c 70 Word checksum;
haarkon 0:6f78c735f07c 71 Word signature;
haarkon 0:6f78c735f07c 72 Word x;
haarkon 0:6f78c735f07c 73 Word y;
haarkon 0:6f78c735f07c 74 Word width;
haarkon 0:6f78c735f07c 75 Word height;
haarkon 0:6f78c735f07c 76 Word angle;
haarkon 0:6f78c735f07c 77 } T_pixyCCBloc;
haarkon 0:6f78c735f07c 78
haarkon 2:90355c600404 79 /**
haarkon 2:90355c600404 80 * \struct T_pixyNMBloc
haarkon 2:90355c600404 81 * \brief Structured type to match pixy normal bloc organisation
haarkon 2:90355c600404 82 * \param Checksum (Word) : modulus sum of all words of the message
haarkon 2:90355c600404 83 * \param signature (Word) : identity (ie : number associated with the color) of the detected bloc
haarkon 2:90355c600404 84 * \param x (Word) : X coordinate (in pixel) of the center of the color code bloc
haarkon 2:90355c600404 85 * \param y (Word) : Y coordinate (in pixel) of the center of the color code bloc
haarkon 2:90355c600404 86 * \param width (Word) : Width (in pixel) of the color code bloc
haarkon 2:90355c600404 87 * \param height (Word) : Height (in pixel) of the color code bloc
haarkon 2:90355c600404 88 */
haarkon 0:6f78c735f07c 89 typedef struct {
haarkon 0:6f78c735f07c 90 Word checksum;
haarkon 0:6f78c735f07c 91 Word signature;
haarkon 0:6f78c735f07c 92 Word x;
haarkon 0:6f78c735f07c 93 Word y;
haarkon 0:6f78c735f07c 94 Word width;
haarkon 0:6f78c735f07c 95 Word height;
haarkon 0:6f78c735f07c 96 } T_pixyNMBloc;
haarkon 0:6f78c735f07c 97
haarkon 2:90355c600404 98 /**
haarkon 2:90355c600404 99 * \union T_pixyCCData
haarkon 5:d395fe0fb0e0 100 * \brief Overlaped type to access a structured pixy Color Code bloc type with both byte and structured
haarkon 2:90355c600404 101 * \param CCBloc (T_pixyCCBloc) : Color Code bloc structured element
haarkon 2:90355c600404 102 * \param tab[14] (Byte) : Byte access to the Color Code bloc
haarkon 2:90355c600404 103 */
haarkon 0:6f78c735f07c 104 typedef union {
haarkon 0:6f78c735f07c 105 Byte tab[14];
haarkon 0:6f78c735f07c 106 T_pixyCCBloc CCbloc;
haarkon 0:6f78c735f07c 107 } T_pixyCCData;
haarkon 0:6f78c735f07c 108
haarkon 2:90355c600404 109 /**
haarkon 2:90355c600404 110 * \union T_pixyNMData
haarkon 5:d395fe0fb0e0 111 * \brief Overlaped type to access a structured pixy Normal bloc type with both byte and structured
haarkon 5:d395fe0fb0e0 112 * \param NMBloc (T_pixyNMBloc) : Normal bloc structured element
haarkon 2:90355c600404 113 * \param tab[12] (Byte) : Byte access to the normal bloc
haarkon 2:90355c600404 114 */
haarkon 0:6f78c735f07c 115 typedef union {
haarkon 0:6f78c735f07c 116 Byte tab[12];
haarkon 0:6f78c735f07c 117 T_pixyNMBloc NMbloc;
haarkon 0:6f78c735f07c 118 } T_pixyNMData;
haarkon 0:6f78c735f07c 119
haarkon 5:d395fe0fb0e0 120 typedef enum {none, begin, normal, colorCode, doubleZero, waitForStart} T_pixyState;
haarkon 0:6f78c735f07c 121
haarkon 0:6f78c735f07c 122 typedef union {
haarkon 5:d395fe0fb0e0 123 lWord motlong;
haarkon 5:d395fe0fb0e0 124 Word mot[2];
haarkon 5:d395fe0fb0e0 125 Byte octet[4];
haarkon 5:d395fe0fb0e0 126 } T_msgBuffer;
haarkon 0:6f78c735f07c 127
haarkon 0:6f78c735f07c 128 typedef union {
haarkon 0:6f78c735f07c 129 Word mot;
haarkon 5:d395fe0fb0e0 130 Byte octet[2];
haarkon 5:d395fe0fb0e0 131 } T_wordBuffer;
haarkon 0:6f78c735f07c 132
haarkon 0:6f78c735f07c 133 /**
haarkon 2:90355c600404 134 * Pixy : CMU CAM 5 - Smart camera
haarkon 2:90355c600404 135 * More informations at http://cmucam.org/projects/cmucam5
haarkon 0:6f78c735f07c 136 */
haarkon 0:6f78c735f07c 137 class PIXY {
haarkon 0:6f78c735f07c 138
haarkon 0:6f78c735f07c 139 protected :
haarkon 0:6f78c735f07c 140
haarkon 5:d395fe0fb0e0 141 Serial* _Pixy;
haarkon 0:6f78c735f07c 142
haarkon 0:6f78c735f07c 143 public :
haarkon 0:6f78c735f07c 144
haarkon 2:90355c600404 145 /** Direct access to the CC FIFO
haarkon 2:90355c600404 146 * @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.
haarkon 2:90355c600404 147 * @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.
haarkon 2:90355c600404 148 *
haarkon 2:90355c600404 149 * \var Pixy_CCFIFO[20]
haarkon 2:90355c600404 150 * \brief is a FIFO where the Color Code objects are stored. FIFO can store up to 20 objects
haarkon 2:90355c600404 151 */
haarkon 2:90355c600404 152
haarkon 2:90355c600404 153 /** Direct access to the NM FIFO
haarkon 2:90355c600404 154 * @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.
haarkon 2:90355c600404 155 * @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.
haarkon 2:90355c600404 156 * \var Pixy_NMFIFO[20]
haarkon 2:90355c600404 157 * \brief is a FIFO where the Normal objects are stored. FIFO can store up to 20 objects
haarkon 2:90355c600404 158 */
haarkon 2:90355c600404 159
haarkon 2:90355c600404 160 /**
haarkon 2:90355c600404 161 * \var Pixy_CCObjet
haarkon 2:90355c600404 162 * \brief is the number of CC object read by the library ISR from the CAM during the last frame
haarkon 2:90355c600404 163 * @note not Thread Safe
haarkon 2:90355c600404 164 * \var Pixy_NMObjet
haarkon 2:90355c600404 165 * \brief is the number of normal object read by the library ISR from the CAM during the last frame
haarkon 2:90355c600404 166 * @note not Thread Safe
haarkon 2:90355c600404 167 */
haarkon 0:6f78c735f07c 168 T_pixyCCData Pixy_CCFIFO[20]; // FIFO des objets ColorCode
haarkon 0:6f78c735f07c 169 T_pixyNMData Pixy_NMFIFO[20]; // FIFO des objets Normaux
haarkon 0:6f78c735f07c 170 Byte Pixy_CCObjet; // Nombre d'objets de type Color Code
haarkon 0:6f78c735f07c 171 Byte Pixy_NMObjet; // Nombre d'objets Normaux
haarkon 0:6f78c735f07c 172 Byte Pixy_FirstCCObjet; // Position dans la FIFO du premier objet de la trame suivante
haarkon 0:6f78c735f07c 173 Byte Pixy_FirstNMObjet; // Position dans la FIFO du premier objet de la trame suivante
haarkon 0:6f78c735f07c 174
haarkon 0:6f78c735f07c 175
haarkon 2:90355c600404 176 /** A new frame as been read
haarkon 0:6f78c735f07c 177 *
haarkon 2:90355c600404 178 * @note Semaphore are global variable used to communicate from ISR with main routine. All semaphores must be cleared by user.
haarkon 2:90355c600404 179 * \var FlagPixy
haarkon 2:90355c600404 180 * \brief is automaticly set after each received image frame
haarkon 2:90355c600404 181 */
haarkon 2:90355c600404 182
haarkon 2:90355c600404 183 /** Data have been lost
haarkon 0:6f78c735f07c 184 *
haarkon 2:90355c600404 185 * @note Semaphore are global variable used to communicate from ISR with main routine. All semaphores must be cleared by user.
haarkon 2:90355c600404 186 * \var FlagPixyOverflow
haarkon 2:90355c600404 187 * \brief is automaticly set if any FIFO oveflows (more than 20 obj of a kind).
haarkon 0:6f78c735f07c 188 */
haarkon 0:6f78c735f07c 189 int FlagPixy, FlagPixyOverflow;
haarkon 0:6f78c735f07c 190 int Pixy_check;
haarkon 0:6f78c735f07c 191
haarkon 0:6f78c735f07c 192 /**
haarkon 2:90355c600404 193 * Constructor of pixy object.
haarkon 0:6f78c735f07c 194 *
haarkon 2:90355c600404 195 * @param tx : the Mbed pin used as TX
haarkon 2:90355c600404 196 * @param rx : the Mbed pin used as RX
haarkon 2:90355c600404 197 * @param debit : the bitrate of the serial (max value is 230400 b/s)
haarkon 0:6f78c735f07c 198 */
haarkon 0:6f78c735f07c 199 PIXY(PinName tx, PinName rx, int debit =230400);
haarkon 0:6f78c735f07c 200
haarkon 0:6f78c735f07c 201 /**
haarkon 0:6f78c735f07c 202 * Return the number of objects (normal and ColorCode) that have been
haarkon 5:d395fe0fb0e0 203 * received from the PIXY and stored in the FIFO during the last frame
haarkon 0:6f78c735f07c 204 *
haarkon 5:d395fe0fb0e0 205 * @param nbNM (int - passed by reference) : number of normal object detected
haarkon 5:d395fe0fb0e0 206 * @param nbCC (int - passed by reference) : number of color code object detected
haarkon 2:90355c600404 207 * @return 0 if sucessfull,
haarkon 0:6f78c735f07c 208 * -1 if no PIXY is talking,
haarkon 5:d395fe0fb0e0 209 * -2 sucessfull but object(s) have been lost from previous frames (missed frame) or from actual (too many objects)
haarkon 0:6f78c735f07c 210 */
haarkon 2:90355c600404 211 int detectedObject (int* nbNM, int* nbCC);
haarkon 0:6f78c735f07c 212
haarkon 0:6f78c735f07c 213 /**
haarkon 0:6f78c735f07c 214 * Reads the oldest Color Code object from the last frame received
haarkon 0:6f78c735f07c 215 *
haarkon 2:90355c600404 216 * @note this function also manage the read pointer of the Color Code FIFO (ie : after use function point the next object to be read)
haarkon 0:6f78c735f07c 217 *
haarkon 0:6f78c735f07c 218 * @return a T_PixyCCBloc (see .h for details)
haarkon 0:6f78c735f07c 219 */
haarkon 0:6f78c735f07c 220 T_pixyCCBloc getCCBloc (void);
haarkon 0:6f78c735f07c 221
haarkon 0:6f78c735f07c 222 /**
haarkon 0:6f78c735f07c 223 * Reads the oldest Normal object from the last frame received
haarkon 0:6f78c735f07c 224 *
haarkon 2:90355c600404 225 * @note this function also manage the read pointer of the Normal FIFO (ie : after use function point the next object to be read)
haarkon 0:6f78c735f07c 226 *
haarkon 0:6f78c735f07c 227 * @return a T_PixyNMBloc (see .h for details)
haarkon 0:6f78c735f07c 228 */
haarkon 0:6f78c735f07c 229 T_pixyNMBloc getNMBloc (void);
haarkon 0:6f78c735f07c 230
haarkon 0:6f78c735f07c 231 /**
haarkon 0:6f78c735f07c 232 * Set the Brightness of the Pixy
haarkon 0:6f78c735f07c 233 *
haarkon 0:6f78c735f07c 234 * @param brightness level (between 0 and 255)
haarkon 5:d395fe0fb0e0 235 */
haarkon 5:d395fe0fb0e0 236 void setBrightness (Byte brightness);
haarkon 5:d395fe0fb0e0 237
haarkon 5:d395fe0fb0e0 238 /**
haarkon 5:d395fe0fb0e0 239 * Gives information about a new image taken by Pixy.
haarkon 5:d395fe0fb0e0 240 * @return 0 if no new image or 1 if there is a new image
haarkon 0:6f78c735f07c 241 */
haarkon 5:d395fe0fb0e0 242 int checkNewImage (void);
haarkon 5:d395fe0fb0e0 243
haarkon 5:d395fe0fb0e0 244 /**
haarkon 5:d395fe0fb0e0 245 * Gives information about a detected Pixy.
haarkon 5:d395fe0fb0e0 246 * @return -1 if no Pixy detected or 0 if Pixy detected
haarkon 5:d395fe0fb0e0 247 */
haarkon 5:d395fe0fb0e0 248 int checkPixy (void);
haarkon 0:6f78c735f07c 249
haarkon 0:6f78c735f07c 250 private :
haarkon 0:6f78c735f07c 251
haarkon 0:6f78c735f07c 252 int Pixy_CCFrameIsNew, Pixy_NMFrameIsNew;
haarkon 0:6f78c735f07c 253
haarkon 0:6f78c735f07c 254 /**
haarkon 0:6f78c735f07c 255 * Fonction d'interruption de lecture sur la liaison série.
haarkon 0:6f78c735f07c 256 */
haarkon 0:6f78c735f07c 257 void getPixyByte();
haarkon 0:6f78c735f07c 258
haarkon 0:6f78c735f07c 259
haarkon 0:6f78c735f07c 260 };
haarkon 0:6f78c735f07c 261
haarkon 0:6f78c735f07c 262 #endif /* PIXY_H */