« MonkeyBread Software … | Home | News from the MBS Xoj… »

Get started with HIDAPI classes in Xojo

If you have an USB device with HID protocol, you can easily use it from your Xojo application. Please check out the HIDAPIDeviceMBS class for macOS, Windows and Linux. With the recent 24.1 plugins, we upgraded the classes to work even better.

You may start with enumerating of available devices. This should find all the HID devices connected to your computer like various keyboards, mice, joysticks or whatever you connect. For Linux, you may need to use chmod with sudo to grant permissions to all applications to connect to the devices. On macOS and Windows, you may just freely connect to your device as long as no standard driver grabbed it.

Let's enumerate the devices and look for ours:

Dim DevicePath As String // find our device Const VendorID = 1234 Const ProductID = 2345 Dim d As HIDAPIDeviceInfoMBS = HIDAPIDeviceMBS.Enumerate While d <> Nil // go thru all enumerated devices System.DebugLog d.Path+", "+d.ManufacturerString+", "+d.ProductString+", "+d.InterfaceNumber.ToString If d.VendorID = VendorID and d.ProductID = ProductID Then // found it DevicePath = d.Path Exit End If d = d.NextDevice Wend

The HIDAPIDeviceInfoMBS class provides all the details on the device, so you know which device you have and you can show manufacturer name, the product string and the serial number.

Please note, that on Linux we may not be able to get the strings if we don't have sufficient permissions to access it. You may see a device, but not get details or connect. Make sure you grant permissions to your app for access or run the app as root. e.g. a rules file in /etc/udev/rules.d folder can define, that a certain device would get permissions for everyone to read and write:

SUBSYSTEMS=="usb", ATTRS{idVendor}=="1234", ATTRS{idProduct}=="2345", GROUP="users", MODE="0666"

Once you know which device to open, you can use the path to open it. Since you may have multiple devices, the path should make it unique on which of the devices you want to connect:

// open by path in case you have multiple and need to pick exactly one Dim device As HIDAPIDeviceMBS = HIDAPIDeviceMBS.OpenPath(DevicePath)

Alternatively you can of course skip all the above and try to connect to the first device matching the vendor and product IDs.

// or pick the first matching one by IDs Dim device As HIDAPIDeviceMBS = HIDAPIDeviceMBS.Open(VendorID, ProductID, "")

Once you got the connection, you can query various details. One of the thing you need to know is the package length for read and writing. This should be in the documentation of the device vendor or you may check the FeatureReportLength property for the report length.

// figure out some details Dim deviceInfo As HIDAPIDeviceInfoMBS = device.DeviceInfo Dim ManufacturerString As String = DeviceInfo.ManufacturerString Dim ProductString As String = DeviceInfo.ProductString Dim FeatureReportLength As Integer = device.FeatureReportLength

When you like to send a data package to the device, please allocate a matching MemoryBlock including a byte in the front for the report ID. Then you put in the data to send in the other bytes and call the Write method.

// now write something Dim buf As New MemoryBlock(36) buf.UInt8Value(0) = 0 // First byte is report number buf.UInt8Value(1) = 123 // some command ID Dim r As Integer = device.Write(buf)

Data arriving is collected in a buffer and you can regularly read it in a thread or timer to process data as it comes in.

// and read something, e.g. in a timer Dim Buffer As MemoryBlock = device.Read(32) if buffer <> nil then // we got something Dim command As Integer = buffer.Int8Value(0) End If Break

When done, you can call Close method or let the last reference go.

Enjoy the class and see if you can find an use for it. Especially if you code something for the Raspberry Pi, you can use the HIDAPIDeviceMBS class to connect to a device.

The biggest plugin in space...
18 03 24 - 10:56