0
# Device Connection and Management
1

2
Device connection and management functionality for establishing, maintaining, and controlling connections to MicroPython devices over serial interfaces.
3

4
## Capabilities
5

6
### Device Connection
7

8
Connect to MicroPython devices with automatic port detection, device enumeration, and connection establishment.
9

10
```python { .api }
11
def do_connect(state, args=None):
12
    """
13
    Connect to MicroPython device.
14
    
15
    Parameters:
16
    - state: State object containing transport and connection info
17
    - args: Connection arguments with device specification
18
    
19
    Device specifications:
20
    - "auto": Auto-detect first available USB serial device
21
    - "list": List all available serial ports
22
    - "id:SERIAL": Connect to device with specific serial number
23
    - "port:PATH": Connect to specific port path
24
    - "/dev/ttyUSB0", "COM3", etc.: Direct device path
25
    """
26
```
27

28
Usage examples:
29

30
```python
31
from mpremote.main import State
32
from mpremote.commands import do_connect
33

34
# Auto-connect to first available device
35
state = State()
36
do_connect(state, type('Args', (), {'device': ['auto']})())
37

38
# Connect to specific port
39
do_connect(state, type('Args', (), {'device': ['/dev/ttyUSB0']})())
40

41
# List available devices
42
do_connect(state, type('Args', (), {'device': ['list']})())
43
```
44

45
### Device Disconnection
46

47
Safely disconnect from the current MicroPython device and clean up transport resources.
48

49
```python { .api }
50
def do_disconnect(state, _args=None):
51
    """
52
    Disconnect from current device.
53
    
54
    Parameters:
55
    - state: State object containing active transport
56
    """
57
```
58

59
### Device Reset Operations
60

61
Perform device reset operations to restart MicroPython without power cycling.
62

63
```python { .api }
64
def do_soft_reset(state, _args=None):
65
    """
66
    Perform soft reset of the MicroPython device.
67
    
68
    Parameters:
69
    - state: State object with active transport connection
70
    
71
    Sends Ctrl-C + Ctrl-D sequence to restart MicroPython interpreter.
72
    """
73
```
74

75
### Command Timing Control
76

77
Control timing between command execution with programmable delays.
78

79
```python { .api }
80
def do_sleep(state, args):
81
    """
82
    Sleep/delay before executing next command.
83
    
84
    Parameters:
85
    - state: State object (not used for sleep)
86
    - args: Sleep duration arguments
87
    
88
    Args attributes:
89
    - ms: List containing sleep duration in seconds (float)
90
    
91
    Useful for timing control in automated scripts.
92
    """
93
```
94

95
### Session Management
96

97
Manage connection sessions and resume previous connections without automatic resets.
98

99
```python { .api }
100
def do_resume(state, _args=None):
101
    """
102
    Resume previous mpremote session without auto soft-reset.
103
    
104
    Parameters:
105
    - state: State object for session management
106
    
107
    Useful for continuing work on a device without interrupting running code.
108
    """
109
```
110

111
## Command-Line Interface
112

113
### Connection Commands
114

115
```bash
116
# Auto-connect to first available device
117
mpremote connect auto
118
mpremote  # auto is default
119

120
# List available serial devices
121
mpremote connect list
122
mpremote devs  # shortcut
123

124
# Connect to specific device
125
mpremote connect /dev/ttyUSB0
126
mpremote connect COM3
127
mpremote connect id:334D335C3138
128
mpremote connect port:/dev/ttyACM0
129

130
# Device shortcuts (built-in)
131
mpremote a0  # /dev/ttyACM0
132
mpremote u0  # /dev/ttyUSB0  
133
mpremote c0  # COM0
134
```
135

136
### Session Management Commands
137

138
```bash
139
# Soft reset device
140
mpremote soft-reset
141

142
# Resume session without reset
143
mpremote resume
144

145
# Disconnect
146
mpremote disconnect
147

148
# Add delays between commands
149
mpremote connect auto sleep 2.5 exec "print('After delay')"
150
```
151

152
## Error Handling
153

154
Connection operations may raise the following exceptions:
155

156
- **TransportError**: Device connection failures, permission issues, device not found
157
- **CommandError**: Invalid device specifications or connection parameters
158

159
Common error scenarios:
160

161
```python
162
from mpremote.transport import TransportError
163
from mpremote.commands import CommandError
164

165
try:
166
    do_connect(state, args)
167
except TransportError as e:
168
    if "no device found" in str(e):
169
        print("No MicroPython devices detected")
170
    elif "failed to access" in str(e):
171
        print("Permission denied - check device permissions")
172
    else:
173
        print(f"Connection failed: {e}")
174
except CommandError as e:
175
    print(f"Invalid connection parameters: {e}")
176
```
177

178
## Device Detection
179

180
mpremote automatically detects MicroPython devices by:
181

182
1. Enumerating all available serial ports
183
2. Filtering for USB devices with valid VID/PID combinations
184
3. Attempting connection with standard MicroPython baud rates
185
4. Verifying MicroPython REPL response
186

187
Supported device types include:
188
- Raspberry Pi Pico and Pico W
189
- ESP32 and ESP8266 boards
190
- PyBoard and PyBoard D
191
- Generic MicroPython devices over USB serial