0
# Device Discovery
1
2
Find and enumerate USB devices using flexible filtering criteria. PyUSB provides powerful device discovery capabilities with support for custom matching logic and backend selection.
3
4
## Capabilities
5
6
### Device Finding
7
8
Locate USB devices based on descriptor properties with support for single or multiple device retrieval.
9
10
```python { .api }
11
def find(find_all=False, backend=None, custom_match=None, **args):
12
"""
13
Find USB devices matching specified criteria.
14
15
Parameters:
16
- find_all: bool, if True return all matches, otherwise return first match
17
- backend: backend instance to use for device discovery
18
- custom_match: callable taking device as argument, return True for matches
19
- **args: device descriptor fields to match (idVendor, idProduct, bDeviceClass, etc.)
20
21
Returns:
22
Device object (find_all=False) or list of Device objects (find_all=True)
23
None if no devices found and find_all=False
24
25
Common descriptor fields for **args:
26
- idVendor: int, vendor ID
27
- idProduct: int, product ID
28
- bDeviceClass: int, device class
29
- bDeviceSubClass: int, device sub-class
30
- bDeviceProtocol: int, device protocol
31
- bcdUSB: int, USB version
32
"""
33
```
34
35
### Device Enumeration
36
37
Display comprehensive information about available USB devices.
38
39
```python { .api }
40
def show_devices(verbose=False, **kwargs):
41
"""
42
Display information about available USB devices.
43
44
Parameters:
45
- verbose: bool, show detailed device information
46
- **kwargs: same filtering arguments as find()
47
"""
48
```
49
50
## Usage Examples
51
52
### Basic Device Discovery
53
54
```python
55
import usb.core
56
57
# Find device by vendor and product ID
58
device = usb.core.find(idVendor=0x1234, idProduct=0x5678)
59
60
if device is None:
61
print("Device not found")
62
else:
63
print(f"Found device: {device}")
64
print(f"Vendor ID: 0x{device.idVendor:04x}")
65
print(f"Product ID: 0x{device.idProduct:04x}")
66
```
67
68
### Find Multiple Devices
69
70
```python
71
import usb.core
72
73
# Find all devices from a specific vendor
74
devices = usb.core.find(find_all=True, idVendor=0x1234)
75
76
print(f"Found {len(devices)} devices from vendor 0x1234:")
77
for i, device in enumerate(devices):
78
print(f" Device {i}: Product ID 0x{device.idProduct:04x}")
79
```
80
81
### Find Devices by Class
82
83
```python
84
import usb.core
85
86
# Find all HID devices (Human Interface Device class)
87
hid_devices = usb.core.find(find_all=True, bDeviceClass=3)
88
89
print(f"Found {len(hid_devices)} HID devices:")
90
for device in hid_devices:
91
print(f" Vendor: 0x{device.idVendor:04x}, Product: 0x{device.idProduct:04x}")
92
```
93
94
### Custom Matching Logic
95
96
```python
97
import usb.core
98
99
def is_high_speed_device(device):
100
"""Custom matcher for high-speed USB devices."""
101
return device.bcdUSB >= 0x0200 # USB 2.0 or higher
102
103
# Find all high-speed devices
104
high_speed_devices = usb.core.find(find_all=True, custom_match=is_high_speed_device)
105
106
print(f"Found {len(high_speed_devices)} high-speed devices")
107
```
108
109
### Complex Device Filtering
110
111
```python
112
import usb.core
113
114
def find_storage_devices():
115
"""Find USB mass storage devices."""
116
return usb.core.find(
117
find_all=True,
118
bDeviceClass=8, # Mass Storage class
119
custom_match=lambda d: d.bDeviceSubClass == 6 # SCSI transparent subclass
120
)
121
122
storage_devices = find_storage_devices()
123
print(f"Found {len(storage_devices)} mass storage devices")
124
```
125
126
### Device Information Display
127
128
```python
129
import usb.core
130
131
# Show all available devices
132
print("All USB devices:")
133
usb.core.show_devices()
134
135
# Show detailed information
136
print("\nDetailed device information:")
137
usb.core.show_devices(verbose=True)
138
139
# Show devices from specific vendor
140
print("\nDevices from vendor 0x1234:")
141
usb.core.show_devices(idVendor=0x1234)
142
```
143
144
### Backend-Specific Discovery
145
146
```python
147
import usb.core
148
import usb.backend.libusb1
149
150
# Use specific backend for device discovery
151
backend = usb.backend.libusb1.get_backend()
152
device = usb.core.find(idVendor=0x1234, backend=backend)
153
154
if device:
155
print(f"Found device using libusb1 backend: {device}")
156
```
157
158
### Iterating Through All Devices
159
160
```python
161
import usb.core
162
163
# Get all USB devices and examine each one
164
all_devices = usb.core.find(find_all=True)
165
166
for device in all_devices:
167
try:
168
# Access device properties
169
vendor_id = device.idVendor
170
product_id = device.idProduct
171
172
print(f"Device: {vendor_id:04x}:{product_id:04x}")
173
174
# Try to get string descriptors
175
try:
176
import usb.util
177
manufacturer = usb.util.get_string(device, device.iManufacturer)
178
product = usb.util.get_string(device, device.iProduct)
179
print(f" Manufacturer: {manufacturer}")
180
print(f" Product: {product}")
181
except:
182
print(" String descriptors not accessible")
183
184
except usb.core.USBError as e:
185
print(f"Error accessing device: {e}")
186
```
187
188
### Device Availability Checking
189
190
```python
191
import usb.core
192
import time
193
194
def wait_for_device(vendor_id, product_id, timeout=30):
195
"""Wait for a specific device to become available."""
196
start_time = time.time()
197
198
while time.time() - start_time < timeout:
199
device = usb.core.find(idVendor=vendor_id, idProduct=product_id)
200
if device is not None:
201
return device
202
time.sleep(1)
203
204
return None
205
206
# Wait for device to be connected
207
print("Waiting for device 0x1234:0x5678...")
208
device = wait_for_device(0x1234, 0x5678)
209
210
if device:
211
print("Device found!")
212
else:
213
print("Device not found within timeout period")
214
```