Merge branch 'jdk21'

# Conflicts:
#	.github/workflows/continuous-integration.yaml
#	java-does-usb/.mvn/wrapper/maven-wrapper.properties

Author: manuelbl

.github/workflows/continuous-integration.yaml

@@ -1,6 +1,15 @@
 name: Continuous Integration
 
-on: [push, pull_request]
+on:
+  push:
+    paths-ignore:
+      - "test-devices/**"
+      - "reference/**"
+  pull_request:
+    paths-ignore:
+      - "test-devices/**"
+      - "reference/**"
+
 
 env:
   MAVEN_ARGS: -B -V -ntp -e -Djansi.passthrough=true -Dstyle.color=always
@@ -20,29 +29,29 @@ jobs:
         uses: actions/setup-java@v3
         with:
           distribution: 'zulu'
-          java-version: '20'
+          java-version: '21'
           cache: 'maven'
-      - name: Configure GPG Key
+      - name: Configure GPG key
         run: |
           echo -n "$GPG_SIGNING_KEY" | base64 --decode | gpg --import
         env:
           GPG_SIGNING_KEY: ${{ secrets.GPG_SIGNING_KEY }}
         shell: bash
-      - name: Library
+      - name: Build java-does-usb
         run: ./mvnw $MAVEN_ARGS -DskipTests clean install javadoc:javadoc
         working-directory: ./java-does-usb
-      - name: Example bulk_transfer
+      - name: Example "bulk_transfer"
         run: ./mvnw $MAVEN_ARGS clean compile
         working-directory: ./examples/bulk_transfer
-      - name: Example enumerate
+      - name: Example "enumerate"
         run: ./mvnw $MAVEN_ARGS clean compile
         working-directory: ./examples/enumerate
-      - name: Example monitor
+      - name: Example "monitor"
         run: ./mvnw $MAVEN_ARGS clean compile
         working-directory: ./examples/monitor
-      - name: Example stm_dfu
+      - name: Example "stm_dfu"
         run: ./mvnw $MAVEN_ARGS clean compile
         working-directory: ./examples/stm_dfu
-      - name: Example epaper_display
+      - name: Example "epaper_display"
         run: ./mvnw $MAVEN_ARGS clean compile
         working-directory: ./examples/epaper_display

.github/workflows/test-devices.yaml

@@ -0,0 +1,37 @@
+name: Test Devices CI
+
+on:
+  push:
+    paths:
+      - "test-devices/**"
+      - ".github/**"
+  pull_request:
+    paths:
+      - "test-devices/**"
+      - ".github/**"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/cache@v3
+        with:
+          path: |
+            ~/.cache/pip
+            ~/.platformio/.cache
+          key: ${{ runner.os }}-pio
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.9'
+      - name: Install PlatformIO Core
+        run: pip install --upgrade platformio
+
+      - name: Build loopback firmware
+        run: pio run
+        working-directory: ./test-devices/loopback-stm32
+
+      - name: Build composite firmware
+        run: pio run
+        working-directory: ./test-devices/composite-stm32

README.md

@@ -4,9 +4,9 @@
 
 *Java Does USB* is a Java library for working with USB devices. It allows to query information about all conntected USB devices and to communicate with USB devices using custom / vendor specific protocols. (It is not intended for communication with standard types of USB devices such as mass storage devices, keyboards etc.)
 
