tessl/pypi-mpremote

Tool for interacting remotely with MicroPython devices

—

Pending

Overview

Eval results

Files

Package Management

Name: tessl/pypi-mpremote
Author: tessl

Install and manage MicroPython packages using the mip (MicroPython Package Installer) with support for multiple package sources including micropython-lib, GitHub, GitLab repositories, and custom package indexes.

Capabilities

Main Package Management Interface

Primary interface for package installation and management operations.

def do_mip(state, args):
    """
    Main MIP package management command.
    
    Parameters:
    - state: State object with active transport
    - args: Package management arguments
    
    Args attributes:
    - command: List containing mip command ('install')
    - packages: List of package specifications to install
    - target: Optional target directory on device
    - index: Optional custom package index URL
    - mpy: Boolean to download compiled .mpy files (default True)
    """

Package Installation

Install individual packages from various sources with dependency resolution and compilation options.

def _install_package(transport, package, index, target, version, mpy):
    """
    Install single package from specified source.
    
    Parameters:
    - transport: Active device transport
    - package: Package specification string
    - index: Package index URL (None for default micropython-lib)
    - target: Target directory on device (None for default)
    - version: Package version constraint
    - mpy: Whether to prefer compiled .mpy files
    
    Package specifications:
    - "package_name": Install from default index
    - "package_name@version": Install specific version
    - "github:user/repo": Install from GitHub repository
    - "github:user/repo@branch": Install from specific branch
    - "gitlab:user/repo": Install from GitLab repository
    - "gitlab:user/repo@branch": Install from specific branch
    """

JSON Package Installation

Install packages from JSON package descriptors with dependency management.

def _install_json(transport, package_json_url, index, target, version, mpy):
    """
    Install package from JSON descriptor.
    
    Parameters:
    - transport: Device transport connection
    - package_json_url: URL to package.json descriptor
    - index: Package index URL
    - target: Installation target directory
    - version: Version constraints
    - mpy: Compile to .mpy format flag
    
    Handles dependency resolution and recursive installation.
    """

File Download and Management

Download and manage package files with integrity checking and progress indication.

def _download_file(transport, url, dest):
    """
    Download file from URL to device.
    
    Parameters:
    - transport: Active device transport
    - url: Source file URL
    - dest: Destination path on device
    
    Handles HTTP/HTTPS downloads with progress indication
    and automatic retry on failure.
    """

def _check_exists(transport, path, short_hash):
    """
    Check if file exists on device with hash validation.
    
    Parameters:
    - transport: Device transport
    - path: File path on device
    - short_hash: Expected file hash for validation
    
    Returns:
    - bool: True if file exists with correct hash
    """

def _ensure_path_exists(transport, path):
    """
    Ensure directory path exists on device.
    
    Parameters:
    - transport: Device transport
    - path: Directory path to create
    
    Creates parent directories as needed.
    """

URL Processing

Process and rewrite URLs for accessing package repositories.

def _rewrite_url(url, branch=None):
    """
    Rewrite GitHub/GitLab URLs for raw file access.
    
    Parameters:
    - url: Repository URL
    - branch: Optional branch specification
    
    Returns:
    - str: Rewritten URL for direct file access
    
    Converts repository URLs to raw content URLs
    for direct file downloading.
    """

Command-Line Interface

Basic Package Installation

# Install packages from micropython-lib
mpremote mip install aioble
mpremote mip install urequests asyncio

# Install multiple packages
mpremote mip install aioble urequests micropython-logging

# Install specific versions
mpremote mip install aioble@1.0.0

GitHub and GitLab Installation

# Install from GitHub repositories
mpremote mip install github:micropython/micropython-lib
mpremote mip install github:user/awesome-micropython-lib

# Install from specific branches
mpremote mip install github:user/repo@development
mpremote mip install github:user/repo@feature-branch

# Install from GitLab
mpremote mip install gitlab:user/project
mpremote mip install gitlab:user/project@main

Installation Options

# Install to specific target directory
mpremote mip install --target /lib aioble

# Use custom package index
mpremote mip install --index https://custom-index.com/packages aioble

# Install as source files (no .mpy compilation)
mpremote mip install --no-mpy urequests

# Force .mpy compilation (default)
mpremote mip install --mpy aioble

Usage Examples

Programmatic Package Installation

