[Libphidget-cvs-commits] CVS: libphidget/src/libphidget phidget.h,1.18,1.19

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/libphidget/libphidget/src/libphidget
In directory sc8-pr-cvs1:/tmp/cvs-serv31576

Modified Files:
	phidget.h 
Log Message:
Updated the documentation

Index: phidget.h
===================================================================
RCS file: /cvsroot/libphidget/libphidget/src/libphidget/phidget.h,v
retrieving revision 1.18
retrieving revision 1.19
diff -C2 -d -r1.18 -r1.19
*** phidget.h	18 Dec 2002 02:51:16 -0000	1.18
--- phidget.h	19 Dec 2002 17:39:36 -0000	1.19
***************
*** 19,28 ****
   * Theoretically it should be possible to use this library on any platform that 
   * libusb supports but it has only been tested on linux. It may be used by itself 
!  * or in conjustion with the C++ phidget library also available on this site.  If 
   * you aren't familiar with phidgets don't ready any further, just go check them 
   * out at <a href="http://www.phidgets.com>www.phidgets.com</a>.</p>
   *
!  * <p>The starting place for this library is in the header, phidget.h.
!  * </p>
   *
   */
--- 19,37 ----
   * Theoretically it should be possible to use this library on any platform that 
   * libusb supports but it has only been tested on linux. It may be used by itself 
!  * or in conjunction with the C++ phidget library also available on this site.  If 
   * you aren't familiar with phidgets don't ready any further, just go check them 
   * out at <a href="http://www.phidgets.com>www.phidgets.com</a>.</p>
   *
!  * <p>The starting place for this library is in the header, phidget.h.</p>
!  *
!  * <p>Below is a list of the different phidgets that are currently supported:</p>
!  * <ul>
!  * 	<li>Single Servo</li>
!  * 	<li>Quad Servo</li>
!  * 	<li>8-way Servo - coming soon</li>
!  * 	<li>4/8/8 Interface Kit</li>
!  * 	<li>8/8/0 Interface Kit - coming soon (keep your fingers crossed)</li>
!  * 	<li>Text LCD</li>
!  * </ul>
   *
   */
***************
*** 41,45 ****
   * and it has to look at all the USB devices again.  When libusb adds a callback
   * I can make this more efficient, but it should be fine for now.  The api shouldn't
!  * change when they add that.
   */

--- 50,57 ----
   * and it has to look at all the USB devices again.  When libusb adds a callback
   * I can make this more efficient, but it should be fine for now.  The api shouldn't
!  * change when they add that.</p>
!  *
!  * <p>Also in this library are some "helper" functions that simplify writing data 
!  * to phidget servo controllers, lcds, and interface kits.</p>
   */

***************
*** 65,89 ****

      LP_SERVO_CONTROLLER = 200,	 /**< Identifies all servo controller phidgets */
      LP_INTERFACE_KIT = 300,	 /**< Identifies all interface kit phidgets, support being added now */
      LP_INTERFACE_KIT_880 = 301,	 /**< 880 interface kit */
      LP_INTERFACE_KIT_488 = 302,	 /**< 488 interface kit */
      LP_ENCODER = 400,		 /**< Currently unsupported */
      LP_POWER = 500,		 /**< Currently unsupported */
      LP_RFID = 600,		 /**< Currently unsupported */
      LP_LED = 700,		 /**< Currently unsupported */
      LP_TEXT_LCD = 800,		 /**< Text LCD */

      // Phidget subdevices, a phidget subdevice is something a phidget controls
      LP_SUB_DEVICE = 101,         /**< A SubDevice of a phidget, not used in this library */
!     LP_SERVO = 201,		 /**< Any servo that a servo controller controls */
!     LP_DIGITAL_IN = 394,	 /**< Any digital input that an interface kit controls */
!     LP_DIGITAL_OUT = 395,	 /**< Any digital output that an interface kit controls */
!     LP_ANALOG_IN = 396,		 /**< Any analog input that an interface kit controls */
!     LP_ANALOG_OUT = 397,         /**< Any analog input that an interface kit controls */
!     LP_IN = 398,                 /**< Any input that an interface kit controls */
!     LP_OUT = 399,                /**< Any output that an interface kit controls */

