or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-reference.mdcode-execution.mddevice-config.mddevice-connection.mdfilesystem.mdindex.mdmounting.mdpackage-management.mdrepl.mdromfs.md
tile.json

tessl/pypi-mpremote

Tool for interacting remotely with MicroPython devices

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/mpremote@1.26.x

To install, run

npx @tessl/cli install tessl/pypi-mpremote@1.26.0

index.mddocs/

mpremote

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.

Package Information

  • Package Name: mpremote
  • Package Type: pypi
  • Language: Python
  • Installation: pip install mpremote
  • Requirements: Python ≥3.4

Core Imports

Import the main entry point:

from mpremote.main import main

Import core classes and functions for programmatic use:

from mpremote.commands import (
    do_connect, do_disconnect, do_filesystem, do_exec, do_eval, do_run,
    do_mount, do_umount, do_repl, do_edit, do_mip, do_rtc, do_romfs, CommandError
)
from mpremote.main import do_sleep, State
from mpremote.transport import Transport, TransportError, TransportExecError
from mpremote.transport_serial import SerialTransport
from mpremote.romfs import VfsRomWriter
from mpremote.console import ConsolePosix, ConsoleWindows

Basic Usage

Basic command-line usage:

# Auto-connect and enter REPL
mpremote

# Connect to specific device
mpremote connect /dev/ttyUSB0

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

# File operations
mpremote ls
mpremote cp main.py :
mpremote cat :boot.py

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

# Install packages
mpremote mip install aioble

# Device shortcuts
mpremote a0  # /dev/ttyACM0
mpremote u1  # /dev/ttyUSB1  
mpremote c0  # COM0

# System information
mpremote df  # Show disk usage

Programmatic usage:

from mpremote.transport_serial import SerialTransport
from mpremote.commands import do_connect, do_exec
from mpremote.main import State

# Create transport and state
state = State()
transport = SerialTransport("/dev/ttyUSB0", baudrate=115200)
state.transport = transport

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

Architecture

mpremote follows a modular architecture with clear separation of concerns:

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

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

Capabilities

Device Connection and Management

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

def do_connect(state, args=None):
    """Connect to MicroPython device"""

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

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

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

def do_sleep(state, args):
    """Sleep/delay before executing next command"""

Device Connection

Filesystem Operations

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

def do_filesystem(state, args):
    """Main filesystem command dispatcher"""

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

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

def do_edit(state, args):
    """Edit files on device using system editor"""

Filesystem Operations

Code Execution

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

def do_exec(state, args):
    """Execute Python code string on device"""

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

def do_run(state, args):
    """Run local Python script on device"""

Code Execution

REPL Interface

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

def do_repl(state, args):
    """Enter interactive REPL mode"""

def do_repl_main_loop(transport, console_in, console_out_real, *, 
                     escape_non_printable, capture_file, inject_code, inject_file):
    """Main REPL loop implementation"""

REPL Interface

Package Management

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

def do_mip(state, args):
    """Main MIP package management command"""

def _install_package(transport, package, index, target, version, mpy):
    """Install single package from specified source"""

Package Management

File System Mounting

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

def do_mount(state, args):
    """Mount local directory on device"""

def do_umount(state, path):
    """Unmount local directory"""

File System Mounting

Device Configuration

Configure device settings including real-time clock synchronization.

def do_rtc(state, args):
    """Get or set device real-time clock"""

Device Configuration

ROM Filesystem Management

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

def do_romfs(state, args):
    """Main ROMFS command dispatcher"""

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

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

def _do_romfs_deploy(state, args):
    """Deploy ROM filesystem to device partition"""

ROM Filesystem

CLI Reference and Configuration

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

def main(argv=None):
    """Main mpremote CLI entry point"""

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

def do_version(state, args):
    """Display version information"""

CLI Reference and Configuration

Types

class State:
    """Application state management"""
    def __init__(self):
        self.transport = None
        self._did_action = False
    
    def did_action(self):
        """Mark that an action was performed"""
    
    def ensure_connected(self):
        """Ensure device is connected"""
    
    def ensure_raw_repl(self, soft_reset=None):
        """Ensure device is in raw REPL mode"""
    
    def ensure_friendly_repl(self):
        """Ensure device is in friendly REPL mode"""

class Transport:
    """Abstract transport interface"""
    def fs_listdir(self, src=""):
        """List directory contents"""
    
    def fs_stat(self, src):
        """Get file/directory statistics"""
    
    def fs_exists(self, src):
        """Check if file/directory exists"""
    
    def fs_isdir(self, src):
        """Check if path is a directory"""
    
    def fs_readfile(self, src, chunk_size=256, progress_callback=None):
        """Read file from device"""
    
    def fs_writefile(self, dest, data, chunk_size=256, progress_callback=None):
        """Write file to device"""
    
    def fs_mkdir(self, path):
        """Create directory"""
    
    def fs_rmdir(self, path):
        """Remove directory"""
    
    def fs_rmfile(self, path):
        """Remove file"""
    
    def fs_touchfile(self, path):
        """Create/touch file"""
    
    def fs_hashfile(self, path, algo, chunk_size=256):
        """Calculate file hash"""
    
    def exec(self, code, data_consumer=None, stream_output=False):
        """Execute code on device"""

class SerialTransport(Transport):
    """Serial transport implementation"""
    fs_hook_mount = "/remote"  # Mount point constant
    
    def __init__(self, device, baudrate=115200, wait=0, exclusive=True, timeout=None):
        """Initialize serial connection"""
    
    def enter_raw_repl(self):
        """Enter raw REPL mode"""
    
    def exit_raw_repl(self):
        """Exit raw REPL mode"""
    
    def exec_raw(self, command, data_consumer=None, stream_output=False):
        """Execute command in raw REPL mode"""
    
    def mount_local(self, path, readonly=False, unsafe_links=False):
        """Mount local directory on device"""
    
    def umount_local(self):
        """Unmount local directory"""

class CommandError(Exception):
    """Command execution error"""

class TransportError(Exception):
    """Transport communication error"""

class TransportExecError(TransportError):
    """Code execution error with status"""
    def __init__(self, status_code, error_output):
        self.status_code = status_code
        self.error_output = error_output

class VfsRomWriter:
    """ROM filesystem writer"""
    ROMFS_HEADER = b"\\xd2\\xcd\\x31"
    ROMFS_RECORD_KIND_FILE = 1
    ROMFS_RECORD_KIND_DIR = 2
    
    def __init__(self, f, mpy_enabled=True):
        """Initialize ROM filesystem writer"""
    
    def add_file(self, path, data, mtime=0):
        """Add file to ROM filesystem"""
    
    def add(self, src_dir, exclude=lambda path: False):
        """Add directory contents to ROM filesystem"""

class ConsolePosix:
    """POSIX console interface for REPL"""
    
class ConsoleWindows:
    """Windows console interface for REPL"""