Control remoto de MicroPython: mpremote¶

La herramienta de línea de comandos mpremote proporciona un conjunto integrado de utilidades para interactuar de forma remota con un dispositivo MicroPython, gestionar su sistema de archivos y automatizarlo a través de una conexión serie. Funciona con todas las OpenMV Cam mediante su conexión serie USB y es una alternativa de línea de comandos a OpenMV IDE para flujos de trabajo de scripting y automatización.

Para usar mpremote, primero instálalo mediante pip:

$ pip install --user mpremote

O mediante pipx:

$ pipx install mpremote

La forma más sencilla de usar esta herramienta es simplemente invocándola sin ningún argumento:

$ mpremote

Este comando detecta y se conecta automáticamente al primer dispositivo serie USB disponible y proporciona un terminal interactivo que puedes usar para acceder al REPL y a la salida de tu programa. Los puertos serie se abren en modo exclusivo, de modo que ejecutar una segunda (o tercera, etc.) instancia de mpremote se conectará a los siguientes dispositivos serie, si hay alguno disponible.

Además, pipx también te permite ejecutar mpremote directamente sin instalarlo primero:

$ pipx run mpremote ...args

Comandos¶

mpremote admite que se le proporcione una serie de comandos en la línea de comandos que realizarán diversas acciones de forma secuencial en un dispositivo MicroPython remoto. Consulta la sección de ejemplos más abajo para hacerte una idea de cómo funciona esto y de algunas combinaciones de comandos habituales.

Cada comando tiene la forma <command name> [--options] [args...]. En el caso de los comandos que admiten varios argumentos (por ejemplo, una lista de archivos), la lista de argumentos puede terminarse con +.

Si no se especifica ningún comando, el comando predeterminado es repl. Además, si algún comando necesita acceder al dispositivo y no se ha especificado antes ningún connect, se añade un connect auto implícito.

Para poner el dispositivo en un estado conocido para cualquier comando de acción (excepto repl), una vez conectado mpremote detendrá cualquier programa en ejecución y hará un reinicio en caliente del dispositivo antes de ejecutar el primer comando. Puedes controlar este comportamiento mediante los comandos resume y soft-reset. Consulta conexión automática y reinicio en caliente automático para más detalles.

Se pueden especificar varios comandos y se ejecutarán de forma secuencial.

La lista completa de comandos admitidos es:

connect ¶

Conéctate al dispositivo especificado por su nombre:

$ mpremote connect <device>

<device> puede ser uno de los siguientes:

list: enumera los dispositivos disponibles
auto: se conecta al primer puerto serie USB disponible
id:<serial>: se conecta al dispositivo con el número de serie USB <serial> (la segunda columna de la salida del comando connect list)
port:<path>: se conecta al dispositivo con la ruta indicada (la primera columna de la salida del comando connect list
rfc2217://<host>:<port>: se conecta al dispositivo usando serie sobre TCP (por ejemplo, un puerto serie en red basado en RFC2217)
cualquier nombre/ruta de dispositivo válido, para conectarse a ese dispositivo

Nota: En lugar de usar el comando connect, existen varios atajos predefinidos para rutas de dispositivo habituales. Por ejemplo, el comando de atajo a0 equivale a connect /dev/ttyACM0 (Linux), o c1 para COM1 (Windows).

Nota: La opción auto solo detectará puertos serie USB, es decir, un puerto serie que tenga un VID/PID USB asociado (es decir, dispositivos de tipo CDC/ACM o FTDI). Otros tipos de puertos serie no se detectarán automáticamente.

disconnect ¶

Desconecta el dispositivo actual:

$ mpremote disconnect

Tras una desconexión, el reinicio en caliente automático queda habilitado.

resume ¶

Mantén el estado actual del intérprete para los comandos posteriores:

$ mpremote resume

Esto deshabilita el reinicio en caliente automático. Resulta útil si quieres ejecutar un comando posterior en una placa sin reiniciarla en caliente primero.

soft-reset ¶

Realiza un reinicio en caliente del dispositivo:

$ mpremote soft-reset

Esto vaciará el heap de Python y reiniciará el intérprete. También evita que el comando posterior active el reinicio en caliente automático.

repl ¶

Entra en el REPL del dispositivo conectado:

$ mpremote repl [--options]

Las opciones son:

--escape-non-printable, para imprimir los bytes/caracteres no imprimibles como su código hexadecimal
--capture <file>, para capturar la salida de la sesión del REPL en el archivo indicado
--inject-code <string>, para especificar caracteres que se inyectarán en el REPL cuando se pulse Ctrl-J. Esto te permite automatizar un comando habitual.
--inject-file <file>, para especificar un archivo que se inyectará en el REPL cuando se pulse Ctrl-K. Esto te permite ejecutar un archivo (por ejemplo, que contenga código de configuración útil, o incluso el programa en el que estás trabajando).

Mientras el comando repl está en ejecución, puedes usar Ctrl-] o Ctrl-x para salir.

