hidapi info structure from C
The hidapi device info structure provided to Perl 6 callers
sub hid_exit() returns int32Initialize the HIDAPI library.
sub hid_enumerate(
uint16 $vendor-id,
uint16 $product-id
) returns NativeCall::Types::Pointer[Device::HIDAPI::InternalDeviceInfo]Enumerate the HID Devices
sub hid_free_enumeration(
NativeCall::Types::Pointer[Device::HIDAPI::InternalDeviceInfo] $devs
) returns MuFree an enumeration Linked List
sub hid_open(
uint16 $vendor-id,
uint16 $product-id,
Str $serial-number
) returns Device::HIDAPIOpen a HID device using a Vendor ID (VID, Product ID (PID) and optionally a serial number.
sub hid_open_path(
Str $path
) returns Device::HIDAPIOpen a HID device by its path name.
sub hid_write(
Device::HIDAPI $dev,
NativeCall::Types::CArray[uint8] $data,
NativeCall::Types::size_t $length
) returns int32Write an Output report to a HID device.
sub hid_read_timeout(
Device::HIDAPI $dev,
NativeCall::Types::CArray[uint8] $data,
NativeCall::Types::size_t $length,
uint32 $milliseconds
) returns int32Read an Input report from a HID device with timeout.
sub hid_read(
Device::HIDAPI $dev,
NativeCall::Types::CArray[uint8] $data,
NativeCall::Types::size_t $length
) returns int32Read an Input report from a HID device.
sub hid_set_nonblocking(
Device::HIDAPI $dev,
int32 $nonblock
) returns int32Set the device handle to be non-blocking.
sub hid_send_feature_report(
Device::HIDAPI $dev,
NativeCall::Types::CArray[uint8] $data,
NativeCall::Types::size_t $length
) returns int32Send a Feature report to the device.
sub hid_get_feature_report(
Device::HIDAPI $dev,
NativeCall::Types::CArray[uint8] $data,
NativeCall::Types::size_t $length
) returns int32Get a feature report from a HID device.
sub hid_close(
Device::HIDAPI $dev
) returns MuClose a HID device.
sub hid_get_manufacturer_string(
Device::HIDAPI $dev,
NativeCall::Types::CArray[int32] $string,
NativeCall::Types::size_t $maxlen
) returns int32Get The Manufacturer String from a HID device.
sub hid_get_product_string(
Device::HIDAPI $dev,
NativeCall::Types::CArray[int32] $string,
NativeCall::Types::size_t $maxlen
) returns int32Get The Product String from a HID device.
sub hid_get_serial_number_string(
Device::HIDAPI $dev,
NativeCall::Types::CArray[int32] $string,
NativeCall::Types::size_t $maxlen
) returns int32Get The Serial Number String from a HID device.
sub hid_get_indexed_string(
Device::HIDAPI $dev,
int32 $string-index,
NativeCall::Types::CArray[int32] $string,
NativeCall::Types::size_t $maxlen
) returns int32Get a string from a HID device, based on its string index.
sub hid_error(
Device::HIDAPI $dev
) returns StrGet a string describing the last error which occurred.
Device::HIDAPI - low-level HID interface
use Device::HIDAPI;
# Read the raw inputs from an XBox One controller
sub MAIN(Str $path) {
# $path is the device path
my $hid = Device::HIDAPI.new($path);
loop {
my $data = $dev.read;
# Read the positions of the left stick
my $lsx = $data.read-int16(6);
my $lsy = $data.read-int16(8);
say "$lsx, $lsy";
}
}
If you need to perform low-level interfacing with a HID (device implementing the Human Interface Device protocol), this library is for you. It depends on a C library named hidapi, which you can get from the libusb project (see INSTALLATION for details).
This is a low-level library, so if you want to interface with a keyboard, mouse, joystick or other standard equipment, there's probably a better way. However, if you have a HID that implements a custom protocol or you need to get to the raw device data for some reason, this library will get you there. It provides a binary interface to read and write data to HIDs.
This class is the primary interface for enumerating devices, All the methods defined under METHODS below belong to this class.
This is a special compile-time generated class that configures the library to use. You should never need to do anythign with this yourself.
Objects of this type are returned by the device enumeration method. It provides the following read-only attributes about each device:
Pod::Defn<140187063716320>
Pod::Defn<140187063716264>
Pod::Defn<140187063716208>
Pod::Defn<140187063716096>
Pod::Defn<140187071420720>
Pod::Defn<140187071420664>
Pod::Defn<140187071420608>
Pod::Defn<140187071420552>
Pod::Defn<140187071420496>
Pod::Defn<140187071420440>
This is the exception object used whenever a wrapped hidapi function returns an error. It provides two attributes:
Pod::Defn<140187071420272>
Pod::Defn<140187071420216>
method enumerate(Device::HIDAPI:_:
UInt $vendor-id = 0,
UInt $product-id = 0,
--> Seq
)
This method is used to enumerate the devices known to the system.
# list all the VIDs and PIDs
for Device::HIDAPI.enumerate -> $dev {
say "$dev.vendor-id():$dev.product-id() "
~ "- $dev.manufacturer-string(): "
~ "$dev.product-string()";
}
The $vendor-id and $product-id can be set to specific numbers to list only devices matching those IDs. A value of 0 (the default) matches all IDs (i.e., list all).
multi method new(Device::HIDAPI:U:
UInt :$vendor-id!,
UInt :$product-id!,
Str :$serial-number,
--> Device::HIDAPI:D
)
multi method new(Device::HIDAPI:U:
Str:D :$path!
--> Device::HIDAPI:D
)
These constructors return an instance of Device::HIDAPI, which can be used to read from and write to the device. You may construct the object either using the $vendor-id and the $product-id or the $path to the device. It is possible to have multiple of the same device connected, in which case you may also want to provide the $serial-number when using the VID and PID.
method write(Device::HIDAPI:D: blob8 $data --> UInt:D)
Writes the given blob to the device. Returns the number of bytes actually written.
method read-timeout(Device::HIDAPI:D: UInt:D $millis --> blob8:D)
Reads data from the device or fails with an exception. If the device does not return anything within $millis milliseconds it returns an empty Blob.
Throws an exception if there's an error during the read.
method read(Device::HIDAPI:D: --> blob8:D)
Reads data from the device. Unless the object has been set to use non-blocking operations, this operation will block until data becomes available. If non-blocking has been set, then this will return data if any is waiting or return an empty Blob immediately if none is currently ready to read.
Throws an exception if there's an error during the read.
method set-nonblocking(Device::HIDAPI:D: Bool:D $nonblock)
Sets the device as non-blocking or not based on the value of $nonblock. If the object is set to non-blocking, then calls to [/method read](/method read) will not block.
May throw an exception if an error occurs making a change to the device object.
method send-feature-report(Device::HIDAPI:D: blob8 $data --> UInt:D)
Sends a feature rreport to the device. Returns the number of bytes written.
Throws an exception if there is an error performing the write.
method get-feature-report(Device::HIDAPI:D: --> blob8:D)
Retrieve a feature report from the device.
Throws an exception if there is an error performing the read.
method close(Device::HIDAPI:D:)
Closes the device and frees up associated resources. You should call this manually after creating the object if you want to make sure resources are freed before the garbage collector gets around to freeing memory:
# You can make calling this automatic when the variable goes out of scope
# like this...
my Device::HIDAPI:D $dev is leave({ .close }) .= new($path);
Throws an error if there is a problem releasing the object.
method get-manufacturer-string(Device::HIDAPI:D: --> Str:D)
Retrieves the manufacturer string from the device.
Throws an error if there's a problem getting the data from the device.
method get-product-string(Device::HIDAPI:D: --> Str:D)
Retrieves the product string from the device.
Throws an error if there's a problem getting the data from the device.
method get-serial-number-string(Device::HIDAPI:D: --> Str:D)
Retrieves the serial number string from the device.
Throws an error if there's a problem getting the data from the device.
method get-indexed-string(Device::HIDAPI:D: Int:D: $index --> Str)
Given an index, returns the indexed string from the device.
Throws an error if there's a problem getting the data from the device.
All exceptions generated by the wrapped hidapi library will be thrown using the X::Device::HIDAPI class. The error string set by the hidapi library can be found in the hid-error attribute (which may be undefined in certain cases, which will show up as "unknown error" in the exception message). The where attribute on the exception will name the hidapi function that was called that caused the error.
If you want more detail regarding how each of the methods in this interface work. You should see the documentation of the wrapped library here:
The methods of this interface all map into functions in the original C library with one-to-one correspondance. It should be clear which methods call which function.
To install this library, you will first need to install the C library. See the latest instructions at the hidapi project page here:
If you install a pre-packaged binary, make sure it's a development package that includes all the headers as well as the libraries (on Debian-type Linuxes, this means the package iwth the -dev suffix).
Once installed, this can be installed like any other Perl 6 module:
zef install Device::HIDAPI
That should work on Linux, Mac, and Windows.