13.3.1.6. Referință API¶

Suprafața publică a pachetului openmv este clasa Camera pentru comunicarea cu o cameră și ierarhia OMVException pentru erorile de protocol. Ambele sunt documentate pe această pagină.

13.3.1.6.1. Clasa 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)¶

Proxy-ul de pe partea gazdei pentru o cameră OpenMV accesată prin USB serial.

Parametrii:

port – Calea dispozitivului serial. Pe Linux, /dev/ttyACMx pentru USB CDC și /dev/ttyUSBx pentru o punte USB-to-UART. Pe macOS, /dev/tty.usbmodem... sau /dev/cu.usbmodem.... Pe Windows, COMx.
baudrate – Rata baud serială. Prin USB, 921600 este valoarea magică ce comută camera de la REPL-ul MicroPython la protocolul OpenMV – orice altă valoare pe o legătură USB lasă camera în modul REPL, deci trebuie folosită valoarea implicită. Pe o legătură UART valoarea este rata baud reală a liniei și poate fi setată liber pe ambele părți.
crc – Activează validarea CRC pe fiecare pachet.
seq – Activează numerele de secvență per pachet.
ack – Solicită confirmarea pachetelor.
events – Activează notificările de evenimente de la cameră.
timeout – Timeout per operație în secunde.
max_retry – Numărul de reîncercări înainte de a ridica o eroare la un pachet eșuat.
max_payload – Dimensiunea maximă negociată a sarcinii utile în octeți. Camera poate negocia o valoare mai mică.
drop_rate – Probabilitatea, doar pentru testare, de a renunța la un pachet, în [0.0, 1.0]. Lăsați la 0.0 în producție.

Clasa acceptă protocolul context-manager; with Camera(port) as cam: apelează connect() la intrare și disconnect() la ieșire.

13.3.1.6.2. Conexiune¶

Camera.connect() → None¶: Deschide portul serial și execută handshake-ul de protocol. Starea memorată în cache (lista de canale, informațiile despre sistem, informațiile despre versiune) este populată ca efect secundar. Apelat automat de context manager.

Camera.disconnect() → None¶: Închide portul serial și eliberează transportul. Apelat automat când context manager-ul iese.

Camera.is_connected() → bool¶

Întoarce:: True dacă portul serial este deschis.

Camera.reset() → None¶: Resetează camera. Conexiunea este pierdută deoarece camera repornește.

Camera.boot() → None¶: Trece camera în bootloader-ul său. Conexiunea este pierdută deoarece camera repornește.

Camera.update_capabilities() → None¶: Renegociază capabilitățile de protocol (CRC, verificarea secvenței, ACK-uri, evenimente, sarcina utilă maximă) cu camera. Camera raportează sarcina utilă maximă pe care o poate gestiona; cererea gazdei este limitată la aceasta, iar setările convenite sunt trimise înapoi. Apelat automat de connect() – nu există niciun motiv să-l apelați din codul utilizatorului decât dacă marcajele constructorului trebuie renegociate pe o conexiune existentă.

Camera.poll_events() → None¶: Rulează o dată calea de recepție a transportului pentru a consuma orice evenimente în așteptare de la cameră fără a trimite o comandă. Util în programele de lungă durată care trec minute fără alt I/O și doresc să afișeze prompt evenimentele de înregistrare a canalelor.

13.3.1.6.3. Execuția scriptului¶

Camera.exec(script: str) → None¶

Încarcă script (un șir sursă Python) în tamponul stdin al camerei și pornește rularea acestuia.

Parametrii:: script – Sursa MicroPython de executat.

Camera.stop() → None¶: Întrerupe scriptul în rulare. Echivalent cu butonul Stop al IDE-ului.

Camera.read_stdout() → str | None¶

Citește toți octeții pe care scriptul în rulare i-a scris în stdout de la ultimul apel.

Întoarce:: Ieșirea ca șir decodat, sau None dacă nu așteaptă date.

13.3.1.6.4. Streaming¶

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

Pornește sau oprește fluxul de cadre și alege formatul transmis.

Parametrii:

enable – True activează streaming-ul, False îl dezactivează.
raw – Când este False (implicit), camera comprimă în JPEG fiecare cadru înainte de a-l plasa în canalul de flux, iar read_frame() îl decomprimă pe gazdă. Când este True, camera trimite tamponul de pixeli capturat necomprimat – alegerea corectă pe camerele fără suport hardware JPEG, unde compresia software este pasul cel mai lent din buclă.
resolution – (width, height) la care camera scalează fiecare cadru brut înainte de trimitere, deoarece cadrele necomprimate sunt mult mai mari decât cele comprimate în JPEG. Necesar când raw=True; ignorat în caz contrar.

Camera.read_frame() → dict | None¶

Citește cel mai recent cadru din canalul de flux.

Întoarce:: None dacă niciun cadru nu așteaptă, sau un dict cu cheile width (int, pixeli), height (int, pixeli), format (int, identificatorul de format de pixel declarat de cameră), depth (int, dimensiunea imaginii comprimate în octeți pentru cadrele JPEG / PNG; nefolosit pentru formatele necomprimate), data (bytes, RGB888 de lungime width * height * 3) și raw_size (int, octeții pe care camera i-a trimis prin USB înainte de decodare).

13.3.1.6.5. Canale personalizate¶

Camera.has_channel(name: str) → bool¶

Întoarce:: True dacă pe cameră există un canal înregistrat cu name.

Camera.channel_size(name: str) → int¶

Întoarce:: Numărul de octeți pe care canalul numit îi are disponibili în prezent, sau 0 când canalul este gol sau nu există.

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

Citește dintr-un canal personalizat.

Parametrii:

name – Numele canalului înregistrat de scriptul de pe partea camerei.
size – Octeți de citit, sau None pentru a citi tot ce este disponibil.

Întoarce:

Octeții, sau None dacă canalul nu există.

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

Scrie data într-un canal personalizat. Scrierile mai mari decât sarcina utilă sunt împărțite automat pe mai multe pachete.

Parametrii:

name – Numele canalului înregistrat de scriptul de pe partea camerei.
data – Sarcină utilă de tip bytes-like de trimis.

Întoarce:

True dacă canalul există și scrierea a fost trimisă, False în caz contrar.

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

Interoghează fiecare canal înregistrat.

Întoarce:: Dict care mapează numele canalului la o valoare booleană indicând „datele sunt gata de citit”.

Camera.update_channels() → None¶: Reîmprospătează lista de canale din cache de la cameră. Rulează automat data viitoare când se efectuează o căutare de canal după nume, după sosirea unui eveniment de înregistrare a canalului; o aplicație care dorește să afle imediat un canal nou înregistrat poate apela direct această metodă.

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

Caută un canal fie după nume (returnând ID-ul său numeric), fie după ID (returnând numele său). Reîmprospătează mai întâi cache-ul de canale prin update_channels() dacă sunt în așteptare evenimente de înregistrare a canalelor.

Parametrii:

name – Numele canalului de rezolvat într-un ID.
channel_id – ID-ul canalului de rezolvat într-un nume.

Întoarce:

ID-ul sau numele corespunzător, sau None când canalul nu există. Trebuie furnizat unul dintre name sau channel_id.

13.3.1.6.6. Introspecția dispozitivului¶

Camera.version() → dict¶

Returnează tripletele de versiune ale protocolului, bootloader-ului și firmware-ului camerei. Memorate în cache după connect(). Fiecare triplet este un tuplu (major, minor, patch) de int:

protocol_version – versiunea protocolului de transmisie OpenMV pe care îl implementează camera.
bootloader_version – imaginea bootloader-ului rezidentă în memoria flash.
firmware_version – firmware-ul MicroPython care rulează în prezent.

Camera.system_info() → dict¶

Returnează informațiile despre capabilitățile hardware și memoria camerei. Memorate în cache după connect(). Cheile dict-ului returnat se încadrează în patru grupuri.

Identitate

cpu_id – identificator CPU pe 32 de biți.
device_id – tuplu de 3 cuvinte pe 32 de biți, numărul de serie unic al dispozitivului încorporat în siliciu.
chip_id – tuplu de 3 cuvinte pe 32 de biți, câte o intrare pentru fiecare senzor de imagine conectat la cameră.
usb_vid – ID-ul de furnizor USB.
usb_pid – ID-ul de produs USB.

Dimensiuni de memorie (toate în kiloocteți)

flash_size_kb – totalul memoriei flash interne.
ram_size_kb – totalul RAM.
framebuffer_size_kb – RAM rezervat pentru captura de imagini.
stream_buffer_size_kb – RAM rezervat pentru canalul de flux care trimite cadre către gazdă.