Nota: El nombre «REPL» aquí refleja el uso habitual de este comando para acceder al Read Eval Print Loop que se ejecuta en el dispositivo MicroPython. En sentido estricto, el comando repl solo funciona como un terminal (o «monitor serie») para acceder al dispositivo. Dado que este comando no activa el comportamiento de reinicio automático, esto significa que si hay un programa en ejecución, primero tendrás que interrumpirlo con Ctrl-C para llegar al REPL, lo que te permitirá entonces acceder al estado del programa. También puedes usar mpremote soft-reset repl para obtener un REPL «limpio» con todo el estado del programa borrado.

eval ¶

Evalúa e imprime el resultado de una expresión de Python:

$ mpremote eval <string>

exec ¶

Ejecuta el código de Python indicado:

$ mpremote exec <string>

De forma predeterminada, mpremote exec mostrará cualquier salida de la expresión hasta que termine. Se puede especificar el indicador --no-follow para regresar de inmediato y dejar que el dispositivo ejecute la expresión en segundo plano.

run ¶

Ejecuta un script del sistema de archivos local:

$ mpremote run <file.py>

Esto ejecutará el archivo directamente desde la RAM del dispositivo sin copiarlo al sistema de archivos. Es una forma muy útil de iterar en el desarrollo de una única pieza de código sin tener que preocuparte por desplegarla en el sistema de archivos.

De forma predeterminada, mpremote run mostrará cualquier salida del script hasta que termine. Se puede especificar el indicador --no-follow para regresar de inmediato y dejar que el dispositivo ejecute el script en segundo plano.

fs ¶

Ejecuta comandos del sistema de archivos en el dispositivo:

$ mpremote fs <sub-command>

<sub-command> puede ser:

cat <file..> para mostrar el contenido de un archivo o archivos en el dispositivo
ls para enumerar el directorio actual
ls <dirs...> para enumerar los directorios indicados
cp [-rf] <src...> <dest> para copiar archivos
rm [-r] <src...> para eliminar archivos o carpetas en el dispositivo
mkdir <dirs...> para crear directorios en el dispositivo
rmdir <dirs...> para eliminar directorios en el dispositivo
touch <file..> para crear los archivos (si aún no existen)
sha256sum <file..> para calcular la suma SHA256 de los archivos
tree [-vsh] <dirs...> para imprimir un árbol de los directorios indicados

El comando cp usa una convención según la cual un : inicial representa una ruta remota. Sin un : inicial significa una ruta local. Esto se basa en la convención utilizada por el cliente del Secure Copy Protocol (scp).

Así, por ejemplo, mpremote fs cp main.py :main.py copia main.py desde el directorio local actual al sistema de archivos remoto, mientras que mpremote fs cp :main.py main.py copia main.py desde el dispositivo de vuelta al directorio actual.

