tessl/pypi-mpremote

Tool for interacting remotely with MicroPython devices

—

Pending

Overview

Eval results

Files

ROM Filesystem Management

Name: tessl/pypi-mpremote
Author: tessl

Manage ROM filesystem partitions for MicroPython devices, enabling efficient storage and deployment of Python code and data files directly in device ROM memory.

Capabilities

ROMFS Command Dispatcher

Main command dispatcher for ROM filesystem operations with query, build, and deploy subcommands.

def do_romfs(state, args):
    """
    Execute ROMFS operations on device.
    
    Parameters:
    - state: State object with active transport
    - args: Arguments containing subcommand and options
    
    Subcommands: query, build, deploy
    """

Query ROMFS Information

Query existing ROM filesystem partitions and their contents on the device.

def _do_romfs_query(state, args):
    """
    Query ROM filesystem partition information.
    
    Parameters:
    - state: State object with transport
    - args: Query options including partition specification
    
    Args attributes:
    - partition: List containing partition number (default: 0)
    """

Build ROMFS from Directory

Build ROM filesystem images from local directory structures with optional bytecode compilation.

def _do_romfs_build(state, args):
    """
    Build ROM filesystem from directory.
    
    Parameters:
    - state: State object (not used for build)
    - args: Build arguments and options
    
    Args attributes:
    - path: List containing source directory path
    - output: Output file path for ROM filesystem image
    - mpy: Boolean to compile .py files to .mpy bytecode (default: True)
    """

Deploy ROMFS to Device

Deploy ROM filesystem images to device partitions with verification.

def _do_romfs_deploy(state, args):
    """
    Deploy ROM filesystem to device partition.
    
    Parameters:
    - state: State object with active transport
    - args: Deploy options including source and partition
    
    Args attributes:
    - path: List containing ROM filesystem image path
    - partition: Partition number for deployment (default: 0)
    """

Command-Line Interface

Query ROMFS Information

# Query default partition (0)
mpremote romfs query

# Query specific partition
mpremote romfs query --partition 1
mpremote romfs query -p 2

Build ROMFS Image

# Build from current directory with default output
mpremote romfs build .

# Build with custom output file
mpremote romfs build --output firmware.romfs src/

# Build without bytecode compilation
mpremote romfs build --no-mpy src/

# Build with specific options
mpremote romfs build -o custom.romfs -m src/

Deploy ROMFS to Device

# Deploy to default partition
mpremote romfs deploy firmware.romfs

# Deploy to specific partition
mpremote romfs deploy --partition 1 firmware.romfs
mpremote romfs deploy -p 2 custom.romfs

Usage Examples

Basic ROMFS Workflow

from mpremote.main import State
from mpremote.commands import do_romfs

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

# Query existing ROMFS partitions
args = type('Args', (), {
    'command': ['query'],
    'partition': [0]
})()
do_romfs(state, args)

# Build ROMFS from directory
args = type('Args', (), {
    'command': ['build'],
    'path': ['./src'],
    'output': 'app.romfs',
    'mpy': True
})()
do_romfs(state, args)

# Deploy to device
args = type('Args', (), {
    'command': ['deploy'],
    'path': ['app.romfs'],
    'partition': [0]
})()
do_romfs(state, args)

Development Workflow

# Typical development cycle
mpremote connect auto

# Build application from source
mpremote romfs build --output app.romfs src/

# Deploy to device partition 1
mpremote romfs deploy --partition 1 app.romfs

# Query to verify deployment
mpremote romfs query --partition 1

# Test application
mpremote exec "
import sys
sys.path.insert(0, '/romfs1')
import main
main.run()
"

Advanced Usage

# Build without bytecode compilation for debugging
mpremote romfs build --no-mpy --output debug.romfs src/

# Deploy multiple partitions
mpremote romfs build -o core.romfs core/ 
mpremote romfs deploy -p 0 core.romfs
mpremote romfs build -o app.romfs app/
mpremote romfs deploy -p 1 app.romfs

# Verify deployments
mpremote romfs query -p 0
mpremote romfs query -p 1

ROM Filesystem Structure

ROM filesystems use a compact binary format optimized for embedded systems:

File Organization

Header: ROM filesystem signature and metadata
Directory entries: Hierarchical directory structure
File data: Compressed file contents with optional bytecode

Supported Files

Python source: .py files (optionally compiled to .mpy)
Data files: Any binary or text data files
Subdirectories: Nested directory structures

Bytecode Compilation

When --mpy is enabled (default):

Python .py files are compiled to .mpy bytecode
Reduces memory usage and improves load performance
Maintains source code compatibility

Error Handling

ROMFS operations may encounter various error conditions:

from mpremote.transport import TransportError, TransportExecError

try:
    do_romfs(state, args)
except TransportExecError as e:
    if "partition not found" in e.error_output:
        print("Invalid partition number")
    elif "insufficient space" in e.error_output: 
        print("Not enough ROM space for filesystem")
    elif "verification failed" in e.error_output:
        print("ROMFS image verification failed")
except TransportError as e:
    print(f"Communication error: {e}")
except FileNotFoundError:
    print("Source directory or ROMFS image not found")

Integration with MicroPython

Accessing ROMFS Content

# Add ROMFS partition to Python path
import sys
sys.path.insert(0, '/romfs0')  # Partition 0
sys.path.insert(0, '/romfs1')  # Partition 1

# Import modules from ROMFS
import my_module
from config import settings

ROMFS Mount Points

MicroPython automatically mounts ROM filesystems at:

/romfs0 - Partition 0 (default)
/romfs1 - Partition 1
/romfs2 - Partition 2
etc.

Performance Benefits

ROMFS provides several advantages:

Fast access: Direct ROM access without filesystem overhead
Memory efficiency: Compressed storage and optional bytecode
Reliability: Read-only, corruption-resistant storage
Boot speed: Faster startup compared to flash filesystem

Best Practices

Directory Organization

# Organize source for optimal ROMFS structure
project/
├── main.py          # Application entry point
├── config.py        # Configuration
├── lib/            # Libraries
│   ├── module1.py
│   └── module2.py
└── data/           # Data files
    ├── config.json
    └── assets/

Build Process

# Use consistent build process
mpremote romfs build --output release.romfs --mpy project/
mpremote romfs deploy --partition 1 release.romfs

# Verify deployment
mpremote romfs query --partition 1
mpremote exec "import sys; print(sys.path)"

Testing

# Test ROMFS content after deployment
mpremote exec "
import os
print('ROMFS contents:')
for item in os.listdir('/romfs1'):
    print(f'  {item}')
"

# Test module imports
mpremote exec "
try:
    import main
    print('Main module loaded successfully')
except ImportError as e:
    print(f'Import failed: {e}')
"

Install with Tessl CLI