Marcaje de capabilitate (câte o valoare booleană per caracteristică, toate denumite <feature>_present)

gpu_present – unitate de procesare grafică.
npu_present – unitate de procesare neuronală.
isp_present – procesor de semnal de imagine.
venc_present – codificator video.
jpeg_present – codificator hardware JPEG.
dram_present – DRAM extern.
crc_present – accelerator CRC.
pmu_present – unitate de monitorizare a performanței.
wifi_present – radio Wi-Fi.
bt_present – radio Bluetooth.
sd_present – slot pentru card SD.
eth_present – PHY Ethernet.
multicore_present – mai multe nuclee CPU.

Altele

usb_highspeed – valoare booleană, True când USB s-a enumerat în modul high-speed (USB 2.0 HS, 480 Mbps).
pmu_eventcnt – numărul de contoare de evenimente PMU disponibile; 0 când nu există PMU.

Camera.print_system_info() → None¶: Înregistrează blocul formatat de informații despre sistem în logging la nivelul INFO. CLI-ul folosește aceasta la conectare.

13.3.1.6.7. Diagnostice¶

Camera.host_stats() → dict¶

Întoarce:: Contoarele de la nivelul de transport urmărite pe partea gazdei: sent, received, checksum, sequence.

Camera.device_stats() → dict¶

Întoarce:: Contoarele de la nivelul de transport urmărite pe partea camerei: sent, received, checksum, sequence, retransmit, transport, sent_events, max_ack_queue_depth.

13.3.1.6.8. Profiler¶

Profiler-ul raportează numărul de apeluri per funcție și timpii de execuție min / max / total pentru modulele de firmware instrumentate – în prezent image, ml și ulab. Intrarea și ieșirea din funcții sunt interceptate la compilare; runtime-ul eșantionează un contor monoton de microsecunde la fiecare, acumulează rezultatul per funcție și expune tabelul către gazdă prin canalul profile.

Profiler-ul este inclus în firmware doar când PROFILE_ENABLE=1 este transmis către make. Imaginile de firmware standard nu îl includ – marcajul -finstrument-functions pe care build-ul îl adaugă modulelor urmărite are o suprasarcină de runtime semnificativă, așa că build-urile de profilare sunt produse din sursă pentru sesiunea specifică de depanare care le necesită. Când firmware-ul nu a fost compilat cu acest marcaj, canalul profile nu este înregistrat și fiecare metodă de profiler de pe această pagină returnează silențios fără a face nimic.

Unitatea de monitorizare a performanței (PMU) Arm este blocul de contoare hardware al Cortex-M55 – un mic set de contoare configurabile care urmăresc numărul de cicluri, accesările și ratările de cache, comportamentul ramurilor și alte evenimente definite de arhitectură fără a încetini codul măsurat. Pe camerele care au unul – AE3 și N6, cele două camere din gama OpenMV construite în jurul M55 – profiler-ul eșantionează aceste contoare alături de datele de cronometrare, iar totalurile evenimentelor apar în fiecare înregistrare per funcție. Camerele fără PMU produc totuși înregistrări de cronometrare; câmpurile de evenimente revin ca zero, iar profiler_event() este o operație inactivă.

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

Comută între cronometrarea inclusivă și exclusivă. Cronometrarea inclusivă atribuie timpul funcțiilor apelate funcției apelante; cronometrarea exclusivă nu face acest lucru.

Parametrii:: exclusive – True selectează cronometrarea exclusivă, False selectează cea inclusivă.

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

Șterge toate contoarele de profil. config=None restaurează de asemenea atribuirea implicită a evenimentelor PMU.

Parametrii:: config – Rezervat pentru viitoare suprascrieri de configurare per contor. Transmiteți None pentru a păstra valorile implicite.

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

Leagă unul dintre sloturile de contor PMU de un eveniment hardware specific.

Parametrii:

counter_num – Indexul contorului.
event_id – Identificator de eveniment definit de arhitectură.

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

Returnează înregistrările de profil per funcție colectate de la ultima resetare. Fiecare înregistrare este un dict cu address, caller, call_count, min_ticks, max_ticks, total_ticks, total_cycles și un tuplu events dimensionat la pmu_eventcnt al camerei.

