0
# mpremote
1

2
A comprehensive command-line interface tool for remote interaction and automation with MicroPython devices over serial connections. mpremote provides developers with an integrated set of utilities including automatic USB serial port detection, interactive REPL access, filesystem operations, code execution capabilities, local directory mounting, and package management through mip integration.
3

4
## Package Information
5

6
- **Package Name**: mpremote
7
- **Package Type**: pypi  
8
- **Language**: Python
9
- **Installation**: `pip install mpremote`
10
- **Requirements**: Python ≥3.4
11

12
## Core Imports
13

14
Import the main entry point:
15

16
```python
17
from mpremote.main import main
18
```
19

20
Import core classes and functions for programmatic use:
21

22
```python
23
from mpremote.commands import (
24
    do_connect, do_disconnect, do_filesystem, do_exec, do_eval, do_run,
25
    do_mount, do_umount, do_repl, do_edit, do_mip, do_rtc, do_romfs, CommandError
26
)
27
from mpremote.main import do_sleep, State
28
from mpremote.transport import Transport, TransportError, TransportExecError
29
from mpremote.transport_serial import SerialTransport
30
from mpremote.romfs import VfsRomWriter
31
from mpremote.console import ConsolePosix, ConsoleWindows
32
```
33

34
## Basic Usage
35

36
Basic command-line usage:
37

38
```bash
39
# Auto-connect and enter REPL
40
mpremote
41

42
# Connect to specific device
43
mpremote connect /dev/ttyUSB0
44

45
# Execute Python code
46
mpremote exec "print('Hello from MicroPython!')"
47

48
# File operations
49
mpremote ls
50
mpremote cp main.py :
51
mpremote cat :boot.py
52

53
# Mount local directory for development
54
mpremote mount . exec "import my_script"
55

56
# Install packages
57
mpremote mip install aioble
58

59
# Device shortcuts
60
mpremote a0  # /dev/ttyACM0
61
mpremote u1  # /dev/ttyUSB1  
62
mpremote c0  # COM0
63

64
# System information
65
mpremote df  # Show disk usage
66
```
67

68
Programmatic usage:
69

70
```python
71
from mpremote.transport_serial import SerialTransport
72
from mpremote.commands import do_connect, do_exec
73
from mpremote.main import State
74

75
# Create transport and state
76
state = State()
77
transport = SerialTransport("/dev/ttyUSB0", baudrate=115200)
78
state.transport = transport
79

80
# Execute code on device
81
do_exec(state, type('Args', (), {'expr': ['print("Hello!")'], 'follow': True})())
82
```
83

84
## Architecture
85

86
mpremote follows a modular architecture with clear separation of concerns:
87

88
- **Transport Layer**: Abstracts device communication (serial, future network protocols)
89
- **Command Layer**: Implements high-level operations (filesystem, execution, REPL)
90
- **CLI Layer**: Provides command-line interface with argument parsing and shortcuts
91
- **State Management**: Maintains connection state and configuration across commands
92
- **Configuration System**: Supports user-defined shortcuts and macros
93

94
The design enables both CLI usage and programmatic integration, with extensible transport mechanisms and comprehensive error handling.
95

96
## Capabilities
97

98
### Device Connection and Management
99

100
Connect to, disconnect from, and manage MicroPython devices with automatic port detection and device identification.
101

102
```python { .api }
103
def do_connect(state, args=None):
104
    """Connect to MicroPython device"""
105

106
def do_disconnect(state, _args=None):
107
    """Disconnect from current device"""
108

109
def do_soft_reset(state, _args=None):
110
    """Perform soft reset of device"""
111

112
def do_resume(state, _args=None):
113
    """Resume previous session without auto soft-reset"""
114

115
def do_sleep(state, args):
116
    """Sleep/delay before executing next command"""
117
```
118

119
[Device Connection](./device-connection.md)
120

121
### Filesystem Operations
122

123
Comprehensive filesystem operations including file transfer, directory management, and tree display with progress indication and hash verification.
124

125
```python { .api }
126
def do_filesystem(state, args):
127
    """Main filesystem command dispatcher"""
128

129
def do_filesystem_cp(state, src, dest, multiple, check_hash=False):
130
    """Copy files between local and remote filesystems"""
131

132
def do_filesystem_tree(state, path, args):
133
    """Display directory tree structure"""
134

135
def do_edit(state, args):
136
    """Edit files on device using system editor"""
137
```
138

139
[Filesystem Operations](./filesystem.md)
140

141
### Code Execution
142

143
Execute Python code on MicroPython devices with support for expressions, scripts, and file execution with output streaming.
144

145
```python { .api }
146
def do_exec(state, args):
147
    """Execute Python code string on device"""
148

149
def do_eval(state, args):
150
    """Evaluate Python expression and print result"""
151

152
def do_run(state, args):
153
    """Run local Python script on device"""
154
```
155

156
[Code Execution](./code-execution.md)
157

158
### REPL Interface
159

160
Interactive Read-Eval-Print Loop with advanced features including output capture, code injection, and escape sequence handling.
161

162
```python { .api }
163
def do_repl(state, args):
164
    """Enter interactive REPL mode"""
165

166
def do_repl_main_loop(transport, console_in, console_out_real, *, 
167
                     escape_non_printable, capture_file, inject_code, inject_file):
168
    """Main REPL loop implementation"""
169
```
170

171
[REPL Interface](./repl.md)
172

173
### Package Management
174

175
Install and manage MicroPython packages using mip with support for multiple package sources including micropython-lib, GitHub, and GitLab repositories.
176