!     LP_OTHER = 0,		 /**< Identifies all unknown phidgets, this shouldn't exists */
!     LP_INVALID = -2,		 /**< Invalid device class */

  };
--- 77,107 ----

      LP_SERVO_CONTROLLER = 200,	 /**< Identifies all servo controller phidgets */
+ 
      LP_INTERFACE_KIT = 300,	 /**< Identifies all interface kit phidgets, support being added now */
      LP_INTERFACE_KIT_880 = 301,	 /**< 880 interface kit */
      LP_INTERFACE_KIT_488 = 302,	 /**< 488 interface kit */
+ 
      LP_ENCODER = 400,		 /**< Currently unsupported */
+ 
      LP_POWER = 500,		 /**< Currently unsupported */
+ 
      LP_RFID = 600,		 /**< Currently unsupported */
+ 
      LP_LED = 700,		 /**< Currently unsupported */
+ 
      LP_TEXT_LCD = 800,		 /**< Text LCD */

      // Phidget subdevices, a phidget subdevice is something a phidget controls
      LP_SUB_DEVICE = 101,         /**< A SubDevice of a phidget, not used in this library */
!     LP_SERVO = 201,		 /**< Sero sub-device, any servo that a servo controller controls */
!     LP_DIGITAL_IN = 394,	 /**< Digital in sub-device, any digital input that an interface kit controls */
!     LP_DIGITAL_OUT = 395,	 /**< Digltal out sub-device, any digital output that an interface kit controls */
!     LP_ANALOG_IN = 396,		 /**< Analog in sub-device, any analog input that an interface kit controls */
!     LP_ANALOG_OUT = 397,         /**< Analog out sub-device, any analog input that an interface kit controls, currently phidget currently handles analog output */
!     LP_IN = 398,                 /**< Input sub-device, Any input that an interface kit controls */
!     LP_OUT = 399,                /**< Output sub-device, Any output that an interface kit controls */

!     LP_OTHER = 0,		 /**< Identifies all unknown phidgets, this shouldn't exist */
!     LP_INVALID = -2,		 /**< Invalid device class, any negative device class is an error. */

  };
***************
*** 119,290 ****
  #endif

! /** Must be called before before any other libphidget function.  Right now this 
!  * initializes some internal structures and queries libusb for all USB devies, 
!  * looking for any phidgets.  So any phidget plugged in after phidget_init is 
!  * called will not be detected.  After libusb is modified to support attach/detach 
!  * events this library will be upgraded to support that functionality also.  If 
!  * necessary it should be safe to call \a phidget_init multiple times as long as 
!  * long as \a phidget_deinit is called between each call to \a phidget_init.  
!  */
!     enum ELPError phidgetInit(int catchSignals);

! /** Must be called at the end of your program.  Frees some internal data 
!  * structures.   If this isn't called then there will be memory leaks.  
!  */
!     enum ELPError phidgetDeinit();

! /** 
!  * Returns a list of currently available phidgets  If an error occurs then NULL is returned
!  * and phidgetLastError() will return the error code.
!  */
!     struct phidget **phidgetGetPhidgets(int *numPhidgets);

! /** 
!  * Open a phidget.  If an error occurs then NULL is returned and phidgetLastError() will
!  * return the error code.
!  */
!     struct phidget *phidgetOpen(struct phidget *phidget	//<! The phidget that we want to open
  	);

! /**
!  * Close a phidget
!  */
!     enum ELPError phidgetClose(struct phidget *device	//<! The phidget to be closed
  	);

! /**
!  * Write some data to a phidget. Currently this function just uses a control 
!  * message, in the future it will adapt depending on the type of phidget we are 
!  * writing to.
!  */
!     enum ELPError phidgetWrite(struct phidget *device,	//<! The phidget to be written to
! 			       char *bytes,	//<! Pointer to data that is to be written to the device
! 			       int size	//<! Size in bytes of data pointed to by \a bytes
! 	);

