13.3.1.6. API-referens¶

Den publika ytan i openmv-paketet utgörs av klassen Camera för att kommunicera med en kamera och hierarkin OMVException för protokollfel. Båda dokumenteras på denna sida.

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

Värdsidans proxy för en OpenMV-kamera som nås över USB-seriell.

Parametrar:

port – Sökväg till seriell enhet. På Linux /dev/ttyACMx för USB CDC och /dev/ttyUSBx för en USB-till-UART-brygga. På macOS /dev/tty.usbmodem... eller /dev/cu.usbmodem.... På Windows COMx.
baudrate – Seriell baudhastighet. Över USB är 921600 det magiska värdet som växlar kameran från MicroPython-REPL till OpenMV-protokollet – vilket annat värde som helst på en USB-länk lämnar kameran i REPL-läge, så standardvärdet måste användas. Över en UART-länk är värdet den faktiska linjebaudhastigheten och kan ställas in fritt på båda sidor.
crc – Aktivera CRC-validering på varje paket.
seq – Aktivera sekvensnummer per paket.
ack – Kräv paketkvittering.
events – Aktivera händelseaviseringar från kameran.
timeout – Tidsgräns per operation i sekunder.
max_retry – Antal omförsök innan ett undantag kastas vid ett misslyckat paket.
max_payload – Maximal förhandlad nyttolaststorlek i byte. Kameran kan förhandla ner den.
drop_rate – Sannolikhet (endast för test) att tappa ett paket, i [0.0, 1.0]. Lämna på 0.0 i produktion.

Klassen stöder kontexthanterarprotokollet; with Camera(port) as cam: anropar connect() vid inträde och disconnect() vid utträde.

13.3.1.6.2. Anslutning¶

Camera.connect() → None¶: Öppna den seriella porten och utför protokollhandskakningen. Cachat tillstånd (kanallista, systeminformation, versionsinformation) fylls i som en sidoeffekt. Anropas automatiskt av kontexthanteraren.

Camera.disconnect() → None¶: Stäng den seriella porten och frigör transporten. Anropas automatiskt när kontexthanteraren avslutas.

Camera.is_connected() → bool¶

Returer:: True om den seriella porten är öppen.

Camera.reset() → None¶: Återställ kameran. Anslutningen bryts eftersom kameran startar om.

Camera.boot() → None¶: Hoppa in kameran i dess startladdare. Anslutningen bryts eftersom kameran startar om.

Camera.update_capabilities() → None¶: Omförhandla protokollets kapaciteter (CRC, sekvenskontroll, ACK:er, händelser, max nyttolast) med kameran. Kameran rapporterar den maximala nyttolast den klarar av; värdens begäran klipps ner till den och de överenskomna inställningarna skickas tillbaka. Anropas automatiskt av connect() – det finns ingen anledning att anropa den från användarkod om inte konstruktorflaggorna behöver omförhandlas på en befintlig anslutning.

Camera.poll_events() → None¶: Kör transportens mottagningsväg en gång för att konsumera eventuella väntande händelser från kameran utan att skicka ett kommando. Användbart i långkörande program som går i minuter utan annan I/O och vill få fram kanalregistreringshändelser snabbt.

13.3.1.6.3. Skriptkörning¶

Camera.exec(script: str) → None¶

Ladda upp script (en Python-källkodssträng) till kamerans stdin-buffert och börja köra det.

Parametrar:: script – MicroPython-källkod att köra.

Camera.stop() → None¶: Avbryt det körande skriptet. Motsvarar IDE:ns Stopp-knapp.

Camera.read_stdout() → str | None¶

Läs de byte det körande skriptet har skrivit till stdout sedan det senaste anropet.

Returer:: Utdata som en avkodad sträng, eller None om inga data väntar.

13.3.1.6.4. Strömning¶

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

Slå på eller av bildströmmen och välj formatet på tråden.

Parametrar:

