13.3.1.6. Referência da API¶

A superfície pública do pacote openmv é a classe Camera para comunicação com uma cam e a hierarquia OMVException para erros de protocolo. Ambas estão documentadas nesta página.

13.3.1.6.1. A classe Camera¶

class openmv.Camera(port: str, *, baudrate: int = 921600, crc: bool = True, seq: bool = True, ack: bool = True, events: bool = True, timeout: float = 1.0, max_retry: int = 3, max_payload: int = 4096, drop_rate: float = 0.0)¶

O proxy do lado do host para uma cam OpenMV acessada por USB serial.

Parâmetros:

port – Caminho do dispositivo serial. 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.
baudrate – Taxa de transmissão (baud rate) serial. Sobre USB, 921600 é o valor mágico que muda a cam do REPL do MicroPython para o protocolo OpenMV – qualquer outro valor em um link USB deixa a cam em modo REPL, portanto o padrão deve ser usado. Sobre um link UART, o valor é a taxa de transmissão (baud rate) real da linha e pode ser definido livremente em ambos os lados.
crc – Habilita a validação CRC em cada pacote.
seq – Habilita números de sequência por pacote.
ack – Exige confirmação de pacote.
events – Habilita notificações de eventos da cam.
timeout – Timeout por operação em segundos.
max_retry – Número de novas tentativas antes de lançar uma exceção em um pacote com falha.
max_payload – Tamanho máximo de payload negociado em bytes. A cam pode negociar para baixo.
drop_rate – Probabilidade, apenas para testes, de descartar um pacote, em [0.0, 1.0]. Deixe em 0.0 em produção.

A classe suporta o protocolo de gerenciador de contexto; with Camera(port) as cam: chama connect() na entrada e disconnect() na saída.

13.3.1.6.2. Conexão¶

Camera.connect() → None¶: Abre a porta serial e executa o handshake do protocolo. O estado em cache (lista de canais, informações do sistema, informações de versão) é populado como efeito colateral. Chamado automaticamente pelo gerenciador de contexto.

Camera.disconnect() → None¶: Fecha a porta serial e libera o transporte. Chamado automaticamente quando o gerenciador de contexto é encerrado.

Camera.is_connected() → bool¶

Retorna:: True se a porta serial estiver aberta.

Camera.reset() → None¶: Reinicia a cam. A conexão é encerrada porque a cam reinicia.

Camera.boot() → None¶: Faz a cam saltar para o seu bootloader. A conexão é encerrada porque a cam reinicia.

Camera.update_capabilities() → None¶: Renegocia as capacidades do protocolo (CRC, verificação de sequência, ACKs, eventos, payload máximo) com a cam. A cam reporta o payload máximo que consegue tratar; a requisição do host é limitada a esse valor e as configurações acordadas são enviadas de volta. Chamado automaticamente por connect() – não há razão para chamá-lo a partir do código do usuário, a menos que as flags do construtor precisem ser renegociadas em uma conexão existente.

Camera.poll_events() → None¶: Executa o caminho de recepção do transporte uma vez para consumir quaisquer eventos pendentes da cam sem enviar um comando. Útil em programas de longa duração que ficam minutos sem outras operações de I/O e querem expor prontamente eventos de registro de canal.

13.3.1.6.3. Execução de scripts¶

Camera.exec(script: str) → None¶

Faz upload de script (uma string de código-fonte Python) para o buffer stdin da cam e inicia sua execução.

Parâmetros:: script – Código-fonte MicroPython a executar.

Camera.stop() → None¶: Interrompe o script em execução. Equivalente ao botão Stop do IDE.

Camera.read_stdout() → str | None¶

Lê quaisquer bytes que o script em execução tenha escrito em stdout desde a última chamada.

Retorna:: A saída como uma string decodificada, ou None se nenhum dado estiver aguardando.

13.3.1.6.4. Streaming¶

Camera.streaming(enable: bool, raw: bool = False, resolution: tuple[int, int] | None = None) → None¶

Liga ou desliga o stream de quadros e seleciona o formato de transmissão.

Parâmetros:

