Controle remoto do MicroPython: mpremote

A ferramenta de linha de comando mpremote fornece um conjunto integrado de utilitários para interagir remotamente com um dispositivo MicroPython, gerenciar seu sistema de arquivos e automatizá-lo por meio de uma conexão serial. Ela funciona com todas as OpenMV Cams através da conexão serial USB e é uma alternativa de linha de comando ao OpenMV IDE para fluxos de trabalho de scripts e automação.

Para usar o mpremote, primeiro instale-o via pip:

$ pip install --user mpremote

Ou via pipx:

$ pipx install mpremote

A maneira mais simples de usar esta ferramenta é apenas invocá-la sem nenhum argumento:

$ mpremote

Este comando detecta e conecta-se automaticamente ao primeiro dispositivo serial USB disponível e fornece um terminal interativo que você pode usar para acessar o REPL e a saída do seu programa. As portas seriais são abertas em modo exclusivo, portanto, executar uma segunda (ou terceira, etc.) instância do mpremote conectará a dispositivos seriais subsequentes, se houver algum disponível.

Além disso, o pipx também permite que você execute diretamente o mpremote sem instalá-lo primeiro:

$ pipx run mpremote ...args

Comandos

O mpremote suporta receber uma série de comandos na linha de comando que executarão várias ações em sequência em um dispositivo MicroPython remoto. Veja a seção de exemplos abaixo para entender como isso funciona e para algumas combinações comuns de comandos.

Cada comando tem a forma <command name> [--options] [args...]. Para comandos que suportam múltiplos argumentos (por exemplo, uma lista de arquivos), a lista de argumentos pode ser encerrada com +.

Se nenhum comando for especificado, o comando padrão é repl. Além disso, se algum comando precisar acessar o dispositivo e nenhum connect anterior tiver sido especificado, então um connect auto implícito é adicionado.

Para colocar o dispositivo em um estado conhecido para qualquer comando de ação (exceto repl), uma vez conectado, o mpremote interromperá qualquer programa em execução e fará um soft-reset do dispositivo antes de executar o primeiro comando. Você pode controlar esse comportamento usando os comandos resume e soft-reset. Veja conexão automática e soft-reset automático para mais detalhes.

Múltiplos comandos podem ser especificados e serão executados sequencialmente.

A lista completa de comandos suportados é:

connect

Conecta-se ao dispositivo especificado pelo nome:

$ mpremote connect <device>

<device> pode ser um dos seguintes:

  • list: lista os dispositivos disponíveis

  • auto: conecta-se à primeira porta serial USB disponível

  • id:<serial>: conecta-se ao dispositivo com o número de série USB <serial> (a segunda coluna da saída do comando connect list)

  • port:<path>: conecta-se ao dispositivo com o caminho fornecido (a primeira coluna da saída do comando connect list

  • rfc2217://<host>:<port>: conecta-se ao dispositivo usando serial sobre TCP (por exemplo, uma porta serial em rede baseada em RFC2217)

  • qualquer nome/caminho de dispositivo válido, para conectar-se a esse dispositivo

Nota: Em vez de usar o comando connect, existem vários atalhos predefinidos para caminhos de dispositivos comuns. Por exemplo, o comando de atalho a0 é equivalente a connect /dev/ttyACM0 (Linux), ou c1 para COM1 (Windows).

Nota: A opção auto só detectará portas seriais USB, ou seja, uma porta serial que tenha um VID/PID USB associado (isto é, dispositivos do tipo CDC/ACM ou FTDI). Outros tipos de portas seriais não serão detectados automaticamente.

disconnect

Desconecta o dispositivo atual:

$ mpremote disconnect

Após uma desconexão, o soft-reset automático é habilitado.

resume

Mantém o estado do interpretador existente para comandos subsequentes:

$ mpremote resume

Isso desabilita o soft-reset automático. Isso é útil se você quiser executar um comando subsequente em uma placa sem fazer primeiro um soft-reset nela.

soft-reset

Executa um soft-reset do dispositivo:

$ mpremote soft-reset

Isso limpará a heap do Python e reiniciará o interpretador. Também impede que o comando subsequente acione o soft-reset automático.

repl

Entra no REPL do dispositivo conectado:

$ mpremote repl [--options]

As opções são:

  • --escape-non-printable, para imprimir bytes/caracteres não imprimíveis como seu código hexadecimal

  • --capture <file>, para capturar a saída da sessão REPL no arquivo fornecido

  • --inject-code <string>, para especificar caracteres a serem injetados no REPL quando Ctrl-J for pressionado. Isso permite automatizar um comando comum.

  • --inject-file <file>, para especificar um arquivo a ser injetado no REPL quando Ctrl-K for pressionado. Isso permite executar um arquivo (por exemplo, contendo algum código de configuração útil, ou até mesmo o programa em que você está trabalhando no momento).

Enquanto o comando repl está em execução, você pode usar Ctrl-] ou Ctrl-x para sair.