enable – True aktiverar strömning, False inaktiverar den.
raw – När False (standard) JPEG-komprimerar kameran varje bildruta innan den placeras i strömkanalen och read_frame() dekomprimerar på värden. När True skickar kameran den fångade pixelbufferten okomprimerad – rätt val på kameror utan JPEG-stöd i hårdvara, där programvarukomprimering är det långsammaste steget i loopen.
resolution – (width, height)-mål som kameran skalar ner varje rå bildruta till innan sändning, eftersom okomprimerade bildrutor är mycket större än JPEG-komprimerade. Krävs när raw=True; ignoreras annars.

Camera.read_frame() → dict | None¶

Läs den senaste bildrutan från strömkanalen.

Returer:: None om ingen bildruta väntar, eller en dict med nycklarna width (int, pixlar), height (int, pixlar), format (int, den pixelformatsidentifierare kameran angav), depth (int, den komprimerade bildstorleken i byte för JPEG-/PNG-bildrutor; oanvänd för okomprimerade format), data (bytes, RGB888 med längden width * height * 3) och raw_size (int, byte som kameran skickade över USB före avkodning).

13.3.1.6.5. Anpassade kanaler¶

Camera.has_channel(name: str) → bool¶

Returer:: True om en kanal registrerad med name finns på kameran.

Camera.channel_size(name: str) → int¶

Returer:: Antal byte som den namngivna kanalen för närvarande har tillgängliga, eller 0 när kanalen är tom eller inte finns.

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

Läs från en anpassad kanal.

Parametrar:

name – Kanalnamn registrerat av kamerasidans skript.
size – Byte att läsa, eller None för att läsa det som finns tillgängligt.

Returer:

Byten, eller None om kanalen inte finns.

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

Skriv data till en anpassad kanal. Skrivningar större än nyttolasten delas automatiskt upp över flera paket.

Parametrar:

name – Kanalnamn registrerat av kamerasidans skript.
data – Byte-liknande nyttolast att skicka.

Returer:

True om kanalen finns och skrivningen skickades, False annars.

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

Avläs varje registrerad kanal.

Returer:: Dict som mappar kanalnamn till ett booleskt värde för ”data är redo att läsas”.

Camera.update_channels() → None¶: Uppdatera den cachade kanallistan från kameran. Körs automatiskt nästa gång en uppslagning av kanal-efter-namn utförs efter att en kanalregistreringshändelse har anlänt; en applikation som vill få reda på en nyligen registrerad kanal omedelbart kan anropa detta direkt.

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

Slå upp en kanal antingen efter namn (returnerar dess numeriska ID) eller efter ID (returnerar dess namn). Uppdaterar kanalcachen via update_channels() först om kanalregistreringshändelser väntar.

Parametrar:

name – Kanalnamn att lösa upp till ett ID.
channel_id – Kanal-ID att lösa upp till ett namn.

Returer:

Motsvarande ID eller namn, eller None när kanalen inte finns. Antingen name eller channel_id måste anges.

13.3.1.6.6. Enhetsintrospektion¶

Camera.version() → dict¶

Returnera kamerans versionstriplar för protokoll, startladdare och fast programvara. Cachas efter connect(). Varje tripel är en (major, minor, patch)-tupel av int:

protocol_version – versionen av OpenMV-trådprotokollet som kameran implementerar.
bootloader_version – startladdarbilden som finns i flashminnet.
firmware_version – den MicroPython-fasta programvara som körs för närvarande.

Camera.system_info() → dict¶

Returnera kamerans information om hårdvarukapacitet och minne. Cachas efter connect(). Den returnerade dictens nycklar faller in i fyra grupper.

Identitet

cpu_id – 32-bitars CPU-identifierare.
device_id – 3-tupel av 32-bitars ord, det unika enhetsserienumret inbränt i kislet.
chip_id – 3-tupel av 32-bitars ord, en post per bildsensor ansluten till kameran.
usb_vid – USB-tillverkar-ID.
usb_pid – USB-produkt-ID.

Minnesstorlekar (alla i kilobyte)

flash_size_kb – totalt internt flashminne.
ram_size_kb – totalt RAM.
framebuffer_size_kb – RAM reserverat för bildfångst.
stream_buffer_size_kb – RAM reserverat för strömkanalen som levererar bildrutor till värden.

