13.3.1.1. A CLI openmv

A instalação do pacote adiciona um executável openmv que abre um visualizador pygame conectado a uma cam via USB. Sem argumentos além da porta serial, ele executa um pequeno script de teste embutido, transmite de volta o frame buffer resultante e o exibe redimensionado e anotado com a taxa de quadros atual:

openmv --port /dev/ttyACM0

O caminho da porta depende da plataforma do host. No Linux, /dev/ttyACMx para USB CDC e /dev/ttyUSBx para uma ponte USB-para-UART. No macOS, /dev/tty.usbmodem... ou /dev/cu.usbmodem.... No Windows, COMx.

O visualizador é a maneira mais rápida de confirmar que o pacote está instalado, que a cam está acessível e que o protocolo está funcionando. Também é uma estrutura de demonstração útil durante o desenvolvimento de scripts – troque o script de teste embutido por qualquer arquivo MicroPython com --script e observe o resultado sem sair do terminal.

Esc, Ctrl+C no terminal ou fechar a janela do visualizador encerram tudo de forma limpa.

13.3.1.1.1. Executando um script personalizado

--script aponta a CLI para um arquivo de código-fonte MicroPython no disco. O arquivo é enviado para a cam, executado no lugar do script de teste embutido, e quaisquer quadros que ele produza são transmitidos de volta para o visualizador:

openmv --port /dev/ttyACM0 --script my_script.py

Tudo o que o script imprime em stdout é espelhado no terminal do host em tempo real. Passe --quiet para suprimir isso, ou --debug para registro detalhado do protocolo.

13.3.1.1.2. Pré-visualizando um canal personalizado

--channel NAME consulta um canal de dados personalizado registrado pelo script em execução no lado da cam e imprime os primeiros dez bytes de cada atualização no terminal:

openmv --port /dev/ttyACM0 --channel ticks

O script de teste embutido que é executado quando nenhum --script é fornecido registra um canal ticks que retorna o tempo de atividade da cam em milissegundos, então --channel ticks demonstra a superfície bidirecional de canais que Canais personalizados cobre em detalhes – sem que você precise escrever código algum no host ou na cam.

13.3.1.1.3. Modo de benchmark

--bench troca o script de teste padrão por um benchmark de throughput de compressão JPEG:

openmv --port /dev/ttyACM0 --bench

A cam captura um quadro RGB565 QVGA, comprime-o em JPEG e, em seguida, descarrega o mesmo buffer comprimido em um loop apertado. O visualizador reporta a taxa bruta de dados USB em vez de um quadro decodificado ao vivo, então o número na tela é o limite superior que o enlace consegue sustentar até aquele host. Útil para comparar cams ou hosts sem a variabilidade de mudar o que está sendo efetivamente capturado.

13.3.1.1.4. Profiling

A CLI pode sobrepor dados ao vivo do profiler nos quadros transmitidos. A sobreposição só é útil quando a cam está executando uma build de firmware com PROFILE_ENABLE=1 e o canal profile registrado; no firmware padrão, os controles de profiling não têm efeito.

• --firmware PATH – carrega o ELF do firmware que a cam está executando para que a sobreposição possa resolver os endereços de função nos registros do profiler em nomes legíveis. Sem ele, a sobreposição mostra endereços brutos.

Três atalhos de teclado no visualizador controlam o profiler:

Tecla	Ação
P	Alterna a sobreposição do profiler: desligada, desempenho, eventos.
M	Alterna o modo do profiler entre inclusivo e exclusivo. O modo inclusivo atribui o tempo das funções chamadas à função chamadora; o modo exclusivo não.
R	Zera os contadores do profiler.

13.3.1.1.5. Flags de ajuste do protocolo

As flags abaixo espelham os parâmetros do construtor de openmv.Camera. Os valores padrão funcionam em todas as cams comercializadas; substitua-os apenas ao depurar uma build de firmware personalizada ou ao simular condições adversas de enlace.

• --baudrate N – o padrão é 921600 (o valor mágico que comuta o USB para o protocolo OpenMV). Substitua apenas em enlaces UART.

• --timeout SEC – tempo limite por operação em segundos (padrão 1.0).

• --max-retry N – número de retentativas antes de o enlace ser declarado quebrado (padrão 3).

• --max-payload N – tamanho máximo do payload em bytes (padrão 4096). A cam negocia um valor menor se não conseguir lidar com tanto.

• --crc BOOL – habilita a validação de CRC em cada pacote (padrão true).

• --seq BOOL – habilita a validação de número de sequência (padrão true).

• --ack BOOL – habilita o reconhecimento por pacote (padrão true).

• --events BOOL – habilita as notificações de eventos da cam (padrão true).

• --drop-rate FLOAT – taxa de simulação de descarte de pacotes em [0.0, 1.0] (padrão 0.0). Apenas para testes.

Um ajuste específico da CLI:

• --poll MS – taxa de polling do loop principal do visualizador, em milissegundos (padrão 4).

13.3.1.1.6. Flags diversas

Duas flags ajustam como o visualizador apresenta o stream sem alterar o comportamento do lado da cam:

• --scale N – fator de zoom da exibição (padrão 4). Útil quando os quadros QVGA são pequenos demais para ler em um monitor 4K.

• --raw – solicita que a cam envie os buffers de pixels sem compressão, em vez de comprimidos em JPEG. Útil em cams sem suporte a JPEG por hardware; Transmitindo quadros cobre as compensações.

13.3.1.1.7. O que o visualizador está fazendo

A própria CLI é um programa openmv.Camera. Ela conecta, chama stop() para limpar qualquer script em execução, envia o script com exec(), habilita o streaming com streaming() e, em seguida, executa um loop chamando read_frame() (para atualizar a exibição), read_stdout() (para espelhar as impressões do script) e read_status() (para observar a atividade de todos os outros canais registrados). O código-fonte está em cli.py e é uma referência funcional de uma aplicação que controla uma cam de ponta a ponta.