Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Device::USB::Device(3)User Contributed Perl DocumentatioDevice::USB::Device(3)

Device::USB::Device
       This class encapsulates the USB device structure	and the	methods	that
       may be applied to it.

NAME
       Device::USB::Device - Use libusb	to access USB devices.

VERSION
       Version 0.29

SYNOPSIS
       Device:USB::Device provides a Perl object for accessing a USB device
       using the libusb	library.

	   use Device::USB;

	   my $usb = Device::USB->new();
	   my $dev = $usb->find_device(	$VENDOR, $PRODUCT );

	   printf "Device: %04X:%04X\n", $dev->idVendor(), $dev->idProduct();
	   print "Manufactured by ", $dev->manufacturer(), "\n",
		 " Product: ", $dev->product(),	"\n";

	   $dev->set_configuration( $CFG );
	   $dev->control_msg( @params );
	   ...

       See the libusb manual for more information about	most of	the methods.
       The functionality is generally the same as the libusb function whose
       name is the method name prepended with "usb_".

DESCRIPTION
       This module defines a Perl object that represents the data and
       functionality associated	with a USB device. The object interface
       provides	read-only access to the	important data associated with a
       device. It also provides	methods	for almost all of the functions
       supplied	by libusb. Where necessary, the	interfaces to these methods
       were changed to better match Perl usage.	However, most of the methods
       are straight-forward wrappers around their libusb counterparts.

   METHODS
       DESTROY
	   Close the device connected to the object.

       filename
	   Retrieve the	filename associated with the device.

       config
	   In list context, return a list of the configuration structures for
	   this	device.	 In scalar context, return a reference to that list.
	   This	method is deprecated in	favor of the two new methods:
	   configurations and get_configuration.

       configurations
	   In list context, return a list of the configuration structures for
	   this	device.	 In scalar context, return a reference to that list.

       get_configuration
	   Retrieve the	configuration requested	by index. The legal values are
	   from	0 to bNumConfigurations() - 1. Negative	values access from the
	   back	of the list of configurations.

	   index numeric index of the index to return. If not supplied,	use 0.

	   Returns an object encapsulating the configuration on	success, or
	   "undef" on failure.

       accessors
	   There a several accessor methods that return	data from the device
	   and device descriptor. Each is named	after the field	that they
	   return. All of the BCD fields have been changed to floating point
	   numbers, so that you	don't have to decode them yourself.

	   The methods include:

	   bcdUSB
	   bDeviceClass
	   bDeviceSubClass
	   bDeviceProtocol
	   bMaxPacketSize0
	   idVendor
	   idProduct
	   bcdDevice
	   iManufacturer
	   iProduct
	   iSerialNumber
	   bNumConfigurations
       manufacturer
	   Retrieve the	manufacture name from the device as a string.  Return
	   undef if the	device read fails.

       product
	   Retrieve the	product	name from the device as	a string.  Return
	   undef if the	device read fails.

       serial_number
	   Retrieve the	serial number from the device as a string.  Return
	   undef if the	device read fails.

       open
	   Open	the device. If the device is already open, close it and	reopen
	   it.

	   If the device fails to open,	the reason will	be available in	$!.

       set_configuration
	   Sets	the active configuration of the	device.

	   configuration
	       the integer specified in	the descriptor field
	       bConfigurationValue.

	   returns 0 on	success	or <0 on error

	   When	using libusb-win32 under Windows, it is	important to call
	   "set_configuration()" after the "open()" but	before any other
	   method calls.  Without this call, other methods may not work. This
	   call	is not required	under Linux.

       set_altinterface
	   Sets	the active alternative setting of the current interface	for
	   the device.

	   alternate
	       the integer specified in	the descriptor field
	       bAlternateSetting.

	   returns 0 on	success	or <0 on error

       clear_halt
	   Clears any halt status on the supplied endpoint.

	   alternate
	       the integer specified bEndpointAddress descriptor field.

	   returns 0 on	success	or <0 on error

       reset
	   Resets the device. This also	closes the handle and invalidates this
	   device.  This device	will be	unusable.

       claim_interface
	   Claims the specified	interface with the operating system.

	   interface
	       The interface value listed in the descriptor field
	       bInterfaceNumber.

	   Returns 0 on	success, <0 on failure.

       release_interface
	   Releases the	specified interface back to the	operating system.

	   interface
	       The interface value listed in the descriptor field
	       bInterfaceNumber.

	   Returns 0 on	success, <0 on failure.

       control_msg
	   Performs a control request to the default control pipe on a device.

	   requesttype
	   request
	   value
	   index
	   bytes
	       Any returned data is placed here. If you	don't want any
	       returned	data, pass undef.

	   size
	       Size of supplied	buffer.

	   timeout
	       Milliseconds to wait for	response.

	   Returns number of bytes read	or written on success, <0 on failure.

       get_string
	   Retrieve a string descriptor	from the device.

	   index
	       The index of the	string in the string list.

	   langid
	       The language id used to specify which of	the supported
	       languages the string should be encoded in.

	   Returns a Unicode string. The function returns undef	on error.

       get_string_simple
	   Retrieve a string descriptor	from the device.

	   index
	       The index of the	string in the string list.

	   Returns a C-style string if successful, or undef on error.

       get_descriptor
	   Retrieve a descriptor from the device

	   type
	       The type	of descriptor to retrieve.

	   index
	       The index of that descriptor in the list	of descriptors of that
	       type.

	   TODO: This method needs major rewrite to be Perl-ish.  I need to
	   provide a better way	to specify the type (or	at least document
	   which are available), and I need to return a	Perl data structure,
	   not a buffer	of binary data.

       get_descriptor_by_endpoint
	   Retrieve an endpoint-specific descriptor from the device

	   ep  Endpoint	to query.

	   type
	       The type	of descriptor to retrieve.

	   index
	       The index of that descriptor in the list	of descriptors.

	   buf Buffer into which to write the requested	descriptor

	   size
	       Max size	to read	into the buffer.

	   TODO: This method needs major rewrite to be Perl-ish.  I need to
	   provide a better way	to specify the type (or	at least document
	   which are available), and I need to return a	Perl data structure,
	   not a buffer	of binary data.

       bulk_read
	   Perform a bulk read request from the	specified endpoint.

	   ep  The number of the endpoint to read

	   bytes
	       Buffer into which to write the requested	data.

	   size
	       Max size	to read	into the buffer.

	   timeout
	       Maximum time to wait (in	milliseconds)

	   The function	returns	the number of bytes returned or	<0 on error.

	   USB is packet based,	not stream based. So using "bulk_read()" to
	   read	part of	the packet acts	like a peek. The next time you read,
	   all of the packet is	still there.

	   The data is only removed when you read the entire packet. For this
	   reason, you should always call "bulk_read()"	with the total packet
	   size.

       interrupt_read
	   Perform a interrupt read request from the specified endpoint.

	   ep  The number of the endpoint to read

	   bytes
	       Buffer into which to write the requested	data.

	   size
	       Max size	to read	into the buffer.

	   timeout
	       Maximum time to wait (in	milliseconds)

	   The function	returns	the number of bytes returned or	<0 on error.

       bulk_write
	   Perform a bulk write	request	to the specified endpoint.

	   ep  The number of the endpoint to write

	   bytes
	       Buffer from which to write the requested	data.

	   timeout
	       Maximum time to wait (in	milliseconds)

	   The function	returns	the number of bytes written or <0 on error.

       interrupt_write
	   Perform a interrupt write request to	the specified endpoint.

	   ep  The number of the endpoint to write

	   bytes
	       Buffer from which to write the requested	data.

	   timeout
	       Maximum time to wait (in	milliseconds)

	   The function	returns	the number of bytes written or <0 on error.

       get_driver_np
	   This	function returns the name of the driver	bound to the interface
	   specified by	the parameter interface.

	   $interface
	       The interface number of interest.

	   Returns "undef" on error.

       detach_kernel_driver_np
	   This	function will detach a kernel driver from the interface
	   specified by	parameter interface. Applications using	libusb can
	   then	try claiming the interface. Returns 0 on success or < 0	on
	   error.