-The library uses the [Foreign Function & Memory API](https://github.com/openjdk/panama-foreign) to access native APIs of the underlying operating system. It only uses Java code and does not need JNI or any native third-party library. The *Foreign Function & Memory API* (aka as project Panama) is in preview and will be introduced in a future Java version. Currently, it can be used with Java 19 or Java 20 (with preview features enabled).
+The library uses the [Foreign Function & Memory API](https://github.com/openjdk/panama-foreign) to access native APIs of the underlying operating system. It is written entirely in Java and does not need JNI or any native third-party library. The *Foreign Function & Memory API* (aka as project Panama) is currently in preview and will leave preview with Java 22. Currently, it can be used with Java 19, Java 20 or Java 21 (with preview features enabled).
 
-*Note: The main branch and published versions ≥ 0.5.0 work with JDK 20 only. For JDK 19, use version 0.4.x.*
+*Note: The main branch and published versions ≥ 0.6.0 work with JDK 21 only. For JDK 20, use version 0.5.*. For JDK 19, use version 0.4.x.
 
 
 ## Features
@@ -41,14 +41,14 @@ If you are using Maven, add the below dependency to your pom.xml:
 <dependency>
       <groupId>net.codecrete.usb</groupId>
       <artifactId>java-does-usb</artifactId>
-      <version>0.5.1</version>
+      <version>0.6.0</version>
 </dependency>
 ```
 
 If you are using Gradle, add the below dependency to your build.gradle file:
 
 ```groovy
-compile group: 'net.codecrete.usb', name: 'java-does-usb', version: '0.5.1'
+compile group: 'net.codecrete.usb', name: 'java-does-usb', version: '0.6.0'
 ```
 
 ```java
@@ -78,31 +78,32 @@ public class EnumerateDevices {
 - [Enumeration](examples/enumerate/) lists all connected USB devices and displays information about interfaces and endpoints.
 - [Monitor](examples/monitor/) lists the connected USB devices and then monitors for USB devices being connected and disconnnected.
 - [Device Firmware Upload (DFU) for STM32](examples/stm_dfu) uploads firmware to STM32 microcontrollers supporting the built-in DFU mode.
+- [ePaper Display](examples/epaper_display) communicates with an IT8951 controller for e-Paper displays and shows an image on the display.
 
 
 ## Prerequisite
 
-- Java 20, preview features enabled (available at https://www.azul.com/downloads/?package=jdk)
+- Java 21, preview features enabled (available at https://www.azul.com/downloads/?package=jdk)
 - Windows (x86 64-bit), macOS (x86 64-bit, ARM 64-bit) or Linux 64 bit (x86 64-bit, ARM 64-bit)
 
-For JDK 19, use the latest published version 0.4.x.
+For JDK 20, use the latest published version 0.5.x. For JDK 19, use the latest published version 0.4.x.
 
 
 ## Platform-specific Considerations
 
 
 ### macOS
 
-No special considerations apply. Using this library, a Java application can connect to any USB device and claim any interfaces that isn't claimed by an operating system driver or another application.
+No special considerations apply. Using this library, a Java application can connect to any USB device and claim any interfaces that isn't claimed by an operating system driver or another application. Standard operation-system drivers can be unloaded if the application is run with root privileges.
 
 
 ### Linux
 
 *libudev* is used to discover and monitor USB devices. It is closely tied to *systemd*. So the library only runs on Linux distributions with *systemd* and the related libraries. The majority of Linux distributions suitable for desktop computing (as opposed to distributions optimized for containers) fulfill this requirement.
 
-Similar to macOS, a Java application can connect to any USB device and claim any interfaces that isn't claimed by an operating system driver or another application.
+Similar to macOS, a Java application can connect to any USB device and claim any interfaces that isn't claimed by an operating system driver or another application. Standard operation system drivers can be unloaded (without the need for root privileges).
 
-Most Linux distributions by default set up user accounts without the permission to access USB devices directly. The *udev* system daemon is responsible for assigning permissions to USB devices. It can be configured to assign specific permissions or ownership:
+Most Linux distributions by default set up user accounts without permissions to access USB devices directly. The *udev* system daemon is responsible for assigning permissions to USB devices. It can be configured to assign specific permissions or ownership:
 
 Create a file called `/etc/udev/rules.d/80-javadoesusb-udev.rules` with the below content:
 
@@ -115,9 +116,9 @@ This adds the rule to assign permission mode 0666 to all USB devices with vendor
 
 ### Windows
 
-The Windows driver model is more rigid than the ones of macOS or Linux. It's not possible to open any USB device by default. Instead, only devices using the *WinUSB* driver can be opened. This even applies to devices with no installed driver.
+The Windows driver model is more rigid than the ones of macOS or Linux. It's not possible to open any USB device that is not claimed. Instead, only devices using the *WinUSB* driver can be opened. This even applies to devices with no installed driver.
 
-USB devices can implement certain control requests to instruct Windows to automatically install the WinUSB driver (search for WCID or Microsoft OS Compatibility Descriptors). The driver can also be manually installed or replaced using a software called [Zadig](https://zadig.akeo.ie/).
+USB devices can implement certain control requests to instruct Windows to automatically install the WinUSB driver (search for *WCID* or *Microsoft OS Compatibility Descriptors*). The WinUSB driver can also be manually installed or replaced using a software called [Zadig](https://zadig.akeo.ie/).
 
 The test devices implement the required control requests. So the driver is installed automatically.
 

examples/bulk_transfer/pom.xml

@@ -6,22 +6,22 @@
 
   <groupId>net.codecrete.usb.examples</groupId>
   <artifactId>bulk-transfer</artifactId>
-  <version>0.5.1</version>
+  <version>0.6.0-SNAPSHOT</version>
 
   <name>bulk-transfer</name>
   <url>https://github.com/manuelbl/JavaDoesUSB/examples/bulk_transfer</url>
 
   <properties>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <maven.compiler.source>20</maven.compiler.source>
-    <maven.compiler.target>20</maven.compiler.target>
+    <maven.compiler.source>21</maven.compiler.source>
+    <maven.compiler.target>21</maven.compiler.target>
   </properties>
 
   <dependencies>
     <dependency>
       <groupId>net.codecrete.usb</groupId>
       <artifactId>java-does-usb</artifactId>
-      <version>0.5.1</version>
+      <version>0.6.0-SNAPSHOT</version>
     </dependency>
   </dependencies>
 
@@ -42,12 +42,12 @@
           <artifactId>maven-compiler-plugin</artifactId>
           <version>3.8.0</version>
           <configuration>
-            <release>20</release>
+            <release>21</release>
             <compilerArgs>
               <arg>--enable-preview</arg>
             </compilerArgs>
-            <source>20</source>
-            <target>20</target>
+            <source>21</source>
+            <target>21</target>
           </configuration>
         </plugin>
         <plugin>

examples/bulk_transfer/src/main/java/net/codecrete/usb/examples/BulkTransfer.java

@@ -14,7 +14,8 @@
  * <p>
  * This example assumes that one of the interfaces has two bulk endpoints,
  * one for sending and one for receiving data. The test device fulfils
- * this requirement (see https://github.com/manuelbl/JavaDoesUSB/tree/main/test-devices/loopback-stm32)
+ * this requirement (see
+ * <a href="https://github.com/manuelbl/JavaDoesUSB/tree/main/test-devices/loopback-stm32">loopback-stm32</a>)
  * </p>
  */
 public class BulkTransfer {
@@ -26,7 +27,13 @@ public class BulkTransfer {
     private static final int ENDPOINT_IN = 2;
 
     public static void main(String[] args) {
-        var device = USB.getDevice(new USBDeviceFilter(VID, PID));
+        var optionalDevice = USB.getDevice(VID, PID);
+        if (optionalDevice.isEmpty()) {
+            System.out.printf("No USB device with VID=0x%04x and PID=0x%04x found.%n", VID, PID);
+            return;
+        }
+
+        var device = optionalDevice.get();
         device.open();
         device.claimInterface(INTERFACE_NO);
 

examples/enumerate/pom.xml

@@ -6,27 +6,42 @@
 
   <groupId>net.codecrete.usb.examples</groupId>
   <artifactId>enumerate</artifactId>
-  <version>0.5.1</version>
+  <version>0.6.0-SNAPSHOT</version>
 
   <name>enumerate</name>
   <url>https://github.com/manuelbl/JavaDoesUSB/examples/enumerate</url>
 
   <properties>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <maven.compiler.source>20</maven.compiler.source>
-    <maven.compiler.target>20</maven.compiler.target>
+    <maven.compiler.source>21</maven.compiler.source>
+    <maven.compiler.target>21</maven.compiler.target>
   </properties>
 
   <dependencies>
     <dependency>
       <groupId>net.codecrete.usb</groupId>
       <artifactId>java-does-usb</artifactId>
-      <version>0.5.1</version>
+      <version>0.6.0-SNAPSHOT</version>
+    </dependency>
+    <dependency>
+      <groupId>org.tinylog</groupId>
+      <artifactId>tinylog-api</artifactId>
+      <version>2.6.2</version>
+    </dependency>
+    <dependency>
+      <groupId>org.tinylog</groupId>
+      <artifactId>tinylog-impl</artifactId>
+      <version>2.6.2</version>
+    </dependency>
+    <dependency>
+      <groupId>org.tinylog</groupId>
+      <artifactId>jsl-tinylog</artifactId>
+      <version>2.6.2</version>
     </dependency>
   </dependencies>
 
   <build>
-    <pluginManagement><!-- lock down plugins versions to avoid using Maven defaults (may be moved to parent pom) -->
+    <pluginManagement><!-- lock down plugins versions to avoid using Maven defaults (maybe moved to parent pom) -->
       <plugins>
         <!-- clean lifecycle, see https://maven.apache.org/ref/current/maven-core/lifecycles.html#clean_Lifecycle -->
         <plugin>
@@ -42,12 +57,12 @@
           <artifactId>maven-compiler-plugin</artifactId>
           <version>3.8.0</version>
           <configuration>
-            <release>20</release>
+            <release>21</release>
             <compilerArgs>
               <arg>--enable-preview</arg>
             </compilerArgs>
-            <source>20</source>
-            <target>20</target>
+            <source>21</source>
+            <target>21</target>
           </configuration>
         </plugin>
         <plugin>

examples/enumerate/src/main/java/net/codecrete/usb/examples/Enumerate.java

@@ -14,6 +14,7 @@
 /**
  * Sample application enumerating connected USB devices.
  */
+@SuppressWarnings("java:S106")
 public class Enumerate {
 
     public static void main(String[] args) {
@@ -42,10 +43,14 @@ private static void printDevice(USBDevice device) {
         for (var intf: device.interfaces())
             printInterface(intf);
 
+        printRawDescriptor("Device descriptor", device.deviceDescriptor());
+        printRawDescriptor("Configuration descriptor", device.configurationDescriptor());
+
         System.out.println();
         System.out.println();
     }
 
+    @SuppressWarnings("OptionalUsedAsFieldOrParameterType")
     private static void printInParens(Optional<String> text) {
         if (text.isPresent()) {
             System.out.printf(" (%s)%n", text.get());
@@ -85,4 +90,17 @@ private static void printEndpoint(USBEndpoint endpoint) {
         System.out.printf("        Transfer type: %s%n", endpoint.transferType().name());
         System.out.printf("        Packet size: %d bytes%n", endpoint.packetSize());
     }
+
+    private static void printRawDescriptor(String title, byte[] descriptor) {
+        System.out.println();
+        System.out.println(title);
+
+        int len = descriptor.length;
+        for (int i = 0; i < len; i += 16) {
+            System.out.printf("%04x ", i);
+            for (int j = i; j < Math.min(i + 16, len); j += 1)
+                System.out.printf(" %02x", descriptor[j] & 255);
+            System.out.println();
+        }
+    }
 }

examples/enumerate/src/main/resources/tinylog.properties

@@ -0,0 +1,3 @@
+writer        = console
+writer.format = {date: HH:mm:ss.SSS} {level|size=5} [{class|size=40}] {message}
+writer.level  = info

examples/epaper_display/README.md

@@ -4,7 +4,7 @@ This sample shows how to communicate with an IT8951 controller for e-paper displ
 
 ## Prerequisites
 
-- Java 20
+- Java 21
 - Apache Maven
 - 64-bit operating system (macOS, Linux, Windows)
 - IT8951 controller
@@ -17,9 +17,9 @@ be temporarily detached.)
 
 ## How to run
 
-### Install Java 20
+### Install Java 21
 
-Check that *Java 20* is installed:
+Check that *Java 21* is installed:
 
 ```shell
 $ java -version