The developer's resource for computer interfacing, especially USB, serial (COM) ports, mass storage, and embedded networking. (Formerly Lvr.com)

Home > USB Central > USB OTG and Embedded Hosts > BeagleBoard Linux Code for Accessing USB Devices > Cross-compiling an application that uses hidapi

Cross-compiling a hidapi application for a USB embedded Linux host

Send comments, suggestions, etc. to jan (at) janaxelson.com.

The hidapi library provides a HID-specific API that can communicate with generic HID-class devices that perform vendor-defined functions. This article shows how to cross-compile a hidapi application for an embedded USB host system. For the development PC, I used an Ubuntu Linux system, and for the target system, I used a BeagleBoard-xM with Ubuntu.

The example application displays information about all installed HIDs, opens a handle to a HID with a specific Vendor ID and Product ID, and sends and receives Input, Output, and Feature reports.

Requirements

This is what you need to cross-compile and run the application.

Development system files

Download the hidapi files onto the development system with:

git clone https://github.com/signal11/hidapi.git

The files will be in the directory hidapi.

The Linux hidapi library provides two implementations. This example uses the libusb implementation, which is based on the libusb-1.0 library, which supports generic I/O with USB devices.

The development system must have (1) the libusb-1.0.so library compiled for the target architecture and (2) libusb.h. The Ångström toolchain provides these files. (Update: Beagleboard now uses Debian.)

Look for libusb-1.0.so in:

 /usr/local/angstrom/arm/arm-angstrom-linux-gnueabi/usr/lib/libusb-1.0

Look for libusb.h in:

 /usr/local/angstrom/arm/arm-angstrom-linux-gnueabi/usr/include/libusb-1.0
The device

The hidapi files include an example application, hidtest.cpp, which communicates with a device running the generic HID application included in Microchip's Application libraries. To communicate with my generic HID PIC firmware, use hidtest_jan.cpp instead of the provided hidtest.cpp file.

Cross-compiling

Below are basic instructions for cross-compiling hidtest. The instructions can serve as a template for compiling your own applications that use hidapi functions.

1. Copy hidtest.cpp and hid-libusb.c into your project’s directory.

hidtest.cpp is in:

 your_installation_directory/hidapi/hidtest/

where your_installation_directory is where you extracted the hidapi files to.

hid-libusb.c is in:

 your_installation_directory/hidapi/linux/

2. Copy hidapi.h into your project’s include directory (or the project's main directory).

hidapi.h is in:

 your_installation_directory/hidapi/hidapi/

3. Include the path to libusb.h.

See above for the file's location. If using an IDE such as Eclipse, add the path to the project’s Include paths. On a command line, use the -I switch to specify the path.

4. Compile hidtest.c and hid-libusb.c using the -lusb-1.0 option.

At a command line, use:

your_gcc_cross_compiler -I path_to_libusb.h hidtest.c hid-libusb.c 
-lusb-1.0 -o hidtest

where your_gcc_cross_compiler invokes the cross-compiler for your target system and path_to_libusb.h is the directory containing libusb.h.

For example:

arm-angstrom-linux-gnueabi-gcc 
-I/usr/local/angstrom/arm/arm-angstrom-linux-gnueabi/usr/include/libusb-1.0
hidtest.cpp hid-libusb.c -lusb-1.0 -o hidtest

Running the application

To test hidtest, copy the created hidtest binary file to the target USB host system and attach a device running the generic HID firmware described above. From the directory containing hidtest, enter:

 sudo ./hidtest

By default, applications that use the libusb-1.0 library require administrative privileges (sudo). To enable users to access a device via the libusb-1.0 library without administrative privileges, add a udev rule for the device. This rule specifies the USB device with Vendor ID = 0925h and Product ID = 7001h and sets the MODE parameter to grant read/write permissions for all users:

SUBSYSTEM=="usb", ATTR{idVendor}=="0925", ATTR{idProduct}=="7001",
MODE="0666"

The rule should be on one line in the file. (Press Enter only at the end.) Place the rule in a file with a .rules extension (such as 81-libusb.rules) and save the file in /etc/udev/rules.d. On the next device attachment or boot, users can run applications that use libusb-1.0 functions to read and write to the specified device.

Follow the same procedure to compile other hidapi applications you write, replacing hidtest.cpp with your own source file.