--- name: "USB::LibUSB" section: "3pm" platform: "linux" package: "libusb-libusb-perl" version: "0.09-3+b1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/USB::LibUSB" --- # USB::LibUSB(3pm) Perl interface to the libusb-1.0 API. ## 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 \ you need the pkg-config, libusb1.0-devel and libcrypt-devel packages. *Windows* On Windows you have to manually download the libusb binaries from \ 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 \). Driver Installation On Windows you need an additional driver to use a device with libusb. See the 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: - major - minor - micro - nano - rc *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 - bLength - bDescriptorType - bcdUSB - bDeviceClass - bDeviceSubClass - bDeviceProtocol - bMaxPacketSize0 - idVendor - idProduct - bcdDevice - iManufacturer - iProduct - iSerialNumber - bNumConfigurations All keys hold a scalar value. *get\_active\_config\_descriptor* ``` my $config = $dev->get_active_config_descriptor(); ``` Return hashref `$config` with the following keys: - bLength - bDescriptorType - wTotalLength - bNumInterfaces - bConfigurationValue - iConfiguration - bmAttributes - MaxPower - interface - extra 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: - bLength - bDescriptorType - bInterfaceNumber - bAlternateSetting - bNumEndpoints - bInterfaceClass - bInterfaceSubClass - bInterfaceProtocol - iInterface - endpoint - extra With the exception of **endpoint**, all values are scalars. **endpoint** holds an arrayref of endpoint descriptors. These are hashrefs with the following keys: - bLength - bDescriptorType - bEndpointAddress - bmAttributes - wMaxPacketSize - bInterval - bRefresh - bSynchAddress - extra 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: - bLength - bDescriptorType - bMaxBurst - bmAttributes - wBytesPerInterval 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: - bLength - bDescriptorType - wTotalLength - bNumDeviceCaps - dev\_capability `"dev_capability"` holds an arrayref of BOS Device Capability descriptors. They have the following keys: - bLength - bDescriptorType - bDevCapabilityType - dev\_capability\_data Additional parsing of the capability data is performed if `"bDevCapabilityType"` has one of the following values: - LIBUSB\_BT\_USB\_2\_0\_EXTENSION The hashref will contain a key `"usb_2_0_extension"`. - LIBUSB\_BT\_SS\_USB\_DEVICE\_CAPABILITY The hashref will contain a key `"ss_usb_device_capability"`. - LIBUSB\_BT\_CONTAINER\_ID 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 \. ## CONTACT Feel free to contact us at the #labmeasurement channel on Freenode IRC. ## AUTHOR Simon Reinhardt, \ ## 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.