Kapacitetsflaggor (en boolean per funktion, alla benämnda <feature>_present)

gpu_present – grafikprocessor.
npu_present – neural processorenhet.
isp_present – bildsignalprocessor.
venc_present – videokodare.
jpeg_present – JPEG-hårdvarukodare.
dram_present – externt DRAM.
crc_present – CRC-accelerator.
pmu_present – prestandaövervakningsenhet.
wifi_present – Wi-Fi-radio.
bt_present – Bluetooth-radio.
sd_present – SD-kortplats.
eth_present – Ethernet-PHY.
multicore_present – flera CPU-kärnor.

Övrigt

usb_highspeed – boolean, True när USB enumererade i höghastighetsläge (USB 2.0 HS, 480 Mbps).
pmu_eventcnt – antal tillgängliga PMU-händelseräknare; 0 när ingen PMU finns.

Camera.print_system_info() → None¶: Logga det formaterade systeminformationsblocket till logging på INFO-nivå. CLI:t använder detta vid anslutning.

13.3.1.6.7. Diagnostik¶

Camera.host_stats() → dict¶

Returer:: Transportlagrets räknare som spåras på värdsidan: sent, received, checksum, sequence.

Camera.device_stats() → dict¶

Returer:: Transportlagrets räknare som spåras på kamerasidan: sent, received, checksum, sequence, retransmit, transport, sent_events, max_ack_queue_depth.

13.3.1.6.8. Profilerare¶

Profileraren rapporterar anropsantal per funktion samt min/max/total exekveringstid för de instrumenterade firmware-modulerna – för närvarande image, ml och ulab. Funktionsinträde och -utträde fångas upp vid kompileringstid; vid körning samplas en monoton mikrosekundsräknare vid varje, resultatet ackumuleras per funktion och tabellen exponeras för värden via kanalen profile.

Profileraren byggs endast in i den fasta programvaran när PROFILE_ENABLE=1 skickas till make. Standardbilder av fast programvara inkluderar den inte – flaggan -finstrument-functions som bygget lägger till i de spårade modulerna har icke-trivial körtidsoverhead, så profileringsbyggen produceras från källkod för den specifika felsökningssession som behöver dem. När den fasta programvaran inte byggdes med flaggan registreras inte kanalen profile och varje profilerarmetod på denna sida återvänder tyst utan att göra något.

Arm Performance Monitoring Unit (PMU) är Cortex-M55:s hårdvaruräknarblock – en liten uppsättning konfigurerbara räknare som spårar cykelantal, cacheträffar och -missar, förgreningsbeteende och andra arkitekturdefinierade händelser utan att sakta ner koden som mäts. På kameror som har en – AE3 och N6, de två kamerorna i OpenMV-sortimentet byggda kring M55 – samplar profileraren dessa räknare jämte tidsdatan och händelsetotalerna dyker upp i varje post per funktion. Kameror utan en PMU producerar fortfarande tidsposter; händelsefälten kommer tillbaka som noll, och profiler_event() är en no-op.

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

Växla mellan inkluderande och exkluderande tidtagning. Inkluderande tidtagning belastar anroparen med de anropade funktionernas tid; exkluderande tidtagning gör det inte.

Parametrar:: exclusive – True väljer exkluderande tidtagning, False väljer inkluderande.

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

Nollställ alla profilräknare. config=None återställer även standardtilldelningen av PMU-händelser.

Parametrar:: config – Reserverat för framtida överstyrningar av konfiguration per räknare. Skicka None för att behålla standardvärdena.

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

Bind en av PMU-räknarplatserna till en specifik hårdvaruhändelse.

Parametrar:

counter_num – Räknarindex.
event_id – Arkitekturdefinierad händelseidentifierare.

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

Returnera profilposterna per funktion som samlats in sedan den senaste nollställningen. Varje post är en dict med address, caller, call_count, min_ticks, max_ticks, total_ticks, total_cycles och en events-tupel dimensionerad efter kamerans pmu_eventcnt.

