tessl/pypi-mpremote

Tool for interacting remotely with MicroPython devices

—

Pending

Overview

Eval results

Files

Filesystem Operations

Name: tessl/pypi-mpremote
Author: tessl

Comprehensive filesystem operations for managing files and directories on MicroPython devices, including file transfer, directory manipulation, and content inspection.

Capabilities

Main Filesystem Command Dispatcher

Central dispatcher for all filesystem operations with support for various commands and options.

def do_filesystem(state, args):
    """
    Execute filesystem commands on the device.
    
    Parameters:
    - state: State object with active transport
    - args: Arguments containing command and paths
    
    Supported commands: cat, ls, cp, rm, mkdir, rmdir, sha256sum, touch, tree
    """

File Copy Operations

Copy files and directories between local filesystem and MicroPython device with progress indication and hash verification.

def do_filesystem_cp(state, src, dest, multiple, check_hash=False):
    """
    Copy files between local and remote filesystems.
    
    Parameters:
    - state: State object with transport
    - src: Source file/directory path
    - dest: Destination path  
    - multiple: Whether copying multiple files
    - check_hash: Verify file integrity with SHA256
    
    Path prefixes:
    - ":" prefix indicates remote device path
    - No prefix indicates local filesystem path
    """

def do_filesystem_recursive_cp(state, src, dest, multiple, check_hash):
    """
    Recursively copy directories with all contents.
    
    Parameters:
    - state: State object with transport
    - src: Source directory path
    - dest: Destination directory path
    - multiple: Multiple file operation flag
    - check_hash: Hash verification flag
    """

File and Directory Management

Create, remove, and manage files and directories on the device filesystem.

def do_filesystem_recursive_rm(state, path, args):
    """
    Recursively remove directories and contents.
    
    Parameters:
    - state: State object with transport
    - path: Directory path to remove
    - args: Command arguments with options
    """

Directory Tree Display

Display directory structure in tree format with optional file sizes and human-readable formatting.

def do_filesystem_tree(state, path, args):
    """
    Display directory tree structure.
    
    Parameters:
    - state: State object with transport  
    - path: Root path for tree display
    - args: Display options (size, human-readable)
    """

File Editing

Edit files on the device using the system's default editor with automatic download/upload.

def do_edit(state, args):
    """
    Edit files on the device using system editor.
    
    Parameters:
    - state: State object with active transport
    - args: Arguments containing file paths to edit
    
    Args attributes:
    - files: List of remote file paths to edit (use : prefix)
    
    Downloads files to temporary location, opens in $EDITOR,
    and uploads changes back to device on save.
    """

Utility Functions

Helper functions for filesystem operations and user feedback.

def show_progress_bar(size, total_size, op="copying"):
    """
    Display progress bar for file operations.
    
    Parameters:
    - size: Current bytes transferred
    - total_size: Total bytes to transfer
    - op: Operation description
    """

def human_size(size, decimals=1):
    """
    Format file size in human-readable format.
    
    Parameters:
    - size: Size in bytes
    - decimals: Decimal places for formatting
    
    Returns:
    - str: Formatted size (e.g., "1.5 MB", "256 KB")
    """

Path Utilities

Remote path manipulation utilities for device filesystem operations.

def _remote_path_join(a, *b):
    """
    Join remote filesystem paths.
    
    Parameters:
    - a: Base path
    - b: Additional path components
    
    Returns:
    - str: Joined path using forward slashes
    """

def _remote_path_dirname(a):
    """
    Get directory name of remote path.
    
    Parameters:
    - a: Path string
    
    Returns:
    - str: Directory portion of path
    """

def _remote_path_basename(a):
    """
    Get base name of remote path.
    
    Parameters:
    - a: Path string
    
    Returns:
    - str: Base filename
    """

Command-Line Interface

File Operations

# List directory contents
mpremote ls
mpremote ls :lib  # list remote directory
mpremote fs ls -l  # detailed listing

# Display file contents
mpremote cat :main.py
mpremote fs cat boot.py

# Copy files
mpremote cp main.py :              # local to device
mpremote cp :main.py .             # device to local  
mpremote cp -r src/ :              # recursive copy
mpremote cp -f main.py :main.py    # force overwrite

# File operations
mpremote rm :old_file.py
mpremote mkdir :new_dir
mpremote rmdir :empty_dir
mpremote touch :new_file.py

# Edit files on device
mpremote edit :main.py           # Edit single file
mpremote edit :boot.py :main.py  # Edit multiple files

Directory Operations

# Recursive operations
mpremote rm -r :old_directory
mpremote cp -r local_dir/ :remote_dir/

# Directory tree display
mpremote tree
mpremote fs tree :lib
mpremote fs tree -s :lib    # show sizes
mpremote fs tree -h :lib    # human-readable sizes

File Verification

# Calculate file hashes
mpremote sha256sum :main.py
mpremote fs sha256sum boot.py main.py

# Show disk usage information
mpremote df

# Copy with hash verification
mpremote fs cp --force main.py :main.py  # verifies by default

Usage Examples

Basic File Management

from mpremote.main import State
from mpremote.commands import do_filesystem

# Set up state with connected device
state = State()
# ... connect to device ...

# List root directory
args = type('Args', (), {
    'command': ['ls'],
    'path': [':'],
    'recursive': False,
    'verbose': True
})()
do_filesystem(state, args)

# Copy local file to device
args = type('Args', (), {
    'command': ['cp'],
    'path': ['main.py', ':main.py'],
    'recursive': False,
    'force': False
})()
do_filesystem(state, args)

Directory Tree Exploration

# Display directory tree with sizes
args = type('Args', (), {
    'command': ['tree'],
    'path': [':'],
    'size': True,
    'human': False,
    'verbose': True
})()
do_filesystem(state, args)

Path Conventions

mpremote uses specific path conventions to distinguish between local and remote paths:

Remote paths: Prefixed with : (e.g., :main.py, :lib/module.py)
Local paths: No prefix (e.g., main.py, src/module.py)
Current directory: . for local, : for remote root

Error Handling

Filesystem operations may encounter various error conditions:

from mpremote.transport import TransportError, TransportExecError

try:
    do_filesystem(state, args)
except TransportExecError as e:
    if "ENOENT" in e.error_output:
        print("File or directory not found")
    elif "EACCES" in e.error_output:
        print("Permission denied")
    elif "ENOSPC" in e.error_output:
        print("No space left on device")
except TransportError as e:
    print(f"Communication error: {e}")