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

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

Nota

As câmaras OpenMV expõem este REPL através da porta série USB (CDC). Só é relevante quando se liga diretamente à câmara com um emulador de terminal série (ou uma ferramenta como Controlo remoto do MicroPython: mpremote). O OpenMV IDE não utiliza o REPL — comunica com a câmara através de um protocolo de depuração separado para executar scripts, transferir ficheiros e transmitir o buffer de fotograma. Tudo o que é descrito nesta página aplica-se apenas a sessões de terminal diretas.

Auto-indentação

Ao escrever instruções Python que terminam com dois pontos (por exemplo if, for, while), o prompt muda para três pontos (…) e o cursor fica indentado por 4 espaços. Ao pressionar RETURN, a linha seguinte continuará ao mesmo nível de indentação para instruções regulares, ou com um nível adicional de indentação quando apropriado. Se pressionar a tecla BACKSPACE, desfaz um nível de indentação.

Se o cursor estiver completamente de volta ao início, pressionar RETURN executará o código que foi introduzido. A seguir mostra-se o que seria exibido após introduzir uma instrução for (o sublinhado indica onde o cursor fica posicionado):

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

Se introduzir uma instrução if, será fornecido um nível adicional de indentação:

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

Agora introduza break seguido de RETURN e pressione BACKSPACE:

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

Por fim, escreva 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 apenas espaços. Isto significa que pode terminar a introdução de uma instrução composta premindo RETURN duas vezes, sendo que a terceira pressão irá concluir e executar.

Auto-completação

Ao escrever um comando no REPL, se a linha escrita até ao momento corresponder ao início do nome de algo, pressionar TAB mostrará possíveis opções que poderiam ser introduzidas. Por exemplo, primeiro importe o módulo machine introduzindo import machine e premindo RETURN. Em seguida, escreva m e pressione TAB — deverá ser expandido para machine. Introduza um ponto . e pressione TAB novamente. Deverá 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é existirem múltiplas possibilidades. Por exemplo, escreva machine.Pin.PULL e pressione TAB — 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_

Interromper um programa em execução

Pode interromper um programa em execução premindo Ctrl-C. Isso irá gerar um KeyboardInterrupt que o levará de volta ao REPL, desde que o seu programa não intercete 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

Se pretender colar código na janela do terminal, a funcionalidade de auto-indentação irá causar problemas. Por exemplo, se tiver o seguinte código Python:

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

e 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 pressionar Ctrl-E, entrará no modo de colagem, que essencialmente desativa a funcionalidade de auto-indentação e muda 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 colar linhas em branco. O texto colado é compilado como se fosse um ficheiro. Pressionar Ctrl-D sai do modo de colagem e inicia a compilação.

Reset suave

Um Reset suave irá reiniciar o interpretador Python, mas tenta não reiniciar o método pelo qual está ligado à câmara OpenMV (USB).

Pode efetuar um reset suave a partir do REPL premindo Ctrl-D, ou a partir do seu código Python executando:

machine.soft_reset()

Por exemplo, se reiniciar a sua câmara OpenMV e executar um comando dir(), verá 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 introduzir Ctrl-D e repetir o comando dir(), verá que as suas variáveis já não existem:

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 os tipos de reset e o processo de arranque, consulte Sequência de Reset e Arranque.

A variável especial _ (sublinhado)

Quando utiliza o REPL, pode efetuar cálculos e ver os resultados. O MicroPython armazena o resultado da instrução anterior na variável _ (sublinhado). Assim, pode utilizar o sublinhado para guardar o resultado numa variável. Por exemplo:

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

Modo bruto e modo de colagem bruta

O modo bruto (também chamado REPL bruto) não é algo que uma pessoa normalmente utilize. Destina-se a uso programático e comporta-se essencialmente como o modo de colagem com o eco desligado e com controlo de fluxo opcional.

O modo bruto é ativado com Ctrl-A. Em seguida, envia o seu código Python, seguido de Ctrl-D. O Ctrl-D será confirmado com “OK” e o código Python será compilado e executado. Qualquer saída (ou erros) será enviada de volta. Introduzir Ctrl-B sairá do modo bruto e regressará ao REPL regular (também conhecido como amigável).

O modo de colagem bruta é um modo adicional dentro do REPL bruto que inclui controlo de fluxo e compila o código à medida que o recebe. Isto torna-o mais robusto para transferência de código a alta velocidade para o dispositivo, e também utiliza menos RAM ao receber porque não necessita de armazenar uma cópia literal do código antes de compilar (ao contrário do modo bruto padrão).

O modo de colagem bruta utiliza o seguinte protocolo:

  1. Entre no REPL bruto como habitualmente através de ctrl-A.

  2. Escreva 3 bytes: b"\x05A\x01" (ou seja, ctrl-E, depois «A», depois ctrl-A).

  3. Leia 2 bytes para determinar se o dispositivo entrou no modo de colagem bruta:

    • Se o resultado for b"R\x00" então o dispositivo compreende o comando mas não suporta colagem bruta.

    • Se o resultado for b"R\x01" então o dispositivo suporta colagem bruta e entrou neste modo.

    • Caso contrário, o resultado deverá ser b"ra" e o dispositivo não suporta colagem bruta, devendo ser lida e descartada a cadeia b"w REPL; CTRL-B to exit\r\n>".

  4. Se o dispositivo estiver em modo de colagem bruta, continue; caso contrário, recorra ao modo bruto padrão.

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

  6. Escreva o código para o dispositivo:

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

    • Se o tamanho da janela restante for 0, ou houver um byte à espera de ser lido, leia 1 byte. Se esse byte for b"\x01" então aumente o tamanho da janela restante pelo incremento do tamanho da janela do passo 5. Se esse byte for b"\x04" então o dispositivo pretende terminar a receçã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 à espera de ser lido do dispositivo, não é necessário lê-lo e agir imediatamente — o dispositivo continuará a consumir bytes recebidos enquanto o tamanho da janela restante for maior que 0.)

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

  8. Leia do dispositivo até receber b"\x04". Neste ponto, o dispositivo recebeu e compilou todo o código enviado e está a executá-lo.

  9. O dispositivo produz os caracteres gerados pelo código em execução. Quando (se) o código terminar, será produzido b"\x04", seguido de qualquer exceção não capturada, seguida novamente de b"\x04". Em seguida, regressa ao REPL bruto padrão e produz b">".

Por exemplo, começando numa nova linha no REPL normal (amigável), se escrever:

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

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>"

Decomposto ao longo do tempo, isto parece:

# 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 controlo de fluxo é 128 e há dois tamanhos de janela de dados disponíveis imediatamente no início — um do valor inicial do incremento do tamanho da janela e outro do valor explícito b"\x01" que é enviado. Isto significa que podem ser escritos até 256 bytes inicialmente antes de aguardar ou verificar mais caracteres de controlo de fluxo recebidos.

A ferramenta Controlo remoto do MicroPython: mpremote utiliza o REPL bruto, incluindo o modo de colagem bruta, para executar código Python nas câmaras OpenMV.