USB::LibUSB - Perl interface to the libusb-1.0 API.
use USB::LibUSB; # # simple program to list all devices on the USB # my $ctx = USB::LibUSB->init(); my @devices = $ctx->get_device_list(); for my $dev (@devices) { my $bus_number = $dev->get_bus_number(); my $device_address = $dev->get_device_address(); my $desc = $dev->get_device_descriptor(); my $idVendor = $desc->{idVendor}; my $idProduct = $desc->{idProduct}; printf("Bus %03d Device %03d: ID %04x:%04x\n", $bus_number, $device_address, $idVendor, $idProduct); } # # Synchronous bulk transfers # my $ctx = USB::LibUSB->init(); my $handle = $ctx->open_device_with_vid_pid(0x1111, 0x2222); $handle->set_auto_detach_kernel_driver(1); # Linux only # We want to use interface 0 $handle->claim_interface(0); $handle->bulk_transfer_write($endpoint, $data, $timeout); my $data = $handle->bulk_transfer_read($endpoint, $length, $timeout);
This module provides a Perl interface to the libusb-1.0 API. It provides access to most basic libusb functionality including read-out of device descriptors and synchronous device I/O.
The design of the module is basically a two-tier system:
Raw XS interface, stay as close at possible to the libusb API. Not intended to be used directly.
Based on USB::LibUSB::XS, adds convenient error handling and additional high-level functionality (e.g. device discovery with vid, pid and serial number). Easy to build more functionality without knowing about XS.
This requires libusb (>= 1.0.17) development files and pkg-config installed.
On Debian like Linux:
$ apt-get install libusb-1.0-0-dev pkg-config
On Cygwin you need the pkg-config, libusb1.0-devel and libcrypt-devel packages.
On Windows you have to manually download the libusb binaries from http://libusb.info and extract them somewhere.
Assuming that the location of the extracted libusb folder is C:\Users\simon\libusb-1.0, you need to set the USB_LIBUSB_INCLUDE and USB_LIBUSB_LIB environment variables as follows:
USB_LIBUSB_INCLUDE
USB_LIBUSB_LIB
> SET USB_LIBUSB_INCLUDE=-IC:\Users\simon\libusb-1.0\include\libusb-1.0 > SET USB_LIBUSB_LIB=-lC:\Users\simon\libusb-1.0\MinGW64\dll\libusb-1.0.dll.a
You will also need to add
C:\Users\simon\libusb-1.0\MinGW64\dll
to the Path environment variable.
For StrawberryPerl, version 5.26 or newer is required (see https://rt.cpan.org/Public/Bug/Display.html?id=121219).
On Windows you need an additional driver to use a device with libusb. See the Windows section in the libusb wiki.
The rest of the installation can be done by a CPAN client like cpanm:
$ cpanm USB::LibUSB
$ctx->set_debug(LIBUSB_LOG_LEVEL_DEBUG);
my $ctx = USB::LibUSB->init();
$ctx->exit();
my $retval = $ctx->last_retval();
Get return value of last called libusb function.
my @device_list = $ctx->get_device_list();
Returned elements are USB::LibUSB::Device objects.
my $bus_number = $dev->get_bus_number();
my $port_number = $dev->get_port_number();
my @port_numbers = $dev->get_port_numbers();
my $parent_dev = $dev->get_parent();
my $address = $dev->get_device_address();
my $speed = $dev->get_device_speed();
my $size = $dev->get_max_packet_size($endpoint);
my $size = $dev->get_max_iso_packet_size($endpoint);
$dev->ref_device();
$dev->unref_device();
my $handle = $dev->open();
Return a USB::LibUSB::Device::Handle object.
my $handle = $ctx->open_device_with_vid_pid(0x1111, 0x2222);
Return a USB::LibUSB::Device::Handle object. If the vid:pid combination is not unique, return the first device which is found.
my $handle = $ctx->open_device_with_vid_pid_unique(0x1111, 0x2222);
Like open_device_with_vid_pid, but croak in case of multiple devices with this vid:pid combination.
open_device_with_vid_pid
my $handle = $ctx->open_device_with_vid_pid_serial(0x0957, 0x0607, "MY47000419");
Like open_device_with_vid_pid, but also requires a serial number.
$handle->close();
my $dev = $handle->get_device();
my $config = $handle->get_configuration();
$handle->set_configuration($config);
$handle->claim_interface($interface_number);
$handle->release_interface($interface_number);
$handle->set_interface_alt_setting($interface_number, $alternate_setting);
$handle->clear_halt($endpoint);
$handle->reset_device();
my $is_active = $handle->kernelt_driver_active($interface_number);
$handle->detach_kernel_driver($interface_number);
$handle->attach_kernel_driver($interface_number);
$handle->set_auto_detach_kernel_driver($enable);
Throws exception on Windows and Darwin.
my $has_cap = libusb_has_capability($capability);
my $error_name = libusb_error_name($error_code);
my $version_hash = libusb_get_version();
Return hashref $version_hash with the following keys:
$version_hash
my $rv = libusb_setlocale($locale);
my $strerror = libusb_strerror($error_code);
All descriptors are returned as hash references.
my $desc = $dev->get_device_descriptor();
Return hashref $desc with the following keys
$desc
All keys hold a scalar value.
my $config = $dev->get_active_config_descriptor();
Return hashref $config with the following keys:
$config
With the exception of interface, all values are scalars. interface holds an arrayref of bNumInterfaces interface descriptors. Each interface consists of an array of alternate settings. These are hashrefs with the following keys:
With the exception of endpoint, all values are scalars. endpoint holds an arrayref of endpoint descriptors. These are hashrefs with the following keys:
All values are scalars. If the endpoint supports USB 3.0 SuperSpeed, the hashref will contain an additional key superspeed which holds a SuperSpeed Endpoint Companion descriptor with the following keys:
superspeed
Dump $config with YAML::XS:
use YAML::XS; print Dump($config);
For a Linux Foundation 3.0 root hub:
--- MaxPower: 0 bConfigurationValue: 1 bDescriptorType: 2 bLength: 9 bNumInterfaces: 1 bmAttributes: 224 extra: ~ iConfiguration: 0 interface: - - bAlternateSetting: 0 bDescriptorType: 4 bInterfaceClass: 9 bInterfaceNumber: 0 bInterfaceProtocol: 0 bInterfaceSubClass: 0 bLength: 9 bNumEndpoints: 1 endpoint: - bDescriptorType: 5 bEndpointAddress: 129 bInterval: 12 bLength: 7 bRefresh: 0 bSynchAddress: 0 bmAttributes: 3 extra: "\x060\0\0\x02\0" ss_endpoint_companion: bDescriptorType: 48 bLength: 6 bMaxBurst: 0 bmAttributes: 0 wBytesPerInterval: 2 wMaxPacketSize: 4 extra: ~ iInterface: 0 wTotalLength: 31
my $config = $dev->get_config_descriptor($config_index);
Return config descriptor as hashref.
my $config = $dev->get_config_descriptor_by_value($bConfigurationValue);
my $bos = $handle->get_bos_descriptor();
Return BOS descriptor as hashref with the following keys:
dev_capability holds an arrayref of BOS Device Capability descriptors. They have the following keys:
dev_capability
Additional parsing of the capability data is performed if bDevCapabilityType has one of the following values:
bDevCapabilityType
The hashref will contain a key usb_2_0_extension.
usb_2_0_extension
The hashref will contain a key ss_usb_device_capability.
ss_usb_device_capability
The hashref will contain a key container_id.
container_id
Dump $bos with YAML::XS:
$bos
use YAML::XS; print Dump($bos);
bDescriptorType: 15 bLength: 5 bNumDeviceCaps: 1 dev_capability: - bDescriptorType: 16 bDevCapabilityType: 3 bLength: 10 dev_capability_data: "\x02\b\0\x03\0\0\0" ss_usb_device_capability: bDescriptorType: 16 bDevCapabilityType: 3 bFunctionalitySupport: 3 bLength: 10 bU1DevExitLat: 0 bU2DevExitLat: 0 bmAttributes: 2 wSpeedSupported: 8 wTotalLength: 15
my $data = $handle->get_string_descriptor_ascii($desc_index, $length);
my $data = $handle->get_descriptor($desc_type, $desc_index, $length);
my $data = $handle->get_string_descriptor($desc_index, $langid, $length);
To be implemented.
$handle->control_transfer_write($bmRequestType, $bRequest, $wValue, $wIndex, $data, $timeout);
my $data = $handle->control_transfer_read($bmRequestType, $bRequest, $wValue, $wIndex, $length, $timeout);
my $transferred = $handle->bulk_transfer_write($endpoint, $data, $timeout);
my $data = $handle->bulk_transfer_read($endpoint, $length, $timeout);
my $transferred = $handle->interrupt_transfer_write($endpoint, $data, $timeout);
my $data = $handle->interrupt_transfer_read($endpoint, $length, $timeout);
Please report bugs at https://github.com/lab-measurement/USB-LibUSB/issues.
Feel free to contact us at the #labmeasurement channel on Freenode IRC.
Simon Reinhardt, <simon.reinhardt@physik.uni-r.de>
Copyright (C) 2017 by Simon Reinhardt
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.24.0 or, at your option, any later version of Perl 5 you may have available.
To install USB::LibUSB, copy and paste the appropriate command in to your terminal.
cpanm
cpanm USB::LibUSB
CPAN shell
perl -MCPAN -e shell install USB::LibUSB
For more information on module installation, please visit the detailed CPAN module installation guide.