hidapi

class source.hidapi(vendorID, productID, nReadBuffer, nWriteBuffer)

Interface to the hidapi library

Notes

  • Developed from the hidapi available at http://www.signal11.us/oss/hidapi/.
  • Windows: hidapi.dll needed.
  • Mac: hidapi.dylib needed. In addition, Xcode has to be installed.
  • Linux: hidapi has to be compiled on host-system.
handle
vendorID

numeric – Vendor-ID of the USB device.

productID

numeric – Product-ID of the USB device.

nReadBuffer

numeric – Read-buffer size in bytes.

nWriteBuffer

numeric – Write-buffer size in bytes. Needs to be 1 Byte bigger than actual packet.

slib

string – Name of shared library file (without file extension). Defaults to ‘hidapi’.

sheader

string – Name of shared library header. Defaults to ‘hidapi.h’.

Example

hidHandle = hidapi(1684,0005,1024,1025); %|br|

close(hid)

Close the connection to a hid device.

Throws:
InvalidHandle: Handle to USB-device not valid

Notes

  • Gets called automatically when deleting the hidapi instance.
  1. Check if pointer is (unexpectedly) already invalidated
enumerate(hid, vendorID, productID)

Enumerates the info about the hid device with the given vendorID and productID and returns a string with the returned hid information.

Parameters:
  • vendorID (numeric) – Vendor-ID of the USB device in decimal.
  • productID (numeric) – Product-ID of the USB device in decimal.

Notes

  • Using a vendorID and productID of (0,0) will enumerate all connected hid devices.
  • MATLAB does not have the hid_device_infoPtr struct so some of the returned information will need to be resized and cast into uint8 or chars.

Enumerate the hid devices

error(hid)

Return the hid device error string if a function produced an error.

Throws:
InvalidHandle: Handle to USB-device not valid

Notes

  • This function must be called explicitly if you think an error was generated from the hid device.
  1. Check if pointer is (unexpectedly) already invalidated
exit(hid)

hidapi.exit Exit hidapi

hid.exit() exits the hidapi library.

Throws:
CommError: Error during communication with device

Notes:: - You should not have to call this function directly.

getHIDInfoString(hid, info)

Get the corresponding hid info from the hid device.

Throws:
CommError: Error during communication with device InvalidHandle: Handle to USB-device not valid

Notes

  • Info is the hid information string.

See also HIDAPI.GETMANUFACTURERSSTRING, HIDAPI.GETPRODUCTSTRING, HIDAPI.GETSERIALNUMBERSTRING.

Read buffer nReadBuffer length

getManufacturersString(hid)

Get manufacturers string from hid object using getHIDInfoString.

getProductString(hid)

Get product string from hid object using getProductString.

getSerialNumberString(hid)

Get serial number from hid object using getSerialNumberString.

init(hid)

Inits the hidapi library.

Throws:
CommError: Error during communication with device

Notes

  • This is called automatically in the library itself with the open function. You should not have to call this function directly.
open(hid)

Open a connection with a hid device

Throws:
CommError: Error during communication with device

Notes

  • Gets called automatically when creating an hidapi-object.
  • The pointer return value from this library call is always null so it is not possible to know if the open was successful.
  • The final parameter to the open hidapi library call has different types depending on OS. On windows it is uint16, on linux/mac int32.

Create a null pointer for the hid_open function (depends on OS)

read(hid)

Read from a hid device and returns the read bytes.

Throws:
CommError: Error during communication with device InvalidHandle: Handle to USB-device not valid

Notes

  • Will print an error if no data was read.

Read buffer of nReadBuffer length

read_timeout(hid, timeOut)

Read from a hid device with a timeout and return the read bytes.

Parameters:timeOut (numeric >= 0) – Milliseconds after which a timeout-error occurs if no packet could be read.
Throws:
CommError: Error during communication with device InvalidHandle: Handle to USB-device not valid

Read buffer of nReadBuffer length

setNonBlocking(hid, nonblock)

Set the non blocking flag on the hid device connection.

Parameters:nonblock (numeric in {0,1}) – 0 disables nonblocking, 1 enables nonblocking
Throws:
CommError: Error during communication with device InvalidHandle: Handle to USB-device not valid
  1. Check if pointer is (unexpectedly) already invalidated
write(hid, wmsg, reportID)

Write to a hid device.

Throws:
CommError: Error during communication with device InvalidHandle: Handle to USB-device not valid

Notes

  • Will print an error if there is a mismatch between the buffer size and the reported number of bytes written.

Append a 0 at the front for HID report ID