El comando mpremote rm -r acepta rutas tanto relativas como absolutas. Usa : para referirte al directorio de trabajo remoto actual (cwd) y permitir que se elimine un árbol de directorios de la ruta predeterminada del dispositivo (p. ej. /flash, /). Usa -v/--verbose para ver los archivos que se están eliminando.

Por ejemplo:

mpremote rm -r :libs eliminará el directorio libs y todos sus elementos hijos del dispositivo.
mpremote rm -rv :/sd eliminará todos los archivos de una tarjeta SD montada y dará lugar a una advertencia no bloqueante. El punto de montaje se conservará.
mpremote rm -rv :/ eliminará todos los archivos del dispositivo, incluidos los que se encuentren en vfs montados como /sd o /flash. Tras eliminar todas las carpetas y archivos, también devolverá un error para imitar el comportamiento de Unix rm -rf /.

Advertencia

No existe ninguna forma admitida de recuperar archivos eliminados con mpremote rm -r :. Úsalo con precaución.

El comando tree imprimirá un árbol de los directorios indicados. Usar la opción --size/-s imprimirá el tamaño de cada archivo, o usa --human/-h para emplear un formato más legible para las personas. Nota: El tamaño de los directorios solo se imprime cuando el sistema de archivos del dispositivo informa de un tamaño distinto de cero. La opción -v se puede usar para incluir el nombre del dispositivo serie en la salida.

Todos los demás comandos asumen implícitamente que la ruta es una ruta remota, pero el : se puede usar opcionalmente para mayor claridad.

Todos los subcomandos del sistema de archivos aceptan varios argumentos de ruta, así que si hay otro comando en la secuencia, debes usar + para terminar los argumentos, p. ej.

$ mpremote fs cp main.py :main.py + repl

Esto copiará el archivo al dispositivo y luego entrará en el REPL. El + evita que "repl" se interprete como una ruta.

El comando cp admite la opción -r para hacer una copia recursiva. De forma predeterminada, cp omitirá la copia de archivos al dispositivo remoto si el hash SHA256 del archivo de origen y de destino coincide. Para forzar la copia sin tener en cuenta el hash, usa la opción -f.

Nota: Por comodidad, todos los subcomandos del sistema de archivos también están disponibles como comandos normales mediante alias, es decir, puedes escribir mpremote cp ... en lugar de mpremote fs cp ....

df ¶

Consulta el espacio libre/usado del dispositivo:

$ mpremote df

El comando df imprimirá estadísticas de tamaño/usado/libre del sistema de archivos del dispositivo, de forma similar al comando df de Unix.

edit ¶

Edita un archivo en el dispositivo:

$ mpremote edit <files...>

El comando edit copiará cada archivo desde el dispositivo a un directorio temporal local y luego abrirá tu editor para cada archivo (definido por la variable de entorno $EDITOR). Si el editor se cierra correctamente, el archivo actualizado se copiará de vuelta al dispositivo.

mip ¶

Instala paquetes desde micropython-lib (o GitHub) usando la herramienta mip:

$ mpremote mip install <packages...>

Consulta Gestión de paquetes para más información.

mount ¶

Monta el directorio local en el dispositivo remoto:

$ mpremote mount [options] <local-dir>

Esto permite que el dispositivo remoto vea el directorio local del host como si fuera su propio sistema de archivos. Resulta útil para el desarrollo y evita la necesidad de copiar archivos al dispositivo mientras trabajas en ellos.

El dispositivo instala un controlador de sistema de archivos, que luego se monta en el VFS del dispositivo como /remote, el cual utiliza la conexión serie con mpremote como canal lateral para acceder a los archivos. El dispositivo tendrá su directorio de trabajo actual (mediante os.chdir) establecido en /remote de modo que las importaciones y el acceso a archivos se produzcan allí en lugar de en la ruta predeterminada del sistema de archivos mientras el montaje esté activo.