enable – True habilita o streaming, False o desabilita.
raw – Quando False (padrão), a cam comprime cada quadro em JPEG antes de colocá-lo no canal de stream e read_frame() descomprime no host. Quando True, a cam envia o buffer de pixels capturado sem compressão – a escolha certa em cams sem suporte a JPEG por hardware, onde a compressão por software é o passo mais lento no laço.
resolution – Alvo (width, height) para o qual a cam reduz cada quadro bruto antes de enviar, já que quadros não comprimidos são muito maiores que os comprimidos em JPEG. Obrigatório quando raw=True; ignorado caso contrário.

Camera.read_frame() → dict | None¶

Lê o quadro mais recente do canal de stream.

Retorna:: None se nenhum quadro estiver aguardando, ou um dict com as chaves width (int, pixels), height (int, pixels), format (int, o identificador de formato de pixel que a cam declarou), depth (int, o tamanho da imagem comprimida em bytes para quadros JPEG / PNG; não usado para formatos não comprimidos), data (bytes, RGB888 de comprimento width * height * 3) e raw_size (int, bytes que a cam enviou via USB antes da decodificação).

13.3.1.6.5. Canais personalizados¶

Camera.has_channel(name: str) → bool¶

Retorna:: True se existir na cam um canal registrado com name.

Camera.channel_size(name: str) → int¶

Retorna:: Número de bytes que o canal nomeado tem disponíveis no momento, ou 0 quando o canal está vazio ou não existe.

Camera.channel_read(name: str, size: int | None = None) → bytes | None¶

Lê de um canal personalizado.

Parâmetros:

name – Nome do canal registrado pelo script do lado da cam.
size – Bytes a ler, ou None para ler o que estiver disponível.

Retorna:

Os bytes, ou None se o canal não existir.

Camera.channel_write(name: str, data: bytes) → bool¶

Escreve data em um canal personalizado. Escritas maiores que o payload são automaticamente divididas em vários pacotes.

Parâmetros:

name – Nome do canal registrado pelo script do lado da cam.
data – Payload do tipo bytes a enviar.

Retorna:

True se o canal existir e a escrita foi enviada, False caso contrário.

Camera.read_status() → dict[str, bool]¶

Consulta todos os canais registrados.

Retorna:: Dict mapeando o nome do canal para um booleano de “há dados prontos para leitura”.

Camera.update_channels() → None¶: Atualiza a lista de canais em cache a partir da cam. É executado automaticamente na próxima vez que uma busca de canal por nome é feita após a chegada de um evento de registro de canal; uma aplicação que queira conhecer imediatamente um canal recém-registrado pode chamar isto diretamente.

Camera.get_channel(name: str | None = None, channel_id: int | None = None) → int | str | None¶

Faz a busca de um canal seja por nome (retornando seu ID numérico) ou por ID (retornando seu nome). Atualiza o cache de canais via update_channels() primeiro se houver eventos de registro de canal pendentes.

Parâmetros:

name – Nome do canal a resolver para um ID.
channel_id – ID do canal a resolver para um nome.

Retorna:

O ID ou nome correspondente, ou None quando o canal não existe. Um de name ou channel_id deve ser fornecido.

13.3.1.6.6. Introspecção do dispositivo¶

Camera.version() → dict¶

Retorna as triplas de versão de protocolo, bootloader e firmware da cam. Em cache após connect(). Cada tripla é uma tupla (major, minor, patch) de int:

protocol_version – a versão do protocolo de transmissão OpenMV que a cam implementa.
bootloader_version – a imagem de bootloader residente na flash.
firmware_version – o firmware MicroPython atualmente em execução.

Camera.system_info() → dict¶

Retorna as informações de capacidade de hardware e memória da cam. Em cache após connect(). As chaves do dict retornado se enquadram em quatro grupos.

Identidade

cpu_id – identificador de CPU de 32 bits.
device_id – tupla de 3 palavras de 32 bits, o número de série único do dispositivo gravado no silício.
chip_id – tupla de 3 palavras de 32 bits, uma entrada por sensor de imagem conectado à cam.
usb_vid – ID de fornecedor USB.
usb_pid – ID de produto USB.

Tamanhos de memória (todos em kilobytes)

flash_size_kb – flash interna total.
ram_size_kb – RAM total.
framebuffer_size_kb – RAM reservada para captura de imagem.
stream_buffer_size_kb – RAM reservada para o canal de stream que envia quadros ao host.

