0
# Control Requests
1

2
Standard USB control transfer operations for device configuration and status management. The control module provides functions for USB standard requests as defined in the USB specification.
3

4
## Capabilities
5

6
### Status Operations
7

8
Retrieve and monitor device, interface, or endpoint status.
9

10
```python { .api }
11
def get_status(dev, recipient, index=0):
12
    """
13
    Get recipient status.
14
    
15
    Parameters:
16
    - dev: Device object
17
    - recipient: int, recipient type (RECIP_DEVICE, RECIP_INTERFACE, RECIP_ENDPOINT)
18
    - index: int, interface or endpoint index
19
    
20
    Returns:
21
    int: status value
22
    
23
    Raises:
24
    - USBError: Status request failed
25
    """
26
```
27

28
### Feature Management
29

30
Set and clear device features for power management and functionality control.
31

32
```python { .api }
33
def clear_feature(dev, feature, recipient, index=0):
34
    """
35
    Clear a recipient feature.
36
    
37
    Parameters:
38
    - dev: Device object
39
    - feature: int, feature selector (ENDPOINT_HALT, DEVICE_REMOTE_WAKEUP, etc.)
40
    - recipient: int, recipient type
41
    - index: int, interface or endpoint index
42
    
43
    Raises:
44
    - USBError: Clear feature request failed
45
    """
46

47
def set_feature(dev, feature, recipient, index=0):
48
    """
49
    Set a recipient feature.
50
    
51
    Parameters:
52
    - dev: Device object
53
    - feature: int, feature selector
54
    - recipient: int, recipient type
55
    - index: int, interface or endpoint index
56
    
57
    Raises:
58
    - USBError: Set feature request failed
59
    """
60
```
61

62
### Descriptor Operations
63

64
Retrieve and set device descriptors for configuration and information access.
65

66
```python { .api }
67
def get_descriptor(dev, desc_size, desc_type, desc_index, wIndex=0):
68
    """
69
    Get a device descriptor.
70
    
71
    Parameters:
72
    - dev: Device object
73
    - desc_size: int, descriptor size to read
74
    - desc_type: int, descriptor type (DT_DEVICE, DT_CONFIG, DT_STRING, etc.)
75
    - desc_index: int, descriptor index
76
    - wIndex: int, wIndex value for control transfer
77
    
78
    Returns:
79
    array.array: descriptor data
80
    
81
    Raises:
82
    - USBError: Get descriptor request failed
83
    """
84

85
def set_descriptor(dev, desc, desc_type, desc_index, wIndex=None):
86
    """
87
    Set a device descriptor.
88
    
89
    Parameters:
90
    - dev: Device object
91
    - desc: array-like, descriptor data to set
92
    - desc_type: int, descriptor type
93
    - desc_index: int, descriptor index
94
    - wIndex: int, wIndex value for control transfer
95
    
96
    Raises:
97
    - USBError: Set descriptor request failed
98
    """
99
```
100

101
### Configuration Management
102

103
Get and set device configurations for operational state control.
104

105
```python { .api }
106
def get_configuration(dev):
107
    """
108
    Get device configuration.
109
    
110
    Parameters:
111
    - dev: Device object
112
    
113
    Returns:
114
    int: active configuration value
115
    
116
    Raises:
117
    - USBError: Get configuration request failed
118
    """
119

120
def set_configuration(dev, config):
121
    """
122
    Set device configuration.
123
    
124
    Parameters:
125
    - dev: Device object
126
    - config: int, configuration value to set
127
    
128
    Raises:
129
    - USBError: Set configuration request failed
130
    """
131
```
132

133
### Interface Management
134

135
Get and set interface alternate settings for interface configuration.
136

137
```python { .api }
138
def get_interface(dev, bInterfaceNumber):
139
    """
140
    Get device interface alternate setting.
141
    
142
    Parameters:
143
    - dev: Device object
144
    - bInterfaceNumber: int, interface number
145
    
146
    Returns:
147
    int: alternate setting value
148
    
149
    Raises:
150
    - USBError: Get interface request failed
151
    """
152

153
def set_interface(dev, bInterfaceNumber, bAlternateSetting):
154
    """
155
    Set device interface alternate setting.
156
    
157
    Parameters:
158
    - dev: Device object
159
    - bInterfaceNumber: int, interface number
160
    - bAlternateSetting: int, alternate setting value
161
    
162
    Raises:
163
    - USBError: Set interface request failed
164
    """
165
```
166

167
### Feature Constants
168

169
Standard USB feature selectors for use with set_feature and clear_feature functions.
170

171
```python { .api }
172
ENDPOINT_HALT = 0           # Endpoint halt feature
173
FUNCTION_SUSPEND = 0        # Function suspend feature
174
DEVICE_REMOTE_WAKEUP = 1    # Device remote wakeup feature
175
LTM_ENABLE = 50             # Link power management feature
176
```
177

178
## Usage Examples
179

180
### Basic Status Check
181