Nota: Si al comando mount no le sigue otra acción en la secuencia, se añadirá implícitamente un comando repl al final de la secuencia.

Durante el uso, Ctrl-D activará un reinicio en caliente como de costumbre, pero el montaje se volverá a conectar automáticamente. Sin embargo, si la unidad tiene un main.py que se ejecuta al arrancar, el remontaje no podrá producirse. En ese caso se puede usar un reinicio en caliente en modo raw: Ctrl-A Ctrl-D para reiniciar, luego Ctrl-B para volver al repl normal, momento en el cual el montaje estará listo.

Las opciones son:

-l, --unsafe-links: De forma predeterminada se generará un error si el dispositivo accede a un archivo o directorio que esté fuera (uno o más niveles de directorio por encima) del directorio local que se ha montado. Esta opción deshabilita esta comprobación para los enlaces simbólicos, permitiendo que el dispositivo siga enlaces simbólicos fuera del directorio local.

unmount ¶

Desmonta el directorio local del dispositivo remoto:

$ mpremote umount

Esto sucede automáticamente cuando mpremote termina, pero se puede usar en una secuencia para desmontar un montaje anterior antes de que se ejecuten los comandos siguientes.

romfs ¶

Gestiona las particiones ROMFS del dispositivo:

$ mpremote romfs <sub-command>

<sub-command> puede ser:

romfs query para enumerar todas las particiones ROMFS disponibles y su tamaño
romfs [-o <output>] build <source> para crear una imagen ROMFS a partir del directorio de origen indicado; el archivo de salida predeterminado es el origen con .romfs añadido
romfs [-p <partition>] deploy <source> para desplegar una imagen ROMFS en el dispositivo; también creará una imagen ROMFS temporal si el origen es un directorio

Los subcomandos build y deploy admiten ambos la opción -m/--mpy para compilar automáticamente los archivos .py a .mpy al crear la imagen ROMFS. Esta opción está habilitada de forma predeterminada, pero solo funciona si se ha instalado el paquete de Python mpy_cross (p. ej. mediante pip install mpy_cross). Si el paquete no está instalado, se imprime una advertencia y los archivos .py se mantienen tal cual. La compilación de archivos .py se puede deshabilitar con la opción --no-mpy.

rtc ¶

Establece/obtén el reloj del dispositivo (RTC):

$ mpremote rtc

Esto consultará el RTC del dispositivo para obtener la hora actual y la imprimirá como una tupla datetime.

$ mpremote rtc --set

Esto establecerá el RTC del dispositivo con la hora actual del PC host.

sleep ¶

Espera (retardo) antes de ejecutar el siguiente comando:

$ mpremote sleep 0.5

Esto pausará la ejecución de la secuencia de comandos durante la duración especificada en segundos, p. ej. para esperar a que el dispositivo haga algo.

reset ¶

Realiza un reinicio en frío del dispositivo:

$ mpremote reset

Nota: el reinicio en frío equivale a machine.reset().

bootloader ¶

Entra en el gestor de arranque (bootloader):

$ mpremote bootloader

Esto hará que el dispositivo entre en su gestor de arranque (bootloader). El gestor de arranque (bootloader) es específico de cada placa: consulta la sección Recovery and debug pins de la referencia rápida de tu placa para más detalles.

Conexión automática y reinicio en caliente¶

La conexión y la desconexión se realizarán automáticamente al inicio y al final de la ejecución de la herramienta, si dichos comandos no se proporcionan explícitamente. La conexión automática buscará el primer dispositivo serie USB disponible.

Una vez conectado a un dispositivo, mpremote reiniciará automáticamente en caliente el dispositivo si es necesario. Esto vacía el heap de Python y reinicia el intérprete, asegurando que el código de Python posterior se ejecute en un entorno nuevo. El reinicio en caliente automático se realiza la primera vez que se ejecuta uno de los siguientes comandos: mount, eval, exec, run, fs. Tras hacer un reinicio en caliente por primera vez, no se volverá a hacer automáticamente hasta que se emita un comando disconnect.

