Table of Contents

Pixy2 General API

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

Member functions

int8_t init(uint32_t arg [optional])

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.

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