! /** 
!  * Read some data back from a phidget, haven't tested this yet because I don't 
!  * have an interface kit or any phidget that supports reads.
!  */
!     enum ELPError phidgetRead(struct phidget *device,	//<! The phidget to be read from 
! 			      char *bytes,	//<! Pointer allocated large enough to hold \a size bytes of data
! 			      int size	//<! Size in bytes of data to read from device
! 	);

! /** 
!  * Send an angle (0.0 to 1.0) to a single servo.  The phidget servo controllers
!  * support a 12 bit 'angle', but this is arbitrary since different types of servos
!  * support different ranges of motion.  So I support a floating point 'percentage'
!  * that controls the extent of rotation on the servo.  If you know the range of 
!  * motion on your servo you can simple say percent = desired_angle / range.
!  */
!     enum ELPError phidgetSingleServo(struct phidget *device,	//<! The phidget to be controlled
! 				     float percent	//<! Percentage to move servo 1
! 	);

! /**
!  * Sets the default value of the servo, this is the value the servo will be set to when the
!  * device is closed (either on purpose, or when the signal handler catches it)
!  */
!     enum ELPError pidgetSingleServoDefault(struct phidget *device,	//<! The phidget whose default we want to set
! 					   float percent	//!< Percentage to move servo 1
! 	);

! /** 
!  * Send an angle (0.0 to 1.0) to four servos.  The phidget servo controllers
!  * support a 12 bit 'angle', but this is arbitrary since different types of servos
!  * support different ranges of motion.  So I support a floating point 'percentage'
!  * that controls the extent of rotation on the servo.  If you know the range of 
!  * motion on your servo you can simple say percent = desired_angle / range.
!  */
!     enum ELPError phidgetQuadServo(struct phidget *device,	//!< The phidget to be contorlled
! 				   float percent1,	//!< Percentage to move servo 1
! 				   float percent2,	//!< Percentage to move servo 2
! 				   float percent3,	//!< Percentage to move servo 3
! 				   float percent4	//!< Percentage to move servo 4
! 	);

! /**
!  * Sets the default value of the servo, this is the value the servo will be set to when the
!  * device is closed (either on purpose, or when the signal handler catches it)
!  */
!     enum ELPError phidgetQuadServoDefault(struct phidget *device,	//<! The phidget whose default we want to set
! 					 float percent1,	//!< Percentage to move servo 1
! 					 float percent2,	//!< Percentage to move servo 2
! 					 float percent3,	//!< Percentage to move servo 3
! 					 float percent4	//!< Percentage to move servo 4
! 	);

! enum ELPError phidget8Servo(struct phidget *phidgetDevice, int id, float percent1, float maxvelocity, float acceleration);

! enum ELPError phidgetTextLCDOn(struct phidget *phidgetDevice);
! enum ELPError phidgetTextLCDOff(struct phidget *phidgetDevice);
! enum ELPError phidgetInterfaceKit488Read(struct phidget *phidgetDevice, float analog[4], int digital[8]);
! enum ELPError phidgetInterfaceKit880Read(struct phidget *phidgetDevice, float analog[8], int digital[8]);
! enum ELPError phidgetInterfaceKitWrite(struct phidget *phidgetDevice, int index, int value);
! enum ELPError phidgetTextLCDWrite(struct phidget *phidgetDevice, int row, int col, const char *str);
! enum ELPError phidgetTextLCDClear(struct phidget *phidgetDevice);

! /**
!  * This checks for any new or changed devices, if anything has changed since the 
!  * last time this function has been called, then it returns 1, else it returns 0.  If an
!  * error occurs it returns an \a ELPError equivalent error number.
!  *
!  * This is an important function to call periodically.  This performs the magic
!  * of updating phidget structures.  If you unplug a phidget that you have opened
!  * then when it is reconnected you will be re-attached to the same USB device.
!  */
!     int phidgetEvents();

! /**
!  * Return a phidget_type structure from a phidget device.  If an error occurs it returns
!  * a NULL and phidgetLastError() will return the error code.
!  */
!     const struct phidget_type *phidgetType(const struct phidget *device);

! /**
!  * Return the serial number from a phidget.  If an error occurs it returns an \a ELPError equivalent error number.
!  */
!     int phidgetSerial(const struct phidget *device);