El comportamiento del reinicio en caliente automático se puede controlar con el comando resume. Esto puede ser útil para usar el comando eval para inspeccionar el estado del dispositivo. El comando soft-reset se puede usar para realizar un reinicio en caliente explícito en medio de una secuencia de comandos.

Atajos¶

Los atajos se pueden definir mediante el sistema de macros. Los atajos integrados son:

devs: Alias de connect list
a0, a1, a2, a3: Alias de connect /dev/ttyACMn
u0, u1, u2, u3: Alias de connect /dev/ttyUSBn
c0, c1, c2, c3: Alias de connect COMn
cat, edit, ls, cp, rm, mkdir, rmdir, touch: Alias de fs <sub-command>

Se pueden definir atajos adicionales en el archivo de configuración del usuario mpremote/config.py, ubicado en el directorio de configuración del usuario. La ubicación correcta para cada sistema operativo se determina usando el módulo platformdirs.

Normalmente es: - $XDG_CONFIG_HOME/mpremote/config.py - $HOME/.config/mpremote/config.py - $env:LOCALAPPDATA/mpremote/config.py

El archivo config.py debe definir un diccionario llamado commands. Las claves de este diccionario son los atajos y los valores son una cadena o una lista de cadenas:

"c33": "connect id:334D335C3138",

El comando c33 se reemplaza por connect id:334D335C3138.

"test": ["mount", ".", "exec", "import test"],

El comando test se reemplaza por mount . exec "import test".

Los atajos también pueden aceptar argumentos. Por ejemplo:

"multiply x=4 y=7": "eval x*y",

Al ejecutar mpremote multiply 3 7 se establecerán x e y como variables en el dispositivo y luego se evaluará la expresión x*y.

Un ejemplo de config.py podría tener este aspecto:

commands = {
    "c33": "connect id:334D335C3138", # Connect to a specific device by ID.
    "bl": "bootloader", # Shorter alias for bootloader.
    "double x=4": "eval x*2",  # x is an argument, with default 4
    "wl_scan": ["exec", """
import network
wl = network.WLAN()
wl.active(1)
for ap in wl.scan():
    print(ap)
""",], # Print out nearby WiFi networks.
    "wl_ipconfig": [
"exec",
"import network; sta_if = network.WLAN(network.WLAN.IF_STA); print(sta_if.ipconfig('addr4'))",
], # Print ip address of station interface.
    "test": ["mount", ".", "exec", "import test"], # Mount current directory and run test.py.
    "demo": ["run", "path/to/demo.py"], # Execute demo.py on the device.
}

Ejemplos¶

mpremote

Conéctate al primer dispositivo disponible y ejecuta implícitamente el comando repl.

mpremote a1

Conéctate al dispositivo en /dev/ttyACM1 (Linux) y ejecuta implícitamente el comando repl. Consulta los atajos anteriores.

mpremote c1

Conéctate al dispositivo en COM1 (Windows) y ejecuta implícitamente el comando repl. Consulta los atajos anteriores.

mpremote connect /dev/ttyUSB0

Especifica explícitamente a qué dispositivo conectarte y, como antes, ejecuta implícitamente el comando repl.

mpremote a1 ls

Conéctate al dispositivo en /dev/ttyACM1 y luego ejecuta el comando ls.

Es equivalente a mpremote connect /dev/ttyACM1 fs ls.

mpremote exec "import micropython; micropython.mem_info()"

Ejecuta el comando de Python especificado y muestra cualquier salida. Esto equivale a escribir el comando en el prompt del REPL.

mpremote eval 1/2 eval 3/4

Evalúa cada expresión por turno e imprime los resultados.

mpremote a0 eval 1/2 a1 eval 3/4

Evalúa 1/2 en el dispositivo en /dev/ttyACM0 y luego 3/4 en el dispositivo en /dev/ttyACM1, imprimiendo cada resultado.

