13.3.1.6. API-referentie¶

Het publieke oppervlak van het openmv-pakket bestaat uit de Camera-klasse om met een cam te communiceren en de OMVException-hiërarchie voor protocolfouten. Beide worden op deze pagina gedocumenteerd.

13.3.1.6.1. De Camera-klasse¶

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)¶

De host-side proxy voor een OpenMV cam die via USB-serieel wordt bereikt.

Parameters:

port – Pad naar het seriële apparaat. Op Linux /dev/ttyACMx voor USB CDC en /dev/ttyUSBx voor een USB-naar-UART-brug. Op macOS /dev/tty.usbmodem... of /dev/cu.usbmodem.... Op Windows COMx.
baudrate – Seriële baudrate. Via USB is 921600 de magische waarde die de cam van de MicroPython REPL naar het OpenMV-protocol omschakelt – elke andere waarde op een USB-verbinding laat de cam in REPL-modus staan, dus de standaardwaarde moet worden gebruikt. Via een UART-verbinding is de waarde de werkelijke lijnbaudrate en kan deze aan beide zijden vrij worden ingesteld.
crc – CRC-validatie op elk pakket inschakelen.
seq – Volgnummers per pakket inschakelen.
ack – Pakketbevestiging vereisen.
events – Gebeurtenismeldingen van de cam inschakelen.
timeout – Time-out per bewerking in seconden.
max_retry – Aantal nieuwe pogingen voordat er bij een mislukt pakket een fout wordt opgeworpen.
max_payload – Maximaal onderhandelde payloadgrootte in bytes. De cam kan naar beneden onderhandelen.
drop_rate – Alleen voor tests bedoelde kans op het laten vallen van een pakket, in [0.0, 1.0]. Laat in productie op 0.0 staan.

De klasse ondersteunt het context-managerprotocol; with Camera(port) as cam: roept connect() aan bij binnenkomst en disconnect() bij vertrek.

13.3.1.6.2. Verbinding¶

Camera.connect() → None¶: Open de seriële poort en voer de protocol-handshake uit. Gecachte status (kanaallijst, systeeminformatie, versie-informatie) wordt als neveneffect gevuld. Wordt automatisch aangeroepen door de context manager.

Camera.disconnect() → None¶: Sluit de seriële poort en geef het transport vrij. Wordt automatisch aangeroepen wanneer de context manager wordt afgesloten.

Camera.is_connected() → bool¶

Retourneert:: True als de seriële poort open is.

Camera.reset() → None¶: Reset de cam. De verbinding wordt verbroken omdat de cam opnieuw opstart.

Camera.boot() → None¶: Laat de cam in zijn bootloader springen. De verbinding wordt verbroken omdat de cam opnieuw opstart.

Camera.update_capabilities() → None¶: Heronderhandel de protocolmogelijkheden (CRC, volgordecontrole, ACK’s, gebeurtenissen, maximale payload) met de cam. De cam meldt de maximale payload die hij aankan; het verzoek van de host wordt daarop afgekapt en de overeengekomen instellingen worden teruggestuurd. Wordt automatisch aangeroepen door connect() – er is geen reden om dit vanuit gebruikerscode aan te roepen, tenzij de constructor-flags op een bestaande verbinding opnieuw onderhandeld moeten worden.

Camera.poll_events() → None¶: Voer het ontvangstpad van het transport eenmaal uit om eventuele in afwachting zijnde gebeurtenissen van de cam te verwerken zonder een commando te versturen. Nuttig in langlopende programma’s die minutenlang geen andere I/O hebben en kanaalregistratie-gebeurtenissen snel naar boven willen brengen.

13.3.1.6.3. Script-uitvoering¶

Camera.exec(script: str) → None¶

Upload script (een Python-bronstring) naar de stdin-buffer van de cam en start de uitvoering ervan.

Parameters:: script – Uit te voeren MicroPython-broncode.

Camera.stop() → None¶: Onderbreek het lopende script. Equivalent aan de Stop-knop van de IDE.

Camera.read_stdout() → str | None¶

Lees alle bytes die het lopende script sinds de laatste aanroep naar stdout heeft geschreven.

Retourneert:: De uitvoer als gedecodeerde string, of None als er geen data wacht.

13.3.1.6.4. Streaming¶

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

Schakel de frame-stream aan of uit en kies het formaat op de draad.

Parameters:

enable – True schakelt streaming in, False schakelt het uit.
raw – Wanneer False (standaard), comprimeert de cam elk frame als JPEG voordat het in het streamkanaal wordt geplaatst en decomprimeert read_frame() op de host. Wanneer True, verstuurt de cam de vastgelegde pixelbuffer ongecomprimeerd – de juiste keuze op cams zonder hardware-JPEG-ondersteuning, waar softwarecompressie de traagste stap in de lus is.
resolution – (width, height) doel waarnaar de cam elk ruw frame verkleint voordat het wordt verzonden, aangezien ongecomprimeerde frames veel groter zijn dan JPEG-gecomprimeerde. Vereist wanneer raw=True; anders genegeerd.

Camera.read_frame() → dict | None¶

Lees het nieuwste frame uit het streamkanaal.

Retourneert:: None als er geen frame wacht, of een dict met de sleutels width (int, pixels), height (int, pixels), format (int, de pixelformaat-identifier die de cam declareerde), depth (int, de gecomprimeerde afbeeldingsgrootte in bytes voor JPEG-/PNG-frames; ongebruikt voor ongecomprimeerde formaten), data (bytes, RGB888 van lengte width * height * 3) en raw_size (int, bytes die de cam via USB verstuurde voor het decoderen).

13.3.1.6.5. Aangepaste kanalen¶

Camera.has_channel(name: str) → bool¶

Retourneert:: True als er een kanaal geregistreerd met name op de cam bestaat.

Camera.channel_size(name: str) → int¶

Retourneert:: Aantal bytes dat het genoemde kanaal momenteel beschikbaar heeft, of 0 wanneer het kanaal leeg is of niet bestaat.

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

Lees uit een aangepast kanaal.

Parameters:

name – Kanaalnaam geregistreerd door het script aan de cam-zijde.
size – Te lezen bytes, of None om te lezen wat beschikbaar is.

Retourneert:

De bytes, of None als het kanaal niet bestaat.

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

Schrijf data naar een aangepast kanaal. Schrijfacties groter dan de payload worden automatisch over meerdere pakketten gesplitst.

Parameters:

name – Kanaalnaam geregistreerd door het script aan de cam-zijde.
data – Bytes-achtige payload om te versturen.

Retourneert:

True als het kanaal bestaat en de schrijfactie is verstuurd, anders False.

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

Peil elk geregistreerd kanaal.

Retourneert:: Dict die de kanaalnaam toewijst aan een boolean van “data is klaar om te lezen”.

Camera.update_channels() → None¶: Ververs de gecachte kanaallijst vanaf de cam. Wordt automatisch uitgevoerd de volgende keer dat een kanaalopzoeking op naam wordt uitgevoerd nadat er een kanaalregistratie-gebeurtenis is binnengekomen; een applicatie die onmiddellijk een nieuw geregistreerd kanaal wil leren kennen, kan dit direct aanroepen.

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

Zoek een kanaal op, ofwel op naam (waarbij de numerieke ID wordt geretourneerd) of op ID (waarbij de naam wordt geretourneerd). Ververst eerst de kanaalcache via update_channels() als er kanaalregistratie-gebeurtenissen in behandeling zijn.

Parameters:

name – Kanaalnaam om naar een ID te herleiden.
channel_id – Kanaal-ID om naar een naam te herleiden.

Retourneert:

Het overeenkomstige ID of de naam, of None wanneer het kanaal niet bestaat. Eén van name of channel_id moet worden opgegeven.

13.3.1.6.6. Apparaat-introspectie¶

Camera.version() → dict¶

Retourneer de protocol-, bootloader- en firmwareversie-triples van de cam. Gecacht na connect(). Elke triple is een (major, minor, patch)-tuple van int:

protocol_version – de versie van het OpenMV-draadprotocol die de cam implementeert.
bootloader_version – de bootloader-image die in het flashgeheugen aanwezig is.
firmware_version – de MicroPython-firmware die momenteel draait.

Camera.system_info() → dict¶

Retourneer de hardwaremogelijkheden- en geheugeninformatie van de cam. Gecacht na connect(). De sleutels van de geretourneerde dict vallen in vier groepen.

Identiteit

cpu_id – 32-bits CPU-identifier.
device_id – 3-tuple van 32-bits woorden, het unieke apparaat-serienummer dat in het silicium is ingebakken.
chip_id – 3-tuple van 32-bits woorden, één vermelding per beeldsensor die met de cam is verbonden.
usb_vid – USB-leverancier-ID.
usb_pid – USB-product-ID.

Geheugengroottes (allemaal in kilobytes)

flash_size_kb – totaal intern flashgeheugen.
ram_size_kb – totaal RAM.
framebuffer_size_kb – RAM gereserveerd voor het vastleggen van afbeeldingen.
stream_buffer_size_kb – RAM gereserveerd voor het streamkanaal dat frames naar de host verzendt.

