13.3.1.6. Referensi API¶

Permukaan publik dari paket openmv adalah kelas Camera untuk berkomunikasi dengan kamera dan hierarki OMVException untuk kesalahan protokol. Keduanya didokumentasikan di halaman ini.

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

Proksi sisi host untuk OpenMV cam yang terhubung melalui USB serial.

Parameter:

port -- Jalur perangkat serial. Di Linux, /dev/ttyACMx untuk USB CDC dan /dev/ttyUSBx untuk jembatan USB-ke-UART. Di macOS, /dev/tty.usbmodem... atau /dev/cu.usbmodem.... Di Windows, COMx.
baudrate -- Laju baud serial. Melalui USB, 921600 adalah nilai ajaib yang mengalihkan kamera dari MicroPython REPL ke protokol OpenMV -- nilai lain pada tautan USB membiarkan kamera dalam mode REPL, sehingga nilai default harus digunakan. Melalui tautan UART, nilai ini adalah laju baud jalur yang sebenarnya dan dapat diatur bebas di kedua sisi.
crc -- Aktifkan validasi CRC pada setiap paket.
seq -- Aktifkan nomor urut per paket.
ack -- Wajibkan pengakuan paket.
events -- Aktifkan notifikasi event dari kamera.
timeout -- Batas waktu per operasi dalam detik.
max_retry -- Jumlah percobaan ulang sebelum memunculkan kesalahan pada paket yang gagal.
max_payload -- Ukuran payload maksimum yang dinegosiasikan dalam byte. Kamera dapat menegosiasikan ke bawah.
drop_rate -- Probabilitas menjatuhkan paket khusus pengujian, dalam [0.0, 1.0]. Biarkan pada 0.0 dalam produksi.

Kelas ini mendukung protokol context-manager; with Camera(port) as cam: memanggil connect() saat masuk dan disconnect() saat keluar.

13.3.1.6.2. Koneksi¶

Camera.connect() → None¶: Buka port serial dan lakukan handshake protokol. Status yang di-cache (daftar channel, informasi sistem, informasi versi) diisi sebagai efek samping. Dipanggil secara otomatis oleh context manager.

Camera.disconnect() → None¶: Tutup port serial dan lepaskan transport. Dipanggil secara otomatis ketika context manager keluar.

Camera.is_connected() → bool¶

Kembali:: True jika port serial terbuka.

Camera.reset() → None¶: Reset kamera. Koneksi terputus karena kamera melakukan reboot.

Camera.boot() → None¶: Loncat kamera ke bootloader-nya. Koneksi terputus karena kamera melakukan reboot.

Camera.update_capabilities() → None¶: Negosiasikan ulang kemampuan protokol (CRC, pemeriksaan urutan, ACK, event, payload maksimum) dengan kamera. Kamera melaporkan payload maksimum yang dapat ditanganinya; permintaan host dipotong ke nilai tersebut dan pengaturan yang disepakati dikirim kembali. Dipanggil secara otomatis oleh connect() -- tidak ada alasan untuk memanggilnya dari kode pengguna kecuali flag konstruktor perlu dinegosiasikan ulang pada koneksi yang sudah ada.

Camera.poll_events() → None¶: Jalankan jalur penerimaan transport sekali untuk mengonsumsi event yang tertunda dari kamera tanpa mengirim perintah. Berguna dalam program yang berjalan lama yang berjalan menit tanpa I/O lain dan ingin menampilkan event pendaftaran channel dengan cepat.

13.3.1.6.3. Eksekusi skrip¶

Camera.exec(script: str) → None¶

Unggah script (string sumber Python) ke buffer stdin kamera dan mulai menjalankannya.

Parameter:: script -- Sumber MicroPython untuk dieksekusi.

Camera.stop() → None¶: Hentikan skrip yang sedang berjalan. Setara dengan tombol Stop di IDE.

Camera.read_stdout() → str | None¶

Baca byte apa pun yang telah ditulis skrip yang sedang berjalan ke stdout sejak panggilan terakhir.

Kembali:: Output sebagai string yang didekode, atau None jika tidak ada data yang menunggu.

13.3.1.6.4. Streaming¶

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

Aktifkan atau nonaktifkan streaming bingkai dan pilih format transmisi.

Parameter:

enable -- True mengaktifkan streaming, False menonaktifkannya.
raw -- Ketika False (default), kamera mengompres setiap bingkai dengan JPEG sebelum menempatkannya di channel stream dan read_frame() melakukan dekompresi di host. Ketika True, kamera mengirim buffer piksel yang ditangkap tanpa kompresi -- pilihan yang tepat pada kamera tanpa dukungan hardware JPEG, di mana kompresi perangkat lunak adalah langkah paling lambat dalam loop.
resolution -- (width, height) target yang menjadi target kamera untuk memperkecil setiap bingkai mentah sebelum dikirim, karena bingkai tanpa kompresi jauh lebih besar dari yang dikompres dengan JPEG. Diperlukan ketika raw=True; diabaikan sebaliknya.

Camera.read_frame() → dict | None¶

Baca bingkai terbaru dari channel stream.

Kembali:: None jika tidak ada bingkai yang menunggu, atau dict dengan kunci width (int, piksel), height (int, piksel), format (int, pengenal format piksel yang dideklarasikan kamera), depth (int, ukuran citra yang dikompres dalam byte untuk bingkai JPEG / PNG; tidak digunakan untuk format tanpa kompresi), data (bytes, RGB888 dengan panjang width * height * 3), dan raw_size (int, byte yang dikirim kamera melalui USB sebelum dekode).

13.3.1.6.5. Channel khusus¶

Camera.has_channel(name: str) → bool¶

Kembali:: True jika channel yang terdaftar dengan name ada di kamera.

Camera.channel_size(name: str) → int¶

Kembali:: Jumlah byte yang saat ini tersedia di channel yang dinamai, atau 0 ketika channel kosong atau tidak ada.

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

Baca dari channel khusus.

Parameter:

name -- Nama channel yang didaftarkan oleh skrip sisi kamera.
size -- Byte yang akan dibaca, atau None untuk membaca apa pun yang tersedia.

Kembali:

Byte-nya, atau None jika channel tidak ada.

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

Tulis data ke channel khusus. Penulisan yang lebih besar dari payload secara otomatis dibagi ke beberapa paket.

Parameter:

name -- Nama channel yang didaftarkan oleh skrip sisi kamera.
data -- Payload berupa bytes untuk dikirim.

Kembali:

True jika channel ada dan penulisan telah dikirim, False sebaliknya.

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

Poll setiap channel yang terdaftar.

Kembali:: Dict yang memetakan nama channel ke boolean "data siap dibaca".

Camera.update_channels() → None¶: Segarkan daftar channel yang di-cache dari kamera. Berjalan secara otomatis pada saat berikutnya pencarian channel-berdasarkan-nama dilakukan setelah event pendaftaran channel tiba; aplikasi yang ingin mengetahui channel yang baru terdaftar segera dapat memanggil ini secara langsung.

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

Cari channel berdasarkan nama (mengembalikan ID numeriknya) atau berdasarkan ID (mengembalikan namanya). Menyegarkan cache channel melalui update_channels() terlebih dahulu jika event pendaftaran channel sedang tertunda.

Parameter:

name -- Nama channel untuk diselesaikan menjadi ID.
channel_id -- ID channel untuk diselesaikan menjadi nama.

Kembali:

ID atau nama yang sesuai, atau None ketika channel tidak ada. Salah satu dari name atau channel_id harus disediakan.

13.3.1.6.6. Introspeksi perangkat¶

Camera.version() → dict¶

Kembalikan triple versi protokol, bootloader, dan firmware kamera. Di-cache setelah connect(). Setiap triple adalah tuple (major, minor, patch) dari int:

protocol_version -- versi protokol wire OpenMV yang diimplementasikan kamera.
bootloader_version -- citra bootloader yang ada di flash.
firmware_version -- firmware MicroPython yang sedang berjalan.

Camera.system_info() → dict¶

Kembalikan informasi kemampuan hardware dan memori kamera. Di-cache setelah connect(). Kunci dict yang dikembalikan terbagi dalam empat kelompok.

Identitas

cpu_id -- pengenal CPU 32-bit.
device_id -- 3-tuple dari kata 32-bit, nomor seri perangkat unik yang tertanam dalam silikon.
chip_id -- 3-tuple dari kata 32-bit, satu entri per sensor citra yang terhubung ke kamera.
usb_vid -- ID vendor USB.
usb_pid -- ID produk USB.

Ukuran memori (semua dalam kilobyte)

