13.3.1.6. API başvurusu¶
openmv paketinin genel arayüzü, bir kamerayla iletişim kurmak için kullanılan Camera sınıfı ve protokol hatalarına yönelik OMVException hiyerarşisinden oluşur. Her ikisi de bu sayfada belgelenmiştir.
13.3.1.6.1. Camera sınıfı¶
- 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)¶
USB seri bağlantısı üzerinden erişilen bir OpenMV kamerasının ana bilgisayar tarafındaki vekilidir (proxy).
- Parametreler:
port – Seri aygıt yolu. Linux’ta, USB CDC için
/dev/ttyACMxve USB-UART köprüsü için/dev/ttyUSBx. macOS’ta,/dev/tty.usbmodem...veya/dev/cu.usbmodem.... Windows’ta iseCOMx.baudrate – Seri baud hızı. USB üzerinden,
921600kamerayı MicroPython REPL’inden OpenMV protokolüne geçiren sihirli değerdir – bir USB bağlantısında başka herhangi bir değer kamerayı REPL modunda bırakır, bu nedenle varsayılan değer kullanılmalıdır. UART bağlantısı üzerinden ise değer gerçek hat baud hızıdır ve her iki tarafta da serbestçe ayarlanabilir.crc – Her pakette CRC doğrulamasını etkinleştirir.
seq – Paket başına sıra numaralarını etkinleştirir.
ack – Paket onayı (acknowledgement) gerektirir.
events – Kameradan gelen olay bildirimlerini etkinleştirir.
timeout – İşlem başına saniye cinsinden zaman aşımı.
max_retry – Başarısız bir pakette hata fırlatmadan önceki yeniden deneme sayısı.
max_payload – Bayt cinsinden müzakere edilen maksimum yük boyutu. Kamera daha düşük bir değer müzakere edebilir.
drop_rate – Bir paketin atılma olasılığı; yalnızca test amaçlıdır,
[0.0, 1.0]aralığındadır. Üretimde0.0olarak bırakın.
Sınıf, bağlam yöneticisi (context manager) protokolünü destekler;
with Camera(port) as cam:girişteconnect(), çıkıştadisconnect()çağrısı yapar.
13.3.1.6.2. Bağlantı¶
- Camera.connect() None¶
Seri bağlantı noktasını açar ve protokol el sıkışmasını (handshake) gerçekleştirir. Önbelleğe alınan durum (kanal listesi, sistem bilgisi, sürüm bilgisi) yan etki olarak doldurulur. Bağlam yöneticisi tarafından otomatik olarak çağrılır.
- Camera.disconnect() None¶
Seri bağlantı noktasını kapatır ve aktarımı (transport) serbest bırakır. Bağlam yöneticisi çıktığında otomatik olarak çağrılır.
- Camera.boot() None¶
Kamerayı önyükleyicisine (bootloader) atlatır. Kamera yeniden başladığı için bağlantı kesilir.
- Camera.update_capabilities() None¶
Protokol yeteneklerini (CRC, sıra kontrolü, ACK’ler, olaylar, maksimum yük) kamerayla yeniden müzakere eder. Kamera işleyebileceği maksimum yükü bildirir; ana bilgisayarın isteği buna göre kırpılır ve üzerinde anlaşılan ayarlar geri gönderilir.
connect()tarafından otomatik olarak çağrılır – mevcut bir bağlantıda yapıcı bayraklarının yeniden müzakere edilmesi gerekmedikçe bunu kullanıcı kodundan çağırmak için bir neden yoktur.
13.3.1.6.3. Betik yürütme¶
13.3.1.6.4. Akış (Streaming)¶
- Camera.streaming(enable: bool, raw: bool = False, resolution: tuple[int, int] | None = None) None¶
Çerçeve akışını açar veya kapatır ve hat üzerindeki (on-the-wire) formatı seçer.
- Parametreler:
enable –
Trueakışı etkinleştirir,Falsedevre dışı bırakır.raw –
Falseolduğunda (varsayılan), kamera her çerçeveyi akış kanalına yerleştirmeden önce JPEG ile sıkıştırır veread_frame()ana bilgisayarda açar.Trueolduğunda, kamera yakalanan piksel arabelleğini sıkıştırılmamış olarak gönderir – yazılımsal sıkıştırmanın döngüdeki en yavaş adım olduğu, donanımsal JPEG desteği bulunmayan kameralar için doğru seçimdir.resolution – Sıkıştırılmamış çerçeveler JPEG ile sıkıştırılmış olanlardan çok daha büyük olduğundan, kameranın göndermeden önce her ham çerçeveyi küçülttüğü
(width, height)hedefi.raw=Trueolduğunda gereklidir; aksi takdirde yok sayılır.
- Camera.read_frame() dict | None¶
En son çerçeveyi akış kanalından okur.
- Dönüşler:
Bekleyen çerçeve yoksa
None, aksi takdirde şu anahtarları içeren bir sözlük:width(int, piksel),height(int, piksel),format(int, kameranın bildirdiği piksel formatı tanımlayıcısı),depth(int, JPEG / PNG çerçeveleri için bayt cinsinden sıkıştırılmış görüntü boyutu; sıkıştırılmamış formatlarda kullanılmaz),data(bytes,width * height * 3uzunluğunda RGB888) veraw_size(int, kameranın çözme öncesinde USB üzerinden gönderdiği bayt sayısı).
13.3.1.6.5. Özel kanallar¶
- Camera.channel_size(name: str) int¶
- Dönüşler:
Adlandırılmış kanalın şu anda kullanılabilir olan bayt sayısı veya kanal boşsa ya da mevcut değilse
0.
- Camera.channel_write(name: str, data: bytes) bool¶
dataöğesini özel bir kanala yazar. Yükten daha büyük yazmalar otomatik olarak paketlere bölünür.- Parametreler:
name – Kamera tarafındaki betik tarafından kaydedilen kanal adı.
data – Gönderilecek bayt benzeri yük.
- Dönüşler:
Kanal varsa ve yazma gönderildiyse
True, aksi takdirdeFalse.
- Camera.read_status() dict[str, bool]¶
Kayıtlı her kanalı yoklar.
- Dönüşler:
Kanal adını “veri okunmaya hazır” boole değerine eşleyen sözlük.
- Camera.update_channels() None¶
Önbelleğe alınmış kanal listesini kameradan tazeler. Bir kanal kayıt olayı geldikten sonra adıyla bir kanal araması yapıldığı bir sonraki sefer otomatik olarak çalışır; yeni kaydedilen bir kanalı hemen öğrenmek isteyen bir uygulama bunu doğrudan çağırabilir.
- Camera.get_channel(name: str | None = None, channel_id: int | None = None) int | str | None¶
Bir kanalı ya adıyla (sayısal kimliğini döndürerek) ya da kimliğiyle (adını döndürerek) arar. Kanal kayıt olayları bekliyorsa önce
update_channels()aracılığıyla kanal önbelleğini tazeler.- Parametreler:
name – Bir kimliğe çözümlenecek kanal adı.
channel_id – Bir ada çözümlenecek kanal kimliği.
- Dönüşler:
Karşılık gelen kimlik veya ad ya da kanal mevcut değilse
None.nameveyachannel_idöğelerinden biri sağlanmalıdır.
13.3.1.6.6. Aygıt iç gözlemi¶
- Camera.version() dict¶
Kameranın protokol, önyükleyici ve aygıt yazılımı sürüm üçlülerini döndürür.
connect()sonrasında önbelleğe alınır. Her üçlü,inttüründe bir(major, minor, patch)demetidir:protocol_version– kameranın uyguladığı OpenMV hat protokolünün sürümü.bootloader_version– flash bellekte yerleşik olan önyükleyici görüntüsü.firmware_version– şu anda çalışan MicroPython aygıt yazılımı.
- Camera.system_info() dict¶
Kameranın donanım yeteneği ve bellek bilgilerini döndürür.
connect()sonrasında önbelleğe alınır. Döndürülen sözlüğün anahtarları dört gruba ayrılır.Kimlik
cpu_id– 32 bitlik CPU tanımlayıcısı.device_id– 32 bitlik üç sözcükten oluşan demet; silikona kazınmış benzersiz aygıt seri numarası.chip_id– 32 bitlik üç sözcükten oluşan demet; kameraya bağlı her görüntü sensörü için bir giriş.usb_vid– USB satıcı kimliği.usb_pid– USB ürün kimliği.
Bellek boyutları (tümü kilobayt cinsinden)
flash_size_kb– toplam dahili flash bellek.ram_size_kb– toplam RAM.framebuffer_size_kb– görüntü yakalama için ayrılmış RAM.stream_buffer_size_kb– çerçeveleri ana bilgisayara gönderen akış kanalı için ayrılmış RAM.
Yetenek bayrakları (özellik başına bir boole, tümü
<feature>_presentolarak adlandırılır)gpu_present– grafik işleme birimi.npu_present– sinir işleme birimi.isp_present– görüntü sinyali işlemcisi.venc_present– video kodlayıcı.jpeg_present– JPEG donanım kodlayıcısı.dram_present– harici DRAM.crc_present– CRC hızlandırıcı.pmu_present– performans izleme birimi.wifi_present– Wi-Fi radyosu.bt_present– Bluetooth radyosu.sd_present– SD kart yuvası.eth_present– Ethernet PHY.multicore_present– birden fazla CPU çekirdeği.
Diğer
usb_highspeed– boole; USB yüksek hızlı (USB 2.0 HS, 480 Mbps) modda numaralandırıldığındaTrue.pmu_eventcnt– kullanılabilir PMU olay sayaçlarının sayısı; PMU yoksa0.
13.3.1.6.7. Tanılama¶
13.3.1.6.8. Profilleyici (Profiler)¶
Profilleyici, donanımına eklenmiş aygıt yazılımı modülleri için işlev başına çağrı sayılarını ve min / maks / toplam yürütme sürelerini raporlar – şu anda image, ml ve ulab. İşlev girişi ve çıkışı derleme zamanında yakalanır; çalışma zamanı her birinde monotonik bir mikrosaniye sayacını örnekler, sonucu işlev başına biriktirir ve tabloyu profile kanalı aracılığıyla ana bilgisayara sunar.
Profilleyici, aygıt yazılımına yalnızca make komutuna PROFILE_ENABLE=1 geçirildiğinde dahil edilir. Standart aygıt yazılımı görüntüleri bunu içermez – derlemenin izlenen modüllere eklediği -finstrument-functions bayrağının önemsenmeyecek bir çalışma zamanı yükü vardır, bu nedenle profilleme derlemeleri bunlara ihtiyaç duyan belirli hata ayıklama oturumu için kaynaktan üretilir. Aygıt yazılımı bu bayrakla derlenmediğinde, profile kanalı kaydedilmez ve bu sayfadaki her profilleyici yöntemi hiçbir şey yapmadan sessizce döner.
Arm Performans İzleme Birimi (PMU), Cortex-M55’in donanımsal sayaç bloğudur – ölçülen kodu yavaşlatmadan çevrim sayılarını, önbellek isabetlerini ve ıskalamalarını, dallanma davranışını ve mimaride tanımlanmış diğer olayları izleyen küçük bir yapılandırılabilir sayaç kümesidir. Bir PMU’ya sahip kameralarda – OpenMV ürün yelpazesinde M55 etrafında inşa edilen iki kamera olan AE3 ve N6 – profilleyici bu sayaçları zamanlama verileriyle birlikte örnekler ve olay toplamları her işlev başına kayıtta görünür. PMU’su olmayan kameralar yine de zamanlama kayıtları üretir; olay alanları sıfır olarak geri döner ve profiler_event() bir işlem yapmaz.
- Camera.profiler_mode(exclusive: bool = False) None¶
Dahil edici (inclusive) ve dışlayıcı (exclusive) zamanlama arasında geçiş yapar. Dahil edici zamanlama, çağrılanların süresini çağırana yükler; dışlayıcı zamanlama yüklemez.
- Parametreler:
exclusive –
Truedışlayıcı zamanlamayı,Falsedahil edici zamanlamayı seçer.
- Camera.profiler_reset(config: list | None = None) None¶
Tüm profil sayaçlarını temizler.
config=Noneayrıca varsayılan PMU olay atamasını da geri yükler.- Parametreler:
config – Sayaç başına yapılacak gelecekteki yapılandırma geçersiz kılmaları için ayrılmıştır. Varsayılanları korumak için
Nonegeçirin.
- Camera.profiler_event(counter_num: int, event_id: int) None¶
PMU sayaç yuvalarından birini belirli bir donanım olayına bağlar.
- Parametreler:
counter_num – Sayaç dizini.
event_id – Mimaride tanımlanmış olay tanımlayıcısı.
- Camera.read_profile() list[dict] | None¶
Son sıfırlamadan bu yana toplanan işlev başına profil kayıtlarını döndürür. Her kayıt,
address,caller,call_count,min_ticks,max_ticks,total_ticks,total_cyclesve kameranınpmu_eventcntdeğerine göre boyutlandırılmış bireventsdemeti içeren bir sözlüktür.- Dönüşler:
Kayıt sözlüklerinin listesi veya profil kanalı kullanılabilir değilse ya da hiç veri toplanmamışsa
None.
13.3.1.6.9. Alt sınıflama ve kanal iç yapıları¶
Yukarıda belgelenen yöntemler, paketin her yaygın kullanımını kapsar. Birkaç desen – ana bilgisayarın tepki vermek istediği kamera tarafı olayları işleme, çok adımlı bir alışveriş için bir kanalı kilitleme, bayt akışları yerine şekillendirilmiş veri taşıyan kanallarla iletişim kurma veya kanala özgü kontrol komutlarını yürütme – Camera öğesinin alt çizgi önekiyle tuttuğu yöntemlere ihtiyaç duyar. Bu adlar kural gereği özeldir (Python bunları ad bozumuna uğratmaz) ve bunlara ihtiyaç duyan uygulamaların ya Camera öğesinin alt sınıfını oluşturması ya da yöntemleri doğrudan çağırması beklenir.
Olaylara tepki vermek için alt sınıflama. Kameranın yaydığı her olay Camera._handle_event() aracılığıyla gelir. Camera öğesinin alt sınıfını oluşturup yöntemi geçersiz kılmak, bir uygulamanın kamera tarafı betiğinin fırlattığı olaylara tepki vermesinin yoludur; Olaylar sayfası tüm deseni adım adım anlatır.
- Camera._handle_event(channel_id: int, event: int) None¶
Kameradan gelen bir olayı yönlendirir. Bir olay paketi geldiğinde aktarım katmanı tarafından çağrılır. Uygulamaya özgü işleme eklemek için bir alt sınıfta geçersiz kılın; varsayılan davranışı korumak için
super()._handle_event(...)çağrısı yapın (CHANNEL_REGISTEREDüzerinde kanal listesi tazeleme,streamkanalında çerçeve hazır izleme,stdinkanalı başlatma / durdurma günlüğü).- Parametreler:
channel_id – Sistem olayları için
0, aksi takdirde kayıtlı kanal kimliği.event – Olay tanımlayıcısı; değerler sistem olayları için
EventTypenumaralandırmasından ve kanal olayları için kamera tarafı kanal arka ucunun seçtiği değerden gelir.
Kendi protokol iletişim yöntemlerini ekleyen bir alt sınıf, bunları retry_if_failed() ile süslemelidir; böylece bu sayfadaki her hazır yöntemin sahip olduğu aynı yeniden eşitleme ve yeniden deneme davranışını miras alırlar.
- static Camera.retry_if_failed(func)¶
Süsleyici (decorator). Bir örnek yöntemini, aktarım
ResyncExceptionfırlattığında bir kez yeniden denenecek şekilde sarmalar._send_cmd_wait_resp()öğesine (doğrudan veya_channel_*sarmalayıcılarından biri aracılığıyla) çağrı yapan herhangi bir yöntem bu süsleyiciyi taşımalıdı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)
Kanal kilitleme, kanalın durumunun iki ilişkili işlem arasında değişmemesini sağlar (örneğin, sürekli veri ekleyen bir kanalda bir _channel_size() ardından bir _channel_read()). read_frame() ve read_profile() bunu dahili olarak kullanır; çok adımlı erişimle özel bir kanal yürüten bir uygulama da aynısını yapar.
- Camera._channel_lock(channel_id: int) bool¶
Bir kanal üzerinde özel bir kilit alır. Aynı kanaldaki diğer ana bilgisayar işlemleri kilit serbest bırakılana kadar bloke olur.
- Parametreler:
channel_id – Sayısal kanal kimliği, tipik olarak
get_channel()ile çözümlenir.- Dönüşler:
Kilit verildiğinde
True.
- Camera._channel_unlock(channel_id: int) bool¶
Daha önce
_channel_lock()ile alınan bir kilidi serbest bırakır. Her zaman bir kilit çağrısıyla eşleştirilir; aradaki okuma bir hata fırlatsa bile kilidin açılmasını sağlamak içintry/finallykullanın.- Parametreler:
channel_id – Sayısal kanal kimliği, tipik olarak
get_channel()ile çözümlenir.
Şekillendirilmiş kanallar, düz bir bayt akışı yerine yapılandırılmış kayıtlar taşır. Profilleyici kanalı hazır örnektir: şekli (record_count, record_size) biçimindedir ve kaç kaydın beklediğini bilmek isteyen bir ana bilgisayar bayt boyutu yerine şekli okur.
- Camera._channel_shape(channel_id: int) tuple[int, ...]¶
Bir kanalın şekil tanımlayıcısını okur.
- Parametreler:
channel_id – Sayısal kanal kimliği, tipik olarak
get_channel()ile çözümlenir.- Dönüşler:
Kanalın düzenini tanımlayan işaretsiz 32 bitlik tam sayılardan oluşan demet. Anlamı kanala özgüdür.
Kanala özgü kontrol komutları – başlatma, durdurma, sıfırlama, yapılandırma – kanala özgü bir komut numarası ve isteğe bağlı bir struct.pack yükü ile tek bir opcode (CHANNEL_IOCTL) üzerinden taşınır. stop(), exec() ve streaming() gibi hazır yöntemler, stdin ve stream kanallarına yönelik _channel_ioctl() çağrılarının ince sarmalayıcılarıdır; kendi ioctl menüsünü tanımlayan özel bir kamera tarafı kanalı da aynı şekilde yürütülür.
- Camera._channel_ioctl(channel_id: int, cmd: int, fmt: str | None = None, *args) bytes | None¶
Bir kanalda bir ioctl komutu yayınlar.
- Parametreler:
channel_id – Sayısal kanal kimliği, tipik olarak
get_channel()ile çözümlenir.cmd – Kamera tarafı kanal arka ucu tarafından tanımlanan komut numarası.
fmt – Argüman demeti için isteğe bağlı
structformat dizesi. Argüman almayan ioctl’ler içinNonegeçirin.args –
fmtile eşleşen değerler.
- Dönüşler:
Kanalın döndürdüğü yük ne ise o, veya
None.
Genel kanal yöntemlerinin kimliğe göre bayt akışı çeşitleri, ad-kimlik aramasını atlar ve açık bir bayt offset değeri kabul eder – büyük bir arabelleğin ortasından bir parça okumak için kullanışlıdır (örneğin profile kanalı kayıtları).
- Camera._channel_size(channel_id: int) int¶
- Parametreler:
channel_id – Sayısal kanal kimliği, tipik olarak
get_channel()ile çözümlenir.- Dönüşler:
Kanalda şu anda kullanılabilir olan baytlar.
- Camera._channel_read(channel_id: int, offset: int, length: int) bytes¶
offsetkonumundan başlayaraklengthbayt okur. Çok paketli okumalar otomatik olarak yeniden birleştirilir.- Parametreler:
channel_id – Sayısal kanal kimliği, tipik olarak
get_channel()ile çözümlenir.offset – Okumaya başlanacak bayt konumu (offset).
length – Okunacak bayt sayısı.
- Camera._channel_write(channel_id: int, data: bytes, offset: int = 0) None¶
dataöğesini verilenoffsetkonumuna yazar. Çok paketli yazmalar otomatik olarak paketlere bölünür.- Parametreler:
channel_id – Sayısal kanal kimliği, tipik olarak
get_channel()ile çözümlenir.data – Yazılacak bayt benzeri yük.
offset – Yazmaya başlanacak bayt konumu (offset).
Protokol ilkelleri (primitives), sınıfın sunduğu en düşük seviyedir – yukarıdaki her şeyin sonunda üzerine inşa edildiği ham komut gönderme, ham kanal listesini getirme ve manuel yeniden eşitleme girişleri. Bir uygulama, sınıfın henüz sarmalamadığı bir opcode gönderirken veya bir alt sınıfta özel kurtarma uygularken bunlara başvurur.
- Camera._send_cmd_wait_resp(opcode: int, channel: int = 0, data: bytes = b'') bytes | None¶
Bir protokol komutu gönderir ve kameranın yanıtını bekler. Bu bölümdeki diğer her yöntemin üzerine inşa edildiği ilkeldir.
- Parametreler:
opcode – Komut numarası. Hazır gelen
Opcodenumaralandırması, aygıt yazılımının birlikte geldiği kodları listeler, ancak parametre yalnızca bir tam sayıdır – özel bir aygıt yazılımı derlemesi kendi kodlarını tanımlayabilir ve bunlara yanıt verebilir.channel – Kanal kimliği veya sistem komutları için
0.data – Komuta özgü yük.
- Dönüşler:
Yanıt yükü veya bağlantıyı kesen
Opcode.SYS_RESETveOpcode.SYS_BOOTgibi komutlar içinNone.
- Camera._channel_list() dict¶
Geçerli kanal listesini,
update_channels()öğesinin doldurduğu önbelleğe alınmışchannels_by_idvechannels_by_namesözlüklerine dokunmadan kameradan getirir. Kameranın kanal durumunu doğrudan incelemek isteyen bir alt sınıf için kullanışlıdır.- Dönüşler:
Kanal kimliğini
{'name': str, 'flags': int}öğesine eşleyen sözlük.
- Camera._resync() None¶
Protokol el sıkışmasını sıfırdan yeniden çalıştırır. İlk bağlantıda
connect()tarafından ve aktarımdan birOMVExceptionyakalayan her genel yöntem tarafından otomatik olarak çağrılır. Bir alt sınıfta kendi kurtarma döngüsünü uygulayan bir uygulama, altta yatan hatayı ele aldıktan sonra bunu doğrudan çağırabilir.
13.3.1.6.10. İstisnalar¶
- exception openmv.OMVException¶
Protokol düzeyindeki her hata için temel sınıf. Aşağıdaki üç alt sınıfın tümü ondan miras alır, bu nedenle tek bir
except OMVExceptiontüm hata yüzeyini kapsar.
- exception openmv.TimeoutException¶
Kamera, yapılandırılan zaman aşımı içinde yanıt vermedi.
OMVExceptionöğesinin alt sınıfı.
- exception openmv.ChecksumException¶
Bir paketin CRC değeri eşleşmedi. Protokol yeniden deneme bütçesini tükettikten sonra fırlatılır.
OMVExceptionöğesinin alt sınıfı.
- exception openmv.SequenceException¶
Yeniden denemelerden sonra beklenmeyen bir sıra numarasıyla bir paket geldi.
OMVExceptionöğesinin alt sınıfı.