Mogelijkheidsvlaggen (één boolean per kenmerk, allemaal genaamd <feature>_present)

gpu_present – grafische verwerkingseenheid.
npu_present – neurale verwerkingseenheid.
isp_present – beeldsignaalprocessor.
venc_present – video-encoder.
jpeg_present – JPEG-hardware-encoder.
dram_present – externe DRAM.
crc_present – CRC-versneller.
pmu_present – prestatiebewakingseenheid.
wifi_present – Wi-Fi-radio.
bt_present – Bluetooth-radio.
sd_present – SD-kaartsleuf.
eth_present – Ethernet-PHY.
multicore_present – meerdere CPU-cores.

Overig

usb_highspeed – boolean, True wanneer USB in high-speed-modus (USB 2.0 HS, 480 Mbps) is geënumereerd.
pmu_eventcnt – aantal beschikbare PMU-gebeurtenistellers; 0 wanneer er geen PMU is.

Camera.print_system_info() → None¶: Log het opgemaakte systeeminformatieblok naar logging op het niveau INFO. De CLI gebruikt dit bij het verbinden.

13.3.1.6.7. Diagnostiek¶

Camera.host_stats() → dict¶

Retourneert:: De tellers op transportlaagniveau die aan de host-zijde worden bijgehouden: sent, received, checksum, sequence.

Camera.device_stats() → dict¶

Retourneert:: De tellers op transportlaagniveau die aan de cam-zijde worden bijgehouden: sent, received, checksum, sequence, retransmit, transport, sent_events, max_ack_queue_depth.

13.3.1.6.8. Profiler¶

De profiler rapporteert aanroeptellingen per functie en min-/max-/totale uitvoeringstijden voor de geïnstrumenteerde firmwaremodules – momenteel image, ml en ulab. De ingang en uitgang van functies worden tijdens het compileren onderschept; de runtime bemonstert bij elk een monotone microsecondenteller, accumuleert het resultaat per functie en stelt de tabel via het profile-kanaal beschikbaar aan de host.

De profiler wordt alleen in de firmware ingebouwd wanneer PROFILE_ENABLE=1 aan make wordt doorgegeven. Standaard firmware-images bevatten hem niet – de -finstrument-functions-vlag die de build aan de bijgehouden modules toevoegt, heeft een niet-triviale runtime-overhead, dus profileringsbuilds worden vanuit de broncode geproduceerd voor de specifieke debugsessie die ze nodig heeft. Wanneer de firmware niet met de vlag is gebouwd, wordt het profile-kanaal niet geregistreerd en keert elke profilermethode op deze pagina stilzwijgend terug zonder iets te doen.

De Arm Performance Monitoring Unit (PMU) is het hardwaretellerblok van de Cortex-M55 – een kleine set configureerbare tellers die cyclustellingen, cache-hits en -misses, vertakkingsgedrag en andere architectuurgedefinieerde gebeurtenissen bijhoudt zonder de gemeten code te vertragen. Op cams die er een hebben – de AE3 en de N6, de twee cams in het OpenMV-assortiment die rond de M55 zijn gebouwd – bemonstert de profiler deze tellers naast de timinggegevens en verschijnen de gebeurtenistotalen in elk record per functie. Cams zonder PMU produceren nog steeds timingrecords; de gebeurtenisvelden komen terug als nul, en profiler_event() doet niets.

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

Schakel tussen inclusieve en exclusieve timing. Bij inclusieve timing wordt de tijd van aangeroepen functies aan de aanroeper toegerekend; bij exclusieve timing niet.

Parameters:: exclusive – True selecteert exclusieve timing, False selecteert inclusieve.

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

Wis alle profieltellers. config=None herstelt ook de standaard PMU-gebeurtenistoewijzing.

Parameters:: config – Gereserveerd voor toekomstige configuratie-overrides per teller. Geef None door om de standaardwaarden te behouden.

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

Koppel een van de PMU-tellerslots aan een specifieke hardwaregebeurtenis.

Parameters:

counter_num – Tellerindex.
event_id – Architectuurgedefinieerde gebeurtenis-identifier.

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

Retourneer de profielrecords per functie die sinds de laatste reset zijn verzameld. Elk record is een dict met address, caller, call_count, min_ticks, max_ticks, total_ticks, total_cycles en een events-tuple met een grootte die overeenkomt met de pmu_eventcnt van de cam.

Retourneert:: Lijst van record-dicts, of None als het profielkanaal niet beschikbaar is of er geen data is verzameld.

