Tool for interacting remotely with MicroPython devices
npx @tessl/cli install tessl/pypi-mpremote@1.26.0A 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.
pip install mpremoteImport the main entry point:
from mpremote.main import mainImport 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, ConsoleWindowsBasic 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 usageProgrammatic 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})())mpremote follows a modular architecture with clear separation of concerns:
The design enables both CLI usage and programmatic integration, with extensible transport mechanisms and comprehensive error handling.
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"""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"""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"""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"""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"""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"""Configure device settings including real-time clock synchronization.
def do_rtc(state, args):
"""Get or set device real-time clock"""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"""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
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"""