Java libusb / libusb-win32 wrapper

Java libusb / libusb-win32 wrapper

Overview

Java libusb wrapper is a Java wrapper for the libsub and libusb-win32 USB library.

• libusb aim is to create a library for use by user level applications to access USB devices regardless of OS.

• libusb-win32 is a port of the libusb library to the Windows operating systems. The library allows user space applications to access any USB device on Windows in a generic way without writing any line of kernel driver code.

 

The Java libusb wrapper is known to work on Linux and Windows, but should work on every operating system which supports libusb and Java.

Implementation

Java libusb wrapper provides the necessary shared libraries and Java classes to access libusb/libusb-win32 trough the Java Native Interface. The class ch.ntb.usb.LibusbJava loads the shared library and provides the native interface to access libusb.

In libusb, the bus structure (with devices, configurations, interfaces and endpoints) is represented in C structs. For each struct, a Java object is created (named Usb_xxx) and the information is copied to this object. This is done when calling LibusbJava.usb_get_busses(). The information about busses and attached devices can now be obtained from a tree like Java Object structure.

It provides a simple Device class which represents a USB device and makes it easy to write to and read from it. Errors and Timeouts will result in Exceptions.

Note that the library is still BETA! It is used in two of our own applications (Programming and Debugging Interface (Cypress FX2) and Experimental Board (AVR AT90USB1287)) which are using bulk transfers. Interrupt transfers are working with a test device as well.

Demo Applications

UsbView

UsbView provides a tree view of the current USB bus. It shows the parameters of the different descriptors including the string descriptors. UsbView is based on Swing and does therefore only need the standard java libraries.

If you right-click on an interface descriptor you can start „USB TestApp“ based on the values of this device and descriptors.

USB TestApp

This simple USB test application allows to write and read bulk or interrupt data to a device. It may be started by „UsbView“ or by its own main method.

Examples

The first example (LogBus) uses the libusb share library directly to initialize libusb, get an object tree which represents the bus with associated devices and descriptors and print it to standard out.

The second example (ReadWrite) demonstrates how to get a device instance, read from and write to the device using the ch.ntb.usb.Device class. This class hides libusb specific methods and implements exceptions in case of error.

API

An online version of the Java API can be found here.

Installation

Windows

Manual Installation

Install libusb-win32 and test your installation using the testlibusb-win.exe test program included in the libusb-win32 distribution. To make libusb-win32 recognize your device you must install a custom device driver (inf-file) for your device (see „Device Installation“ ).

Download the jar-file and Dll from the „Binaries and Source“ section.

Inf USB Library Installer

A second approach is to use the installer which will install the USB library (see „Download and Installation“ ) for our own devices. It includes the libusb-win32 files, the dll for the Java wrapper and three device drivers for the devices we are using.

The installer basically performs the following steps:

• installs libusb-win32 (CVS build 20060920)

  • copies libusb0.dll to windows\system32\

  • copies libusb0.sys to windows\system32\drivers\

• installs the Java wrapper dll

  • copies LibusbJava.dll to windows\system32\

• installs 3 device drivers (.inf-files) for our USB devices

• creates an uninstaller and a driver folder in the install location which contains the inf-files and dlls

 

There will be a notification at the beginning about whether you want setup to change your path. You can cancel that, as you won't need it.

Device Installation

As mentioned above, to use libusb-win32 you need to install a device driver for your device. There are two ways to create such a file.

A programm called inf-wizard.exe is included in the binary distribution of libusb-win32. It will create a device driver with the device information you provide. When Windows asks for the driver for your USB device, point it to your inf-file. This will install all the necessary files and the service needed for libusb to work. It will NOT install LibusbJava.dll (see the next section).

The second approach is to adapt an existing inf-file from the <INSTALLDIR>/driver/ folder which is created by the Inf USB Library Installer. You need to change the vendor and product id in the [Devices] section. For a vendor id of 0x1234 and a product id of 0x6789 it will look like this: "My Devicename"=LIBUSB_DEV, USB\VID_1234&PID_6789. This will install all libusb files and also LibusbJava.dll to the Windows\System32 directory.

To verify successful installation you can use the testlibusb-win.exe of the libusb-win32 distribution or the UsbView Program. The devices will also show up in the Windows device manager:

 

Linux

Libusb needs to be installed and working. Make shure you have the proper permissions to access the devices (see this post). To build the source with the included build.xml file, Ant must be installed.

Get the source (see „Binaries and Source“ ) and execute

# ant linux

in the LibusbJava directory. This will build a shared library named libusbJava.so.x.x.x, where x.x.x is the current version number. Create a symbolic link to that library

# ln -s libusbJava.so.x.x.x libusbJava.so

Note that the library must be on the java.library.path (see this JNI-Howto for more information).

 

Binaries and Source

You can get the Java jar-file here. The shared library (Windows Dll) can be downloaded here.

The Java and C++ source code is available in a Subversion repository with anonymous read access at https://svn.ntb.ch/svninf/ch.ntb.usb/.

License

Java libusb-win32 wrapper is licensed under the GNU Lesser General Public License (LGPL). You will find licensing information about libusb-win32 on their page.

Feedback and Support

For any feedback or suggestions send a mail to Simon Pertschy .

Links

• libusb-win32, supported platforms: Win98SE, WinME, Win2k, WinXP

• libusb, supported platforms: Linux, FreeBSD, NetBSD, OpenBSD, Darwin, MacOS X

 Reference: http://inf.ntb.ch/infoportal/help/index.jsp?topic=/ch.ntb.infoportal/projects.html