13.3.1.6.9. Subclassing en kanaalinternals¶

De hierboven gedocumenteerde methoden dekken elk algemeen gebruik van het pakket. Een paar patronen – het afhandelen van cam-side gebeurtenissen waarop de host wil reageren, het vergrendelen van een kanaal voor een meerstapsuitwisseling, het communiceren met kanalen die gevormde data dragen in plaats van bytestromen, of het aansturen van kanaalspecifieke controlecommando’s – hebben methoden nodig die Camera met een underscore vooraf laat gaan. Deze namen zijn per conventie privé (Python past er geen name-mangling op toe), en van applicaties die ze nodig hebben wordt verwacht dat ze ofwel Camera subclassen of de methoden direct aanroepen.

Subclassen om op gebeurtenissen te reageren. Elke gebeurtenis die de cam uitstoot, komt binnen via Camera._handle_event(). Het subclassen van Camera en het overschrijven van de methode is de manier waarop een applicatie reageert op gebeurtenissen die het script aan de cam-zijde opwerpt; de pagina Gebeurtenissen doorloopt het volledige patroon.

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

Verzend één gebeurtenis van de cam. Wordt aangeroepen door de transportlaag telkens wanneer er een gebeurtenispakket binnenkomt. Overschrijf in een subklasse om applicatiespecifieke afhandeling toe te voegen; roep super()._handle_event(...) aan om het standaardgedrag te behouden (verversen van de kanaallijst bij CHANNEL_REGISTERED, frame-gereed-tracking op het stream-kanaal, start-/stoplogging van het stdin-kanaal).

Parameters:

channel_id – 0 voor systeemgebeurtenissen, anders het geregistreerde kanaal-ID.
event – Gebeurtenis-identifier; de waarden komen uit de EventType-enum voor systeemgebeurtenissen en uit wat de kanaalbackend aan de cam-zijde voor kanaalgebeurtenissen heeft gekozen.

Een subklasse die zijn eigen protocolcommuniceren-methoden toevoegt, moet deze decoreren met retry_if_failed() zodat ze hetzelfde resync-en-retry-gedrag erven dat elke verzonden methode op deze pagina heeft.

static Camera.retry_if_failed(func)¶

Decorator. Wikkelt een instantiemethode zodanig in dat deze één keer opnieuw probeert wanneer het transport een ResyncException opwerpt. Elke methode die _send_cmd_wait_resp() aanroept (direct of via een van de _channel_*-wrappers) moet deze decorator dragen:

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

Kanaalvergrendeling zorgt ervoor dat de status van het kanaal niet verandert tussen twee gerelateerde bewerkingen (bijvoorbeeld een _channel_size() gevolgd door een _channel_read() op een kanaal dat blijft data toevoegen). read_frame() en read_profile() gebruiken dit intern; een applicatie die een aangepast kanaal met meerstapstoegang aanstuurt, doet hetzelfde.

Camera._channel_lock(channel_id: int) → bool¶

Verkrijg een exclusieve vergrendeling op een kanaal. Andere host-bewerkingen op hetzelfde kanaal blokkeren totdat de vergrendeling wordt vrijgegeven.

Parameters:: channel_id – Numeriek kanaal-ID, doorgaans herleid met get_channel().
Retourneert:: True wanneer de vergrendeling is verleend.

Camera._channel_unlock(channel_id: int) → bool¶

Geef een vergrendeling vrij die eerder met _channel_lock() is genomen. Altijd gepaard met een vergrendelingsaanroep; gebruik try / finally om ervoor te zorgen dat de ontgrendeling plaatsvindt, zelfs wanneer de leesactie ertussen een fout opwerpt.

Parameters:: channel_id – Numeriek kanaal-ID, doorgaans herleid met get_channel().

Gevormde kanalen dragen gestructureerde records in plaats van een platte bytestroom. Het profilerkanaal is het meegeleverde voorbeeld: zijn vorm is (record_count, record_size) en een host die wil weten hoeveel records er wachten, leest de vorm in plaats van de bytegrootte.

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

Lees de vormdescriptor van een kanaal.

Parameters:: channel_id – Numeriek kanaal-ID, doorgaans herleid met get_channel().
Retourneert:: Tuple van niet-getekende 32-bits gehele getallen die de lay-out van het kanaal beschrijven. De betekenis is kanaalspecifiek.