182
```python
183
import usb.core
184
import usb.control
185

186
device = usb.core.find(idVendor=0x1234, idProduct=0x5678)
187

188
# Get device status
189
try:
190
    status = usb.control.get_status(device, usb.control.RECIP_DEVICE)
191
    print(f"Device status: 0x{status:04x}")
192
    
193
    # Check if device is self-powered
194
    if status & 0x01:
195
        print("Device is self-powered")
196
    else:
197
        print("Device is bus-powered")
198
        
199
    # Check remote wakeup capability
200
    if status & 0x02:
201
        print("Remote wakeup enabled")
202
        
203
except usb.core.USBError as e:
204
    print(f"Failed to get device status: {e}")
205
```
206

207
### Clear Endpoint Halt
208

209
```python
210
import usb.core
211
import usb.control
212
import usb.util
213

214
device = usb.core.find(idVendor=0x1234, idProduct=0x5678)
215
endpoint_addr = 0x81  # IN endpoint 1
216

217
try:
218
    # Clear endpoint halt condition
219
    usb.control.clear_feature(
220
        device, 
221
        usb.control.ENDPOINT_HALT,
222
        usb.control.RECIP_ENDPOINT,
223
        endpoint_addr
224
    )
225
    print("Endpoint halt cleared")
226
    
227
except usb.core.USBError as e:
228
    print(f"Failed to clear endpoint halt: {e}")
229
```
230

231
### Device Remote Wakeup Management
232

233
```python
234
import usb.core
235
import usb.control
236

237
device = usb.core.find(idVendor=0x1234, idProduct=0x5678)
238

239
try:
240
    # Enable remote wakeup
241
    usb.control.set_feature(
242
        device,
243
        usb.control.DEVICE_REMOTE_WAKEUP,
244
        usb.control.RECIP_DEVICE
245
    )
246
    print("Remote wakeup enabled")
247
    
248
    # Later, disable remote wakeup
249
    usb.control.clear_feature(
250
        device,
251
        usb.control.DEVICE_REMOTE_WAKEUP,
252
        usb.control.RECIP_DEVICE
253
    )
254
    print("Remote wakeup disabled")
255
    
256
except usb.core.USBError as e:
257
    print(f"Remote wakeup operation failed: {e}")
258
```
259

260
### Configuration Management
261

262
```python
263
import usb.core
264
import usb.control
265

266
device = usb.core.find(idVendor=0x1234, idProduct=0x5678)
267

268
try:
269
    # Get current configuration
270
    current_config = usb.control.get_configuration(device)
271
    print(f"Current configuration: {current_config}")
272
    
273
    # Set configuration (usually 1 for single-configuration devices)
274
    usb.control.set_configuration(device, 1)
275
    print("Configuration set to 1")
276
    
277
except usb.core.USBError as e:
278
    print(f"Configuration operation failed: {e}")
279
```
280

281
### Interface Alternate Setting
282

283
```python
284
import usb.core
285
import usb.control
286

287
device = usb.core.find(idVendor=0x1234, idProduct=0x5678)
288
interface_num = 0
289

290
try:
291
    # Get current alternate setting
292
    alt_setting = usb.control.get_interface(device, interface_num)
293
    print(f"Interface {interface_num} alternate setting: {alt_setting}")
294
    
295
    # Set alternate setting
296
    usb.control.set_interface(device, interface_num, 1)
297
    print(f"Interface {interface_num} alternate setting changed to 1")
298
    
299
except usb.core.USBError as e:
300
    print(f"Interface operation failed: {e}")
301
```
302

303
### Descriptor Retrieval
304

305
```python
306
import usb.core
307
import usb.control
308

309
device = usb.core.find(idVendor=0x1234, idProduct=0x5678)
310

311
try:
312
    # Get device descriptor
313
    device_desc = usb.control.get_descriptor(
314
        device,
315
        18,  # Device descriptor size
316
        usb.control.DT_DEVICE
317
    )
318
    print(f"Device descriptor: {device_desc}")
319
    
320
    # Get configuration descriptor
321
    config_desc = usb.control.get_descriptor(
322
        device,
323
        9,   # Configuration descriptor size  
324
        usb.control.DT_CONFIG,
325
        0    # First configuration
326
    )
327
    print(f"Configuration descriptor: {config_desc}")
328
    
329
except usb.core.USBError as e:
330
    print(f"Descriptor retrieval failed: {e}")
331
```
332

333
### String Descriptor Access
334

335
```python
336
import usb.core
337
import usb.control
338
import usb.util
339

340
device = usb.core.find(idVendor=0x1234, idProduct=0x5678)
341

342
try:
343
    # Get supported language IDs
344
    langids = usb.util.get_langids(device)
345
    print(f"Supported language IDs: {langids}")
346
    
347
    if langids:
348
        langid = langids[0]  # Use first supported language
349
        
350
        # Get manufacturer string
351
        if device.iManufacturer:
352
            manufacturer = usb.util.get_string(device, device.iManufacturer, langid)
353
            print(f"Manufacturer: {manufacturer}")
354
            
355
        # Get product string
356
        if device.iProduct:
357
            product = usb.util.get_string(device, device.iProduct, langid)
358
            print(f"Product: {product}")
359
            
360
except usb.core.USBError as e:
361
    print(f"String descriptor access failed: {e}")
362
```