Nota: O nome “REPL” aqui reflete o uso comum deste comando para acessar o Read Eval Print Loop que está em execução no dispositivo MicroPython. A rigor, o comando repl está apenas funcionando como um terminal (ou “monitor serial”) para acessar o dispositivo. Como este comando não aciona o comportamento de reset automático, isso significa que, se um programa estiver em execução no momento, você precisará primeiro interrompê-lo com Ctrl-C para chegar ao REPL, o que então permitirá acessar o estado do programa. Você também pode usar mpremote soft-reset repl para obter um REPL “limpo” com todo o estado do programa apagado.

eval

Avalia e imprime o resultado de uma expressão Python:

$ mpremote eval <string>

exec

Executa o código Python fornecido:

$ mpremote exec <string>

Por padrão, o mpremote exec exibirá toda a saída da expressão até que ela termine. A flag --no-follow pode ser especificada para retornar imediatamente e deixar o dispositivo executando a expressão em segundo plano.

run

Executa um script do sistema de arquivos local:

$ mpremote run <file.py>

Isso executará o arquivo diretamente da RAM no dispositivo sem copiá-lo para o sistema de arquivos. Esta é uma maneira muito útil de iterar no desenvolvimento de um único trecho de código sem ter que se preocupar em implantá-lo no sistema de arquivos.

Por padrão, o mpremote run exibirá toda a saída do script até que ele termine. A flag --no-follow pode ser especificada para retornar imediatamente e deixar o dispositivo executando o script em segundo plano.

fs

Executa comandos de sistema de arquivos no dispositivo:

$ mpremote fs <sub-command>

<sub-command> pode ser:

  • cat <file..> para mostrar o conteúdo de um arquivo ou arquivos no dispositivo

  • ls para listar o diretório atual

  • ls <dirs...> para listar os diretórios fornecidos

  • cp [-rf] <src...> <dest> para copiar arquivos

  • rm [-r] <src...> para remover arquivos ou pastas no dispositivo

  • mkdir <dirs...> para criar diretórios no dispositivo

  • rmdir <dirs...> para remover diretórios no dispositivo

  • touch <file..> para criar os arquivos (se ainda não existirem)

  • sha256sum <file..> para calcular a soma SHA256 dos arquivos

  • tree [-vsh] <dirs...> para imprimir uma árvore dos diretórios fornecidos

O comando cp usa uma convenção em que um : inicial representa um caminho remoto. Sem um : inicial significa um caminho local. Isso é baseado na convenção usada pelo cliente do Secure Copy Protocol (scp).

Assim, por exemplo, mpremote fs cp main.py :main.py copia main.py do diretório local atual para o sistema de arquivos remoto, enquanto mpremote fs cp :main.py main.py copia main.py do dispositivo de volta para o diretório atual.

O comando mpremote rm -r aceita tanto caminhos relativos quanto absolutos. Use : para referir-se ao diretório de trabalho remoto atual (cwd) para permitir que uma árvore de diretórios seja removida do caminho padrão do dispositivo (por exemplo, /flash, /). Use -v/--verbose para ver os arquivos sendo removidos.

Por exemplo:

  • mpremote rm -r :libs removerá o diretório libs e todos os seus itens filhos do dispositivo.

  • mpremote rm -rv :/sd removerá todos os arquivos de um cartão SD montado e resultará em um aviso não bloqueante. A montagem será mantida.

  • mpremote rm -rv :/ removerá todos os arquivos no dispositivo, incluindo qualquer um localizado em vfs montados, como /sd ou /flash. Após remover todas as pastas e arquivos, isso também retornará um erro para imitar o comportamento do rm -rf / do unix.