! /**
!  * Return the human readable description of a phidget type.  If an error occurs it returns
!  * a NULL and phidgetLastError() will return the error code.
!  */
!     const char *phidgetTypeName(const struct phidget_type *tp);

! /**
!  * Returns the product ID of a phidget type   If an error occurs it returns an \a ELPError equivalent error number.
!  */
!     int phidgetTypeProductID(const struct phidget_type *tp);

- /**
-  * Returns a vendor ID of a phidget type  If an error occurs it returns an \a ELPError equivalent error number.
-  */
-     int phidgetTypeVendorID(const struct phidget_type *tp);

! /**
!  * Returns the device class of a phidget type  If an error occurs it returns an \a ELPError equivalent error number.
!  */
!     enum EDeviceClass phidgetTypeDeviceClass(const struct phidget_type *tp);

! /**
!  * Returns 1 if a phidget is attached, 0 if it isn't attached.  If an error occurs it returns an \a ELPError equivalent error number.
!  */
!     int phidgetAttached(const struct phidget *device);

!     int phidgetWasAttached(const struct phidget *device);

! /**
!  * Returns the last error that occured.  No defined error can occur during this call.
!  */
!     enum ELPError phidgetLastError();

! /**
!  * Returns a human readable string that describes the error number.
!  */
!     const char *phidgetErrorString(const enum ELPError err);

--- 137,391 ----
  #endif

! 	/** 
! 	 * Must be called before before any other libphidget function.  Right now this 
! 	 * initializes some internal structures and queries libusb for all USB devies, 
! 	 * looking for any phidgets.  So any phidget plugged in after phidget_init is 
! 	 * called will not be detected.  After libusb is modified to support attach/detach 
! 	 * events this library will be upgraded to support that functionality also.  If 
! 	 * necessary it should be safe to call \a phidget_init multiple times as long as 
! 	 * long as \a phidget_deinit is called between each call to \a phidget_init.  
! 	 */
! 	enum ELPError phidgetInit(int catchSignals);

! 	/** 
! 	 * Must be called at the end of your program.  Frees some internal data 
! 	 * structures.   If this isn't called then there will be memory leaks.  
! 	 */
! 	enum ELPError phidgetDeinit();

! 	/** 
! 	 * Returns a list of currently available phidgets  If an error occurs then NULL is returned
! 	 * and phidgetLastError() will return the error code.
! 	 */
! 	struct phidget **phidgetGetPhidgets(int *numPhidgets);

! 	/** 
! 	 * Open a phidget.  If an error occurs then NULL is returned and phidgetLastError() will
! 	 * return the error code.
! 	 */
! 	struct phidget *phidgetOpen(struct phidget *phidget	//<! The phidget that we want to open
  	);

! 	/**
! 	 * Close a phidget
! 	 */
! 	enum ELPError phidgetClose(struct phidget *device	//<! The phidget to be closed
  	);

! 	/**
! 	 * Write some data to a phidget. Currently this function just uses a control 
! 	 * message, in the future it will adapt depending on the type of phidget we are 
! 	 * writing to.
! 	 */
! 	enum ELPError phidgetWrite(
! 		struct phidget *device,	//<! The phidget to be written to
! 		char *bytes,	//<! Pointer to data that is to be written to the device
! 		int size	//<! Size in bytes of data pointed to by \a bytes
! 		);

! 	/** 
! 	 * Read some data back from a phidget, haven't tested this yet because I don't 
! 	 * have an interface kit or any phidget that supports reads.
! 	 */
! 	enum ELPError phidgetRead(
! 		struct phidget *device,	//<! The phidget to be read from 
! 		char *bytes,	//<! Pointer allocated large enough to hold \a size bytes of data
! 		int size	//<! Size in bytes of data to read from device
! 		);

