13.3.1.6. API referenca¶

Javna površina paketa openmv je klasa Camera za komunikaciju s kamerom te hijerarhija OMVException za pogreške protokola. Obje su dokumentirane na ovoj stranici.

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

Posrednik na strani domaćina za OpenMV kameru dostupnu preko USB serijske veze.

Parametri:

port – Putanja serijskog uređaja. Na Linuxu, /dev/ttyACMx za USB CDC i /dev/ttyUSBx za USB-na-UART most. Na macOS-u, /dev/tty.usbmodem... ili /dev/cu.usbmodem.... Na Windowsu, COMx.
baudrate – Serijska brzina prijenosa (baud). Preko USB-a, 921600 je magična vrijednost koja prebacuje kameru iz MicroPython REPL-a u OpenMV protokol – bilo koja druga vrijednost na USB vezi ostavlja kameru u REPL načinu rada, pa se mora koristiti zadana vrijednost. Preko UART veze vrijednost je stvarna brzina prijenosa linije (baud) i može se slobodno postaviti na obje strane.
crc – Omogući CRC provjeru valjanosti na svakom paketu.
seq – Omogući redne brojeve po paketu.
ack – Zahtijevaj potvrdu primitka paketa.
events – Omogući obavijesti o događajima s kamere.
timeout – Vremensko ograničenje po operaciji u sekundama.
max_retry – Broj ponovnih pokušaja prije podizanja iznimke na neuspjelom paketu.
max_payload – Maksimalna dogovorena veličina korisnog tereta u bajtovima. Kamera može dogovoriti manju.
drop_rate – Vjerojatnost ispuštanja paketa samo za testiranje, u [0.0, 1.0]. U produkciji ostavite na 0.0.

Klasa podržava protokol upravitelja konteksta; with Camera(port) as cam: poziva connect() pri ulasku i disconnect() pri izlasku.

13.3.1.6.2. Veza¶

Camera.connect() → None¶: Otvori serijski port i izvrši rukovanje protokolom. Predmemorirano stanje (popis kanala, informacije o sustavu, informacije o verziji) popunjava se kao nuspojava. Automatski ga poziva upravitelj konteksta.

Camera.disconnect() → None¶: Zatvori serijski port i otpusti transport. Automatski se poziva kada upravitelj konteksta izlazi.

Camera.is_connected() → bool¶

Vraća:: True ako je serijski port otvoren.

Camera.reset() → None¶: Resetiraj kameru. Veza se prekida jer se kamera ponovno pokreće.

Camera.boot() → None¶: Skoči s kamerom u njezin pokretač (bootloader). Veza se prekida jer se kamera ponovno pokreće.

Camera.update_capabilities() → None¶: Ponovno dogovori mogućnosti protokola (CRC, provjera redoslijeda, ACK-ovi, događaji, maksimalni korisni teret) s kamerom. Kamera prijavljuje maksimalni korisni teret koji može obraditi; zahtjev domaćina ograničava se na to i dogovorene postavke se vraćaju. Automatski ga poziva connect() – nema razloga pozivati ga iz korisničkog koda osim ako se zastavice konstruktora trebaju ponovno dogovoriti na postojećoj vezi.

Camera.poll_events() → None¶: Pokreni prijemni put transporta jednom kako bi se potrošili svi neobrađeni događaji s kamere bez slanja naredbe. Korisno u dugotrajnim programima koji prolaze minutama bez drugog I/O-a, a žele pravovremeno prikazati događaje registracije kanala.

13.3.1.6.3. Izvršavanje skripte¶

Camera.exec(script: str) → None¶

Učitaj script (niz Python izvornog koda) u međuspremnik stdin kamere i pokreni njegovo izvršavanje.

Parametri:: script – MicroPython izvorni kod za izvršavanje.

Camera.stop() → None¶: Prekini skriptu koja se izvršava. Ekvivalentno gumbu Stop u IDE-u.

Camera.read_stdout() → str | None¶

Pročitaj sve bajtove koje je skripta u izvršavanju zapisala u stdout od posljednjeg poziva.

Vraća:: Izlaz kao dekodirani niz, ili None ako nema podataka na čekanju.

13.3.1.6.4. Strujanje¶

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

Uključi ili isključi strujanje sličica i odaberi format prijenosa.

Parametri:

enable – True omogućuje strujanje, False ga onemogućuje.
raw – Kada je False (zadano), kamera JPEG-komprimira svaku sličicu prije nego što je smjesti u kanal strujanja, a read_frame() je dekomprimira na domaćinu. Kada je True, kamera šalje uhvaćeni međuspremnik piksela nekomprimiran – ispravan izbor na kamerama bez hardverske podrške za JPEG, gdje je softverska kompresija najsporiji korak u petlji.
resolution – (width, height) cilj na koji kamera smanjuje svaku sirovu sličicu prije slanja, budući da su nekomprimirane sličice puno veće od JPEG-komprimiranih. Obavezno kada je raw=True; inače se zanemaruje.

Camera.read_frame() → dict | None¶

Pročitaj najnoviju sličicu iz kanala strujanja.

Vraća:: None ako nema sličice na čekanju, ili rječnik s ključevima width (int, pikseli), height (int, pikseli), format (int, identifikator formata piksela koji je kamera deklarirala), depth (int, veličina komprimirane slike u bajtovima za JPEG / PNG sličice; nekorišteno za nekomprimirane formate), data (bytes, RGB888 duljine width * height * 3) i raw_size (int, bajtovi koje je kamera poslala preko USB-a prije dekodiranja).

13.3.1.6.5. Prilagođeni kanali¶

Camera.has_channel(name: str) → bool¶

Vraća:: True ako na kameri postoji kanal registriran s name.

Camera.channel_size(name: str) → int¶

Vraća:: Broj bajtova koje imenovani kanal trenutno ima dostupne, ili 0 kada je kanal prazan ili ne postoji.

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

Čitaj iz prilagođenog kanala.

Parametri:

name – Naziv kanala registriran skriptom na strani kamere.
size – Bajtovi za čitanje, ili None za čitanje svega što je dostupno.

Vraća:

Bajtovi, ili None ako kanal ne postoji.

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

Zapiši data u prilagođeni kanal. Zapisi veći od korisnog tereta automatski se dijele preko paketa.

Parametri:

name – Naziv kanala registriran skriptom na strani kamere.
data – Korisni teret nalik bajtovima za slanje.

Vraća:

True ako kanal postoji i zapis je poslan, inače False.

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

Ispitaj svaki registrirani kanal.

Vraća:: Rječnik koji preslikava naziv kanala u booleovu vrijednost „podaci su spremni za čitanje”.

Camera.update_channels() → None¶: Osvježi predmemorirani popis kanala s kamere. Pokreće se automatski sljedeći put kada se izvrši pretraga kanala po nazivu nakon dolaska događaja registracije kanala; aplikacija koja želi odmah saznati novoregistrirani kanal može ovo pozvati izravno.

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

Potraži kanal bilo po nazivu (vraćajući njegov brojčani ID) ili po ID-u (vraćajući njegov naziv). Prvo osvježava predmemoriju kanala putem update_channels() ako su događaji registracije kanala na čekanju.

Parametri:

name – Naziv kanala za razrješavanje u ID.
channel_id – ID kanala za razrješavanje u naziv.

Vraća:

Odgovarajući ID ili naziv, ili None kada kanal ne postoji. Mora se navesti jedan od name ili channel_id.

13.3.1.6.6. Introspekcija uređaja¶

Camera.version() → dict¶

Vrati trojke verzija protokola, pokretača (bootloader) i ugrađenog programa (firmware) kamere. Predmemorirano nakon connect(). Svaka trojka je torka (major, minor, patch) od int:

protocol_version – verzija OpenMV protokola prijenosa koju kamera implementira.
bootloader_version – slika pokretača (bootloader) rezidentna u flash memoriji.
firmware_version – MicroPython ugrađeni program (firmware) koji se trenutno izvršava.

Camera.system_info() → dict¶

Vrati informacije o hardverskim mogućnostima i memoriji kamere. Predmemorirano nakon connect(). Ključevi vraćenog rječnika spadaju u četiri skupine.

Identitet

cpu_id – 32-bitni identifikator CPU-a.
device_id – trojka 32-bitnih riječi, jedinstveni serijski broj uređaja utisnut u silicij.
chip_id – trojka 32-bitnih riječi, jedan unos po senzoru slike spojenom na kameru.
usb_vid – USB ID dobavljača.
usb_pid – USB ID proizvoda.

Veličine memorije (sve u kilobajtima)

flash_size_kb – ukupna unutarnja flash memorija.
ram_size_kb – ukupni RAM.
framebuffer_size_kb – RAM rezerviran za snimanje slika.
stream_buffer_size_kb – RAM rezerviran za kanal strujanja koji šalje sličice domaćinu.

