O Modo Interpretador Interativo do MicroPython (também conhecido como REPL)

Esta seção aborda algumas características do Modo Interpretador Interativo do MicroPython. Um termo comumente usado para isso é REPL (read-eval-print-loop), que será utilizado para se referir a este prompt interativo.

Nota

As OpenMV Cams expõem este REPL através de sua porta serial USB (CDC). Ele só é relevante quando você se conecta diretamente à câmera com um emulador de terminal serial (ou uma ferramenta como o Controle remoto do MicroPython: mpremote). O OpenMV IDE não usa o REPL — ele se comunica com a câmera através de um protocolo de depuração separado para executar scripts, transferir arquivos e transmitir o framebuffer. Tudo o que é descrito nesta página se aplica apenas a sessões de terminal diretas.

Auto-indentação

Ao digitar instruções Python que terminam em dois-pontos (por exemplo, if, for, while), o prompt mudará para três pontos (…) e o cursor será indentado em 4 espaços. Quando você pressionar Enter, a próxima linha continuará no mesmo nível de indentação para instruções regulares ou em um nível adicional de indentação quando apropriado. Se você pressionar a tecla backspace, isso desfará um nível de indentação.

Se o seu cursor estiver de volta totalmente ao início, pressionar RETURN executará o código que você digitou. O exemplo a seguir mostra o que você veria após inserir uma instrução for (o sublinhado mostra onde o cursor acaba parando):

>>> for i in range(30):
...     _

Se você então inserir uma instrução if, um nível adicional de indentação será fornecido:

>>> for i in range(30):
...     if i > 3:
...         _

Agora digite break seguido de RETURN e pressione BACKSPACE:

>>> for i in range(30):
...     if i > 3:
...         break
...     _

Por fim, digite print(i), pressione RETURN, pressione BACKSPACE e pressione RETURN novamente:

>>> for i in range(30):
...     if i > 3:
...         break
...     print(i)
...
0
1
2
3
>>>

A auto-indentação não será aplicada se as duas linhas anteriores forem compostas apenas por espaços. Isso significa que você pode terminar de inserir uma instrução composta pressionando RETURN duas vezes, e então um terceiro toque concluirá e executará.

Auto-completação

Ao digitar um comando no REPL, se a linha digitada até o momento corresponder ao início do nome de algo, pressionar TAB mostrará as possíveis opções que poderiam ser inseridas. Por exemplo, primeiro importe o módulo machine digitando import machine e pressionando RETURN. Em seguida, digite m e pressione TAB, e isso deve expandir para machine. Insira um ponto . e pressione TAB novamente. Você deve ver algo como:

>>> machine.
__name__        info            unique_id       reset
bootloader      freq            rng             idle
sleep           deepsleep       disable_irq     enable_irq
Pin

A palavra será expandida o máximo possível até que existam múltiplas possibilidades. Por exemplo, digite machine.Pin.PULL e pressione TAB, e isso será expandido para machine.Pin.PULL_. Pressionar TAB uma segunda vez mostrará as possíveis expansões:

>>> machine.Pin.PULL_
PULL_DOWN       PULL_UP
>>> machine.Pin.PULL_

Interrompendo um programa em execução

Você pode interromper um programa em execução pressionando Ctrl-C. Isso levantará uma KeyboardInterrupt que o trará de volta ao REPL, desde que o seu programa não intercepte a exceção KeyboardInterrupt.

Por exemplo:

>>> for i in range(1000000):
...     print(i)
...
0
1
2
3
...
6466
6467
6468
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
KeyboardInterrupt:
>>>

Modo de colagem (paste mode)

Se você quiser colar algum código na janela do seu terminal, o recurso de auto-indentação vai bagunçar as coisas. Por exemplo, se você tivesse o seguinte código Python:

def foo():
    print('This is a test to show paste mode')
    print('Here is a second line')
foo()

e você tentar colá-lo no REPL normal, verá algo como isto:

>>> def foo():
...         print('This is a test to show paste mode')
...             print('Here is a second line')
...             foo()
...
Traceback (most recent call last):
  File "<stdin>", line 3
IndentationError: unexpected indent

Se você pressionar Ctrl-E, entrará no modo de colagem, que essencialmente desativa o recurso de auto-indentação e altera o prompt de >>> para ===. Por exemplo:

>>>
paste mode; Ctrl-C to cancel, Ctrl-D to finish
=== def foo():
===     print('This is a test to show paste mode')
===     print('Here is a second line')
=== foo()
===
This is a test to show paste mode
Here is a second line
>>>

O Modo de Colagem permite que linhas em branco sejam coladas. O texto colado é compilado como se fosse um arquivo. Pressionar Ctrl-D sai do modo de colagem e inicia a compilação.

Soft reset

Um Soft Reset reiniciará o interpretador Python, mas tenta não reiniciar o método pelo qual você está conectado à OpenMV Cam (USB).

Você pode realizar um soft reset a partir do REPL pressionando Ctrl-D, ou a partir do seu código Python executando:

machine.soft_reset()

Por exemplo, se você reiniciar a sua OpenMV Cam e executar um comando dir(), veria algo como isto:

>>> dir()
['__name__']

Agora crie algumas variáveis e repita o comando dir():

>>> i = 1
>>> j = 23
>>> x = 'abc'
>>> dir()
['j', 'x', '__name__', 'i']
>>>

Agora, se você pressionar Ctrl-D e repetir o comando dir(), verá que as suas variáveis não existem mais:

MPY: sync filesystems
MPY: soft reboot
MicroPython v1.25.0 on 2025-05-15; OpenMV Cam H7 with STM32H743
Type "help()" for more information.
>>> dir()
['__name__']
>>>

Para mais informações sobre tipos de reinicialização e o processo de inicialização, consulte Sequência de Reset e Inicialização.

A variável especial _ (sublinhado)

Quando você usa o REPL, pode realizar cálculos e ver os resultados. O MicroPython armazena o resultado da instrução anterior na variável _ (sublinhado). Assim, você pode usar o sublinhado para salvar o resultado em uma variável. Por exemplo:

>>> 1 + 2 + 3 + 4 + 5
15
>>> x = _
>>> x
15
>>>

Modo raw e modo raw-paste

O modo raw (também chamado de REPL raw) não é algo que uma pessoa normalmente usaria. Ele se destina ao uso programático e essencialmente se comporta como o modo de colagem com o eco desativado e com controle de fluxo opcional.

O modo raw é acessado usando Ctrl-A. Você então envia o seu código Python, seguido de um Ctrl-D. O Ctrl-D será confirmado com ‘OK’ e então o código Python será compilado e executado. Qualquer saída (ou erros) será enviada de volta. Pressionar Ctrl-B sairá do modo raw e retornará ao REPL regular (também conhecido como amigável).

O modo raw-paste é um modo adicional dentro do REPL raw que inclui controle de fluxo e que compila o código à medida que o recebe. Isso o torna mais robusto para a transferência de código em alta velocidade para o dispositivo, e também usa menos RAM ao receber, pois não precisa armazenar uma cópia literal do código antes de compilar (diferentemente do modo raw padrão).

O modo raw-paste usa o seguinte protocolo:

  1. Entre no REPL raw normalmente via Ctrl-A.

  2. Escreva 3 bytes: b"\x05A\x01" (ou seja, Ctrl-E, depois “A” e então Ctrl-A).

  3. Leia 2 bytes para determinar se o dispositivo entrou no modo raw-paste:

    • Se o resultado for b"R\x00", então o dispositivo entende o comando, mas não suporta raw paste.

    • Se o resultado for b"R\x01", então o dispositivo suporta raw paste e entrou neste modo.

    • Caso contrário, o resultado deve ser b"ra" e o dispositivo não suporta raw paste, e a string b"w REPL; CTRL-B to exit\r\n>" deve ser lida e descartada.

  4. Se o dispositivo estiver no modo raw-paste, então continue; caso contrário, recorra ao modo raw padrão.

  5. Leia 2 bytes; este é o incremento do tamanho da janela de controle de fluxo (em bytes) armazenado como um inteiro de 16 bits sem sinal em little endian. O valor inicial para a variável de tamanho-de-janela-restante deve ser definido como este número.

  6. Escreva o código no dispositivo:

    • Enquanto houver bytes a enviar, escreva até o equivalente ao tamanho-de-janela-restante em bytes e diminua o tamanho-de-janela-restante pelo número de bytes escritos.

    • Se o tamanho-de-janela-restante for 0, ou se houver um byte aguardando leitura, leia 1 byte. Se este byte for b"\x01", então aumente o tamanho-de-janela-restante pelo incremento do tamanho da janela do passo 5. Se este byte for b"\x04", então o dispositivo quer encerrar a recepção de dados, e b"\x04" deve ser escrito no dispositivo e nenhum código adicional deve ser enviado depois disso. (Nota: se houver um byte aguardando para ser lido do dispositivo, ele não precisa ser lido e processado imediatamente; o dispositivo continuará a consumir os bytes recebidos enquanto o tamanho-de-janela-restante for maior que 0.)

  7. Quando todo o código tiver sido escrito no dispositivo, escreva b"\x04" para indicar o fim dos dados.

  8. Leia do dispositivo até que b"\x04" seja recebido. Neste ponto, o dispositivo recebeu e compilou todo o código que foi enviado e está executando-o.

  9. O dispositivo emite quaisquer caracteres produzidos pelo código em execução. Quando (se) o código terminar, b"\x04" será emitido, seguido de qualquer exceção que não tenha sido capturada, seguido novamente de b"\x04". Em seguida, ele retorna ao REPL raw padrão e emite b">".

Por exemplo, começando em uma nova linha no REPL normal (amigável), se você escrever:

b"\x01\x05A\x01print(123)\x04"

Então o dispositivo responderá com algo como:

b"\r\nraw REPL; CTRL-B to exit\r\n>R\x01\x80\x00\x01\x04123\r\n\x04\x04>"

Detalhado ao longo do tempo, isso se parece com:

# Step 1: enter raw REPL
write: b"\x01"
read: b"\r\nraw REPL; CTRL-B to exit\r\n>"

# Step 2-5: enter raw-paste mode
write: b"\x05A\x01"
read: b"R\x01\x80\x00\x01"

# Step 6-8: write out code
write: b"print(123)\x04"
read: b"\x04"

# Step 9: code executes and result is read
read: b"123\r\n\x04\x04>"

Neste caso, o incremento do tamanho da janela de controle de fluxo é 128 e há duas janelas de dados imediatamente disponíveis no início, uma do valor inicial do incremento do tamanho da janela e outra do valor explícito b"\x01" que é enviado. Isso significa que até 256 bytes podem ser escritos para começar, antes de esperar ou verificar por mais caracteres de controle de fluxo recebidos.

A ferramenta Controle remoto do MicroPython: mpremote usa o REPL raw, incluindo o modo raw-paste, para executar código Python nas OpenMV Cams.