Aviso

Não há maneira suportada de recuperar arquivos removidos pelo mpremote rm -r :. Por favor, use com cautela.

O comando tree imprimirá uma árvore dos diretórios fornecidos. Usar a opção --size/-s imprimirá o tamanho de cada arquivo, ou use --human/-h para usar um formato mais legível por humanos. Nota: O tamanho do diretório só é impresso quando um tamanho diferente de zero é informado pelo sistema de arquivos do dispositivo. A opção -v pode ser usada para incluir o nome do dispositivo serial na saída.

Todos os outros comandos assumem implicitamente que o caminho é remoto, mas o : pode ser usado opcionalmente para maior clareza.

Todos os subcomandos de sistema de arquivos aceitam múltiplos argumentos de caminho, portanto, se houver outro comando na sequência, você deve usar + para encerrar os argumentos, por exemplo:

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

Isso copiará o arquivo para o dispositivo e então entrará no REPL. O + impede que "repl" seja interpretado como um caminho.

O comando cp suporta a opção -r para fazer uma cópia recursiva. Por padrão, o cp pulará a cópia de arquivos para o dispositivo remoto se o hash SHA256 do arquivo de origem e de destino coincidir. Para forçar uma cópia independentemente do hash, use a opção -f.

Nota: Por conveniência, todos os subcomandos de sistema de arquivos também têm alias como comandos regulares, ou seja, você pode escrever mpremote cp ... em vez de mpremote fs cp ....

df

Consulta o espaço livre/usado do dispositivo:

$ mpremote df

O comando df imprimirá estatísticas de tamanho/usado/livre do sistema de arquivos do dispositivo, semelhante ao comando df do Unix.

edit

Edita um arquivo no dispositivo:

$ mpremote edit <files...>

O comando edit copiará cada arquivo do dispositivo para um diretório temporário local e então iniciará seu editor para cada arquivo (definido pela variável de ambiente $EDITOR). Se o editor sair com sucesso, o arquivo atualizado será copiado de volta para o dispositivo.

mip

Instala pacotes da micropython-lib (ou do GitHub) usando a ferramenta mip:

$ mpremote mip install <packages...>

Veja Gerenciamento de pacotes para mais informações.

mount

Monta o diretório local no dispositivo remoto:

$ mpremote mount [options] <local-dir>

Isso permite que o dispositivo remoto veja o diretório do host local como se fosse seu próprio sistema de arquivos. Isso é útil para o desenvolvimento e evita a necessidade de copiar arquivos para o dispositivo enquanto você está trabalhando neles.

O dispositivo instala um driver de sistema de arquivos, que é então montado no VFS do dispositivo como /remote, que usa a conexão serial com o mpremote como um canal lateral para acessar os arquivos. O dispositivo terá seu diretório de trabalho atual (via os.chdir) definido como /remote, de modo que importações e acesso a arquivos ocorrerão lá em vez do caminho padrão do sistema de arquivos enquanto a montagem estiver ativa.

Nota: Se o comando mount não for seguido por outra ação na sequência, um comando repl será adicionado implicitamente ao final da sequência.

Durante o uso, Ctrl-D acionará um soft-reset normalmente, mas a montagem será reconectada automaticamente. No entanto, se a unidade tiver um main.py em execução na inicialização, a remontagem não poderá ocorrer. Nesse caso, uma reinicialização suave em modo raw pode ser usada: Ctrl-A Ctrl-D para reiniciar, depois Ctrl-B para voltar ao repl normal, momento em que a montagem estará pronta.

As opções são:

  • -l, --unsafe-links: Por padrão, um erro será gerado se o dispositivo acessar um arquivo ou diretório que esteja fora (um ou mais níveis de diretório acima) do diretório local que está montado. Esta opção desabilita essa verificação para links simbólicos, permitindo que o dispositivo siga links simbólicos fora do diretório local.

unmount

Desmonta o diretório local do dispositivo remoto:

$ mpremote umount

Isso acontece automaticamente quando o mpremote é encerrado, mas pode ser usado em uma sequência para desmontar uma montagem anterior antes que comandos subsequentes sejam executados.

romfs

Gerencia partições ROMFS no dispositivo:

$ mpremote romfs <sub-command>

