===== Pixy2 General API =====

Pixy2's general API can be called through the base Pixy2 object, for example:

<code>
Pixy2 pixy;

pixy.init(); // call init() member function
</code>

See also the [[wiki:v2:ccc_api|Color Connected Components API]], [[wiki:v2:line_api|Line tracking API]], and [[wiki:v2:video_api|Video API]] for other functionality.

For a byte-level reference to the protocol, check out the new [[wiki:v2:protocol_reference|Pixy2 Serial Protocol - Packet Reference]]


==== Member functions ====
  
=== int8_t init(uint32_t arg [optional]) ===

init() should be called before your program communicates with Pixy.  init() returns an [[wiki:v2:general_api#Error codes|error value]] (<0) if it fails and 0 (PIXY\_RESULT\_OK) if it succeeds. 


=== int8_t getVersion() ===

getVersion() queries and receives the firmware and hardware version of Pixy2., which is put in the **version** member variable.  It returns an [[wiki:v2:general_api#Error codes|error value]] (<0) if it fails and 0 (PIXY\_RESULT\_OK) if it succeeds.  It is called automatically as part of init().  


=== int8_t changeProg(const char *prog) ===

changeProg() instructs Pixy2 to switch programs.  It takes a string argument that indicates the name of the program.  The argument can be a partial string of the program name as long as it is unique with respect to the other program names.  It returns an [[wiki:v2:general_api#Error codes|error value]] (<0) if it fails and 0 (PIXY\_RESULT\_OK) if it succeeds.
 

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

setServos() sets the servo positions of servos plugged into Pixy2's two RC servo connectors.  The servo values range between PIXY\_RCS\_MIN\_POS (0) and PIXY\_RCS\_MAX\_POS (1000).  It returns an [[wiki:v2:general_api#Error codes|error value]] (<0) if it fails and 0 (PIXY\_RESULT\_OK) if it succeeds.
 

=== int8_t setCameraBrightness(uint8_t brightness) ===

setCameraBrightness() sets the relative exposure level of Pixy2's image sensor.  Higher values result in a brighter (more exposed) image.  It returns an [[wiki:v2:general_api#Error codes|error value]] (<0) if it fails and 0 (PIXY\_RESULT\_OK) if it succeeds. 


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

setLED() sets 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.  It returns an [[wiki:v2:general_api#Error codes|error value]] (<0) if it fails and 0 (PIXY\_RESULT\_OK) if it succeeds. 


=== int8_t setLamp(uint8_t upper, uint8_t lower) ===

setLamp() 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. Both arguments are binary, zero or non-zero.  It returns an [[wiki:v2:general_api#Error codes|error value]] (<0) if it fails and 0 (PIXY\_RESULT\_OK) if it succeeds. 


=== int8_t getResolution() ===

getResolution() gets the width and height of the frames used by the current program.  After calling this function, the width and height can be found in the **frameWidth** and **frameHeight** member variables.  Note, calling changeProg() will call getResolution() automatically and update **frameWidth** and **frameHeight**.  


Pixy2 will automatically change programs if, for example, you call ccc.getBlocks() from the color connected components program followed by line.getMainFeatures() from the line tracking program.  These "automatic program changes" will not update **frameWidth** and **frameHeight** member variables.


=== int8_t getFPS() ===

getFPS() gets Pixy2's framerate.  The framerate can range between 2 and 62 frames per second depending on the amount of light in the environment and the **min frames per second** setting in the [[wiki:v2:pixymon_index#camera-tab|Camera configuration tab]].  This function can also serve as a simple indicator of the amount of light in the environment.  That is, low framerates necessarily imply lower lighting levels.  



==== Member variables ====

=== Version *version ===

This contains the Pixy2's version information as a result of getVersion().  Inside the Version struct:
== void print() == 
Calling this prints the version information to the console.  
 
== uint16_t hardware ==
This variable contains the hardware version number.

== uint8_t firmwareMajor ==
This variable contains the firmware major version number.

== uint8_t firmwareMinor ==
This variable contains the firmware minor version number.

== uint16_t firmwareBuild ==
This variable contains the firmware build version number.

== char *firmwareType ==   
This variable contains the a string description of the firmware type. 

=== uint16_t frameWidth ===
This variable contains the width of the frame in pixels.  This field is updated upon calling init() and upon calling changeProg() as each program may have a unique frame size.  
 
=== uint16_t frameHeight ===
This variable contains the height of the frame in pixels.  This field is updated upon calling init() and upon calling changeProg() as each program may have a unique frame size.  
 
=== Pixy2CCC ccc ===
This is an instance of the Color Connected Components object associated with the color\_connected\_components program.  

=== Pixy2Line line ===
This is an instance of the Line Tracking object associated with the line\_tracking program.  

==== Error codes ====

=== PIXY_RESULT_ERROR ===
General error result

=== PIXY_RESULT_BUSY ===
This is returned when Pixy has no new data.  It is used in polling mode, as opposed to blocking mode.

=== PIXY_RESULT_CHECKSUM_ERROR ===
This is returned when the data packet received contains a checksum error.

=== PIXY_RESULT_TIMEOUT ===
This is returned when Pixy2 has taken too long to return its result.

=== PIXY_RESULT_BUTTON_OVERRIDE ===
This is returned when the user is interacting with the button (e.g. teaching Pixy a signature) and can't perform the requested action.