0
# libusb1
1
2
A pure-Python wrapper for libusb-1.0 providing comprehensive USB device access functionality. libusb1 enables developers to build cross-platform USB communication applications entirely in Python, supporting all USB transfer types (control, bulk, interrupt, isochronous) in both synchronous and asynchronous modes with robust error handling and event-driven programming patterns.
3
4
## Package Information
5
6
- **Package Name**: libusb1
7
- **Language**: Python
8
- **Installation**: `pip install libusb1`
9
- **Dependencies**: libusb-1.0 system library
10
- **Supported Platforms**: GNU/Linux, Windows, macOS, FreeBSD, OpenBSD
11
12
## Core Imports
13
14
```python
15
import usb1
16
```
17
18
## Basic Usage
19
20
```python
21
import usb1
22
23
# Create USB context and enumerate devices
24
with usb1.USBContext() as context:
25
# List all USB devices
26
for device in context.getDeviceIterator(skip_on_error=True):
27
print(f'ID {device.getVendorID():04x}:{device.getProductID():04x}')
28
print(f'Bus {device.getBusNumber():03d} Device {device.getDeviceAddress():03d}')
29
30
# Find specific device by vendor/product ID
31
device = context.getByVendorIDAndProductID(0x1234, 0x5678)
32
if device:
33
# Open device for communication
34
with device.open() as handle:
35
# Claim interface for exclusive access
36
with handle.claimInterface(0):
37
# Perform synchronous control transfer
38
data = handle.controlRead(
39
request_type=usb1.TYPE_VENDOR | usb1.RECIPIENT_DEVICE | usb1.ENDPOINT_IN,
40
request=0x01,
41
value=0,
42
index=0,
43
length=64,
44
timeout=1000
45
)
46
print(f'Received: {data.hex()}')
47
```
48
49
## Architecture
50
51
libusb1 follows a hierarchical object model that mirrors the USB specification:
52
53
- **USBContext**: Top-level USB context managing system resources and device enumeration
54
- **USBDevice**: Represents a USB device with access to descriptors (no communication)
55
- **USBDeviceHandle**: Handle for opened device enabling data transfer and configuration
56
- **USBTransfer**: Asynchronous transfer objects for non-blocking I/O operations
57
- **Descriptor Objects**: Configuration, interface, and endpoint descriptor wrappers
58
59
The library provides both synchronous methods (blocking) for simple use cases and asynchronous transfers (non-blocking) for high-performance applications requiring concurrent USB operations.
60
61
## Capabilities
62
63
### USB Context Management
64
65
Core USB context functionality for initializing the library, enumerating devices, and managing system resources with comprehensive device discovery and filtering capabilities.
66
67
```python { .api }
68
class USBContext:
69
def __init__(self, log_level=None, use_usbdk=False, with_device_discovery=True, log_callback=None): ...
70
def __enter__(self): ...
71
def __exit__(self, exc_type, exc_val, exc_tb): ...
72
def getDeviceIterator(self, skip_on_error=False): ...
73
def getDeviceList(self, skip_on_access_error=False, skip_on_error=False): ...
74
def getByVendorIDAndProductID(self, vendor_id, product_id, skip_on_access_error=False, skip_on_error=False): ...
75
def openByVendorIDAndProductID(self, vendor_id, product_id, skip_on_access_error=False, skip_on_error=False): ...
76
```
77
78
[USB Context Management](./usb-context.md)
79
80
### Device Access and Configuration
81
82
USB device representation and handle management for accessing device properties, opening communication channels, claiming interfaces, and configuring device settings.
83
84
```python { .api }
85
class USBDevice:
86
def open(self): ...
87
def getBusNumber(self): ...
88
def getDeviceAddress(self): ...
89
def getVendorID(self): ...
90
def getProductID(self): ...
91
def getDeviceSpeed(self): ...
92
93
class USBDeviceHandle:
94
def close(self): ...
95
def claimInterface(self, interface): ...
96
def releaseInterface(self, interface): ...
97
def setConfiguration(self, configuration): ...
98
def getConfiguration(self): ...
99
```
100
101
[Device Access and Configuration](./device-access.md)
102
103
### Synchronous USB Transfers
104
105
Blocking USB transfer operations for control, bulk, and interrupt endpoints with timeout support and error handling, suitable for simple request-response communication patterns.
106
107
```python { .api }
108
class USBDeviceHandle:
109
def controlRead(self, request_type, request, value, index, length, timeout=0): ...
110
def controlWrite(self, request_type, request, value, index, data, timeout=0): ...
111
def bulkRead(self, endpoint, length, timeout=0): ...
112
def bulkWrite(self, endpoint, data, timeout=0): ...
113
def interruptRead(self, endpoint, length, timeout=0): ...
114
def interruptWrite(self, endpoint, data, timeout=0): ...
115
```
116
117
[Synchronous USB Transfers](./sync-transfers.md)
118
119
### Asynchronous USB Transfers
120
121
Non-blocking USB transfer operations using event-driven callbacks for high-performance applications requiring concurrent transfers and integration with event loops.
122
123
```python { .api }
124
class USBTransfer:
125
def setControl(self, request_type, request, value, index, buffer_or_len, callback=None, user_data=None, timeout=0): ...
126
def setBulk(self, endpoint, buffer_or_len, callback=None, user_data=None, timeout=0): ...
127
def setIsochronous(self, endpoint, buffer_or_len, callback=None, user_data=None, timeout=0, iso_transfer_length_list=None): ...
128
def submit(self): ...
129
def cancel(self): ...
130
131
class USBTransferHelper:
132
def setEventCallback(self, event, callback): ...
133
def setDefaultCallback(self, callback): ...
134
```
135
136
[Asynchronous USB Transfers](./async-transfers.md)
137
138
### USB Descriptors
139
140
USB descriptor object wrappers providing structured access to device configuration data including configurations, interfaces, alternate settings, and endpoints.
141
142
```python { .api }
143
class USBConfiguration:
144
def getNumInterfaces(self): ...
145
def getConfigurationValue(self): ...
146
def getMaxPower(self): ...
147
148
class USBInterface:
149
def getNumSettings(self): ...
150
151
class USBInterfaceSetting:
152
def getNumber(self): ...
153
def getClass(self): ...
154
def getSubClass(self): ...
155
def getProtocol(self): ...
156
def getNumEndpoints(self): ...
157
158
class USBEndpoint:
159
def getAddress(self): ...
160
def getAttributes(self): ...
161
def getMaxPacketSize(self): ...
162
```
163
164
[USB Descriptors](./descriptors.md)
165
166
## Global Functions
167
168
```python { .api }
169
def getVersion():
170
"""
171
Get libusb version information.
172
173
Returns:
174
Version: Named tuple with major, minor, micro, nano, rc, describe fields
175
"""
176
177
def hasCapability(capability):
178
"""
179
Test libusb capability support.
180
181
Args:
182
capability: Capability constant (CAP_HAS_CAPABILITY, CAP_HAS_HOTPLUG, etc.)
183
184
Returns:
185
bool: True if capability is supported
186
"""
187
188
def setLogCallback(callback):
189
"""
190
Set global log callback function.
191
192
Args:
193
callback: Function accepting (context, level, message) or None to disable
194
"""
195
196
def setLocale(locale):
197
"""
198
Set locale for translatable libusb messages.
199
200
Args:
201
locale (str): 2-letter ISO 639-1 code
202
"""
203
204
def loadLibrary(libusb=None):
205
"""
206
Load libusb library from custom path.
207
208
Args:
209
libusb (str, optional): Path to libusb library file, or None to use default lookup
210
211
Note:
212
Must be called before creating any USB contexts. Allows applications to
213
customize library loading for specific libusb versions or locations.
214
"""
215
```
216
217
## Exception Classes
218
219
```python { .api }
220
class USBError(Exception):
221
"""Base class for USB-related errors."""
222
223
class USBErrorIO(USBError):
224
"""I/O error."""
225
226
class USBErrorInvalidParam(USBError):
227
"""Invalid parameter."""
228
229
class USBErrorAccess(USBError):
230
"""Access denied (insufficient permissions)."""
231
232
class USBErrorNoDevice(USBError):
233
"""No such device (disconnected)."""
234
235
class USBErrorNotFound(USBError):
236
"""Entity not found."""
237
238
class USBErrorBusy(USBError):
239
"""Resource busy."""
240
241
class USBErrorTimeout(USBError):
242
"""Operation timed out."""
243
# Has .transferred or .received property with partial data
244
245
class USBErrorOverflow(USBError):
246
"""Overflow."""
247
248
class USBErrorPipe(USBError):
249
"""Pipe error."""
250
251
class USBErrorInterrupted(USBError):
252
"""System call interrupted."""
253
254
class USBErrorNoMem(USBError):
255
"""Insufficient memory."""
256
257
class USBErrorNotSupported(USBError):
258
"""Operation not supported or unimplemented."""
259
260
class USBErrorOther(USBError):
261
"""Other error."""
262
263
class DoomedTransferError(Exception):
264
"""Exception raised when operating on a doomed transfer."""
265
```
266
267
## Constants
268
269
### Transfer Types
270
```python { .api }
271
TRANSFER_TYPE_CONTROL = 0
272
TRANSFER_TYPE_ISOCHRONOUS = 1
273
TRANSFER_TYPE_BULK = 2
274
TRANSFER_TYPE_INTERRUPT = 3
275
```
276
277
### Transfer Status
278
```python { .api }
279
TRANSFER_COMPLETED = 0
280
TRANSFER_ERROR = 1
281
TRANSFER_TIMED_OUT = 2
282
TRANSFER_CANCELLED = 3
283
TRANSFER_STALL = 4
284
TRANSFER_NO_DEVICE = 5
285
TRANSFER_OVERFLOW = 6
286
```
287
288
### Endpoint Directions
289
```python { .api }
290
ENDPOINT_IN = 0x80
291
ENDPOINT_OUT = 0x00
292
ENDPOINT_DIR_MASK = 0x80
293
```
294
295
### Request Types
296
```python { .api }
297
TYPE_STANDARD = 0x00
298
TYPE_CLASS = 0x20
299
TYPE_VENDOR = 0x40
300
301
RECIPIENT_DEVICE = 0x00
302
RECIPIENT_INTERFACE = 0x01
303
RECIPIENT_ENDPOINT = 0x02
304
RECIPIENT_OTHER = 0x03
305
```
306
307
### Device Speeds
308
```python { .api }
309
SPEED_UNKNOWN = 0
310
SPEED_LOW = 1
311
SPEED_FULL = 2
312
SPEED_HIGH = 3
313
SPEED_SUPER = 4
314
SPEED_SUPER_PLUS = 5
315
```
316
317
### Log Levels
318
```python { .api }
319
LOG_LEVEL_NONE = 0
320
LOG_LEVEL_ERROR = 1
321
LOG_LEVEL_WARNING = 2
322
LOG_LEVEL_INFO = 3
323
LOG_LEVEL_DEBUG = 4
324
```
325
326
### Capabilities
327
```python { .api }
328
CAP_HAS_CAPABILITY = 0x0000
329
CAP_HAS_HOTPLUG = 0x0001
330
CAP_HAS_HID_ACCESS = 0x0100
331
CAP_SUPPORTS_DETACH_KERNEL_DRIVER = 0x0101
332
```
333
334
### Hotplug Events
335
```python { .api }
336
HOTPLUG_EVENT_DEVICE_ARRIVED = 0x01
337
HOTPLUG_EVENT_DEVICE_LEFT = 0x02
338
HOTPLUG_ENUMERATE = 0x01
339
HOTPLUG_MATCH_ANY = -1
340
```
341
342
### USB Interface Classes
343
```python { .api }
344
CLASS_PER_INTERFACE = 0
345
CLASS_AUDIO = 1
346
CLASS_COMM = 2
347
CLASS_HID = 3
348
CLASS_PHYSICAL = 5
349
CLASS_IMAGE = 6
350
CLASS_PRINTER = 7
351
CLASS_MASS_STORAGE = 8
352
CLASS_HUB = 9
353
CLASS_DATA = 10
354
CLASS_SMART_CARD = 11
355
CLASS_CONTENT_SECURITY = 13
356
CLASS_VIDEO = 14
357
CLASS_PERSONAL_HEALTHCARE = 15
358
CLASS_DIAGNOSTIC_DEVICE = 220
359
CLASS_WIRELESS = 224
360
CLASS_APPLICATION = 254
361
CLASS_VENDOR_SPEC = 255
362
```
363
364
### Standard USB Requests
365
```python { .api }
366
REQUEST_GET_STATUS = 0x00
367
REQUEST_CLEAR_FEATURE = 0x01
368
REQUEST_SET_FEATURE = 0x03
369
REQUEST_SET_ADDRESS = 0x05
370
REQUEST_GET_DESCRIPTOR = 0x06
371
REQUEST_SET_DESCRIPTOR = 0x07
372
REQUEST_GET_CONFIGURATION = 0x08
373
REQUEST_SET_CONFIGURATION = 0x09
374
REQUEST_GET_INTERFACE = 0x0A
375
REQUEST_SET_INTERFACE = 0x0B
376
REQUEST_SYNCH_FRAME = 0x0C
377
REQUEST_SET_SEL = 0x30
378
REQUEST_SET_ISOCH_DELAY = 0x31
379
```