! 	/** 
! 	 * Send an angle (0.0 to 1.0) to a single servo.  The phidget servo controllers
! 	 * support a 12 bit 'angle', but this is arbitrary since different types of servos
! 	 * support different ranges of motion.  So I support a floating point 'percentage'
! 	 * that controls the extent of rotation on the servo.  If you know the range of 
! 	 * motion on your servo you can simple say percent = desired_angle / range.
! 	 */
! 	enum ELPError phidgetSingleServo(
! 		struct phidget *device,	//<! The phidget to be controlled
! 		float percent	//<! Percentage to move servo 1
! 		);

! 	/**
! 	 * Sets the default value of the servo, this is the value the servo will be set to when the
! 	 * device is closed (either on purpose, or when the signal handler catches it)
! 	 */
! 	enum ELPError pidgetSingleServoDefault(
! 		struct phidget *device,	//<! The phidget whose default we want to set
! 		float percent	//!< Percentage to move servo 1
! 		);

! 	/** 
! 	 * Send an angle (0.0 to 1.0) to four servos.  The phidget servo controllers
! 	 * support a 12 bit 'angle', but this is arbitrary since different types of servos
! 	 * support different ranges of motion.  So I support a floating point 'percentage'
! 	 * that controls the extent of rotation on the servo.  If you know the range of 
! 	 * motion on your servo you can simple say percent = desired_angle / range.
! 	 */
! 	enum ELPError phidgetQuadServo(
! 		struct phidget *device,	//!< The phidget to be contorlled
! 		float percent1,	//!< Percentage to move servo 1
! 		float percent2,	//!< Percentage to move servo 2
! 		float percent3,	//!< Percentage to move servo 3
! 		float percent4	//!< Percentage to move servo 4
! 		);

! 	/**
! 	 * Sets the default value of the servo, this is the value the servo will be set to when the
! 	 * device is closed (either on purpose, or when the signal handler catches it)
! 	 */
! 	enum ELPError phidgetQuadServoDefault(
! 		struct phidget *device,	//<! The phidget whose default we want to set
! 		float percent1,	//!< Percentage to move servo 1
! 		float percent2,	//!< Percentage to move servo 2
! 		float percent3,	//!< Percentage to move servo 3
! 		float percent4	//!< Percentage to move servo 4
! 		);

! 	//enum ELPError phidget8Servo(struct phidget *phidgetDevice, int id, float percent1, float maxvelocity, float acceleration);

! 	/**
! 	 * Turns a Text LCD screen on.  This does not clear the memory but simply turns the dispaly on.
! 	 * So you can write to the display without it being on and when you switch it on it will show.
! 	 */
! 	enum ELPError phidgetTextLCDOn(
! 		struct phidget *phidgetDevice //!< The phidget to use
! 		);
! 	
! 	/**
! 	 * Turns a Text LCD screen off. This does not clear the memory.
! 	 */
! 	enum ELPError phidgetTextLCDOff(
! 		struct phidget *phidgetDevice //!< The phidget to use
! 		);

! 	/**
! 	 * Reads a 4/8/8 interface kit
! 	 */
! 	enum ELPError phidgetInterfaceKit488Read(
! 		struct phidget *phidgetDevice,  //!< The phidget to read from
! 		float analog[4], //!< This will be filled with the value of the four analog inputs
! 		int digital[8] //!< This iwll be filled with the value of the four digital inputs.  1 is on, 0 is off.
! 		);

+ 	/**
+ 	 * Reads a 8/8/0 interface kit
+ 	 */
+ 	enum ELPError phidgetInterfaceKit880Read(
+ 		struct phidget *phidgetDevice,  //!< The phidget to read from
+ 		float analog[8], //!< This will be filled with the value of eight analog inputs
+ 		int digital[8] //!< This will be filled with the value of eight digital inputs, 1 is on, 0 is off.
+ 		);

! 	/**
! 	 * Write data to any of the eight analog outputs of an interface kit (either 4/8/8 or 8/8/0).  There are
! 	 * no bounds checking on these values
! 	 */
! 	enum ELPError phidgetInterfaceKitWrite(
! 		struct phidget *phidgetDevice,  //!< The phidget to write to
! 		int index,  //!< The digital out to write a value to where 0 >= index < 8 is true.
! 		int value //!< The value either to write, 1 is on, 0 is off.  
! 		);