Returer:: Lista med postdictar, eller None om profilkanalen inte är tillgänglig eller inga data har samlats in.

13.3.1.6.9. Underklassning och kanalinternt¶

Metoderna som dokumenteras ovan täcker varje vanlig användning av paketet. Ett fåtal mönster – att hantera kamerasidans händelser som värden vill reagera på, att låsa en kanal för ett flerstegsutbyte, att kommunicera med kanaler som bär formad data i stället för byteströmmar, eller att driva kanalspecifika styrkommandon – behöver metoder som Camera håller prefixade med understreck. Dessa namn är privata enligt konvention (Python namnmanglar dem inte), och applikationer som behöver dem förväntas antingen underklassa Camera eller anropa metoderna direkt.

Underklassning för att reagera på händelser. Varje händelse kameran sänder ut anländer via Camera._handle_event(). Att underklassa Camera och åsidosätta metoden är sättet en applikation reagerar på händelser som dess kamerasidans skript utlöser; sidan Händelser går igenom hela mönstret.

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

Avskicka en händelse från kameran. Anropas av transportlagret närhelst ett händelsepaket anländer. Åsidosätt i en underklass för att lägga till applikationsspecifik hantering; anropa super()._handle_event(...) för att behålla standardbeteendet (uppdatering av kanallista vid CHANNEL_REGISTERED, spårning av bildruta-redo på kanalen stream, start/stopp-loggning på stdin-kanalen).

Parametrar:

channel_id – 0 för systemhändelser, annars det registrerade kanal-ID:t.
event – Händelseidentifierare; värden kommer från EventType-enumet för systemhändelser och från det som kamerasidans kanalbackend valde för kanalhändelser.

En underklass som lägger till sina egna protokollkommunicerande metoder bör dekorera dem med retry_if_failed() så att de ärver samma omsynkroniserings- och omförsöksbeteende som varje levererad metod på denna sida har.

static Camera.retry_if_failed(func)¶

Dekoratör. Lindar en instansmetod så att den gör ett omförsök en gång när transporten kastar ResyncException. Varje metod som anropar _send_cmd_wait_resp() (direkt eller via en av _channel_*-wrapparna) bör bära denna dekoratör:

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

Kanallåsning säkerställer att kanalens tillstånd inte ändras mellan två relaterade operationer (en _channel_size() följd av en _channel_read(), till exempel, på en kanal som hela tiden lägger till data). read_frame() och read_profile() använder detta internt; en applikation som driver en anpassad kanal med flerstegsåtkomst gör detsamma.

Camera._channel_lock(channel_id: int) → bool¶

Begär ett exklusivt lås på en kanal. Andra värdoperationer på samma kanal blockeras tills låset släpps.

Parametrar:: channel_id – Numeriskt kanal-ID, vanligtvis upplöst med get_channel().
Returer:: True när låset beviljades.

Camera._channel_unlock(channel_id: int) → bool¶

Släpp ett lås som tidigare tagits med _channel_lock(). Alltid parat med ett låsanrop; använd try / finally för att säkerställa att upplåsningen sker även när läsningen däremellan kastar ett undantag.

Parametrar:: channel_id – Numeriskt kanal-ID, vanligtvis upplöst med get_channel().

Formade kanaler bär strukturerade poster snarare än en platt byteström. Profilerarkanalen är det levererade exemplet: dess form är (record_count, record_size) och en värd som vill veta hur många poster som väntar läser formen i stället för bytestorleken.

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

Läs formdeskriptorn för en kanal.

Parametrar:: channel_id – Numeriskt kanal-ID, vanligtvis upplöst med get_channel().
Returer:: Tupel av osignerade 32-bitars heltal som beskriver kanalens layout. Innebörden är kanalspecifik.

Kanalspecifika styrkommandon – start, stopp, återställning, konfigurering – åker på en enda opkod (CHANNEL_IOCTL) med ett kanalspecifikt kommandonummer och en valfri struct.pack-nyttolast. De levererade metoderna som stop(), exec() och streaming() är tunna wrappar kring _channel_ioctl()-anrop mot kanalerna stdin och stream; en anpassad kamerasidans kanal som definierar sin egen ioctl-meny drivs på samma sätt.

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

