Project status

🌟 Summary

The hid4java project supports USB HID devices through a common API which is provided here under the MIT license. The API is very simple but provides great flexibility such as support for feature reports and blocking reads with timeouts. Attach/detach events are provided to allow applications to respond instantly to device availability.

Telegram group

If you want to discuss hid4java in general please use the Telegram chat. I can't guarantee an instant response but I'm usually active on Telegram during office hours in the GMT timezone.

👀 Remember to check the Wiki first before asking questions to avoid causing frustration!

Technologies

hidapi - Native USB HID library for multiple platforms
JNA - Removes the need for Java Native Interface (JNI) and greatly simplify the project
dockcross - Cross-compilation environments for multiple platforms to create hidapi libraries
Maven - Build environment for Java projects if you need to customise the library
Java 8+ - to remove dependencies on JVMs that have reached end of life

Maven dependency


<dependencies>

  <!-- hid4java for cross-platform HID USB -->
  <dependency>
    <groupId>org.hid4java</groupId>
    <artifactId>hid4java</artifactId>
    <version>0.8.0</version>
  </dependency>

</dependencies>

If you are developing and want the latest code, you'll need to reference release candidate artifacts deployed to the Maven Central snapshot repository. These are updated more frequently as part of wider user acceptance testing, but they are not considered stable enough for production use.

Add the following repositories section to your project's pom.xml if you're using Maven for your build process.

  <!-- Enable Maven Central snapshots repository -->
<repositories>
  <repository>
    <id>oss.sonatype.org-snapshot</id>
    <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    <releases>
      <enabled>false</enabled>
    </releases>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
</repositories>

Gradle dependency


repositories {
    mavenCentral()
}

dependencies {
    implementation('org.hid4java:hid4java')
}

🚀 Code example

Taken from UsbHidEnumerationExample which provides more details.

// Configure to use custom specification
HidServicesSpecification hidServicesSpecification = new HidServicesSpecification();

// Use the v0.7.0 manual start feature to get immediate attach events
hidServicesSpecification.setAutoStart(false);

// Get HID services using custom specification
HidServices hidServices = HidManager.getHidServices(hidServicesSpecification);
hidServices.addHidServicesListener(this);

// Manually start the services to get attachment event
hidServices.start();

// Provide a list of attached devices
for (HidDevice hidDevice : hidServices.getAttachedHidDevices()) {
  System.out.println(hidDevice);
}

⚙ Local build

If you're unfamiliar with Maven and git the wiki provides an easy guide to creating a development environment.

The project uses the standard Maven build process and can be used without having external hardware attached. Just do the usual

cd <workspace>
git clone https://github.com/gary-rowe/hid4java.git
cd hid4java

# Maven build
mvn clean install

and you're good to go.

Maven will place the built JAR into the target directory. The Maven install process will also place copies of the built JARs into ~/.m2/repository/org/hid4java/hid4java/<version>/ so that other local projects can find and share them.

🤔 More information

Much of the information previously in this README has been migrated to the project Wiki as it was getting rather long. Here are some useful jumping off points that should help:

Home - The wiki Home page with lots of useful launch points
FAQ - Frequently asked questions
Examples - Using the examples to kickstart your own project
Troubleshooting - A comprehensive troubleshooting guide

📕 Closing notes

All trademarks and copyrights are acknowledged.

Many thanks to victorix who provided the basis for this library. Please see the inspiration on the mbed site.

Thanks also go to everyone who has contributed their knowledge and advice during the creation and subsequent improvement of this library.

gary-rowe / hid4java

readme