! 	/**
! 	 * Writes a single line of text to a TextLCD screen.  There are no bounds checking on these values.
! 	 */
! 	enum ELPError phidgetTextLCDWrite(
! 		struct phidget *phidgetDevice,  //!< The phidget to write to
! 		int row, //!< The row to write the string where 0 >= row < 4 is true.
! 		int col, //!< The column to start the string on where 0 >= column < 12 is true.
! 		const char *str //!< The string to write.  strlen(str)+col must be less than 12.
! 		);

! 	/**
! 	 * Sends four calls to phidgetTextLCDWrite clearing the screen.
! 	 */
! 	enum ELPError phidgetTextLCDClear(
! 		struct phidget *phidgetDevice //!< The phidget to write to
! 		);

! 	/**
! 	 * This checks for any new or changed devices, if anything has changed since the 
! 	 * last time this function has been called, then it returns 1, else it returns 0.  If an
! 	 * error occurs it returns an \a ELPError equivalent error number.
! 	 *
! 	 * This is an important function to call periodically.  This performs the magic
! 	 * of updating phidget structures.  If you unplug a phidget that you have opened
! 	 * then when it is reconnected you will be re-attached to the same USB device.
! 	 */
! 	int phidgetEvents();

! 	/**
! 	 * Return a phidget_type structure from a phidget device.  If an error occurs it returns
! 	 * a NULL and phidgetLastError() will return the error code.
! 	 */
! 	const struct phidget_type *phidgetType(
! 		const struct phidget *device //!< The phidget whose type you are requesting.
! 		);

! 	/**
! 	 * Return the serial number from a phidget.  If an error occurs it returns an \a ELPError equivalent error number.
! 	 */
! 	int phidgetSerial(
! 		const struct phidget *device //!< The phidget whose serial number you are requesting.
! 		);

! 	/**
! 	 * Return the human readable description of a phidget type.  If an error occurs it returns
! 	 * a NULL and phidgetLastError() will return the error code.
! 	 */
! 	const char *phidgetTypeName(
! 		const struct phidget_type *tp //!< Thep hidget whose type name you are requesting.
! 		);
! 
! 	/**
! 	 * Returns the product ID of a phidget type   If an error occurs it returns an \a ELPError equivalent error number.
! 	 */
! 	int phidgetTypeProductID(
! 		const struct phidget_type *tp //!< The phidget whose product ID you are requesting.
! 		);

+ 	/**
+ 	 * Returns a vendor ID of a phidget type  If an error occurs it returns an \a ELPError equivalent error number.
+ 	 */
+ 	int phidgetTypeVendorID(
+ 		const struct phidget_type *tp //!< The phidget whose vendor ID you are requesting.
+ 		);

! 	/**
! 	 * Returns the device class of a phidget type  If an error occurs it returns an \a ELPError equivalent error number.
! 	 */
! 	enum EDeviceClass phidgetTypeDeviceClass(
! 		const struct phidget_type *tp //!< The phidget whose type class you are requesting.
! 		);

! 	/**
! 	 * Returns 1 if a phidget is attached, 0 if it isn't attached.  If an error occurs it returns an \a ELPError equivalent error number.
! 	 * By calling phidgetAttached and phidgetWasAttached you can determine if the phidget just became attached or detached.
! 	 */
! 	int phidgetAttached(
! 		const struct phidget *device //!< The phidget whose attachment status you are requesting.
! 		);
! 
! 	/**
! 	 * Returns the previous value that pridgetAttached would have returned.  If an error occurs it returns an \a ELPError requivalent error number.
! 	 * By calling phidgetAttached and phidgetWasAttached you can determine if the phidget just became attached or detached.
! 	 */
! 	int phidgetWasAttached(
! 		const struct phidget *device //!< The phidget whose previous attachment status you are requesting.
! 		);
! 
! 
! 	/**
! 	 * Returns the last error that occured.  No defined error can occur during this call.
! 	 */
! 	enum ELPError phidgetLastError();
! 
! 	/**
! 	 * Returns a human readable string that describes the error number.
! 	 */
! 	const char *phidgetErrorString(
! 		const enum ELPError err //!< The error number you want made human readable
! 		);