Controlo remoto do MicroPython: mpremote¶

A ferramenta de linha de comandos mpremote fornece um conjunto integrado de utilitários para interagir remotamente, gerir o sistema de ficheiros e automatizar um dispositivo MicroPython através de uma ligação série. Funciona com todas as OpenMV Cams através da sua ligação série USB, e é uma alternativa de linha de comandos ao OpenMV IDE para fluxos de trabalho de scripting e automatização.

Para utilizar o mpremote, instale-o primeiro através do pip:

$ pip install --user mpremote

Ou através do pipx:

$ pipx install mpremote

A forma mais simples de utilizar esta ferramenta é invocá-la sem quaisquer argumentos:

$ mpremote

Este comando deteta e liga automaticamente ao primeiro dispositivo série USB disponível e fornece um terminal interativo que pode ser utilizado para aceder ao REPL e à saída do seu programa. As portas série são abertas em modo exclusivo, pelo que executar uma segunda (ou terceira, etc.) instância de mpremote irá ligar aos dispositivos série subsequentes, caso existam disponíveis.

Adicionalmente, o pipx também permite executar mpremote diretamente sem instalação prévia:

$ pipx run mpremote ...args

Comandos¶

O mpremote suporta a especificação de uma série de comandos na linha de comandos que executarão várias ações em sequência num dispositivo MicroPython remoto. Consulte a secção de exemplos abaixo para ter uma ideia de como isto 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 ficheiros), a lista de argumentos pode ser terminada com +.

Se nenhum comando for especificado, o comando predefinido é repl. Adicionalmente, se algum comando necessitar de aceder ao dispositivo e nenhum connect anterior tiver sido especificado, é adicionado implicitamente um connect auto.

Para colocar o dispositivo num estado conhecido para qualquer comando de ação (exceto repl), uma vez ligado, o mpremote irá parar qualquer programa em execução e efetuar um soft-reset do dispositivo antes de executar o primeiro comando. Pode controlar este comportamento utilizando os comandos resume e soft-reset. Consulte ligação automática e soft-reset automático para mais detalhes.

Podem ser especificados múltiplos comandos, que serão executados sequencialmente.

A lista completa de comandos suportados é:

connect ¶

Ligar ao dispositivo especificado pelo nome:

$ mpremote connect <device>

<device> pode ser um dos seguintes:

list: listar os dispositivos disponíveis
auto: ligar à primeira porta série USB disponível
id:<serial>: ligar ao dispositivo com o número de série USB <serial> (a segunda coluna da saída do comando connect list)
port:<path>: ligar ao dispositivo com o caminho especificado (a primeira coluna da saída do comando connect list
rfc2217://<host>:<port>: ligar ao dispositivo utilizando série sobre TCP (por exemplo, uma porta série em rede baseada em RFC2217)
qualquer nome/caminho de dispositivo válido, para ligar a esse dispositivo

Nota: Em vez de utilizar 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 apenas detetará portas série USB, ou seja, uma porta série que tenha um VID/PID USB associado (dispositivos CDC/ACM ou do tipo FTDI). Outros tipos de portas série não serão detetados automaticamente.

disconnect ¶

Desligar do dispositivo atual:

$ mpremote disconnect

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

resume ¶

Manter o estado existente do interpretador para os comandos subsequentes:

$ mpremote resume

Isto desativa o soft-reset automático. É útil se pretender executar um comando subsequente numa placa sem primeiro efetuar um soft-reset.

soft-reset ¶

Efetuar um soft-reset do dispositivo:

$ mpremote soft-reset

Isto irá limpar o heap do Python e reiniciar o interpretador. Também impede o comando subsequente de acionar o soft-reset automático.

repl ¶

Entrar no REPL do dispositivo ligado:

$ mpremote repl [--options]

As opções são:

--escape-non-printable, para imprimir bytes/caracteres não imprimíveis como o seu código hexadecimal
--capture <file>, para capturar a saída da sessão REPL para o ficheiro especificado
--inject-code <string>, para especificar caracteres a injetar no REPL quando Ctrl-J é premido. Isto permite automatizar um comando comum.
--inject-file <file>, para especificar um ficheiro a injetar no REPL quando Ctrl-K é premido. Isto permite executar um ficheiro (por exemplo, contendo algum código de configuração útil, ou mesmo o programa em que está a trabalhar atualmente).

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

Nota: O nome «REPL» aqui reflete o uso comum deste comando para aceder ao ciclo Read Eval Print que está a ser executado no dispositivo MicroPython. Estritamente falando, o comando repl funciona apenas como um terminal (ou «monitor série») para aceder ao dispositivo. Como este comando não aciona o comportamento de reset automático, isso significa que se um programa estiver atualmente em execução, primeiro terá de o interromper com Ctrl-C para aceder ao REPL, o que lhe permitirá aceder ao estado do programa. Também pode usar mpremote soft-reset repl para obter um REPL «limpo» com todo o estado do programa limpo.

eval ¶

Avaliar e imprimir o resultado de uma expressão Python:

$ mpremote eval <string>

exec ¶

Executar o código Python fornecido:

$ mpremote exec <string>

Por predefinição, o mpremote exec irá exibir qualquer saída da expressão até esta terminar. O sinalizador --no-follow pode ser especificado para retornar imediatamente e deixar o dispositivo executar a expressão em segundo plano.

run ¶

Executar um script a partir do sistema de ficheiros local:

$ mpremote run <file.py>

Isto irá executar o ficheiro diretamente a partir da RAM do dispositivo sem o copiar para o sistema de ficheiros. Esta é uma forma muito útil de iterar no desenvolvimento de um único trecho de código sem ter de se preocupar em implementá-lo no sistema de ficheiros.

Por predefinição, o mpremote run irá exibir qualquer saída do script até este terminar. O sinalizador --no-follow pode ser especificado para retornar imediatamente e deixar o dispositivo executar o script em segundo plano.

fs ¶

Executar comandos do sistema de ficheiros no dispositivo:

$ mpremote fs <sub-command>

<sub-command> pode ser:

cat <file..> para mostrar o conteúdo de um ou mais ficheiros no dispositivo
ls para listar o diretório atual
ls <dirs...> para listar os diretórios especificados
cp [-rf] <src...> <dest> para copiar ficheiros
rm [-r] <src...> para remover ficheiros 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 ficheiros (caso não existam ainda)
sha256sum <file..> para calcular a soma SHA256 de ficheiros
tree [-vsh] <dirs...> para imprimir uma árvore dos diretórios especificados

O comando cp utiliza uma convenção em que um : inicial representa um caminho remoto. Sem um : inicial significa um caminho local. Isto baseia-se na convenção utilizada pelo cliente 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 ficheiros remoto, ao passo que 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 como absolutos. Utilize : para se referir ao diretório de trabalho remoto atual (cwd) para permitir que uma árvore de diretórios seja removida do caminho predefinido do dispositivo (por exemplo, /flash, /). Utilize -v/--verbose para ver os ficheiros a serem removidos.

Por exemplo:

mpremote rm -r :libs irá remover o diretório libs e todos os seus itens filhos do dispositivo.
mpremote rm -rv :/sd irá remover todos os ficheiros de um SDCard montado e resultará num aviso não bloqueante. A montagem será mantida.
mpremote rm -rv :/ irá remover todos os ficheiros no dispositivo, incluindo quaisquer localizados em vfs montados como /sd ou /flash. Após remover todas as pastas e ficheiros, isto também devolverá um erro para imitar o comportamento do rm -rf / do unix.

Aviso

Não existe uma forma suportada de recuperar ficheiros removidos por mpremote rm -r :. Por favor, utilize com precaução.

O comando tree irá imprimir uma árvore dos diretórios especificados. Utilizar a opção --size/-s irá imprimir o tamanho de cada ficheiro, ou use --human/-h para um formato mais legível para humanos. Nota: O tamanho do diretório apenas é impresso quando um tamanho não nulo é reportado pelo sistema de ficheiros do dispositivo. A opção -v pode ser utilizada para incluir o nome do dispositivo série na saída.

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

Todos os subcomandos do sistema de ficheiros aceitam múltiplos argumentos de caminho, pelo que se houver outro comando na sequência, deve utilizar + para terminar os argumentos, por exemplo,

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

Isto irá copiar o ficheiro para o dispositivo e depois 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 predefinição, o cp irá ignorar a cópia de ficheiros para o dispositivo remoto se o hash SHA256 do ficheiro de origem e do ficheiro de destino coincidir. Para forçar uma cópia independentemente do hash, utilize a opção -f.

Nota: Por conveniência, todos os subcomandos do sistema de ficheiros também estão disponíveis como comandos regulares, ou seja, pode escrever mpremote cp ... em vez de mpremote fs cp ....

df ¶

Consultar o espaço livre/utilizado do dispositivo:

$ mpremote df

O comando df irá imprimir estatísticas de tamanho/utilizado/livre para o sistema de ficheiros do dispositivo, semelhante ao comando df do Unix.

edit ¶

Editar um ficheiro no dispositivo:

$ mpremote edit <files...>

O comando edit irá copiar cada ficheiro do dispositivo para um diretório temporário local e depois lançar o seu editor para cada ficheiro (definido pela variável de ambiente $EDITOR). Se o editor sair com êxito, o ficheiro atualizado será copiado de volta para o dispositivo.

mip ¶

Instalar pacotes do micropython-lib (ou GitHub) utilizando a ferramenta mip:

$ mpremote mip install <packages...>

Consulte Gestão de pacotes para mais informações.

mount ¶

Montar o diretório local no dispositivo remoto:

$ mpremote mount [options] <local-dir>

Isto permite que o dispositivo remoto veja o diretório do host local como se fosse o seu próprio sistema de ficheiros. É útil para desenvolvimento, e evita a necessidade de copiar ficheiros para o dispositivo enquanto trabalha neles.

O dispositivo instala um controlador de sistema de ficheiros, que é então montado no VFS do dispositivo como /remote, que utiliza a ligação série ao mpremote como canal lateral para aceder aos ficheiros. O diretório de trabalho atual do dispositivo (através de os.chdir) será definido como /remote, de modo que as importações e o acesso a ficheiros ocorram aí em vez do caminho predefinido do sistema de ficheiros 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 a utilização, Ctrl-D acionará um soft-reset normalmente, mas a montagem será automaticamente reconectada. No entanto, se a unidade tiver um main.py em execução no arranque, a remontagem não poderá ocorrer. Neste caso, pode ser utilizado um soft reboot em modo raw: Ctrl-A Ctrl-D para reiniciar, depois Ctrl-B para voltar ao repl normal, altura em que a montagem estará pronta.

As opções são:

-l, --unsafe-links: Por predefinição, será gerado um erro se o dispositivo aceder a um ficheiro 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 desativa esta verificação para ligações simbólicas, permitindo ao dispositivo seguir ligações simbólicas fora do diretório local.

unmount ¶

Desmontar o diretório local do dispositivo remoto:

$ mpremote umount

Isto acontece automaticamente quando o mpremote termina, mas pode ser utilizado numa sequência para desmontar uma montagem anterior antes de os comandos subsequentes serem executados.

romfs ¶

Gerir 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 o seu tamanho
romfs [-o <output>] build <source> para criar uma imagem ROMFS a partir do diretório de origem especificado; o ficheiro de saída predefinido é a origem com .romfs adicionado
romfs [-p <partition>] deploy <source> para implementar uma imagem ROMFS no dispositivo; também irá criar uma imagem ROMFS temporária se a origem for um diretório

Os subcomandos build e deploy suportam ambos a opção -m/--mpy para compilar automaticamente ficheiros .py para .mpy ao criar a imagem ROMFS. Esta opção está ativada por predefinição, mas apenas funciona se o pacote Python mpy_cross estiver instalado (por exemplo, através de pip install mpy_cross). Se o pacote não estiver instalado, é impresso um aviso e os ficheiros .py permanecem como estão. A compilação de ficheiros .py pode ser desativada com a opção --no-mpy.

rtc ¶

Definir/obter o relógio do dispositivo (RTC):

$ mpremote rtc

Isto irá consultar o RTC do dispositivo para obter a hora atual e imprimi-la como um tuplo datetime.

$ mpremote rtc --set

Isto irá definir o RTC do dispositivo para a hora atual do PC anfitrião.

sleep ¶

Aguardar (atrasar) antes de executar o próximo comando:

$ mpremote sleep 0.5

Isto irá pausar a execução da sequência de comandos durante a duração especificada em segundos, por exemplo, para aguardar que o dispositivo faça algo.

reset ¶

Efetuar um hard reset do dispositivo:

$ mpremote reset

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

bootloader ¶

Entrar no bootloader:

$ mpremote bootloader

Isto fará com que o dispositivo entre no seu bootloader. O bootloader é específico da placa — consulte a secção Pinos de recuperação e depuração da referência rápida da sua placa para mais detalhes.

Ligação automática e soft-reset¶

A ligação e a desconexão serão efetuadas automaticamente no início e no fim da execução da ferramenta, se esses comandos não forem fornecidos explicitamente. A ligação automática irá procurar o primeiro dispositivo série USB disponível.

Uma vez ligado a um dispositivo, o mpremote irá efetuar automaticamente um soft-reset do dispositivo se necessário. Isto limpa o heap do Python e reinicia o interpretador, garantindo que o código Python subsequente é executado num ambiente limpo. O soft-reset automático é efetuado na primeira vez que um dos seguintes comandos é executado: mount, eval, exec, run, fs. Após efetuar um soft-reset pela primeira vez, este não será efetuado novamente automaticamente, até que seja emitido um comando disconnect.

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

Atalhos¶

Os atalhos podem ser definidos utilizando o sistema de macros. Os atalhos incorporados 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 ficheiro de configuração do utilizador mpremote/config.py, localizado no Diretório de Configuração do Utilizador. A localização correta para cada sistema operativo é determinada utilizando o módulo platformdirs.

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

O ficheiro config.py deve definir um dicionário com o nome commands. As chaves deste 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 irá definir x e y como variáveis no dispositivo e depois avaliar a expressão x*y.

Um exemplo de config.py pode ser:

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

Ligar ao primeiro dispositivo disponível e executar implicitamente o comando repl.

mpremote a1

Ligar ao dispositivo em /dev/ttyACM1 (Linux) e executar implicitamente o comando repl. Consulte atalhos acima.

mpremote c1

Ligar ao dispositivo em COM1 (Windows) e executar implicitamente o comando repl. Consulte atalhos acima.

mpremote connect /dev/ttyUSB0

Especificar explicitamente a qual dispositivo ligar e, como acima, executar implicitamente o comando repl.

mpremote a1 ls

Ligar ao dispositivo em /dev/ttyACM1 e depois executar o comando ls.

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

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

Executar o comando Python especificado e exibir qualquer saída. Isto é equivalente a escrever o comando no prompt do REPL.

mpremote eval 1/2 eval 3/4

Avaliar cada expressão por sua vez e imprimir os resultados.

mpremote a0 eval 1/2 a1 eval 3/4

Avaliar 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

Ligar ao dispositivo sem acionar um soft reset e executar a função print_state_info() (por exemplo, para obter informações sobre o estado atual do programa), depois acionar um soft reset.

mpremote reset sleep 0.5 bootloader

Efetuar um hard-reset do dispositivo, aguardar 500ms para que fique disponível e depois entrar no bootloader.

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

Atualizar a cópia de utils/driver.py no dispositivo e depois executar o script local test.py no dispositivo. test.py nunca é copiado para o sistema de ficheiros do dispositivo, sendo antes executado a partir da RAM.

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

Atualizar a cópia de utils/driver.py no dispositivo e depois executar app.py no dispositivo.

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

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

Atualizar a cópia de utils/driver.py no dispositivo, depois acionar um soft-reset para reiniciar o seu programa e monitorizar a saída através do comando repl.

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

Igual ao anterior, mas atualizar primeiro o diretório utils completo.

mpremote mount .

Montar o diretório local atual em /remote no dispositivo e iniciar uma sessão repl que utilizará /remote como diretório de trabalho.

mpremote mount . exec "import demo"

Após montar o diretório local atual, executa demo.py a partir 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 a partir do diretório atual do host sem o copiar para o sistema de ficheiros.

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

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

Primeiro terá de premir Ctrl-D para repor o estado do interpretador (o que preservará a montagem) antes de premir Ctrl-J para reimportar demo.py.

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

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

mpremote cat boot.py

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

mpremote edit utils/driver.py

Editar utils/driver.py no dispositivo utilizando o seu $EDITOR local.

mpremote cp :main.py .

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

mpremote cp main.py :

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

mpremote cp :a.py :b.py

Copiar a.py no dispositivo para b.py no dispositivo.

mpremote cp -r dir/ :

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

mpremote cp a.py b.py : + repl

Copiar a.py e b.py do diretório local para o dispositivo e depois executar o comando repl.

mpremote mip install aioble

Instalar o pacote aioble do micropython-lib no dispositivo. Consulte Gestão de pacotes.

mpremote mip install github:org/repo@branch

Instalar o pacote a partir do ramo especificado em org/repo no GitHub no dispositivo. Consulte Gestão de pacotes.

mpremote mip install gitlab:org/repo@branch

Instalar o pacote a partir do ramo especificado em org/repo no GitLab no dispositivo. Consulte Gestão de pacotes.

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

Instalar o pacote functools do micropython-lib no diretório /flash/third-party do dispositivo. Consulte Gestão de pacotes.