<sub-command> pode ser:

  • romfs query para listar todas as partições ROMFS disponíveis e seu tamanho

  • romfs [-o <output>] build <source> para criar uma imagem ROMFS a partir do diretório de origem fornecido; o arquivo de saída padrão é a origem com .romfs acrescentado

  • romfs [-p <partition>] deploy <source> para implantar uma imagem ROMFS no dispositivo; também criará uma imagem ROMFS temporária se a origem for um diretório

Os subcomandos build e deploy suportam a opção -m/--mpy para compilar automaticamente arquivos .py em .mpy ao criar a imagem ROMFS. Esta opção é habilitada por padrão, mas só funciona se o pacote Python mpy_cross tiver sido instalado (por exemplo, via pip install mpy_cross). Se o pacote não estiver instalado, um aviso é impresso e os arquivos .py permanecem como estão. A compilação de arquivos .py pode ser desabilitada com a opção --no-mpy.

rtc

Define/obtém o relógio do dispositivo (RTC):

$ mpremote rtc

Isso consultará o RTC do dispositivo para obter a hora atual e a imprimirá como uma tupla datetime.

$ mpremote rtc --set

Isso definirá o RTC do dispositivo para a hora atual do PC host.

sleep

Aguarda (atraso) antes de executar o próximo comando:

$ mpremote sleep 0.5

Isso pausará a execução da sequência de comandos pela duração especificada em segundos, por exemplo, para aguardar o dispositivo fazer algo.

reset

Faz um hard reset do dispositivo:

$ mpremote reset

Nota: o hard reset é equivalente a machine.reset().

bootloader

Entra no bootloader:

$ mpremote bootloader

Isso fará com que o dispositivo entre em seu bootloader. O bootloader é específico de cada placa — veja a seção Recovery and debug pins da referência rápida da sua placa para detalhes.

Conexão automática e soft-reset

A conexão e a desconexão serão feitas automaticamente no início e no fim da execução da ferramenta, se tais comandos não forem fornecidos explicitamente. A conexão automática procurará o primeiro dispositivo serial USB disponível.

Uma vez conectado a um dispositivo, o mpremote fará automaticamente um soft-reset do dispositivo, se necessário. Isso limpa a heap do Python e reinicia o interpretador, garantindo que o código Python subsequente seja executado em um ambiente novo. O soft-reset automático é realizado na primeira vez que um dos seguintes comandos é executado: mount, eval, exec, run, fs. Após fazer um soft-reset pela primeira vez, ele não será feito novamente automaticamente, até que um comando disconnect seja emitido.

O comportamento do soft-reset automático pode ser controlado pelo comando resume. Isso pode ser útil para usar o comando eval para inspecionar o estado do dispositivo. O comando soft-reset pode ser usado para realizar um soft reset explícito no meio de uma sequência de comandos.

Atalhos

Os atalhos podem ser definidos usando o sistema de macros. Os atalhos embutidos são:

  • devs: Alias para connect list

  • a0, a1, a2, a3: Aliases para connect /dev/ttyACMn

  • u0, u1, u2, u3: Aliases para connect /dev/ttyUSBn

  • c0, c1, c2, c3: Aliases para connect COMn

  • cat, edit, ls, cp, rm, mkdir, rmdir, touch: Aliases para fs <sub-command>

Atalhos adicionais podem ser definidos no arquivo de configuração do usuário mpremote/config.py, localizado no Diretório de Configuração do Usuário. A localização correta para cada SO é determinada usando o módulo platformdirs.

Isso normalmente é: - $XDG_CONFIG_HOME/mpremote/config.py - $HOME/.config/mpremote/config.py - $env:LOCALAPPDATA/mpremote/config.py

O arquivo config.py deve definir um dicionário chamado commands. As chaves desse dicionário são os atalhos e os valores são uma string ou uma lista de strings:

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

O comando c33 é substituído por connect id:334D335C3138.

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

O comando test é substituído por mount . exec "import test".

Os atalhos também podem aceitar argumentos. Por exemplo:

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

Executar mpremote multiply 3 7 definirá x e y como variáveis no dispositivo e então avaliará a expressão x*y.

Um exemplo de config.py pode ser assim:

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.
}

Exemplos

mpremote

Conecta-se ao primeiro dispositivo disponível e executa implicitamente o comando repl.

mpremote a1