flash_size_kb -- total flash internal.
ram_size_kb -- total RAM.
framebuffer_size_kb -- RAM yang dicadangkan untuk penangkapan citra.
stream_buffer_size_kb -- RAM yang dicadangkan untuk channel stream yang mengirimkan bingkai ke host.

Flag kemampuan (satu boolean per fitur, semua dinamai <feature>_present)

gpu_present -- unit pemrosesan grafis.
npu_present -- unit pemrosesan saraf.
isp_present -- prosesor sinyal citra.
venc_present -- enkoder video.
jpeg_present -- enkoder hardware JPEG.
dram_present -- DRAM eksternal.
crc_present -- akselerator CRC.
pmu_present -- unit pemantauan kinerja.
wifi_present -- radio Wi-Fi.
bt_present -- radio Bluetooth.
sd_present -- slot kartu SD.
eth_present -- Ethernet PHY.
multicore_present -- beberapa inti CPU.

Lainnya

usb_highspeed -- boolean, True ketika USB dienumerasi dalam mode high-speed (USB 2.0 HS, 480 Mbps).
pmu_eventcnt -- jumlah penghitung event PMU yang tersedia; 0 ketika tidak ada PMU.

Camera.print_system_info() → None¶: Catat blok informasi sistem yang diformat ke logging pada level INFO. CLI menggunakan ini saat koneksi.

13.3.1.6.7. Diagnostik¶

Camera.host_stats() → dict¶

Kembali:: Penghitung lapisan transport yang dilacak di sisi host: sent, received, checksum, sequence.

Camera.device_stats() → dict¶

Kembali:: Penghitung lapisan transport yang dilacak di sisi kamera: sent, received, checksum, sequence, retransmit, transport, sent_events, max_ack_queue_depth.

13.3.1.6.8. Profiler¶

Profiler melaporkan jumlah panggilan per fungsi dan waktu eksekusi min / maks / total untuk modul firmware yang diinstrumentasi -- saat ini image, ml, dan ulab. Entri dan keluar fungsi dicegat pada waktu kompilasi; runtime mengambil sampel penghitung mikrodetik monoton pada setiap entri dan keluar, mengakumulasi hasilnya per fungsi, dan mengekspos tabel ke host melalui channel profile.

Profiler hanya dibangun ke dalam firmware ketika PROFILE_ENABLE=1 diteruskan ke make. Citra firmware stok tidak menyertakannya -- flag -finstrument-functions yang ditambahkan build ke modul yang dilacak memiliki overhead runtime yang tidak sepele, sehingga build profiling diproduksi dari sumber untuk sesi debugging spesifik yang membutuhkannya. Ketika firmware tidak dibangun dengan flag tersebut, channel profile tidak terdaftar dan setiap metode profiler di halaman ini kembali dengan diam tanpa melakukan apa pun.

Arm Performance Monitoring Unit (PMU) adalah blok penghitung hardware Cortex-M55 -- sekumpulan kecil penghitung yang dapat dikonfigurasi yang melacak jumlah siklus, cache hit dan miss, perilaku cabang, dan event yang didefinisikan arsitektur lainnya tanpa memperlambat kode yang sedang diukur. Pada kamera yang memilikinya -- AE3 dan N6, dua kamera dalam jajaran OpenMV yang dibangun di sekitar M55 -- profiler mengambil sampel penghitung ini bersama data waktu dan total event muncul di setiap rekaman per fungsi. Kamera tanpa PMU tetap menghasilkan rekaman waktu; kolom event dikembalikan sebagai nol, dan profiler_event() adalah no-op.

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

Beralih antara timing inklusif dan eksklusif. Timing inklusif membebankan waktu callee ke pemanggil; timing eksklusif tidak.

Parameter:: exclusive -- True memilih timing eksklusif, False memilih timing inklusif.

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

Hapus semua penghitung profil. config=None juga memulihkan penetapan event PMU default.

Parameter:: config -- Dicadangkan untuk override konfigurasi per-penghitung di masa mendatang. Teruskan None untuk mempertahankan default.

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

Ikat salah satu slot penghitung PMU ke event hardware tertentu.

Parameter:

counter_num -- Indeks penghitung.
event_id -- Pengenal event yang didefinisikan arsitektur.

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

Kembalikan rekaman profil per fungsi yang dikumpulkan sejak reset terakhir. Setiap rekaman adalah dict dengan address, caller, call_count, min_ticks, max_ticks, total_ticks, total_cycles, dan tuple events yang berukuran sesuai pmu_eventcnt kamera.