Flags de capacidade (um booleano por recurso, todos nomeados <feature>_present)

gpu_present – unidade de processamento gráfico.
npu_present – unidade de processamento neural.
isp_present – processador de sinal de imagem.
venc_present – codificador de vídeo.
jpeg_present – codificador JPEG por hardware.
dram_present – DRAM externa.
crc_present – acelerador CRC.
pmu_present – unidade de monitoramento de desempenho.
wifi_present – rádio Wi-Fi.
bt_present – rádio Bluetooth.
sd_present – slot de cartão SD.
eth_present – PHY Ethernet.
multicore_present – múltiplos núcleos de CPU.

Outros

usb_highspeed – booleano, True quando o USB foi enumerado em modo de alta velocidade (USB 2.0 HS, 480 Mbps).
pmu_eventcnt – número de contadores de eventos PMU disponíveis; 0 quando não há PMU.

Camera.print_system_info() → None¶: Registra o bloco formatado de informações do sistema em logging no nível INFO. A CLI usa isto na conexão.

13.3.1.6.7. Diagnóstico¶

Camera.host_stats() → dict¶

Retorna:: Os contadores da camada de transporte rastreados no lado do host: sent, received, checksum, sequence.

Camera.device_stats() → dict¶

Retorna:: Os contadores da camada de transporte rastreados no lado da cam: sent, received, checksum, sequence, retransmit, transport, sent_events, max_ack_queue_depth.

13.3.1.6.8. Profiler¶

O profiler reporta contagens de chamadas por função e tempos de execução mínimo / máximo / total para os módulos de firmware instrumentados – atualmente image, ml e ulab. A entrada e a saída de funções são interceptadas em tempo de compilação; o runtime amostra um contador monotônico de microssegundos em cada uma, acumula o resultado por função e expõe a tabela ao host através do canal profile.

O profiler só é incluído no firmware quando PROFILE_ENABLE=1 é passado para o make. As imagens de firmware padrão não o incluem – a flag -finstrument-functions que a build adiciona aos módulos rastreados tem uma sobrecarga de runtime não trivial, portanto builds de profiling são produzidas a partir do código-fonte para a sessão específica de depuração que precisa delas. Quando o firmware não foi compilado com a flag, o canal profile não é registrado e todos os métodos de profiler desta página retornam silenciosamente sem fazer nada.

A Performance Monitoring Unit (PMU) da Arm é o bloco de contadores por hardware do Cortex-M55 – um pequeno conjunto de contadores configuráveis que rastreiam contagens de ciclos, acertos e falhas de cache, comportamento de desvio e outros eventos definidos pela arquitetura sem retardar o código sob medição. Em cams que possuem uma – a AE3 e a N6, as duas cams da linha OpenMV construídas em torno do M55 – o profiler amostra esses contadores junto com os dados de tempo e os totais de eventos aparecem em cada registro por função. Cams sem PMU ainda produzem registros de tempo; os campos de evento retornam como zero e profiler_event() é uma operação nula.

Camera.profiler_mode(exclusive: bool = False) → None¶

Alterna entre tempo inclusivo e exclusivo. O tempo inclusivo atribui o tempo dos callees ao chamador; o tempo exclusivo não.

Parâmetros:: exclusive – True seleciona tempo exclusivo, False seleciona inclusivo.

Camera.profiler_reset(config: list | None = None) → None¶

Zera todos os contadores de profile. config=None também restaura a atribuição padrão de eventos da PMU.

Parâmetros:: config – Reservado para futuras substituições de configuração por contador. Passe None para manter os padrões.

Camera.profiler_event(counter_num: int, event_id: int) → None¶

Vincula um dos slots de contador da PMU a um evento de hardware específico.

Parâmetros:

counter_num – Índice do contador.
event_id – Identificador de evento definido pela arquitetura.

Camera.read_profile() → list[dict] | None¶

Retorna os registros de profile por função coletados desde a última reinicialização. Cada registro é um dict com address, caller, call_count, min_ticks, max_ticks, total_ticks, total_cycles e uma tupla events dimensionada para o pmu_eventcnt da cam.

Retorna:: Lista de dicts de registro, ou None se o canal de profile não estiver disponível ou nenhum dado tiver sido coletado.

13.3.1.6.9. Subclassificação e internos de canal¶