Utfärda ett ioctl-kommando på en kanal.

Parametrar:

channel_id – Numeriskt kanal-ID, vanligtvis upplöst med get_channel().
cmd – Kommandonummer definierat av kamerasidans kanalbackend.
fmt – Valfri struct-formatsträng för argumenttupeln. Skicka None för ioctls som inte tar några argument.
args – Värden som matchar fmt.

Returer:

Vilken nyttolast kanalen än returnerade, eller None.

Byteströmsvarianter efter ID av de publika kanalmetoderna hoppar över namn-till-ID-uppslagningen och accepterar en explicit byte-offset – användbart för att läsa en bit från mitten av en stor buffert (posterna i kanalen profile, till exempel).

Camera._channel_size(channel_id: int) → int¶

Parametrar:: channel_id – Numeriskt kanal-ID, vanligtvis upplöst med get_channel().
Returer:: Byte som för närvarande är tillgängliga på kanalen.

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

Läs length byte med start vid offset. Flerpaketsläsningar sätts samman automatiskt.

Parametrar:

channel_id – Numeriskt kanal-ID, vanligtvis upplöst med get_channel().
offset – Byte-offset att börja läsa från.
length – Antal byte att läsa.

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

Skriv data vid den givna offset. Flerpaketsskrivningar delas automatiskt upp över paket.

Parametrar:

channel_id – Numeriskt kanal-ID, vanligtvis upplöst med get_channel().
data – Byte-liknande nyttolast att skriva.
offset – Byte-offset att börja skriva vid.

Protokollprimitiver är den lägsta nivå klassen exponerar – de råa posterna för att skicka-ett-kommando, hämta-den-råa-kanallistan och manuell-omsynkronisering som allt ovanför till slut bygger på. En applikation tar till dem när den skickar en opkod klassen inte redan wrappar, eller när den implementerar anpassad återhämtning i en underklass.

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

Skicka ett protokollkommando och vänta på kamerans svar. Primitiven som varje annan metod i detta avsnitt bygger på.

Parametrar:

opcode – Kommandonummer. Det levererade Opcode-enumet listar de koder den fasta programvaran levereras med, men parametern är bara ett heltal – ett anpassat firmware-bygge kan definiera och svara på sina egna.
channel – Kanal-ID, eller 0 för systemkommandon.
data – Kommandospecifik nyttolast.

Returer:

Svarsnyttolast, eller None för kommandon som Opcode.SYS_RESET och Opcode.SYS_BOOT som bryter anslutningen.

Camera._channel_list() → dict¶

Hämta den aktuella kanallistan från kameran utan att röra de cachade dictarna channels_by_id och channels_by_name som update_channels() fyller i. Användbart för en underklass som vill inspektera kamerans kanaltillstånd direkt.

Returer:: Dict som mappar kanal-ID till {'name': str, 'flags': int}.

Camera._resync() → None¶: Kör om protokollhandskakningen från början. Anropas automatiskt av connect() vid initial anslutning och av varje publik metod som fångar ett OMVException från transporten. En applikation som implementerar sin egen återhämtningsloop i en underklass kan anropa detta direkt efter att ha hanterat det underliggande felet.

13.3.1.6.10. Undantag¶

exception openmv.OMVException¶: Basklass för varje fel på protokollnivå. De tre underklasserna nedan ärver alla från den, så ett enda except OMVException täcker hela felytan.

exception openmv.TimeoutException¶: Kameran svarade inte inom den konfigurerade tidsgränsen. Underklass till OMVException.

exception openmv.ChecksumException¶: Ett pakets CRC matchade inte. Kastas efter att protokollet har förbrukat sin omförsöksbudget. Underklass till OMVException.

exception openmv.SequenceException¶: Ett paket anlände med ett oväntat sekvensnummer efter omförsök. Underklass till OMVException.