Kembali:: Daftar dict rekaman, atau None jika channel profil tidak tersedia atau belum ada data yang dikumpulkan.

13.3.1.6.9. Subklassing dan internal channel¶

Metode yang didokumentasikan di atas mencakup setiap penggunaan umum dari paket ini. Beberapa pola -- menangani event sisi kamera yang ingin direaksi host, mengunci channel untuk pertukaran multi-langkah, berkomunikasi dengan channel yang membawa data berbentuk sebagai pengganti byte stream, atau mengendalikan perintah kontrol khusus channel -- memerlukan metode yang disimpan Camera dengan awalan garis bawah. Nama-nama ini bersifat privat secara konvensi (Python tidak mengubah namanya), dan aplikasi yang membutuhkannya diharapkan untuk membuat subkelas Camera atau memanggil metode secara langsung.

Subklassing untuk bereaksi terhadap event. Setiap event yang dikirim kamera tiba melalui Camera._handle_event(). Membuat subkelas Camera dan menimpa metode ini adalah cara aplikasi bereaksi terhadap event yang diangkat skrip sisi kamera; halaman Kejadian memandu pola lengkapnya.

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

Kirimkan satu event dari kamera. Dipanggil oleh lapisan transport setiap kali paket event tiba. Timpa dalam subkelas untuk menambahkan penanganan khusus aplikasi; panggil super()._handle_event(...) untuk mempertahankan perilaku default (penyegaran daftar channel pada CHANNEL_REGISTERED, pelacakan frame-ready pada channel stream, logging mulai / berhenti channel stdin).

Parameter:

channel_id -- 0 untuk event sistem, sebaliknya ID channel yang terdaftar.
event -- Pengenal event; nilai berasal dari enum EventType untuk event sistem dan dari apa pun yang dipilih backend channel sisi kamera untuk event channel.

Subkelas yang menambahkan metode berbicara protokolnya sendiri harus menghiasi metode tersebut dengan retry_if_failed() agar mewarisi perilaku resync-dan-coba-ulang yang sama yang dimiliki setiap metode yang dikirimkan di halaman ini.

static Camera.retry_if_failed(func)¶

Dekorator. Membungkus metode instance sehingga mencoba ulang sekali ketika transport memunculkan ResyncException. Setiap metode yang memanggil _send_cmd_wait_resp() (secara langsung atau melalui salah satu wrapper _channel_*) harus membawa dekorator ini:

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

Penguncian channel memastikan status channel tidak berubah di antara dua operasi terkait (misalnya _channel_size() diikuti oleh _channel_read(), pada channel yang terus menambahkan data). read_frame() dan read_profile() menggunakan ini secara internal; aplikasi yang mengendalikan channel khusus dengan akses multi-langkah melakukan hal yang sama.

Camera._channel_lock(channel_id: int) → bool¶

Dapatkan kunci eksklusif pada channel. Operasi host lainnya pada channel yang sama diblokir hingga kunci dilepaskan.

Parameter:: channel_id -- ID channel numerik, biasanya diselesaikan dengan get_channel().
Kembali:: True ketika kunci diberikan.

Camera._channel_unlock(channel_id: int) → bool¶

Lepaskan kunci yang sebelumnya diambil dengan _channel_lock(). Selalu dipasangkan dengan panggilan kunci; gunakan try / finally untuk memastikan pelepasan kunci terjadi bahkan ketika pembacaan di antaranya memunculkan pengecualian.

Parameter:: channel_id -- ID channel numerik, biasanya diselesaikan dengan get_channel().

Channel berbentuk membawa rekaman terstruktur daripada byte stream datar. Channel profiler adalah contoh yang dikirimkan: bentuknya adalah (record_count, record_size) dan host yang ingin mengetahui berapa banyak rekaman yang menunggu membaca bentuknya daripada ukuran byte.

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

Baca deskriptor bentuk dari sebuah channel.

Parameter:: channel_id -- ID channel numerik, biasanya diselesaikan dengan get_channel().
Kembali:: Tuple dari integer 32-bit tidak bertanda yang mendeskripsikan tata letak channel. Maknanya bersifat khusus channel.