Întoarce:: Listă de dict-uri de înregistrări, sau None dacă canalul de profil nu este disponibil sau nu au fost colectate date.

13.3.1.6.9. Subclasarea și componentele interne ale canalelor¶

Metodele documentate mai sus acoperă fiecare utilizare comună a pachetului. Câteva tipare – gestionarea evenimentelor de pe partea camerei la care gazda dorește să reacționeze, blocarea unui canal pentru un schimb în mai mulți pași, comunicarea cu canale care transportă date structurate în loc de fluxuri de octeți, sau acționarea comenzilor de control specifice canalului – necesită metode pe care Camera le păstrează prefixate cu un underscore. Aceste nume sunt private prin convenție (Python nu le aplică name-mangling), iar aplicațiile care le necesită sunt așteptate fie să subclaseze Camera, fie să apeleze direct metodele.

Subclasarea pentru a reacționa la evenimente. Fiecare eveniment pe care îl emite camera sosește prin Camera._handle_event(). Subclasarea Camera și suprascrierea metodei este modul în care o aplicație reacționează la evenimentele ridicate de scriptul său de pe partea camerei; pagina Evenimente parcurge tiparul complet.

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

Distribuie un eveniment de la cameră. Apelat de nivelul de transport ori de câte ori sosește un pachet de eveniment. Suprascrieți într-o subclasă pentru a adăuga gestionare specifică aplicației; apelați super()._handle_event(...) pentru a păstra comportamentul implicit (reîmprospătarea listei de canale la CHANNEL_REGISTERED, urmărirea pregătirii cadrelor pe canalul stream, înregistrarea pornirii / opririi canalului stdin).

Parametrii:

channel_id – 0 pentru evenimente de sistem, în caz contrar ID-ul canalului înregistrat.
event – Identificator de eveniment; valorile provin din enumerarea EventType pentru evenimentele de sistem și din ceea ce a ales backend-ul de canal de pe partea camerei pentru evenimentele de canal.

O subclasă care adaugă propriile metode de comunicare prin protocol ar trebui să le decoreze cu retry_if_failed() astfel încât să moștenească același comportament de resincronizare-și-reîncercare pe care îl are fiecare metodă livrată de pe această pagină.

static Camera.retry_if_failed(func)¶

Decorator. Înfășoară o metodă de instanță astfel încât aceasta să reîncerce o dată când transportul ridică ResyncException. Orice metodă care apelează _send_cmd_wait_resp() (direct sau printr-unul dintre wrapper-ele _channel_*) ar trebui să poarte acest decorator:

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

Blocarea canalului asigură că starea canalului nu se schimbă între două operații înrudite (de exemplu, un _channel_size() urmat de un _channel_read(), pe un canal care continuă să adauge date). read_frame() și read_profile() folosesc aceasta intern; o aplicație care acționează un canal personalizat cu acces în mai mulți pași face la fel.

Camera._channel_lock(channel_id: int) → bool¶

Obține un blocaj exclusiv asupra unui canal. Alte operații ale gazdei pe același canal se blochează până când blocajul este eliberat.

Parametrii:: channel_id – ID numeric de canal, de regulă rezolvat cu get_channel().
Întoarce:: True când blocajul a fost acordat.

Camera._channel_unlock(channel_id: int) → bool¶

Eliberează un blocaj obținut anterior cu _channel_lock(). Întotdeauna asociat cu un apel de blocare; folosiți try / finally pentru a vă asigura că deblocarea are loc chiar și când citirea dintre ele ridică o eroare.

Parametrii:: channel_id – ID numeric de canal, de regulă rezolvat cu get_channel().

Canalele structurate transportă înregistrări structurate mai degrabă decât un flux plat de octeți. Canalul de profiler este exemplul livrat: forma sa este (record_count, record_size), iar o gazdă care dorește să afle câte înregistrări așteaptă citește forma în loc de dimensiunea în octeți.

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

Citește descriptorul de formă al unui canal.

Parametrii:: channel_id – ID numeric de canal, de regulă rezolvat cu get_channel().
Întoarce:: Tuplu de întregi fără semn pe 32 de biți care descrie aspectul canalului. Semnificația este specifică canalului.

