Getting Started with mpremote for MicroPython

Introduction to mpremote

If you’re working with MicroPython on microcontrollers, you’ll often need a convenient way to interact with your device from your computer. This is where mpremote comes in. mpremote is a command-line tool that allows you to remotely control and interact with MicroPython boards over USB or serial connections.

What is mpremote?

mpremote is an official tool provided by the MicroPython project. It enables you to:

• Run Python code directly on your MicroPython device from your computer.
• Upload and download files to and from the device.
• Access the REPL (interactive prompt) easily.
• Automate tasks such as flashing scripts, managing files, and more.

Why use mpremote?

• Convenience: No need to manually copy files or use less user-friendly serial tools.
• Automation: Easily script repetitive tasks for development or deployment.
• Cross-platform: Works on Linux, Windows, and macOS.
• Official support: Maintained by the MicroPython team, ensuring compatibility and updates.

Installing mpremote

On Ubuntu and Debian-based systems, you can install mpremote using the package manager. Here’s how you can search for and install it:

# Search for mpremote package in apt
sudo apt search mpremote

# Example output:
# micropython-mpremote/noble,now 0.4.0-0ubuntu1 all [installed]
#   Tool for interacting remotely with MicroPython on a microcontroller

# Install mpremote
sudo apt install micropython-mpremote

# Example output:
# Reading package lists... Done
# Building dependency tree... Done
# Reading state information... Done
# micropython-mpremote is already the newest version (0.4.0-0ubuntu1).
# 0 upgraded, 0 newly installed, 0 to remove and 7 not upgraded.

If you’re using another operating system, you can also install mpremote via pip:

pip install mpremote

mpremote Command Overview

Once installed, you can use the mpremote command to interact with your MicroPython device. Here’s how to get help and list available devices:

# Show help and available commands
mpremote help

Example output:

mpremote -- MicroPython remote control
See https://docs.micropython.org/en/latest/reference/mpremote.html

List of commands:
  connect     connect to given device
  disconnect  disconnect current device
  edit        edit files on the device
  eval        evaluate and print the string
  exec        execute the string
  fs          execute filesystem commands on the device
  help        print help and exit
  mip         install packages from micropython-lib or third-party sources
  mount       mount local directory on device
  repl        connect to given device
  resume      resume a previous mpremote session (will not auto soft-reset)
  run         run the given local script
  soft-reset  perform a soft-reset of the device
  umount      unmount the local directory
  version     print version and exit

See the full official documentation here.

To list available USB devices and MicroPython boards:

> **Note:** `lsusb` is a built-in Ubuntu/Linux command for listing all USB devices. It is not part of mpremote, but is useful for confirming your board is connected.

<div class="code-header">
  <button class="copy-code-button" aria-label="Copy code to clipboard" title="Copy code">
    <svg width="16" height="16" fill="currentColor" aria-hidden="true" focusable="false" viewBox="0 0 16 16">
      <path d="M10 1.5A1.5 1.5 0 0 1 11.5 3v1H13a2 2 0 0 1 2 2v7a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2v-1.5H4A1.5 1.5 0 0 1 2.5 9V3A1.5 1.5 0 0 1 4 1.5h6zm1.5 3V3A.5.5 0 0 0 11 2.5H4A.5.5 0 0 0 3.5 3v6A.5.5 0 0 0 4 9.5h.5V6a2 2 0 0 1 2-2h5z"/>
    </svg>
    <span class="copy-label">Copy</span>
  </button>
</div>
```bash
lsusb
mpremote connect list

Example lsusb output:

Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 002: ID 2109:3431 VIA Labs, Inc. Hub
Bus 001 Device 003: ID 2e8a:0005 MicroPython Board in FS mode
Bus 001 Device 004: ID 03e7:2485 Intel Movidius MyriadX
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

Example mpremote connect list output:

/dev/ttyACM0 e66164084361382d 2e8a:0005 MicroPython Board in FS mode
/dev/ttyS0 None 0000:0000 None None

Connecting to Your Board and Checking MicroPython Version

To connect to your MicroPython board, use the appropriate shortcut or device path. For example, to connect to /dev/ttyACM0 (often the default for many boards):

mpremote a0

Example output:

Connected to MicroPython at /dev/ttyACM0
Use Ctrl-] to exit this shell

>>> import machine
>>> 

Once connected, you can run Python commands directly in the REPL. To check your MicroPython version, enter:

import sys
print(sys.implementation)
(name='micropython', version=(1, 25, 0, ''), _machine='Raspberry Pi Pico W with RP2040', _mpy=4870, _build='RPI_PICO_W')
>>>

This will display the MicroPython version and build info for your board.

Managing Files and Resetting the Board

You can use mpremote to manage files on your MicroPython board. For example, to rename a file on the device:

mpremote fs mv oldname.py newname.py

This renames oldname.py to newname.py on the board’s filesystem.

To reset the board (soft reset):

mpremote soft-reset

This will perform a soft reset, restarting your MicroPython board without disconnecting it from your computer.

Let me know if you want to see example usage for specific commands!

mpremote Full Help (Addendum)