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.