13.3.1.1. La CLI openmv

L’installazione del pacchetto aggiunge un eseguibile openmv che apre un visualizzatore pygame collegato a una cam tramite USB. Senza argomenti oltre alla porta seriale, esegue un piccolo script di test integrato, restituisce in streaming il frame buffer risultante e lo visualizza scalato e annotato con il frame rate corrente:

openmv --port /dev/ttyACM0

Il percorso della porta dipende dalla piattaforma host. Su Linux, /dev/ttyACMx per USB CDC e /dev/ttyUSBx per un bridge USB-to-UART. Su macOS, /dev/tty.usbmodem... o /dev/cu.usbmodem.... Su Windows, COMx.

Il visualizzatore è il modo più rapido per confermare che il pacchetto sia installato, che la cam sia raggiungibile e che il protocollo funzioni. È anche un comodo banco di prova durante lo sviluppo degli script: sostituisci lo script di test integrato con qualsiasi file MicroPython tramite --script e osserva il risultato senza lasciare il terminale.

Esc, Ctrl+C nel terminale o la chiusura della finestra del visualizzatore consentono tutti di uscire in modo pulito.

13.3.1.1.1. Esecuzione di uno script personalizzato

--script indica alla CLI un file sorgente MicroPython su disco. Il file viene caricato sulla cam, eseguito al posto dello script di test integrato, e tutti i frame che produce vengono restituiti in streaming al visualizzatore:

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

Tutto ciò che lo script stampa su stdout viene rispecchiato in tempo reale sul terminale host. Passa --quiet per sopprimerlo, oppure --debug per un logging dettagliato del protocollo.

13.3.1.1.2. Anteprima di un canale personalizzato

--channel NAME interroga un canale dati personalizzato registrato dallo script in esecuzione lato cam e stampa i primi dieci byte di ogni aggiornamento sul terminale:

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

Lo script di test integrato che viene eseguito quando non è fornito alcun --script registra un canale ticks che restituisce l’uptime in millisecondi della cam, quindi --channel ticks dimostra la superficie del canale bidirezionale trattata in dettaglio in Canali personalizzati, senza che tu debba scrivere alcun codice sull’host o sulla cam.

13.3.1.1.3. Modalità benchmark

--bench sostituisce lo script di test standard con un benchmark di throughput della compressione JPEG:

openmv --port /dev/ttyACM0 --bench

La cam acquisisce un frame RGB565 QVGA, lo comprime in JPEG e poi svuota in un ciclo serrato lo stesso buffer compresso. Il visualizzatore riporta la velocità grezza dei dati USB anziché un frame decodificato in tempo reale, quindi il numero sullo schermo è il limite superiore che il collegamento può sostenere verso quell’host. Utile per confrontare cam o host senza la variabilità data dal cambiamento di ciò che viene effettivamente acquisito.

13.3.1.1.4. Profilazione

La CLI può sovrapporre dati live del profiler ai frame trasmessi in streaming. L’overlay è utile solo quando la cam esegue una build del firmware con PROFILE_ENABLE=1 e il canale profile registrato; sul firmware standard i controlli di profilazione non hanno effetto.

• --firmware PATH – carica l’ELF del firmware in esecuzione sulla cam in modo che l’overlay possa risolvere gli indirizzi delle funzioni nei record del profilo in nomi leggibili. Senza di esso l’overlay mostra gli indirizzi grezzi.

Tre scorciatoie da tastiera nel visualizzatore controllano il profiler:

Tasto	Azione
P	Cicla l’overlay del profiler: off, prestazioni, eventi.
M	Commuta la modalità del profiler tra inclusive ed exclusive. Il timing inclusivo attribuisce il tempo del chiamato al chiamante; il timing esclusivo no.
R	Reimposta i contatori del profiler.

13.3.1.1.5. Flag di tuning del protocollo

I flag seguenti rispecchiano i parametri del costruttore di openmv.Camera. I valori predefiniti funzionano su ogni cam spedita; sovrascrivili solo durante il debug di una build firmware personalizzata o la simulazione di condizioni di collegamento avverse.

• --baudrate N – il valore predefinito è 921600 (il valore magico che commuta l’USB al protocollo OpenMV). Sovrascrivilo solo sui collegamenti UART.

• --timeout SEC – timeout per operazione in secondi (predefinito 1.0).

• --max-retry N – tentativi prima che il collegamento sia dichiarato interrotto (predefinito 3).

• --max-payload N – dimensione massima del payload in byte (predefinita 4096). La cam negozia al ribasso se non riesce a gestire una quantità così elevata.

• --crc BOOL – abilita la validazione CRC su ogni pacchetto (predefinito true).

• --seq BOOL – abilita la validazione del numero di sequenza (predefinito true).

• --ack BOOL – abilita la conferma per pacchetto (predefinito true).

• --events BOOL – abilita le notifiche di eventi dalla cam (predefinito true).

• --drop-rate FLOAT – tasso di simulazione di perdita dei pacchetti in [0.0, 1.0] (predefinito 0.0). Solo per test.

Una manopola di tuning specifica della CLI:

• --poll MS – frequenza di polling del ciclo principale del visualizzatore, in millisecondi (predefinito 4).

13.3.1.1.6. Flag vari

Due flag regolano il modo in cui il visualizzatore presenta lo stream senza modificare il comportamento lato cam:

• --scale N – fattore di zoom della visualizzazione (predefinito 4). Utile quando i frame QVGA sono troppo piccoli da leggere su un display 4K.

• --raw – richiede che la cam invii i buffer dei pixel non compressi anziché compressi in JPEG. Utile su cam senza supporto JPEG hardware; Streaming dei frame tratta i compromessi.

13.3.1.1.7. Cosa sta facendo il visualizzatore

La CLI è essa stessa un programma openmv.Camera. Si connette, chiama stop() per cancellare qualsiasi script in esecuzione, carica lo script con exec(), abilita lo streaming con streaming(), quindi esegue un ciclo chiamando read_frame() (per aggiornare la visualizzazione), read_stdout() (per rispecchiare le stampe dello script) e read_status() (per osservare l’attività di ogni altro canale registrato). Il sorgente si trova in cli.py ed è un riferimento funzionante per un’applicazione che pilota una cam dall’inizio alla fine.