Conecta-se ao dispositivo em /dev/ttyACM1 (Linux) e executa implicitamente o comando repl. Veja os atalhos acima.

mpremote c1

Conecta-se ao dispositivo em COM1 (Windows) e executa implicitamente o comando repl. Veja os atalhos acima.

mpremote connect /dev/ttyUSB0

Especifica explicitamente a qual dispositivo conectar e, como acima, executa implicitamente o comando repl.

mpremote a1 ls

Conecta-se ao dispositivo em /dev/ttyACM1 e então executa o comando ls.

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

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

Executa o comando Python especificado e exibe qualquer saída. Isso é equivalente a digitar o comando no prompt do REPL.

mpremote eval 1/2 eval 3/4

Avalia cada expressão por vez e imprime os resultados.

mpremote a0 eval 1/2 a1 eval 3/4

Avalia 1/2 no dispositivo em /dev/ttyACM0, depois 3/4 no dispositivo em /dev/ttyACM1, imprimindo cada resultado.

mpremote resume exec "print_state_info()" soft-reset

Conecta-se ao dispositivo sem acionar um soft reset e executa a função print_state_info() (por exemplo, para descobrir informações sobre o estado atual do programa), e então aciona um soft reset.

mpremote reset sleep 0.5 bootloader

Faz um hard-reset do dispositivo, aguarda 500ms para que ele fique disponível e então entra no bootloader.

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

Atualiza a cópia de utils/driver.py no dispositivo e então executa o script local test.py no dispositivo. O test.py nunca é copiado para o sistema de arquivos do dispositivo, ao invés disso, ele é executado a partir da RAM.

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

Atualiza a cópia de utils/driver.py no dispositivo e então executa app.py no dispositivo.

Este é um fluxo de trabalho de desenvolvimento comum para atualizar um único arquivo e então reiniciar seu programa. Nesse cenário, seu main.py no dispositivo também faria import app.

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

Atualiza a cópia de utils/driver.py no dispositivo, então aciona um soft-reset para reiniciar seu programa e então monitora a saída via comando repl.

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

Igual ao anterior, mas atualiza primeiro o diretório utils inteiro.

mpremote mount .

Monta o diretório local atual em /remote no dispositivo e inicia uma sessão repl que usará /remote como diretório de trabalho.

mpremote mount . exec "import demo"

Após montar o diretório local atual, executa demo.py do diretório montado.

mpremote mount app run test.py

Após montar o diretório local app como /remote no dispositivo, executa o test.py local do diretório atual do host sem copiá-lo para o sistema de arquivos.

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

Após montar o diretório local atual, executa demo.py do diretório montado cada vez que Ctrl-J é pressionado.

Você precisará primeiro pressionar Ctrl-D para resetar o estado do interpretador (o que preservará a montagem) antes de pressionar Ctrl-J para reimportar demo.py.

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

Igual ao anterior, mas executa o conteúdo do arquivo local demo.py no REPL cada vez que Ctrl-K é pressionado. Como acima, use Ctrl-D para resetar primeiro o estado do interpretador.

mpremote cat boot.py

Exibe o conteúdo de boot.py no dispositivo.

mpremote edit utils/driver.py

Edita utils/driver.py no dispositivo usando seu $EDITOR local.

mpremote cp :main.py .

Copia main.py do dispositivo para o diretório local.

mpremote cp main.py :

Copia main.py do diretório local para o dispositivo.

mpremote cp :a.py :b.py

Copia a.py no dispositivo para b.py no dispositivo.

mpremote cp -r dir/ :

Copia recursivamente o diretório local dir para o dispositivo remoto.

mpremote cp a.py b.py : + repl

Copia a.py e b.py do diretório local para o dispositivo e então executa o comando repl.

mpremote mip install aioble

Instala o pacote aioble da micropython-lib no dispositivo. Veja Gerenciamento de pacotes.

mpremote mip install github:org/repo@branch

Instala o pacote do branch especificado em org/repo no GitHub para o dispositivo. Veja Gerenciamento de pacotes.

mpremote mip install gitlab:org/repo@branch

Instala o pacote do branch especificado em org/repo no GitLab para o dispositivo. Veja Gerenciamento de pacotes.

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

Instala o pacote functools da micropython-lib no diretório /flash/third-party do dispositivo. Veja Gerenciamento de pacotes.