You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
*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.)
5
+
*Java Does USB* is a Java library for working with USB devices. It allows to query the conntected USB devices and to communicate with them using custom / vendor specific protocols. (It is not intended for communication with standard types of USB devices such as mass storage devices, keyboards etc.)
6
6
7
-
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).
7
+
The library uses the [Foreign Function and Memory API](https://docs.oracle.com/en/java/javase/21/core/foreign-function-and-memory-api.html#GUID-FBE990DA-C356-46E8-9109-C75567849BA8) to access native APIs of the underlying operating system. It is written entirely in Java and does not use JNI or any native third-party library. The *Foreign Function and Memory API*has been introduced with Java 22. Preview versions were available in several earlier releases.
8
8
9
-
| Version | Main New Features | Compatibility |
10
-
| - | - | - |
11
-
| 0.7.x | New setter/getter names for improved Kotlin support; Kotlin examples | JDK 21 |
12
-
| 0.6.x | Support for JDK 21; better handling of composite devices on Windows | JDK 21 |
13
-
| 0.5.x | Support for JDK 20; high-throuput I/O streams | JDK 20 |
14
-
| 0.4.x | Early release | JDK 19 |
15
-
16
-
*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.
17
9
18
10
19
11
## Features
@@ -25,17 +17,8 @@ The library uses the [Foreign Function & Memory API](https://github.com/openjdk/
25
17
- Descriptive information about interfaces, settings and endpoints
26
18
- High-throughput input/output streams
27
19
- Support for alternate interface settings, composite devices and interface association
28
-
- Published on Maven Central
29
-
30
-
### Planned
31
-
32
-
- Isochronous transfer
33
-
34
-
### Not planned
20
+
- Published on Maven Central and licensed under the permissive MIT license
35
21
36
-
- Changing configuration: The library selects the first configuration. Changing configurations is rarely used and not supported on Windows (limitation of WinUSB).
37
-
- USB 3.0 streams: Not supported on Windows (limitation of WinUSB).
38
-
- Providing information about USB buses, controllers and hubs
39
22
40
23
41
24
## Getting Started
@@ -48,14 +31,14 @@ If you are using Maven, add the below dependency to your pom.xml:
48
31
<dependency>
49
32
<groupId>net.codecrete.usb</groupId>
50
33
<artifactId>java-does-usb</artifactId>
51
-
<version>0.7.1</version>
34
+
<version>1.0.0-SNAPSHOT</version>
52
35
</dependency>
53
36
```
54
37
55
38
If you are using Gradle, add the below dependency to your build.gradle file:
-[Bulk Transfer](examples/bulk_transfer/) demonstrates how to find a USB device, open it and communicate using bulk transfer.
@@ -88,29 +74,29 @@ public class EnumerateDevices {
88
74
-[ePaper Display](examples/epaper_display) communicates with an IT8951 controller for e-Paper displays and shows an image on the display.
89
75
90
76
77
+
91
78
## Prerequisite
92
79
93
-
- Java 21, preview features enabled (available at https://www.azul.com/downloads/?package=jdk)
80
+
- Java 22 available at [jdk.java.net](https://jdk.java.net/21/), [Azul](https://www.azul.com/downloads/?package=jdk), [Adoptium](https://adoptium.net/temurin/releases/) or with your favorite package manager.
94
81
- Windows (x86 64-bit), macOS (x86 64-bit, ARM 64-bit) or Linux 64 bit (x86 64-bit, ARM 64-bit)
95
82
96
-
For JDK 20, use the latest published version 0.5.x. For JDK 19, use the latest published version 0.4.x.
97
83
98
84
99
85
## Platform-specific Considerations
100
86
101
87
102
88
### macOS
103
89
104
-
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.
90
+
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 operationsystem drivers can be unloaded if the application is run with root privileges. It runs both on Macs with Apple Silicon and Intel processors.
105
91
106
92
107
93
### Linux
108
94
109
-
*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.
95
+
*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. It runs on both Intel and ARM64 processors.
110
96
111
97
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).
112
98
113
-
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:
99
+
Most Linux distributions set up user accounts without permissions to access USB devices. The *udev* system daemon is responsible for assigning permissions to USB devices. It can be configured to assign specific permissions or ownership:
114
100
115
101
Create a file called `/etc/udev/rules.d/80-javadoesusb-udev.rules` with the below content:
This adds the rule to assign permission mode 0666 to all USB devices with vendor ID `0xCAFE`. This unregistered vendor ID is used by the test devices.
122
108
109
+
Without the *udev* rule, it is still possible to enumerate and query all USB devices.
110
+
123
111
124
112
### Windows
125
113
126
-
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.
114
+
The Windows driver model is rather rigid. It's not possible to open any USB device unless it uses the *WinUSB* driver. This even applies to devices with no installed driver. Enumerating and querying USB devices is possible independent of the driver.
127
115
128
-
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/).
116
+
USB devices can implement special 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/).
129
117
130
118
The test devices implement the required control requests. So the driver is installed automatically.
131
119
132
-
The library has not been tested on Windows for ARM64. It might or might not work.
120
+
Windows for ARM64 is not yet supported. A port is probably easy, provided you have hardware to test it.
133
121
134
122
135
-
### Troubleshooting
136
123
137
-
#### `ClassFormatError` (all platforms)
124
+
##Troubleshooting
138
125
139
-
The error `java.lang.ClassFormatError: Illegal field name "" in class net/codecrete/usb/windows/WindowsUsbDeviceRegistry` is caused by a bug in JDK 21, which has been fixed in the mean-time. Please upgrade to the latest release of JDK 21 (at least 21.0.1).
126
+
### 32-bit versions
140
127
128
+
The *Foreign Function And Memory API* has not been implemented for 32-bit operating systems / JDKs (and likely never will be).
141
129
142
130
143
-
### 32-bit versions
144
131
145
-
The Foreign Function & Memory API has not been implemented for 32-bit operating systems / JDKs (and likely never will be).
132
+
## Running on older JDK versions
146
133
134
+
The *Foreign Function And Memory API* has been available as a preview feature in JDKs before 22. However, incompatible changes were made from preview to preview to release. Earlier versions can be used with specific versions of this library:
147
135
136
+
| Version | Main New Features | Compatibility |
137
+
| - | - | - |
138
+
| 1.0.x | Release for final Java API | JDK 22 |
139
+
| 0.7.x | New setter/getter names for improved Kotlin support; Kotlin examples | JDK 21 |
140
+
| 0.6.x | Support for JDK 21; better handling of composite devices on Windows | JDK 21 |
141
+
| 0.5.x | Support for JDK 20; high-throuput I/O streams | JDK 20 |
142
+
| 0.4.x | Early release | JDK 19 |
148
143
149
-
## Code generation
144
+
When using an older JDK, preview features must be enabled using the `--enable-preview` VM option.
150
145
151
-
Many bindings for the native APIs have been generated with *jextract*. See the [jextract](java-does-usb/jextract) subdirectory for more information. For functions that need to retain the error state (`errno` on Linux, `GetLastError()` on Windows), the bindings have been manually written as *jextract* does not support it.
146
+
147
+
148
+
## Building from source
149
+
150
+
To build from source, run the following command:
151
+
152
+
```
153
+
cd java-does-usb
154
+
mvn clean install -DskipTests
155
+
```
156
+
157
+
The tests are skipped as they require that a special test device is connected to the computer. See the next section for more information.
152
158
153
159
154
160
@@ -164,17 +170,26 @@ The test device with the *loopback-stm32* code supports all tests. If the test d
164
170
Tests can be run from the command line:
165
171
166
172
```
173
+
cd java-does-usb
167
174
mvn clean test
168
175
```
169
176
170
-
If they are run from an IDE (such as IntelliJ IDEA), you must likely configure VM options to enable preview features and allow native access:
177
+
If they are run from an IDE (such as IntelliJ IDEA), you must likely configure VM options to allow native access:
Many bindings for the native APIs have been generated with *jextract*. See the [jextract](java-does-usb/jextract) subdirectory for more information. For functions that need to retain the error state (`errno` on Linux, `GetLastError()` on Windows), the bindings have been manually written as *jextract* does not support it.
194
+
195
+
Since the code can only be generated for the current operating system, it must be generated on separate computers for Linux, Windows and macOS. Thus, the generated code is included in the repository. The generated code is compilable on all operating systems.
Copy file name to clipboardExpand all lines: examples/bulk_transfer/README.md
+11-13Lines changed: 11 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,16 +4,16 @@ This sample shows how to find a device, open it and transfer data from and to bu
4
4
5
5
## Prerequisites
6
6
7
-
- Java 21
7
+
- Java 22
8
8
- Apache Maven
9
9
- 64-bit operating system (Windows, macOS, Linux)
10
10
- A USB device with bulk IN and OUT endpoints (e.g. the test device, see https://github.com/manuelbl/JavaDoesUSB/tree/main/test-devices/loopback-stm32)
0 commit comments