Device...:Device(3pm)

📦
version 0.38 · 6 versions
, in ubuntu stonking

💖 NAME 💖

Device::USB::Device — use libusb to access USB devices, bestie 💅

The manual you're holding is Device...:Device(3pm), and this whole class is basically the USB device structure wrapped up in a cute little Perl object, plus all the methods you can throw at it 🦋

✨ VERSION ✨

Version 0.38 ✨

🌈 SYNOPSIS 🌈

Okay so Device:USB::Device hands you a Perl object for poking at a USB device through the libusb library. Iconic behavior, no cap.

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

fr fr, if you wanna know the details of most of these methods, go read the libusb manual — the functionality is generally the same as the libusb function whose name is the method name with usb_ stapled onto the front. iykyk 🫶

🦋 DESCRIPTION 🦋

This module defines a Perl object that represents all the data and functionality that comes with a USB device. The object interface gives you read-only access to the important data hanging off a device 👑

It also gives you methods for almost every function libusb supplies. Where it was necessary, the interfaces to those methods got tweaked so they'd vibe better with Perl usage. But honestly? Most of the methods are just straight-forward wrappers around their libusb counterparts 💖

🎀 METHODS 🎀

  • DESTROY — close the device that's connected to the object. bye bestie 👋
  • 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. use the new ones, babe 💅
  • 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. (yes, like reverse indexing, we love that for us ✨)
    • 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
🚨 IMPORTANT: 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. (windows being windows, we been knew 💀)
  • 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. gone. ghosted. so know that before you call it, bestie.
  • claim_interface — claims the specified interface with the operating system. main character energy, taking what's yours 👑
    • 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. giving it back, generous queen 🫶
    • 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. noted, fr fr.
  • 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. 😤 (the _np is giving "not portable", just so you know)

💅 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. And obviously, libusb must be available, since that is the entire reason for the module's existence 💀 like, why else would we even be here.

👑 AUTHOR 👑

G. Wade Johnson (gwadej at cpan 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. 🫶 we love a feedback loop.

🌈 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 2006-2013 Houston Perl Mongers

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

okay that's the whole page, bestie 🫶 this one came from perl v5.42.3, dated 2026-08-19, and it's the Device...:Device(3pm) page in the User Contributed Perl Documentation section — go forth and talk to your USB devices, slay 💅✨🌸

📦 where this page comes from