====== Arduino Library and API ======


===== Installing the Arduino Library =====

Download the latest Arduino library "arduino%%_%%pixy2-x.y.z.zip" [[https://pixycam.com/downloads-pixy2/|here]]. Bring up the Arduino IDE and import the Pixy library by selecting **Sketch➜Import Library** in the Arduino IDE, and then browse to the Arduino zip file that you just downloaded.


===== Updating the Arduino Library =====

Before installing a new version of the Arduino Library, it's recommended that you delete the existing library. To do this, you can go into your C:\Users\<yourname>\Documents\Arduino\libraries (or similar directory, <yourname>/Documents/Arduino in OSX and Linux) and remove the Pixy directory. Then re-run the Arduino IDE.


===== Arduino API =====


==== Include files ====

Be sure to include these two files:

<code>
#include <SPI.h>
#include <Pixy2.h>
</code>

==== Instantiation ====

You need to declare an instance of a Pixy object outside of your setup() and loop() functions:

<code>
Pixy2 pixy;
</code>

==== uint16_t getBlocks(uint16_t maxBlocks=1000) ====

The most important method in the Arduino library is ''%%getBlocks()%%'', which returns the number of objects Pixy has detected. You can then look in the ''%%pixy.ccc.blocks[]%%'' array for information about each detected object (one array member for each detected object.) Each array member (''%%i%%'') contains the following fields:

  * ''%%pixy.ccc.blocks[i].m_signature%%'' The signature number of the detected object (1-7 for normal signatures)
  * ''%%pixy.ccc.blocks[i].m_x%%'' The x location of the center of the detected object (0 to 316)
  * ''%%pixy.ccc.blocks[i].m_y%%'' The y location of the center of the detected object (0 to 208)
  * ''%%pixy.ccc.blocks[i].m_width%%'' The width of the detected object (1 to 316)
  * ''%%pixy.ccc.blocks[i].m_height%%'' The height of the detected object (1 to 208)
  * ''%%pixy.ccc.blocks[i].m_angle%%'' The angle of the object detected object if the detected object is a [[wiki:v2:Using_Color_Codes|color code]] (-180 to 180).
  * ''%%pixy.ccc.blocks[i].m_index%%'' The [[wiki:v2:color_connected_components#Pixy2 "tracks" each object it detects|tracking index]] of the block
  * ''%%pixy.ccc.blocks[i].m_age%%'' The number of frames the block has been tracked.
  * ''%%pixy.ccc.blocks[i].print()%%'' A member function that prints the detected object information to the serial port

''%%getBlocks()%%'' accepts an optional number argument (''%%uint16_t%%'') that indicates the maximum number of blocks you want ''%%getBlocks()%%'' to return.


==== int8_t setServos(uint16_t s0, uint16_t s1) ====

This method sets the pan/tilt servos that are plugged into Pixy's two servo ports. The two arguments ''%%s0%%'' and ''%%s1%%'' can range from 0 to 1000.


==== int8_t setBrightness(uint8_t brightness) ====

This method sets the brightness (exposure) of Pixy's camera. The ''%%brightness%%'' argument can range between 0 and 255 with 255 being the brightest setting.


==== int8_t setLED(uint8_t r, uint8_t g, uint8_t b) ====

This method sets the RGB LED on front of Pixy. The ''%%r%%'', ''%%g%%'' and ''%%b%%'' arguments can range between 0 and 255.