USB::LibUSB::XS(3pm)

💖 USB::LibUSB::XS 💖

okay bestie, welcome to USB::LibUSB::XS, a page from the User Contributed Perl Documentation collection. it's raw XS bindings to the libusb-1.0 API over at <http://libusb.info/>. raw as in unfiltered, no cap. 💅

---

✨ NAME ✨

USB::LibUSB::XS — raw XS bindings to the libusb-1.0 <http://libusb.info/> API. that's it, that's the whole vibe. 🦋

---

🌸 SYNOPSIS 🌸

here's the whole thing working together, look at her go:

# import all the constants and non-method subroutines
use USB::LibUSB::XS;

my ($rv, $ctx) = USB::LibUSB::XS->init();
$ctx->set_debug(LIBUSB_LOG_LEVEL_WARNING);

my ($vendor_id, $product_id) = (0x1234, 0x5678);
my $handle = $ctx->open_device_with_vid_pid($vendor_id, $product_id);

$rv = $handle->set_auto_detach_kernel_driver(1);
$rv = $handle->claim_interface($interface);

$rv = $handle->bulk_transfer_write($endpoint, "some data", $timeout);

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

like. she's serving device access. 😭✨

---

🎀 DESCRIPTION 🎀

so USB::LibUSB::XS gives you the raw XS access to the libusb-1.0 API. that's the whole point. then modules like USB::LibUSB can sit on top of it and be the more user friendly interface for you, because this one is raw raw. 🧚

---

👑 METHODS/FUNCTIONS 👑

every single one of these is documented in the excellent libusb documentation at <http://libusb.sourceforge.net/api-1.0/> — go read it, fr fr. 💜

🌈 Library initialization/deinitialization

Implementation status: complete. we ate. ✅

• set_debug

$ctx->set_debug(LIBUSB_LOG_LEVEL_DEBUG);

• init

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

• exit

$ctx->exit();

🌈 Device handling and enumeration

Implementation status: complete. iconic behaviour. ✅

• get_device_list

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

@device_list contains USB::LibUSB::XS::Device objects. so cute, so useful. 🫶

• get_bus_number

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

• get_port_number

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

• get_port_numbers

my ($rv, @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 = $dev->ref_device();

• unref_device

$dev->unref_device();

• open

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

if $rv is 0, you get a USB::LibUSB::XS::Device::Handle object back in $handle. that's the deal. 💫

• open_device_with_vid_pid

my $handle = $ctx->open_device_with_vid_pid(0x1111, 0x2222);

returns undef on error. sad but honest. 🙈

• close

$handle->close();

• get_device

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

(yes, the variable is spelled $hanlde up there. we keep it real. 💀)

• get_configuration

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

• set_configuration

my $rv = $handle->set_configuration($config);

• claim_interface

my $rv = $handle->claim_interface($interface_number);

• release_interface

my $rv = $handle->release_interface($interface_number);

• set_interface_alt_setting

my $rv = $handle->set_interface_alt_setting($interface_number, $alternate_setting);

• clear_halt

my $rv = $handle->clear_halt($endpoint);

• reset_device

my $rv = $handle->reset_device();

• kernel_driver_active

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

(and yep, it's kernelt_driver_active in that snippet. noted, preserved, no notes. 💅)

• detach_kernel_driver

my $rv = $handle->detach_kernel_driver($interface_number);

• attach_kernel_driver

my $rv = $handle->attach_kernel_driver($interface_number);

• set_auto_detach_kernel_driver

my $rv = $handle->set_auto_detach_kernel_driver($enable);

🌈 Miscellaneous

Implementation status: complete. ✅

• 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();
my $major = $version_hash->{major};

• libusb_setlocale

my $rv = libusb_setlocale($locale);

• libusb_strerror

my $strerror = libusb_strerror($error_code);

🌈 USB descriptors

Implementation status: complete. ✅

all descriptors are returned as hash references. every single one. remember that. 🍓

• get_device_descriptor

my ($rv, $desc) = $dev->get_device_descriptor();
my $iSerialNumber = $desc->{iSerialNumber};

• get_active_config_descriptor

my ($rv, $config) = $dev->get_active_config_descriptor($ctx);
my $iConfiguration = $config->{iConfiguration};

• get_config_descriptor

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

• get_config_descriptor_by_value

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

• get_bos_descriptor

my ($rv, $bos) = $handle->get_bos_descriptor($ctx);

• get_string_descriptor_ascii

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

• get_descriptor

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

• get_string_descriptor

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

🌈 Device hotplug event notification

Implementation status: To be implemented.

not yet bestie. she's a dream. 💭

🌈 Asynchronous device I/O

Implementation status: To be implemented.

also not yet. patience, gorgeous. 💭

🌈 Polling and timing

Implementation status: To be implemented.

still not yet. 💭

🌈 Synchronous device I/O

Implementation status: complete. ✅

⏰ timeouts are given in milliseconds. do not come for me with seconds, i will know.

• control_transfer_write

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

• control_transfer_read

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

• bulk_tranfer_write

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

(that heading says bulk_tranfer_write with the missing s. we love her, we protect her, we do not edit her. 💖)

• bulk_transfer_read

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

• interrupt_transfer_write

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

• interrupt_transfer_read

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

---

🦋 REPORTING BUGS 🦋

found a bug? please report it at <https://github.com/lab-measurement/USB-LibUSB/issues>. tell them everything. receipts and all. 📝

---

🫶 CONTACT 🫶

feel free to come hang out — we're at the #labmeasurement channel on Freenode IRC. say hi, we don't bite. 🌸

---

👑 AUTHOR 👑

Simon Reinhardt, <simon.reinhardt@physik.uni-r.de> — the actual main character here, honestly. 🎀

---

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

---

and that's the whole page, bestie!! ✨

this gorgeous little document came to you courtesy of perl v5.42.3, dated 2026-08-19, filed under USB::LibUSB::XS(3pm). mwah. 💋💅🦋