Os métodos documentados acima cobrem todos os usos comuns do pacote. Alguns padrões – tratar eventos do lado da cam aos quais o host queira reagir, bloquear um canal para uma troca de múltiplos passos, comunicar-se com canais que carregam dados estruturados em vez de fluxos de bytes, ou acionar comandos de controle específicos de canal – precisam de métodos que a Camera mantém prefixados com um underscore. Esses nomes são privados por convenção (o Python não faz name-mangling neles), e espera-se que aplicações que precisem deles ou criem uma subclasse de Camera ou chamem os métodos diretamente.

Subclassificar para reagir a eventos. Todo evento que a cam emite chega através de Camera._handle_event(). Criar uma subclasse de Camera e sobrescrever o método é a forma de uma aplicação reagir a eventos que seu script do lado da cam lança; a página Eventos percorre o padrão completo.

Camera._handle_event(channel_id: int, event: int) → None¶

Despacha um evento da cam. Chamado pela camada de transporte sempre que um pacote de evento chega. Sobrescreva em uma subclasse para adicionar tratamento específico da aplicação; chame super()._handle_event(...) para manter o comportamento padrão (atualização da lista de canais em CHANNEL_REGISTERED, rastreamento de quadro pronto no canal stream, registro de início / parada do canal stdin).

Parâmetros:

channel_id – 0 para eventos de sistema, caso contrário o ID do canal registrado.
event – Identificador de evento; os valores vêm do enum EventType para eventos de sistema e de qualquer coisa que o backend de canal do lado da cam tenha escolhido para eventos de canal.

Uma subclasse que adiciona seus próprios métodos de comunicação de protocolo deve decorá-los com retry_if_failed() para que herdem o mesmo comportamento de ressincronização e nova tentativa que todo método incluído nesta página possui.

static Camera.retry_if_failed(func)¶

Decorador. Envolve um método de instância de modo que ele tente novamente uma vez quando o transporte lançar ResyncException. Qualquer método que chame _send_cmd_wait_resp() (diretamente ou através de um dos wrappers _channel_*) deve carregar este decorador:

class MyCamera(Camera):
    @Camera.retry_if_failed
    def my_custom_command(self, payload):
        return self._send_cmd_wait_resp(Opcode.MY_CMD,
                                        0, payload)

O bloqueio de canal garante que o estado do canal não mude entre duas operações relacionadas (um _channel_size() seguido de um _channel_read(), por exemplo, em um canal que continua acrescentando dados). read_frame() e read_profile() usam isto internamente; uma aplicação que aciona um canal personalizado com acesso de múltiplos passos faz o mesmo.

Camera._channel_lock(channel_id: int) → bool¶

Adquire um bloqueio exclusivo em um canal. Outras operações do host no mesmo canal ficam bloqueadas até que o bloqueio seja liberado.

Parâmetros:: channel_id – ID numérico do canal, normalmente resolvido com get_channel().
Retorna:: True quando o bloqueio foi concedido.

Camera._channel_unlock(channel_id: int) → bool¶

Libera um bloqueio previamente adquirido com _channel_lock(). Sempre pareado com uma chamada de bloqueio; use try / finally para garantir que o desbloqueio ocorra mesmo quando a leitura intermediária lançar uma exceção.

Parâmetros:: channel_id – ID numérico do canal, normalmente resolvido com get_channel().

Canais estruturados carregam registros estruturados em vez de um fluxo plano de bytes. O canal do profiler é o exemplo incluído: sua forma é (record_count, record_size) e um host que queira saber quantos registros estão aguardando lê a forma em vez do tamanho em bytes.

Camera._channel_shape(channel_id: int) → tuple[int, ...]¶

Lê o descritor de forma de um canal.

Parâmetros:: channel_id – ID numérico do canal, normalmente resolvido com get_channel().
Retorna:: Tupla de inteiros de 32 bits sem sinal descrevendo o layout do canal. O significado é específico do canal.

Comandos de controle específicos de canal – iniciar, parar, reiniciar, configurar – viajam em um único opcode (CHANNEL_IOCTL) com um número de comando específico do canal e um payload struct.pack opcional. Os métodos incluídos como stop(), exec() e streaming() são wrappers finos em torno de chamadas _channel_ioctl() contra os canais stdin e stream; um canal personalizado do lado da cam que define seu próprio menu de ioctl é acionado da mesma forma.