from mpremote.main import State
from mpremote.mip import do_mip

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

# Install package programmatically
args = type('Args', (), {
    'command': ['install'],
    'packages': ['aioble', 'urequests'],
    'target': None,
    'index': None,
    'mpy': True
})()
do_mip(state, args)

Custom Package Index

# Use private package repository
mpremote mip install --index https://company.com/micropython-packages asyncio-mqtt

# Install development versions
mpremote mip install --index https://dev-packages.micropython.org/latest experimental-driver

Development Workflow Integration

# Install development dependencies
mpremote mip install --target /dev-lib unittest-micropython pytest-micropython

# Install from development repository
mpremote mip install github:developer/micropython-dev-tools@experimental

# Set up project dependencies
mpremote mip install \
  --target /lib \
  aioble \
  micropython-logging \
  urequests \
  github:project/custom-drivers@v2.1

Package Sources and Formats

MicroPython-lib (Default Index)

The default package source with curated MicroPython packages:

# Standard library packages
mpremote mip install asyncio
mpremote mip install logging
mpremote mip install unittest

# Networking packages  
mpremote mip install urequests
mpremote mip install umqtt.simple
mpremote mip install aioble

# Utility packages
mpremote mip install micropython-logging
mpremote mip install micropython-unittest

GitHub Repositories

Install directly from GitHub repositories:

# Repository formats
mpremote mip install github:owner/repository
mpremote mip install github:owner/repository@branch
mpremote mip install github:owner/repository@tag

# Examples
mpremote mip install github:micropython/micropython-lib
mpremote mip install github:peterhinch/micropython-async@master

GitLab Repositories

Install from GitLab repositories with same syntax:

# GitLab formats
mpremote mip install gitlab:owner/project
mpremote mip install gitlab:owner/project@branch

# Examples
mpremote mip install gitlab:company/micropython-drivers
mpremote mip install gitlab:team/iot-sensors@stable

Custom Package Indexes

Use custom package repositories:

# Corporate package index
mpremote mip install --index https://packages.company.com/micropython device-drivers

# Development index
mpremote mip install --index https://dev.micropython.org/packages experimental-features

Package Installation Process

Installation Steps

Package Resolution: Resolve package name to download URL
Dependency Analysis: Parse package.json for dependencies
Download: Fetch package files from source
Compilation: Optionally compile .py to .mpy files
Installation: Copy files to target directory on device
Verification: Validate file integrity and installation

File Formats

.py files: Source Python files
.mpy files: Compiled MicroPython bytecode (faster import, smaller size)
package.json: Package metadata and dependency information

Target Directories

Default installation locations:

Root: / (device root filesystem)
Library: /lib (recommended for libraries)
Custom: User-specified with --target option

Error Handling

Package management operations may encounter various errors:

from mpremote.transport import TransportError, TransportExecError

try:
    do_mip(state, args)
except TransportExecError as e:
    if "No space left" in e.error_output:
        print("Insufficient storage space on device")
    elif "404" in e.error_output:
        print("Package not found in repository")
    elif "Connection" in e.error_output:
        print("Network connection failed")
except TransportError as e:
    print(f"Device communication error: {e}")

Common Error Scenarios

# Package not found
mpremote mip install nonexistent-package
# Error: Package not found in index

# Network connectivity issues
mpremote mip install github:user/private-repo
# Error: Repository not accessible

# Storage space issues
mpremote mip install large-package
# Error: No space left on device

# Version conflicts
mpremote mip install package@999.0.0
# Error: Version not available

Best Practices

Package Management Strategy

# Install to dedicated library directory
mpremote mip install --target /lib core-libraries

# Use version pinning for production
mpremote mip install aioble@1.2.3 urequests@0.6

# Prefer compiled packages for performance
mpremote mip install --mpy performance-critical-lib

Development vs Production

# Development: source files for debugging
mpremote mip install --no-mpy --target /dev-lib debug-tools

# Production: compiled files for efficiency  
mpremote mip install --mpy --target /lib production-libs

Dependency Management

# Install project dependencies from requirements
cat micropython-requirements.txt | while read package; do
    mpremote mip install "$package"
done

# Verify installations
mpremote exec "
import sys
print('Installed packages:')
for module in sys.modules:
    print(' ', module)
"

Install with Tessl CLI