Zastavice mogućnosti (jedna booleova vrijednost po značajki, sve nazvane <feature>_present)

gpu_present – grafička procesorska jedinica.
npu_present – neuronska procesorska jedinica.
isp_present – procesor signala slike.
venc_present – video koder.
jpeg_present – hardverski JPEG koder.
dram_present – vanjski DRAM.
crc_present – CRC akcelerator.
pmu_present – jedinica za nadzor performansi.
wifi_present – Wi-Fi radio.
bt_present – Bluetooth radio.
sd_present – utor za SD karticu.
eth_present – Ethernet PHY.
multicore_present – više CPU jezgri.

Ostalo

usb_highspeed – booleova vrijednost, True kada se USB enumerirao u brzom načinu rada (USB 2.0 HS, 480 Mbps).
pmu_eventcnt – broj dostupnih PMU brojača događaja; 0 kada nema PMU-a.

Camera.print_system_info() → None¶: Zabilježi formatirani blok informacija o sustavu u logging na razini INFO. CLI ovo koristi pri povezivanju.

13.3.1.6.7. Dijagnostika¶

Camera.host_stats() → dict¶

Vraća:: Brojači transportnog sloja praćeni na strani domaćina: sent, received, checksum, sequence.

Camera.device_stats() → dict¶

Vraća:: Brojači transportnog sloja praćeni na strani kamere: sent, received, checksum, sequence, retransmit, transport, sent_events, max_ack_queue_depth.

13.3.1.6.8. Profiler¶

Profiler izvještava o broju poziva po funkciji te min / max / ukupnim vremenima izvršavanja za instrumentirane module ugrađenog programa (firmware) – trenutno image, ml i ulab. Ulazak i izlazak iz funkcije presreću se u vrijeme prevođenja; izvršno okruženje uzorkuje monotoni mikrosekundni brojač na svakom, akumulira rezultat po funkciji i izlaže tablicu domaćinu putem kanala profile.

Profiler se ugrađuje u ugrađeni program (firmware) samo kada se PROFILE_ENABLE=1 proslijedi naredbi make. Standardne slike ugrađenog programa (firmware) ga ne uključuju – zastavica -finstrument-functions koju build dodaje praćenim modulima ima netrivijalne troškove izvršnog okruženja, pa se profilirani buildovi proizvode iz izvornog koda za određenu sesiju otklanjanja pogrešaka kojoj su potrebni. Kada ugrađeni program (firmware) nije izgrađen s tom zastavicom, kanal profile nije registriran i svaka metoda profilera na ovoj stranici vraća se tiho bez ikakve radnje.

Arm Jedinica za nadzor performansi (PMU) je blok hardverskih brojača Cortex-M55 – mali skup konfigurabilnih brojača koji prate broj ciklusa, pogotke i promašaje predmemorije, ponašanje grananja i druge arhitekturno definirane događaje bez usporavanja koda koji se mjeri. Na kamerama koje ga imaju – AE3 i N6, dvije kamere u OpenMV ponudi izgrađene oko M55 – profiler uzorkuje ove brojače uz podatke o vremenu, a ukupni iznosi događaja pojavljuju se u svakom zapisu po funkciji. Kamere bez PMU-a i dalje proizvode zapise o vremenu; polja događaja vraćaju se kao nula, a profiler_event() ne radi ništa.

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

Prebaci se između uključivog i isključivog mjerenja vremena. Uključivo mjerenje vremena pripisuje vrijeme pozvanih funkcija pozivatelju; isključivo mjerenje vremena to ne čini.

Parametri:: exclusive – True odabire isključivo mjerenje vremena, False odabire uključivo.

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

Očisti sve brojače profila. config=None također vraća zadanu dodjelu PMU događaja.

Parametri:: config – Rezervirano za buduća nadjačavanja konfiguracije po brojaču. Proslijedite None za zadržavanje zadanih vrijednosti.

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

Poveži jedan od PMU utora brojača s određenim hardverskim događajem.

Parametri:

counter_num – Indeks brojača.
event_id – Arhitekturno definiran identifikator događaja.

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

Vrati zapise profila po funkciji prikupljene od posljednjeg resetiranja. Svaki zapis je rječnik s address, caller, call_count, min_ticks, max_ticks, total_ticks, total_cycles i torkom events veličine prema pmu_eventcnt kamere.