Camera._channel_ioctl(channel_id: int, cmd: int, fmt: str | None = None, *args) → bytes | None¶

Emite um comando ioctl em um canal.

Parâmetros:

channel_id – ID numérico do canal, normalmente resolvido com get_channel().
cmd – Número de comando definido pelo backend de canal do lado da cam.
fmt – String de formato struct opcional para a tupla de argumentos. Passe None para ioctls que não recebem argumentos.
args – Valores correspondentes a fmt.

Retorna:

Qualquer payload que o canal retornou, ou None.

Variantes por ID de fluxo de bytes dos métodos de canal públicos pulam a busca de nome para ID e aceitam um offset de byte explícito – útil para ler um pedaço do meio de um buffer grande (os registros do canal profile, por exemplo).

Camera._channel_size(channel_id: int) → int¶

Parâmetros:: channel_id – ID numérico do canal, normalmente resolvido com get_channel().
Retorna:: Bytes atualmente disponíveis no canal.

Camera._channel_read(channel_id: int, offset: int, length: int) → bytes¶

Lê length bytes começando em offset. Leituras de múltiplos pacotes são remontadas automaticamente.

Parâmetros:

channel_id – ID numérico do canal, normalmente resolvido com get_channel().
offset – Offset de byte a partir do qual iniciar a leitura.
length – Número de bytes a ler.

Camera._channel_write(channel_id: int, data: bytes, offset: int = 0) → None¶

Escreve data no offset dado. Escritas de múltiplos pacotes são divididas em pacotes automaticamente.

Parâmetros:

channel_id – ID numérico do canal, normalmente resolvido com get_channel().
data – Payload do tipo bytes a escrever.
offset – Offset de byte a partir do qual iniciar a escrita.

Primitivas de protocolo são o nível mais baixo que a classe expõe – as entradas brutas de enviar-um-comando, buscar-a-lista-bruta-de-canais e ressincronização-manual sobre as quais tudo acima é eventualmente construído. Uma aplicação recorre a elas ao enviar um opcode que a classe ainda não envolve, ou ao implementar recuperação personalizada em uma subclasse.

Camera._send_cmd_wait_resp(opcode: int, channel: int = 0, data: bytes = b'') → bytes | None¶

Envia um comando de protocolo e aguarda a resposta da cam. A primitiva sobre a qual todos os outros métodos desta seção são construídos.

Parâmetros:

opcode – Número do comando. O enum Opcode incluído lista os códigos com que o firmware vem, mas o parâmetro é apenas um inteiro – uma build de firmware personalizada pode definir e responder aos seus próprios.
channel – ID do canal, ou 0 para comandos de sistema.
data – Payload específico do comando.

Retorna:

Payload de resposta, ou None para comandos como Opcode.SYS_RESET e Opcode.SYS_BOOT que encerram a conexão.

Camera._channel_list() → dict¶

Busca a lista de canais atual da cam sem tocar nos dicionários em cache channels_by_id e channels_by_name que update_channels() popula. Útil para uma subclasse que queira inspecionar o estado de canais da cam diretamente.

Retorna:: Dict mapeando o ID do canal para {'name': str, 'flags': int}.

Camera._resync() → None¶: Reexecuta o handshake do protocolo do zero. Chamado automaticamente por connect() na conexão inicial e por todo método público que captura uma OMVException do transporte. Uma aplicação que implemente seu próprio laço de recuperação em uma subclasse pode chamar isto diretamente após tratar o erro subjacente.

13.3.1.6.10. Exceções¶

exception openmv.OMVException¶: Classe base para todo erro de nível de protocolo. As três subclasses abaixo herdam dela, então um único except OMVException cobre toda a superfície de erros.

exception openmv.TimeoutException¶: A cam não respondeu dentro do timeout configurado. Subclasse de OMVException.

exception openmv.ChecksumException¶: O CRC de um pacote não correspondeu. Lançada após o protocolo ter esgotado seu orçamento de novas tentativas. Subclasse de OMVException.

exception openmv.SequenceException¶: Um pacote chegou com um número de sequência inesperado após as novas tentativas. Subclasse de OMVException.