<< return to Pixycam.com

User Tools

Site Tools


wiki:v2:general_api

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
wiki:v2:general_api [2018/05/22 03:16]
pixycam
wiki:v2:general_api [2019/04/29 20:08] (current)
pixycam
Line 1: Line 1:
 ===== Pixy2 General API ===== ===== Pixy2 General API =====
  
-==== Methods ​====+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]) ===+=== 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. ​
  
-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() === === 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) === === 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) === === 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) === === 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) === === 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) === === int8_t setLamp(uint8_t upper, uint8_t lower) ===
  
-==== Data members ​====+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 === === 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 === === 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 === === 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 === === Pixy2CCC ccc ===
 +This is an instance of the Color Connected Components object associated with the color\_connected\_components program.  ​
 +
 === Pixy2Line line === === Pixy2Line line ===
 +This is an instance of the Line Tracking object associated with the line\_tracking program.  ​
  
-===== Error codes =====+==== Error codes ====
  
 === PIXY_RESULT_ERROR === === PIXY_RESULT_ERROR ===
 +General error result
 +
 === PIXY_RESULT_BUSY === === 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 === === PIXY_RESULT_CHECKSUM_ERROR ===
 +This is returned when the data packet received contains a checksum error.
 +
 === PIXY_RESULT_TIMEOUT === === PIXY_RESULT_TIMEOUT ===
 +This is returned when Pixy2 has taken too long to return its result.
 +
 === PIXY_RESULT_BUTTON_OVERRIDE === === 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.
  
wiki/v2/general_api.1526958999.txt.gz · Last modified: 2018/05/22 03:16 by pixycam