Vraća:: Popis rječnika zapisa, ili None ako kanal profila nije dostupan ili nisu prikupljeni nikakvi podaci.

13.3.1.6.9. Podklasiranje i interni elementi kanala¶

Gore dokumentirane metode pokrivaju svaku uobičajenu upotrebu paketa. Nekoliko obrazaca – rukovanje događajima na strani kamere na koje domaćin želi reagirati, zaključavanje kanala za višekoračnu razmjenu, komunikacija s kanalima koji nose oblikovane podatke umjesto tokova bajtova, ili upravljanje kontrolnim naredbama specifičnim za kanal – treba metode koje Camera drži s prefiksom donje crte. Ti su nazivi privatni po dogovoru (Python im ne mijenja imena), a od aplikacija koje ih trebaju očekuje se da ili podklasiraju Camera ili pozovu metode izravno.

Podklasiranje za reagiranje na događaje. Svaki događaj koji kamera emitira stiže putem Camera._handle_event(). Podklasiranje Camera i nadjačavanje metode način je na koji aplikacija reagira na događaje koje podiže njezina skripta na strani kamere; stranica Događaji provodi cijeli obrazac.

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

Otpremi jedan događaj s kamere. Poziva ga transportni sloj kad god stigne paket događaja. Nadjačajte u podklasi za dodavanje rukovanja specifičnog za aplikaciju; pozovite super()._handle_event(...) za zadržavanje zadanog ponašanja (osvježavanje popisa kanala na CHANNEL_REGISTERED, praćenje spremnosti sličice na kanalu stream, zapisivanje pokretanja / zaustavljanja kanala stdin).

Parametri:

channel_id – 0 za sistemske događaje, inače registrirani ID kanala.
event – Identifikator događaja; vrijednosti dolaze iz enumeracije EventType za sistemske događaje i iz onoga što je pozadinski sustav kanala na strani kamere odabrao za događaje kanala.

Podklasa koja dodaje vlastite metode za komunikaciju protokola trebala bi ih ukrasiti s retry_if_failed() kako bi naslijedile isto ponašanje resinkronizacije i ponovnog pokušaja koje ima svaka isporučena metoda na ovoj stranici.

static Camera.retry_if_failed(func)¶

Dekorator. Omotava metodu instance tako da ponavlja pokušaj jednom kada transport podigne ResyncException. Svaka metoda koja poziva _send_cmd_wait_resp() (izravno ili kroz jedan od omotača _channel_*) trebala bi nositi ovaj dekorator:

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

Zaključavanje kanala osigurava da se stanje kanala ne promijeni između dvije povezane operacije (na primjer _channel_size() praćen s _channel_read(), na kanalu koji nastavlja dodavati podatke). read_frame() i read_profile() ovo koriste interno; aplikacija koja upravlja prilagođenim kanalom s višekoračnim pristupom čini isto.

Camera._channel_lock(channel_id: int) → bool¶

Zauzmi ekskluzivnu bravu na kanalu. Druge operacije domaćina na istom kanalu blokiraju dok se brava ne otpusti.

Parametri:: channel_id – Brojčani ID kanala, obično razriješen s get_channel().
Vraća:: True kada je brava odobrena.

Camera._channel_unlock(channel_id: int) → bool¶

Otpusti bravu prethodno zauzetu s _channel_lock(). Uvijek uparen s pozivom zaključavanja; koristite try / finally kako biste osigurali da se otključavanje dogodi čak i kada čitanje između podigne iznimku.

Parametri:: channel_id – Brojčani ID kanala, obično razriješen s get_channel().

Oblikovani kanali nose strukturirane zapise umjesto ravnog toka bajtova. Kanal profilera je isporučeni primjer: njegov oblik je (record_count, record_size), a domaćin koji želi znati koliko zapisa čeka čita oblik umjesto veličine u bajtovima.

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

Pročitaj deskriptor oblika kanala.

Parametri:: channel_id – Brojčani ID kanala, obično razriješen s get_channel().
Vraća:: Torka nepredznačenih 32-bitnih cijelih brojeva koja opisuje raspored kanala. Značenje je specifično za kanal.