Perintah kontrol khusus channel -- mulai, berhenti, reset, konfigurasi -- menggunakan satu opcode (CHANNEL_IOCTL) dengan nomor perintah khusus channel dan payload struct.pack opsional. Metode yang dikirimkan seperti stop(), exec(), dan streaming() adalah pembungkus tipis di sekitar panggilan _channel_ioctl() terhadap channel stdin dan stream; channel sisi kamera khusus yang mendefinisikan menu ioctlnya sendiri dikendalikan dengan cara yang sama.

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

Keluarkan perintah ioctl pada sebuah channel.

Parameter:

channel_id -- ID channel numerik, biasanya diselesaikan dengan get_channel().
cmd -- Nomor perintah yang didefinisikan oleh backend channel sisi kamera.
fmt -- String format struct opsional untuk tuple argumen. Teruskan None untuk ioctl yang tidak menerima argumen.
args -- Nilai yang cocok dengan fmt.

Kembali:

Payload apa pun yang dikembalikan channel, atau None.

Varian byte-stream berdasarkan ID dari metode channel publik melewati pencarian nama-ke-ID dan menerima offset byte eksplisit -- berguna untuk membaca potongan dari tengah buffer besar (misalnya rekaman channel profile).

Camera._channel_size(channel_id: int) → int¶

Parameter:: channel_id -- ID channel numerik, biasanya diselesaikan dengan get_channel().
Kembali:: Byte yang saat ini tersedia pada channel.

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

Baca length byte mulai dari offset. Pembacaan multi-paket dirakit ulang secara otomatis.

Parameter:

channel_id -- ID channel numerik, biasanya diselesaikan dengan get_channel().
offset -- Offset byte untuk mulai membaca.
length -- Jumlah byte yang akan dibaca.

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

Tulis data pada offset yang diberikan. Penulisan multi-paket dibagi ke beberapa paket secara otomatis.

Parameter:

channel_id -- ID channel numerik, biasanya diselesaikan dengan get_channel().
data -- Payload berupa bytes untuk ditulis.
offset -- Offset byte untuk mulai menulis.

Primitif protokol adalah level terendah yang diekspos kelas -- entri kirim-perintah-mentah, ambil-daftar-channel-mentah, dan resinkronisasi-manual yang menjadi landasan semua hal di atas. Aplikasi menggunakannya ketika mengirim opcode yang belum dibungkus kelas, atau ketika mengimplementasikan pemulihan khusus dalam subkelas.

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

Kirim perintah protokol dan tunggu respons kamera. Primitif yang menjadi landasan setiap metode lain di bagian ini.

Parameter:

opcode -- Nomor perintah. Enum Opcode yang dikirimkan mencantumkan kode yang dikirimkan firmware, tetapi parameternya hanyalah integer -- build firmware khusus dapat mendefinisikan dan merespons kodenya sendiri.
channel -- ID channel, atau 0 untuk perintah sistem.
data -- Payload khusus perintah.

Kembali:

Payload respons, atau None untuk perintah seperti Opcode.SYS_RESET dan Opcode.SYS_BOOT yang memutus koneksi.

Camera._channel_list() → dict¶

Ambil daftar channel saat ini dari kamera tanpa menyentuh kamus channels_by_id dan channels_by_name yang di-cache yang diisi oleh update_channels(). Berguna untuk subkelas yang ingin memeriksa status channel kamera secara langsung.

Kembali:: Dict yang memetakan ID channel ke {'name': str, 'flags': int}.

Camera._resync() → None¶: Jalankan ulang handshake protokol dari awal. Dipanggil secara otomatis oleh connect() pada koneksi awal dan oleh setiap metode publik yang menangkap OMVException dari transport. Aplikasi yang mengimplementasikan loop pemulihan sendiri dalam subkelas dapat memanggil ini secara langsung setelah menangani kesalahan yang mendasarinya.

13.3.1.6.10. Pengecualian¶

exception openmv.OMVException¶: Kelas dasar untuk setiap kesalahan tingkat protokol. Tiga subkelas di bawah ini semuanya mewarisi darinya, sehingga satu except OMVException mencakup seluruh permukaan kesalahan.

exception openmv.TimeoutException¶: Kamera tidak merespons dalam batas waktu yang dikonfigurasi. Subkelas dari OMVException.

exception openmv.ChecksumException¶: CRC sebuah paket tidak cocok. Dimunculkan setelah protokol menghabiskan anggaran percobaan ulangnya. Subkelas dari OMVException.

exception openmv.SequenceException¶: Paket tiba dengan nomor urut yang tidak terduga setelah percobaan ulang. Subkelas dari OMVException.