DIAGNOSTICS
       This is an explanation of the diagnostic	and error messages this	module
       can generate.

       Cannot open device: reason string
	   Unable to open the USB device for the reason	given.

DEPENDENCIES
       This module depends on the Carp,	Inline and Inline::C modules, as well
       as the strict and warnings pragmas. Obviously, libusb must be available
       since that is the entire	reason for the module's	existence.

AUTHOR
       G. Wade Johnson (wade at	anomaly	dot org) Paul Archer (paul at
       paularcher dot org)

       Houston Perl Mongers Group

BUGS
       Please report any bugs or feature requests to
       "bug-device-usb@rt.cpan.org", or	through	the web	interface at
       <http://rt.cpan.org/NoAuth/ReportBug.html?Device::USB>.	I will be
       notified, and then you'll automatically be notified of progress on your
       bug as I	make changes.

ACKNOWLEDGEMENTS
       Thanks go to various members of the Houston Perl	Mongers	group for
       input on	the module. But	thanks mostly go to Paul Archer	who proposed
       the project and helped with the development.

COPYRIGHT & LICENSE
       Copyright 2006 Houston Perl Mongers

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.32.1			  2009-04-02		Device::USB::Device(3)

Device::USB::Device | NAME | VERSION | SYNOPSIS | DESCRIPTION | DIAGNOSTICS | DEPENDENCIES | AUTHOR | BUGS | ACKNOWLEDGEMENTS | COPYRIGHT & LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Device::USB::Device&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help