Comenzile de control specifice canalului – start, stop, reset, configurare – folosesc un singur opcode (CHANNEL_IOCTL) cu un număr de comandă specific canalului și o sarcină utilă struct.pack opțională. Metodele livrate precum stop(), exec() și streaming() sunt wrapper-e subțiri în jurul apelurilor _channel_ioctl() către canalele stdin și stream; un canal personalizat de pe partea camerei care își definește propriul meniu ioctl este acționat în același mod.

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

Emite o comandă ioctl pe un canal.

Parametrii:

channel_id – ID numeric de canal, de regulă rezolvat cu get_channel().
cmd – Număr de comandă definit de backend-ul de canal de pe partea camerei.
fmt – Șir de format struct opțional pentru tuplul de argumente. Transmiteți None pentru ioctl-urile care nu primesc argumente.
args – Valori care corespund cu fmt.

Întoarce:

Orice sarcină utilă returnată de canal, sau None.

Variantele de flux de octeți după ID ale metodelor publice de canal sar peste căutarea nume-la-ID și acceptă un offset de octeți explicit – util pentru citirea unei bucăți din mijlocul unui tampon mare (de exemplu, înregistrările canalului profile).

Camera._channel_size(channel_id: int) → int¶

Parametrii:: channel_id – ID numeric de canal, de regulă rezolvat cu get_channel().
Întoarce:: Octeți disponibili în prezent pe canal.

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

Citește length octeți începând de la offset. Citirile pe mai multe pachete sunt reasamblate automat.

Parametrii:

channel_id – ID numeric de canal, de regulă rezolvat cu get_channel().
offset – Decalaj de octeți de la care să înceapă citirea.
length – Numărul de octeți de citit.

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

Scrie data la offset-ul dat. Scrierile pe mai multe pachete sunt împărțite automat pe pachete.

Parametrii:

channel_id – ID numeric de canal, de regulă rezolvat cu get_channel().
data – Sarcină utilă de tip bytes-like de scris.
offset – Decalaj de octeți de la care să înceapă scrierea.

Primitivele de protocol sunt cel mai jos nivel pe care îl expune clasa – intrările brute de trimitere-a-unei-comenzi, preluare-a-listei-brute-de-canale și resincronizare-manuală pe care este construit în cele din urmă tot ce este deasupra. O aplicație apelează la ele când trimite un opcode pe care clasa nu îl înfășoară deja, sau când implementează o recuperare personalizată într-o subclasă.

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

Trimite o comandă de protocol și așteaptă răspunsul camerei. Primitiva pe care este construită fiecare altă metodă din această secțiune.

Parametrii:

opcode – Număr de comandă. Enumerarea livrată Opcode listează codurile cu care vine firmware-ul, dar parametrul este doar un întreg – un build de firmware personalizat își poate defini și răspunde la propriile coduri.
channel – ID de canal, sau 0 pentru comenzile de sistem.
data – Sarcină utilă specifică comenzii.

Întoarce:

Sarcina utilă de răspuns, sau None pentru comenzi precum Opcode.SYS_RESET și Opcode.SYS_BOOT care pierd conexiunea.

Camera._channel_list() → dict¶

Preia lista curentă de canale de la cameră fără a atinge dicționarele memorate în cache channels_by_id și channels_by_name pe care le populează update_channels(). Util pentru o subclasă care dorește să inspecteze direct starea canalelor camerei.

Întoarce:: Dict care mapează ID-ul canalului la {'name': str, 'flags': int}.

Camera._resync() → None¶: Re-execută handshake-ul de protocol de la zero. Apelat automat de connect() la conexiunea inițială și de fiecare metodă publică care prinde o OMVException de la transport. O aplicație care implementează propria buclă de recuperare într-o subclasă poate apela direct această metodă după gestionarea erorii de bază.

13.3.1.6.10. Excepții¶

exception openmv.OMVException¶: Clasă de bază pentru fiecare eroare la nivel de protocol. Cele trei subclase de mai jos moștenesc toate din ea, astfel încât un singur except OMVException acoperă întreaga suprafață de erori.

exception openmv.TimeoutException¶: Camera nu a răspuns în timeout-ul configurat. Subclasă a OMVException.

exception openmv.ChecksumException¶: CRC-ul unui pachet nu s-a potrivit. Ridicat după ce protocolul și-a epuizat bugetul de reîncercări. Subclasă a OMVException.

exception openmv.SequenceException¶: Un pachet a sosit cu un număr de secvență neașteptat după reîncercări. Subclasă a OMVException.