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

Pixy2 pixy;

pixy.init(); // call init() member function

See also the Color Connected Components API, Line tracking API, and Video API for other functionality.

For a byte-level reference to the protocol, check out the new Pixy2 Serial Protocol - Packet Reference

init() should be called before your program communicates with Pixy. init() returns an error value (<0) if it fails and 0 (PIXY_RESULT_OK) if it succeeds.

getVersion() queries and receives the firmware and hardware version of Pixy2., which is put in the version member variable. It returns an error value (<0) if it fails and 0 (PIXY_RESULT_OK) if it succeeds. It is called automatically as part of init().

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 error value (<0) if it fails and 0 (PIXY_RESULT_OK) if it succeeds.

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 error value (<0) if it fails and 0 (PIXY_RESULT_OK) if it succeeds.

setCameraBrightness() sets the relative exposure level of Pixy2's image sensor. Higher values result in a brighter (more exposed) image. It returns an error value (<0) if it fails and 0 (PIXY_RESULT_OK) if it succeeds.

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 error value (<0) if it fails and 0 (PIXY_RESULT_OK) if it succeeds.

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 error value (<0) if it fails and 0 (PIXY_RESULT_OK) if it succeeds.

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.

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 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.

This contains the Pixy2's version information as a result of getVersion(). Inside the Version struct:

Calling this prints the version information to the console.

This variable contains the hardware version number.

This variable contains the firmware major version number.

This variable contains the firmware minor version number.

This variable contains the firmware build version number.

This variable contains the a string description of the firmware type.

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.

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.

This is an instance of the Color Connected Components object associated with the color_connected_components program.

This is an instance of the Line Tracking object associated with the line_tracking program.

General error result

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

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

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

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