0
# Device Discovery and Connection
1

2
YubiKey device discovery and connection management, supporting multiple connected devices, automatic device type detection, and device-specific class instantiation.
3

4
## Capabilities
5

6
### Primary Device Discovery
7

8
The main function for locating and connecting to YubiKey devices, with automatic version detection and appropriate class instantiation.
9

10
```python { .api }
11
def find_yubikey(debug=False, skip=0):
12
    """
13
    Locate and connect to a YubiKey device.
14
    
15
    This is the primary entry point for YubiKey communication. It automatically
16
    detects the connected YubiKey model and returns the appropriate class instance.
17
    
18
    Parameters:
19
    - debug (bool): Enable debug output for troubleshooting
20
    - skip (int): Number of YubiKey devices to skip (for multiple devices)
21
    
22
    Returns:
23
    YubiKey: Connected YubiKey instance (YubiKeyUSBHID, YubiKeyNEO_USBHID, or YubiKey4_USBHID)
24
    
25
    Raises:
26
    YubiKeyError: If no YubiKey device is found
27
    YubiKeyUSBHIDError: If USB communication fails
28
    """
29
```
30

31
Usage example:
32

33
```python
34
import yubico
35

36
# Connect to first available YubiKey
37
try:
38
    yk = yubico.find_yubikey()
39
    print(f"Connected to YubiKey version {yk.version()}")
40
except yubico.yubico_exception.YubiKeyError:
41
    print("No YubiKey found")
42

43
# Connect to second YubiKey if multiple are connected
44
try:
45
    yk2 = yubico.find_yubikey(skip=1)
46
    print(f"Connected to second YubiKey: {yk2.version()}")
47
except yubico.yubico_exception.YubiKeyError:
48
    print("Second YubiKey not found")
49

50
# Enable debug output
51
yk_debug = yubico.find_yubikey(debug=True)
52
```
53

54
### Alternative Discovery Function
55

56
Lower-level device discovery function available in the yubikey module.
57

58
```python { .api }
59
def find_key(debug=False, skip=0):
60
    """
61
    Locate a connected YubiKey (alternative interface).
62
    
63
    This function provides the same functionality as find_yubikey() but is
64
    available directly from the yubikey module.
65
    
66
    Parameters:
67
    - debug (bool): Enable debug output
68
    - skip (int): Number of YubiKeys to skip
69
    
70
    Returns:
71
    YubiKey: Connected YubiKey instance
72
    
73
    Raises:
74
    YubiKeyError: If no YubiKey found
75
    YubiKeyUSBHIDError: If USB communication fails
76
    """
77
```
78

79
### Low-Level HID Device Connection
80

81
Direct USB HID device connection for advanced use cases requiring low-level access.
82

83
```python { .api }
84
class YubiKeyHIDDevice:
85
    def __init__(self, debug=False, skip=0):
86
        """
87
        Connect directly to YubiKey USB HID interface.
88
        
89
        This class provides low-level access to the YubiKey USB HID interface
90
        without the higher-level abstractions of the main YubiKey classes.
91
        
92
        Parameters:
93
        - debug (bool): Enable debug output
94
        - skip (int): Number of devices to skip
95
        
96
        Raises:
97
        YubiKeyUSBHIDError: If device connection fails
98
        """
99
    
100
    def status(self):
101
        """
102
        Poll YubiKey for status information.
103
        
104
        Returns:
105
        YubiKeyUSBHIDStatus: Device status object
106
        """
107
```
108

109
## Device Type Detection
110

111
The discovery system automatically detects YubiKey models and returns the appropriate class:
112

113
### Supported Device Types
114

115
- **YubiKey 1.x - 2.1.3**: Returns `YubiKeyUSBHID` instance
116
- **YubiKey NEO (2.1.4 - 2.1.9)**: Returns `YubiKeyNEO_USBHID` instance  
117
- **YubiKey NEO (3.x)**: Returns `YubiKeyNEO_USBHID` instance
118
- **YubiKey 4 (4.x+)**: Returns `YubiKey4_USBHID` instance
119

120
### Version Detection Logic
121

122
The discovery system uses firmware version information to determine the appropriate class:
123

124
```python
125
# Internal logic (for reference)
126
if (2, 1, 4) <= yk_version <= (2, 1, 9):
127
    return YubiKeyNEO_USBHID(debug, skip, hid_device)
128
if yk_version < (3, 0, 0):
129
    return YubiKeyUSBHID(debug, skip, hid_device)
130
if yk_version < (4, 0, 0):
131
    return YubiKeyNEO_USBHID(debug, skip, hid_device)
132
return YubiKey4_USBHID(debug, skip, hid_device)
133
```
134

135
## Error Handling
136

137
Common connection errors and their meanings:
138

139
```python
140
try:
141
    yk = yubico.find_yubikey()
142
except yubico.yubico_exception.YubiKeyError as e:
143
    if "No YubiKey found" in str(e):
144
        print("No YubiKey device is connected")
145
    else:
146
        print(f"YubiKey error: {e.reason}")
147
except yubico.yubikey_usb_hid.YubiKeyUSBHIDError as e:
148
    print(f"USB communication error: {e.reason}")
149
```
150

151
## Multiple Device Handling
152

153
When multiple YubiKeys are connected, use the `skip` parameter:
154

155
```python
156
# Get all connected YubiKeys
157
yubikeys = []
158
skip = 0
159
while True:
160
    try:
161
        yk = yubico.find_yubikey(skip=skip)
162
        yubikeys.append(yk)
163
        print(f"Found YubiKey {skip + 1}: {yk.version()}")
164
        skip += 1
165
    except yubico.yubico_exception.YubiKeyError:
166
        break
167

168
print(f"Total YubiKeys found: {len(yubikeys)}")
169
```