177
```python { .api }
178
def do_mip(state, args):
179
    """Main MIP package management command"""
180

181
def _install_package(transport, package, index, target, version, mpy):
182
    """Install single package from specified source"""
183
```
184

185
[Package Management](./package-management.md)
186

187
### File System Mounting
188

189
Mount local directories on MicroPython devices for seamless development workflows with support for symbolic links and safety options.
190

191
```python { .api }
192
def do_mount(state, args):
193
    """Mount local directory on device"""
194

195
def do_umount(state, path):
196
    """Unmount local directory"""
197
```
198

199
[File System Mounting](./mounting.md)
200

201
### Device Configuration
202

203
Configure device settings including real-time clock synchronization.
204

205
```python { .api }
206
def do_rtc(state, args):
207
    """Get or set device real-time clock"""
208
```
209

210
[Device Configuration](./device-config.md)
211

212
### ROM Filesystem Management
213

214
Manage ROM filesystem partitions with query, build, and deploy operations for optimized code storage on MicroPython devices.
215

216
```python { .api }
217
def do_romfs(state, args):
218
    """Main ROMFS command dispatcher"""
219

220
def _do_romfs_query(state, args):
221
    """Query ROM filesystem partition information"""
222

223
def _do_romfs_build(state, args):
224
    """Build ROM filesystem from directory"""
225

226
def _do_romfs_deploy(state, args):
227
    """Deploy ROM filesystem to device partition"""
228
```
229

230
[ROM Filesystem](./romfs.md)
231

232
### CLI Reference and Configuration
233

234
Complete command-line interface with built-in shortcuts, command chaining, and user configuration system for streamlined development workflows.
235

236
```python { .api }
237
def main(argv=None):
238
    """Main mpremote CLI entry point"""
239

240
def do_help(state, args):
241
    """Display help information"""
242

243
def do_version(state, args):
244
    """Display version information"""
245
```
246

247
[CLI Reference and Configuration](./cli-reference.md)
248

249
## Types
250

251
```python { .api }
252
class State:
253
    """Application state management"""
254
    def __init__(self):
255
        self.transport = None
256
        self._did_action = False
257
    
258
    def did_action(self):
259
        """Mark that an action was performed"""
260
    
261
    def ensure_connected(self):
262
        """Ensure device is connected"""
263
    
264
    def ensure_raw_repl(self, soft_reset=None):
265
        """Ensure device is in raw REPL mode"""
266
    
267
    def ensure_friendly_repl(self):
268
        """Ensure device is in friendly REPL mode"""
269

270
class Transport:
271
    """Abstract transport interface"""
272
    def fs_listdir(self, src=""):
273
        """List directory contents"""
274
    
275
    def fs_stat(self, src):
276
        """Get file/directory statistics"""
277
    
278
    def fs_exists(self, src):
279
        """Check if file/directory exists"""
280
    
281
    def fs_isdir(self, src):
282
        """Check if path is a directory"""
283
    
284
    def fs_readfile(self, src, chunk_size=256, progress_callback=None):
285
        """Read file from device"""
286
    
287
    def fs_writefile(self, dest, data, chunk_size=256, progress_callback=None):
288
        """Write file to device"""
289
    
290
    def fs_mkdir(self, path):
291
        """Create directory"""
292
    
293
    def fs_rmdir(self, path):
294
        """Remove directory"""
295
    
296
    def fs_rmfile(self, path):
297
        """Remove file"""
298
    
299
    def fs_touchfile(self, path):
300
        """Create/touch file"""
301
    
302
    def fs_hashfile(self, path, algo, chunk_size=256):
303
        """Calculate file hash"""
304
    
305
    def exec(self, code, data_consumer=None, stream_output=False):
306
        """Execute code on device"""
307

308
class SerialTransport(Transport):
309
    """Serial transport implementation"""
310
    fs_hook_mount = "/remote"  # Mount point constant
311
    
312
    def __init__(self, device, baudrate=115200, wait=0, exclusive=True, timeout=None):
313
        """Initialize serial connection"""
314
    
315
    def enter_raw_repl(self):
316
        """Enter raw REPL mode"""
317
    
318
    def exit_raw_repl(self):
319
        """Exit raw REPL mode"""
320
    
321
    def exec_raw(self, command, data_consumer=None, stream_output=False):
322
        """Execute command in raw REPL mode"""
323
    
324
    def mount_local(self, path, readonly=False, unsafe_links=False):
325
        """Mount local directory on device"""
326
    
327
    def umount_local(self):
328
        """Unmount local directory"""
329

330
class CommandError(Exception):
331
    """Command execution error"""
332

333
class TransportError(Exception):
334
    """Transport communication error"""
335

336
class TransportExecError(TransportError):
337
    """Code execution error with status"""
338
    def __init__(self, status_code, error_output):
339
        self.status_code = status_code
340
        self.error_output = error_output
341

342
class VfsRomWriter:
343
    """ROM filesystem writer"""
344
    ROMFS_HEADER = b"\\xd2\\xcd\\x31"
345
    ROMFS_RECORD_KIND_FILE = 1
346
    ROMFS_RECORD_KIND_DIR = 2
347
    
348
    def __init__(self, f, mpy_enabled=True):
349
        """Initialize ROM filesystem writer"""
350
    
351
    def add_file(self, path, data, mtime=0):
352
        """Add file to ROM filesystem"""
353
    
354
    def add(self, src_dir, exclude=lambda path: False):
355
        """Add directory contents to ROM filesystem"""
356

357
class ConsolePosix:
358
    """POSIX console interface for REPL"""
359
    
360
class ConsoleWindows:
361
    """Windows console interface for REPL"""
362
```