Kanaalspecifieke controlecommando’s – start, stop, reset, configure – rijden mee op één opcode (CHANNEL_IOCTL) met een kanaalspecifiek commandonummer en een optionele struct.pack-payload. De meegeleverde methoden zoals stop(), exec() en streaming() zijn dunne wrappers rond _channel_ioctl()-aanroepen tegen de stdin- en stream-kanalen; een aangepast kanaal aan de cam-zijde dat zijn eigen ioctl-menu definieert, wordt op dezelfde manier aangestuurd.

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

Geef een ioctl-commando uit op een kanaal.

Parameters:

channel_id – Numeriek kanaal-ID, doorgaans herleid met get_channel().
cmd – Commandonummer gedefinieerd door de kanaalbackend aan de cam-zijde.
fmt – Optionele struct-formaatstring voor de argumenttuple. Geef None door voor ioctls die geen argumenten aannemen.
args – Waarden die overeenkomen met fmt.

Retourneert:

Welke payload het kanaal ook retourneerde, of None.

Op-ID-bytestroomvarianten van de publieke kanaalmethoden slaan de naam-naar-ID-opzoeking over en accepteren een expliciete byte-offset – nuttig voor het lezen van een deel uit het midden van een grote buffer (bijvoorbeeld de records van het profile-kanaal).

Camera._channel_size(channel_id: int) → int¶

Parameters:: channel_id – Numeriek kanaal-ID, doorgaans herleid met get_channel().
Retourneert:: Bytes die momenteel beschikbaar zijn op het kanaal.

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

Lees length bytes vanaf offset. Meerdere-pakketten-leesacties worden automatisch weer samengevoegd.

Parameters:

channel_id – Numeriek kanaal-ID, doorgaans herleid met get_channel().
offset – Byte-offset om vanaf te beginnen lezen.
length – Aantal te lezen bytes.

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

Schrijf data op de opgegeven offset. Meerdere-pakketten-schrijfacties worden automatisch over pakketten gesplitst.

Parameters:

channel_id – Numeriek kanaal-ID, doorgaans herleid met get_channel().
data – Bytes-achtige payload om te schrijven.
offset – Byte-offset om vanaf te beginnen schrijven.

Protocolprimitieven zijn het laagste niveau dat de klasse blootlegt – de ruwe verstuur-een-commando-, haal-de-ruwe-kanaallijst-op- en handmatige-resync-vermeldingen waarop alles hierboven uiteindelijk is gebouwd. Een applicatie grijpt ernaar bij het versturen van een opcode die de klasse nog niet wrapt, of bij het implementeren van aangepaste herstelacties in een subklasse.

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

Verstuur een protocolcommando en wacht op het antwoord van de cam. De primitief waarop elke andere methode in deze sectie is gebouwd.

Parameters:

opcode – Commandonummer. De meegeleverde Opcode-enum somt de codes op waarmee de firmware wordt geleverd, maar de parameter is gewoon een geheel getal – een aangepaste firmwarebuild kan zijn eigen codes definiëren en erop reageren.
channel – Kanaal-ID, of 0 voor systeemcommando’s.
data – Commandospecifieke payload.

Retourneert:

Antwoordpayload, of None voor commando’s zoals Opcode.SYS_RESET en Opcode.SYS_BOOT die de verbinding verbreken.

Camera._channel_list() → dict¶

Haal de huidige kanaallijst op van de cam zonder de gecachte channels_by_id- en channels_by_name-dictionaries aan te raken die update_channels() vult. Nuttig voor een subklasse die de kanaalstatus van de cam direct wil inspecteren.

Retourneert:: Dict die kanaal-ID toewijst aan {'name': str, 'flags': int}.

Camera._resync() → None¶: Voer de protocol-handshake helemaal opnieuw uit. Wordt automatisch aangeroepen door connect() bij de initiële verbinding en door elke publieke methode die een OMVException van het transport opvangt. Een applicatie die zijn eigen herstellus in een subklasse implementeert, mag dit direct aanroepen na het afhandelen van de onderliggende fout.

13.3.1.6.10. Uitzonderingen¶

exception openmv.OMVException¶: Basisklasse voor elke fout op protocolniveau. De drie onderstaande subklassen erven er allemaal van, dus één enkele except OMVException dekt het volledige foutoppervlak.

exception openmv.TimeoutException¶: De cam heeft niet binnen de geconfigureerde time-out gereageerd. Subklasse van OMVException.

exception openmv.ChecksumException¶: De CRC van een pakket kwam niet overeen. Wordt opgeworpen nadat het protocol zijn budget aan nieuwe pogingen heeft uitgeput. Subklasse van OMVException.

exception openmv.SequenceException¶: Er kwam een pakket binnen met een onverwacht volgnummer na nieuwe pogingen. Subklasse van OMVException.