Scroll to navigation

USB::LibUSB(3pm) User Contributed Perl Documentation USB::LibUSB(3pm)

NAME

USB::LibUSB - Perl interface to the libusb-1.0 API.

SYNOPSIS

 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);

DESCRIPTION

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.

Staying as close as possible to the libusb-1.0 API, this module 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.

INSTALLATION

Prerequisites

Linux/UNIX

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 <https://www.cygwin.com/> you need the pkg-config, libusb1.0-devel and libcrypt-devel packages.

Windows

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:

 > 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>).

Driver Installation

On Windows you need an additional driver to use a device with libusb. See the Windows <https://github.com/libusb/libusb/wiki/Windows> section in the libusb wiki.

Building USB::LibUSB

The rest of the installation can be done by a CPAN client like cpanm:

 $ cpanm USB::LibUSB

METHODS/FUNCTIONS

Library initialization/deinitialization

set_debug

 $ctx->set_debug(LIBUSB_LOG_LEVEL_DEBUG);

init

 my $ctx = USB::LibUSB->init();

exit

 $ctx->exit();

last_retval

 my $retval = $ctx->last_retval();

Get return value of last called libusb function.

Device handling and enumeration

get_device_list

 my @device_list = $ctx->get_device_list();

Returned elements are USB::LibUSB::Device objects.

get_bus_number

 my $bus_number = $dev->get_bus_number();

get_port_number

 my $port_number = $dev->get_port_number();

get_port_numbers

 my @port_numbers = $dev->get_port_numbers();

get_parent

 my $parent_dev = $dev->get_parent();

get_device_address

 my $address = $dev->get_device_address();

get_device_speed

 my $speed = $dev->get_device_speed();

get_max_packet_size

 my $size = $dev->get_max_packet_size($endpoint);

get_max_iso_packet_size

 my $size = $dev->get_max_iso_packet_size($endpoint);

ref_device

 $dev->ref_device();

unref_device

 $dev->unref_device();

open

 my $handle = $dev->open();

Return a USB::LibUSB::Device::Handle object.

open_device_with_vid_pid

 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.

open_device_with_vid_pid_unique

 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_serial

 my $handle = $ctx->open_device_with_vid_pid_serial(0x0957, 0x0607, "MY47000419");

Like "open_device_with_vid_pid", but also requires a serial number.

close

 $handle->close();

get_device

 my $dev = $handle->get_device();

get_configuration

 my $config = $handle->get_configuration();

set_configuration

 $handle->set_configuration($config);

claim_interface

 $handle->claim_interface($interface_number);

release_interface

 $handle->release_interface($interface_number);

set_interface_alt_setting

 $handle->set_interface_alt_setting($interface_number, $alternate_setting);

clear_halt

 $handle->clear_halt($endpoint);

reset_device

 $handle->reset_device();

kernel_driver_active

 my $is_active = $handle->kernelt_driver_active($interface_number);

detach_kernel_driver

 $handle->detach_kernel_driver($interface_number);

attach_kernel_driver

 $handle->attach_kernel_driver($interface_number);

set_auto_detach_kernel_driver

 $handle->set_auto_detach_kernel_driver($enable);

Throws exception on Windows and Darwin.

Miscellaneous

libusb_has_capability

 my $has_cap = libusb_has_capability($capability);

libusb_error_name

 my $error_name = libusb_error_name($error_code);

libusb_get_version

 my $version_hash = libusb_get_version();

Return hashref $version_hash with the following keys:

libusb_setlocale

 my $rv = libusb_setlocale($locale);

libusb_strerror

 my $strerror = libusb_strerror($error_code);

USB descriptors

All descriptors are returned as hash references.

get_device_descriptor

 my $desc = $dev->get_device_descriptor();

Return hashref $desc with the following keys

All keys hold a scalar value.

get_active_config_descriptor

 my $config = $dev->get_active_config_descriptor();

Return hashref $config with the following keys:

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:

Example

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

get_config_descriptor

 my $config = $dev->get_config_descriptor($config_index);

Return config descriptor as hashref.

get_config_descriptor_by_value

 my $config = $dev->get_config_descriptor_by_value($bConfigurationValue);

Return config descriptor as hashref.

get_bos_descriptor

 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:

Additional parsing of the capability data is performed if "bDevCapabilityType" has one of the following values:

The hashref will contain a key "usb_2_0_extension".
The hashref will contain a key "ss_usb_device_capability".
The hashref will contain a key "container_id".

Example

Dump $bos with YAML::XS:

 use YAML::XS;
 print Dump($bos);

For a Linux Foundation 3.0 root hub:

 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

get_string_descriptor_ascii

 my $data = $handle->get_string_descriptor_ascii($desc_index, $length);

get_descriptor

 my $data = $handle->get_descriptor($desc_type, $desc_index, $length);

get_string_descriptor

 my $data = $handle->get_string_descriptor($desc_index, $langid, $length);

Device hotplug event notification

To be implemented.

Asynchronous device I/O

To be implemented.

Polling and timing

To be implemented.

Synchronous device I/O

control_transfer_write

 $handle->control_transfer_write($bmRequestType, $bRequest, $wValue, $wIndex, $data, $timeout);

control_transfer_read

 my $data = $handle->control_transfer_read($bmRequestType, $bRequest, $wValue, $wIndex, $length, $timeout);

bulk_tranfer_write

 my $transferred = $handle->bulk_transfer_write($endpoint, $data, $timeout);

bulk_transfer_read

 my $data = $handle->bulk_transfer_read($endpoint, $length, $timeout);

interrupt_transfer_write

 my $transferred = $handle->interrupt_transfer_write($endpoint, $data, $timeout);

interrupt_transfer_read

 my $data = $handle->interrupt_transfer_read($endpoint, $length, $timeout);

REPORTING BUGS

Please report bugs at <https://github.com/lab-measurement/USB-LibUSB/issues>.

CONTACT

Feel free to contact us at the #labmeasurement channel on Freenode IRC.

AUTHOR

Simon Reinhardt, <simon.reinhardt@physik.uni-r.de>

COPYRIGHT AND LICENSE

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.

2020-11-09 perl v5.32.0