Kontrolne naredbe specifične za kanal – pokretanje, zaustavljanje, resetiranje, konfiguriranje – voze se na jednom opkodu (CHANNEL_IOCTL) s brojem naredbe specifičnim za kanal i opcionalnim struct.pack korisnim teretom. Isporučene metode poput stop(), exec() i streaming() tanki su omotači oko poziva _channel_ioctl() prema kanalima stdin i stream; prilagođeni kanal na strani kamere koji definira vlastiti ioctl izbornik upravlja se na isti način.

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

Izdaj ioctl naredbu na kanalu.

Parametri:

channel_id – Brojčani ID kanala, obično razriješen s get_channel().
cmd – Broj naredbe definiran pozadinskim sustavom kanala na strani kamere.
fmt – Opcionalni struct format niz za torku argumenata. Proslijedite None za ioctl-ove koji ne primaju argumente.
args – Vrijednosti koje odgovaraju fmt.

Vraća:

Bilo koji korisni teret koji je kanal vratio, ili None.

Varijante toka bajtova po ID-u javnih metoda kanala preskaču pretragu naziva-u-ID i prihvaćaju eksplicitni bajtni offset – korisno za čitanje dijela iz sredine velikog međuspremnika (zapisi kanala profile, na primjer).

Camera._channel_size(channel_id: int) → int¶

Parametri:: channel_id – Brojčani ID kanala, obično razriješen s get_channel().
Vraća:: Bajtovi trenutno dostupni na kanalu.

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

Pročitaj length bajtova počevši od offset. Višepaketna čitanja automatski se ponovno sastavljaju.

Parametri:

channel_id – Brojčani ID kanala, obično razriješen s get_channel().
offset – Bajtni pomak od kojeg se počinje čitati.
length – Broj bajtova za čitanje.

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

Zapiši data na zadani offset. Višepaketni zapisi automatski se dijele preko paketa.

Parametri:

channel_id – Brojčani ID kanala, obično razriješen s get_channel().
data – Korisni teret nalik bajtovima za zapisivanje.
offset – Bajtni pomak od kojeg se počinje zapisivati.

Primitivi protokola najniža su razina koju klasa izlaže – unosi za sirovo slanje naredbe, dohvaćanje sirovog popisa kanala i ručnu resinkronizaciju na kojima je sve gore u konačnici izgrađeno. Aplikacija poseže za njima kada šalje opkod koji klasa već ne omotava, ili kada implementira prilagođeni oporavak u podklasi.

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

Pošalji naredbu protokola i čekaj odgovor kamere. Primitiv na kojem je izgrađena svaka druga metoda u ovom odjeljku.

Parametri:

opcode – Broj naredbe. Isporučena enumeracija Opcode navodi kodove s kojima se ugrađeni program (firmware) isporučuje, ali parametar je samo cijeli broj – prilagođeni build ugrađenog programa (firmware) može definirati i odgovarati na vlastite.
channel – ID kanala, ili 0 za sistemske naredbe.
data – Korisni teret specifičan za naredbu.

Vraća:

Korisni teret odgovora, ili None za naredbe poput Opcode.SYS_RESET i Opcode.SYS_BOOT koje prekidaju vezu.

Camera._channel_list() → dict¶

Dohvati trenutni popis kanala s kamere bez diranja predmemoriranih rječnika channels_by_id i channels_by_name koje popunjava update_channels(). Korisno za podklasu koja želi izravno pregledati stanje kanala kamere.

Vraća:: Rječnik koji preslikava ID kanala u {'name': str, 'flags': int}.

Camera._resync() → None¶: Ponovno pokreni rukovanje protokolom od početka. Automatski ga poziva connect() pri početnom povezivanju i svaka javna metoda koja uhvati OMVException iz transporta. Aplikacija koja implementira vlastitu petlju oporavka u podklasi može ga pozvati izravno nakon rukovanja temeljnom pogreškom.

13.3.1.6.10. Iznimke¶

exception openmv.OMVException¶: Bazna klasa za svaku pogrešku na razini protokola. Tri podklase u nastavku sve nasljeđuju od nje, pa jedan except OMVException pokriva cijelu površinu pogrešaka.

exception openmv.TimeoutException¶: Kamera nije odgovorila unutar konfiguriranog vremenskog ograničenja. Podklasa od OMVException.

exception openmv.ChecksumException¶: CRC paketa se nije podudarao. Podiže se nakon što je protokol iscrpio svoj proračun ponovnih pokušaja. Podklasa od OMVException.

exception openmv.SequenceException¶: Paket je stigao s neočekivanim rednim brojem nakon ponovnih pokušaja. Podklasa od OMVException.