mpremote resume exec "print_state_info()" soft-reset

Conéctate al dispositivo sin activar un reinicio en caliente y ejecuta la función print_state_info() (por ejemplo, para obtener información sobre el estado actual del programa) y luego activa un reinicio en caliente.

mpremote reset sleep 0.5 bootloader

Realiza un reinicio en frío del dispositivo, espera 500 ms a que esté disponible y luego entra en el gestor de arranque (bootloader).

mpremote cp utils/driver.py :utils/driver.py + run test.py

Actualiza la copia de utils/driver.py en el dispositivo y luego ejecuta el script local test.py en el dispositivo. test.py nunca se copia al sistema de archivos del dispositivo, sino que se ejecuta desde la RAM.

mpremote cp utils/driver.py :utils/driver.py + exec "import app"

Actualiza la copia de utils/driver.py en el dispositivo y luego ejecuta app.py en el dispositivo.

Este es un flujo de trabajo de desarrollo habitual para actualizar un único archivo y luego reiniciar tu programa. En este escenario, tu main.py en el dispositivo también haría import app.

mpremote cp utils/driver.py :utils/driver.py + soft-reset repl

Actualiza la copia de utils/driver.py en el dispositivo, luego activa un reinicio en caliente para reiniciar tu programa y después monitoriza la salida mediante el comando repl.

mpremote cp -r utils/ :utils/ + soft-reset repl

Igual que el anterior, pero actualiza primero todo el directorio utils.

mpremote mount .

Monta el directorio local actual en /remote en el dispositivo e inicia una sesión repl que usará /remote como directorio de trabajo.

mpremote mount . exec "import demo"

Tras montar el directorio local actual, ejecuta demo.py desde el directorio montado.

mpremote mount app run test.py

Tras montar el directorio local app como /remote en el dispositivo, ejecuta el archivo local test.py desde el directorio actual del host sin copiarlo al sistema de archivos.

mpremote mount . repl --inject-code "import demo"

Tras montar el directorio local actual, ejecuta demo.py desde el directorio montado cada vez que se pulsa Ctrl-J.

Primero tendrás que pulsar Ctrl-D para reiniciar el estado del intérprete (lo que conservará el montaje) antes de pulsar Ctrl-J para volver a importar demo.py.

mpremote mount app repl --inject-file demo.py

Igual que el anterior, pero ejecuta el contenido del archivo local demo.py en el REPL cada vez que se pulsa Ctrl-K. Como antes, usa Ctrl-D para reiniciar primero el estado del intérprete.

mpremote cat boot.py

Muestra el contenido de boot.py en el dispositivo.

mpremote edit utils/driver.py

Edita utils/driver.py en el dispositivo usando tu $EDITOR local.

mpremote cp :main.py .

Copia main.py desde el dispositivo al directorio local.

mpremote cp main.py :

Copia main.py desde el directorio local al dispositivo.

mpremote cp :a.py :b.py

Copia a.py del dispositivo a b.py en el dispositivo.

mpremote cp -r dir/ :

Copia de forma recursiva el directorio local dir al dispositivo remoto.

mpremote cp a.py b.py : + repl

Copia a.py y b.py desde el directorio local al dispositivo y luego ejecuta el comando repl.

mpremote mip install aioble

Instala el paquete aioble desde micropython-lib en el dispositivo. Consulta Gestión de paquetes.

mpremote mip install github:org/repo@branch

Instala en el dispositivo el paquete desde la rama especificada en org/repo en GitHub. Consulta Gestión de paquetes.

mpremote mip install gitlab:org/repo@branch

Instala en el dispositivo el paquete desde la rama especificada en org/repo en GitLab. Consulta Gestión de paquetes.

mpremote mip install --target /flash/third-party functools

Instala el paquete functools desde micropython-lib en el directorio /flash/third-party del dispositivo. Consulta Gestión de paquetes.