`protocol` --- ช่องสัญญาณโปรโตคอล OpenMV#

โมดูล protocol เปิดเผยโปรโตคอลโฮสต์ OpenMV สู่ Python ช่วยให้สามารถเริ่มต้นและกำหนดค่าสแต็กโปรโตคอลฝั่งเฟิร์มแวร์ได้ และให้โค้ดผู้ใช้ลงทะเบียนช่องสัญญาณเชิงตรรกะแบบกำหนดเองที่รองรับด้วยออบเจกต์ Python ที่ใช้อินเทอร์เฟซช่องสัญญาณ (read, write, size, poll เป็นต้น) นี่คือสิ่งที่เครื่องมือคู่หูบนเดสก์ท็อปพูดถึงเมื่อสตรีมข้อมูลภาพหรือแสดงวิดเจ็ตแบบโต้ตอบกับกล้องที่เชื่อมต่อ

ตัวอย่าง#

สตรีมภาพ RGB565 ไปยังเครื่องมือโฮสต์โดยใช้แบ็กเอนด์แบบกำหนดเองที่ใช้อินเทอร์เฟซช่องสัญญาณดิบ (backend.size(), backend.shape(), backend.poll(), backend.read()):

import csi
import protocol

csi0 = csi.CSI()
csi0.reset()
csi0.pixformat(csi.RGB565)
csi0.framesize(csi.HD)

img = csi0.snapshot()
img_mv = memoryview(img.bytearray())
frame_ready = True


class FrameChannel:
    def size(self):
        return len(img_mv)

    def shape(self):
        return (img.height(), img.width(), len(img_mv))

    def poll(self):
        return frame_ready

    def read(self, offset, size):
        global frame_ready
        end = offset + size
        chunk = img_mv[offset:end]
        if end >= len(img_mv):
            frame_ready = False
        return chunk


protocol.register(name="frame", backend=FrameChannel())

while True:
    if not frame_ready:
        img = csi0.snapshot()
        img_mv = memoryview(img.bytearray())
        frame_ready = True

สคริปต์ฝั่งโฮสต์ที่ตรงกัน โดยใช้แพ็กเกจ Python openmv (pip install openmv) เพื่อเชื่อมต่อ ส่งสคริปต์บนกล้อง และดึงแต่ละเฟรม:

import cv2
import numpy as np
from openmv.camera import Camera

# The on-cam script above, stored as a string (or read from a file).
SCRIPT = open("frame_streamer_on_cam.py").read()

with Camera("/dev/ttyACM0", baudrate=921600) as cam:
    cam.stop()
    cam.exec(SCRIPT)

    while True:
        status = cam.read_status()
        if not cam.has_channel("frame") or not status.get("frame"):
            continue

        h, w, size = cam._channel_shape(cam.get_channel(name="frame"))
        if cam.channel_size("frame") < size:
            continue

        data = cam.channel_read("frame", size)
        rgb565 = np.frombuffer(data, dtype="<u2").reshape(h, w)

        # Unpack RGB565 to an HxWx3 uint8 RGB image.
        r = ((rgb565 >> 11) & 0x1F) << 3
        g = ((rgb565 >>  5) & 0x3F) << 2
        b = ( rgb565        & 0x1F) << 3
        frame = np.dstack([r, g, b]).astype(np.uint8)

        # Display with OpenCV (cv2 expects BGR, not RGB).
        cv2.imshow("OpenMV", cv2.cvtColor(frame, cv2.COLOR_RGB2BGR))
        if cv2.waitKey(1) == ord("q"):
            break

cv2.destroyAllWindows()

แทนที่ /dev/ttyACM0 ด้วยพอร์ตซีเรียลของกล้อง (เช่น COM3 บน Windows) ตัวสร้าง openmv.camera.Camera ยอมรับพารามิเตอร์โปรโตคอลเดียวกับ init (crc / seq / ack / events / max_payload / max_retry / timeout) เมื่อสแต็กฝั่งกล้องถูกกำหนดค่าใหม่ให้ตรงกัน

ฟังก์ชัน#

protocol.init(crc: bool = True, seq: bool = True, ack: bool = True, events: bool = True, max_payload: int = ..., rtx_retries: int = 3, rtx_timeout_ms: int = 500, lock_interval_ms: int = 10, poll_ms: int = 0) → None#

เริ่มต้น (หรือกำหนดค่าใหม่) โปรโตคอลสแตกและลงทะเบียนช่องข้อมูลเชิงตรรกะเริ่มต้น (stdin, stdout, stream และ profile หากคอมไพล์รวมมาด้วย) จะแสดงข้อผิดพลาด RuntimeError หากการเริ่มต้นล้มเหลว เฟิร์มแวร์จะบูตพร้อมโปรโตคอลสแตก USB เริ่มต้นที่ทำงานอยู่แล้ว ดังนั้นจึงจำเป็นต้องเรียกฟังก์ชันนี้เฉพาะเมื่อต้องการเปลี่ยนทรานสปอร์ตหรือแทนที่พารามิเตอร์การจัดเฟรมเริ่มต้นเท่านั้น การเรียกอีกครั้งจะเริ่มต้นสแตกใหม่: ตัวตั้งเวลาการ poll เดิมจะถูกลบออกและช่องสัญญาณต่างๆ จะถูกลงทะเบียนใหม่

crc เปิดใช้งานการตรวจสอบ CRC บนเฟรมโปรโตคอล

seq เปิดใช้งานการติดตามหมายเลขลำดับ

ack เปิดใช้งานการตอบรับต่อเฟรม

events เปิดใช้งานการแจ้งเตือนเหตุการณ์ช่องสัญญาณ

max_payload คือขนาดเพย์โหลดสูงสุดในหน่วยไบต์ หากละไว้จะใช้ค่าเริ่มต้นต่อกล้องด้านล่าง ซึ่งได้มาจากขนาดบัฟเฟอร์โปรโตคอลของแต่ละบอร์ดเป็น buffer - 10 (header) - 4 (CRC)

Camera	ขนาดบัฟเฟอร์	เพย์โหลดสูงสุด
OpenMV Cam M4 (`OPENMV2`)	512	498
OpenMV Cam M7 (`OPENMV3`)	512	498
OpenMV Cam H7 (`OPENMV4`)	512	498
OpenMV Cam H7 Plus (`OPENMV4P`)	4096	4082
OpenMV Pure Thermal (`OPENMVPT`)	4096	4082
OpenMV Cam RT1062 (`OPENMV_RT1060`)	4096	4082
OpenMV Cam N6 (`OPENMV_N6`)	8192	8178
OpenMV AE3 (`OPENMV_AE3`)	8192	8178
Arduino Portenta H7 (`ARDUINO_PORTENTA_H7`)	4096	4082
Arduino Giga (`ARDUINO_GIGA`)	4096	4082
Arduino Nicla Vision (`ARDUINO_NICLA_VISION`)	4096	4082

rtx_retries คือจำนวนครั้งในการส่งซ้ำ ค่าเริ่มต้นคือ 3

rtx_timeout_ms คือช่วงเวลาหมดเวลาการส่งซ้ำในมิลลิวินาที (เพิ่มเป็นสองเท่าหลังจากแต่ละการหมดเวลา) ค่าเริ่มต้นคือ 500

lock_interval_ms คือช่วงเวลาล็อกขั้นต่ำในมิลลิวินาที ค่าเริ่มต้นคือ 10

poll_ms คือช่วงเวลาโพลในมิลลิวินาที 0 (ค่าเริ่มต้น) ปิดการใช้งานการโพลแบบตัวจับเวลา

protocol.is_active() → bool#: ส่งคืน True หากโฮสต์เชื่อมต่ออยู่ในขณะนี้และสแต็กโปรโตคอลทำงานอยู่ มิฉะนั้นจะส่งคืน False

protocol.poll() → int#

รันการวนซ้ำหนึ่งรอบของงานโปรโตคอล: ระบายบัฟเฟอร์รับของทรานสปอร์ต แยกวิเคราะห์เฟรมที่สมบูรณ์ทั้งหมด ส่งต่อคำสั่ง และให้บริการเหตุการณ์ของช่องสัญญาณ โดยปกติเฟิร์มแวร์จะทำสิ่งนี้ให้จากอินเทอร์รัปต์ USB และจากตัวตั้งเวลา poll_ms ดังนั้นจึงจำเป็นเฉพาะกับทรานสปอร์ตแบบกำหนดเองที่ไม่ได้ถูกขับเคลื่อนด้วยทั้งสองอย่างนี้ -- เช่น เมื่อ poll_ms=0 และทรานสปอร์ตถูก poll จากลูปหลักของสคริปต์

คืนค่า 0 เมื่อสำเร็จ และ -1 หากไม่มีทรานสปอร์ตที่ใช้งานอยู่ถูกลงทะเบียนไว้ หรือถูกเรียกจากบริบทของอินเทอร์รัปต์

protocol.register(name: str, *, backend: object, flags: int = 0) → ProtocolChannel#

ลงทะเบียนออบเจกต์ Python backend เป็นช่องสัญญาณเชิงตรรกะใหม่และส่งคืน handle ProtocolChannel เมธอดที่มีอยู่ของออบเจกต์ backend (ดู อินเทอร์เฟซแบ็กเอนด์ ด้านล่าง) จะกำหนดความสามารถของช่องสัญญาณ โดย protocol.CHANNEL_FLAG_READ, protocol.CHANNEL_FLAG_WRITE และ protocol.CHANNEL_FLAG_LOCK จะถูกเพิ่มใน flags โดยอัตโนมัติเมื่อมีการใช้งานเมธอดที่เกี่ยวข้อง

name คือชื่อช่องสัญญาณเป็นสตริง จะถูกตัดให้สั้นลงตามขนาดบัฟเฟอร์ชื่อช่องสัญญาณของเฟิร์มแวร์ จำเป็น

backend คือออบเจกต์ Python ที่ใช้อินเทอร์เฟซแบ็กเอนด์ จำเป็น โดยทั่วไปส่งผ่านโดยคีย์เวิร์ด (backend=...)

flags คือบิตแฟล็กช่องสัญญาณเพิ่มเติม (ดูค่าคงที่ CHANNEL_FLAG_*) ไม่บังคับ ค่าเริ่มต้นคือ 0

ยกข้อผิดพลาด RuntimeError หากไม่สามารถลงทะเบียนช่องสัญญาณได้ (เช่น ไม่มีช่องสัญญาณว่าง)

คลาส#

class protocol.ProtocolChannel#

Handle ที่ส่งคืนโดย protocol.register ไม่สร้าง Instance โดยตรง

send_event(event: int, wait_ack: bool = False) → None#

ส่งการแจ้งเตือนเหตุการณ์ช่องสัญญาณไปยังโฮสต์

event คือตัวระบุเหตุการณ์ (จำนวนเต็ม)

wait_ack หาก True จะบล็อกจนกว่าโฮสต์จะตอบรับเหตุการณ์

ยกข้อผิดพลาด RuntimeError หากการส่งเหตุการณ์ล้มเหลว

อินเทอร์เฟซแบ็กเอนด์#

ออบเจกต์แบ็กเอนด์ที่ส่งไปยัง protocol.register อาจใช้เมธอดย่อยใดก็ได้จากต่อไปนี้ มีเฉพาะเมธอดที่มีอยู่ในออบเจกต์เท่านั้นที่จะถูกเชื่อมต่อกับชั้น C protocol เมธอดที่หายไปจะปิดใช้งานความสามารถที่เกี่ยวข้อง

class protocol.backend#

ออบเจกต์แบ็กเอนด์ช่องสัญญาณที่ส่งไปยัง protocol.register เมธอดด้านล่างอธิบายอินเทอร์เฟซเสริมที่แบ็กเอนด์ Python อาจใช้งาน

init() → object#: เรียกใช้ครั้งเดียวเมื่อช่องสัญญาณถูกเริ่มต้น ส่งคืนค่าที่ไม่ใช่ None ใดก็ได้เพื่อบ่งชี้ความสำเร็จ ข้อยกเว้นหรือการขาดค่าส่งคืนจะถูกถือเป็นข้อผิดพลาด

poll() → bool#: ส่งคืน True หากช่องสัญญาณมีข้อมูลพร้อมให้โฮสต์อ่าน

lock() → bool#: ล็อกช่องสัญญาณสำหรับการถ่ายโอน ส่งคืน True เมื่อสำเร็จ

unlock() → bool#: ปลดล็อกช่องสัญญาณหลังจากการถ่ายโอน ส่งคืน True เมื่อสำเร็จ

size() → int#: ส่งคืนจำนวนไบต์ที่อ่านได้จากช่องสัญญาณในขณะนี้

shape() → tuple#: ส่งคืน tuple ของจำนวนเต็มสูงสุดสี่ตัวที่อธิบายรูปร่างของข้อมูล (เช่น มิติของภาพ) โดยโปรโตคอลเลเยอร์จะใช้สูงสุดสี่องค์ประกอบ

flush() → object#: ล้างข้อมูลที่รอดำเนินการ ส่งคืนค่าที่ไม่ใช่ None ใดก็ได้เพื่อบ่งชี้ความสำเร็จ

read(offset: int, size: int) → bytes#: ส่งคืนสูงสุด size ไบต์เริ่มต้นที่ offset เป็นออบเจกต์คล้าย bytes ที่รองรับโปรโตคอลบัฟเฟอร์

readp(offset: int, size: int) → bytes#: ตัวแปร zero-copy ของ read ส่งคืนบัฟเฟอร์ที่หน่วยความจำพื้นฐานถูกอ่านโดยตรงโดยชั้นโปรโตคอล บัฟเฟอร์ต้องยังคงใช้งานได้ตลอดระยะเวลาการถ่ายโอน

write(offset: int, data: bytearray) → int#: เขียน data ที่ offset โดย data คือ bytearray ที่อ้างอิงบัฟเฟอร์ C โดยตรง ส่งคืนจำนวนไบต์ที่เขียน หรือ 0 เมื่อสำเร็จตามค่าเริ่มต้น

ioctl(cmd: int, length: int, arg: bytearray | None) → int#: จัดการ ioctl โดย arg คือ None หาก length เป็นศูนย์ มิฉะนั้นจะเป็น bytearray ที่อ้างอิงบัฟเฟอร์ C ส่งคืน 0 หรือ None เมื่อสำเร็จ หรือจำนวนเต็มลบเมื่อเกิดข้อผิดพลาด

is_active() → bool#: สำหรับช่องสัญญาณการขนส่ง ส่งคืน True หากการขนส่งพื้นฐานเชื่อมต่ออยู่ในขณะนี้

class protocol.CBORChannel(on_read: Callable | None = None, on_write: Callable | None = None)#

แบ็กเอนด์ Python ระดับสูงขึ้น (จัดเตรียมโดยแพ็กเกจ protocol แบบ frozen) ที่ซีเรียลไลซ์ฟิลด์ที่มีชื่อเป็น CBOR โดยใช้คีย์จำนวนเต็มที่เข้ากันได้กับ SenML รองรับวิดเจ็ตแสดงผล (label, text, depth, waveform) และตัวควบคุมแบบโต้ตอบ (toggle, pushbutton, slider, spinbox, select, radio, lineedit) พร้อมคอลแบ็ก on_read/on_write

on_read คือ callable เสริม on_read(channel) ที่เรียกใช้ก่อนที่ช่องสัญญาณจะถูกจัดลำดับสำหรับโฮสต์ ใช้เพื่อรีเฟรชค่าฟิลด์

on_write คือ callable เสริม on_write(channel, name, value) ที่เรียกใช้เมื่อโฮสต์เขียนค่าใหม่สำหรับฟิลด์ที่มีชื่อ

เพิ่มฟิลด์ที่มีชื่อในช่องสัญญาณ

name คือชื่อแสดงผล ต้องไม่ซ้ำกันภายในช่องสัญญาณนี้

type คือชนิดของวิดเจ็ต:

"label" -- การแสดงค่าตัวเลขแบบอ่านอย่างเดียว พร้อม unit ที่ระบุหรือไม่ก็ได้
"text" -- การแสดงสตริงแบบอ่านอย่างเดียว
"toggle" -- สวิตช์ค่าบูลีน
"pushbutton" -- การกระทำชั่วขณะ (trigger, calibrate, ...) โฮสต์จะเขียน True เมื่อคลิกและไม่แสดงสถานะใดๆ
"slider" -- ตัวควบคุมค่าตัวเลขพร้อม min/max/step
"spinbox" -- ช่องป้อนค่าตัวเลขแบบขั้นที่แม่นยำ ใช้ฟิลด์ร่วมกับ slider และรูปแบบการอัปเดตด้วย tuple (min, max, value)
"select" -- รายการแบบดรอปดาวน์ของสตริง options
"radio" -- options ที่แสดงเป็นกลุ่มของปุ่มเรดิโอ
"lineedit" -- ช่องป้อนสตริงที่เขียนได้
"depth" -- การแสดงแผนที่ความลึก 2 มิติขนาด width x height
"waveform" -- กราฟอนุกรมเวลา 1 มิติของตัวอย่างสัญญาณแบบสลับกัน (interleaved)

value คือค่าตั้งต้น ค่าเริ่มต้นจะขึ้นอยู่กับ type: 0 สำหรับ label, "" สำหรับ text/lineedit/select/ radio, False สำหรับ toggle/pushbutton, min สำหรับ slider/spinbox

unit คือสตริงหน่วยสำหรับ label/slider/spinbox/ waveform (เช่น "Cel", "%RH")

min คือค่าต่ำสุด (ช่วงของ slider/spinbox หรือช่วงการแสดงผลของ depth/waveform)

max คือค่าสูงสุด (ช่วงของ slider/spinbox หรือช่วงการแสดงผลของ depth/waveform)

step คือขนาดของขั้น (slider/spinbox)

options คือรายการสตริงตัวเลือก (select/radio) หรือรายการชื่อของแต่ละอนุกรม (waveform)

width คือความกว้างเป็นพิกเซล (depth)

height คือความสูงเป็นพิกเซล (depth)

sample_rate คืออัตราการสุ่มตัวอย่างในหน่วยตัวอย่างต่อวินาที (waveform) จะถูกส่งไปยังโฮสต์ในรูปของคาบการสุ่มตัวอย่าง

series คือจำนวนอนุกรมที่สลับกันในแต่ละบล็อกตัวอย่าง (waveform) เช่น 3 สำหรับข้อมูล accelerometer แบบ XYZ

typecode คือ typecode ของ array สำหรับตัวอย่างสัญญาณของ waveform (เช่น "H", "h", "f") ค่าเริ่มต้นคือ "H" (จำนวนเต็ม 16 บิตไม่มีเครื่องหมาย)

__getitem__(name: str) → object#: คืนค่าปัจจุบันของฟิลด์ที่ระบุชื่อ สำหรับฟิลด์ depth และ waveform จะคืนบัฟเฟอร์ข้อมูลไบนารี มิฉะนั้นจะคืนค่าสเกลาร์

__setitem__(name: str, value: Any) → None#: ตั้งค่าของฟิลด์ที่ระบุชื่อ สำหรับฟิลด์ slider และ spinbox การส่ง tuple (min, max, value) จะอัปเดตช่วงและค่าปัจจุบันพร้อมกัน สำหรับฟิลด์ depth ค่า value คือบัฟเฟอร์ข้อมูลไบนารี สำหรับฟิลด์ waveform ค่า value คือบล็อกแบบ bytes-like ของตัวอย่างสัญญาณที่สลับกันตาม typecode ของฟิลด์ จำนวนตัวอย่างต่ออนุกรมจะคำนวณจากความยาวของบล็อก และจะแนบไทม์สแตมป์แบบเพิ่มขึ้นเสมอ (ในหน่วยไมโครวินาที สะสมจาก time.ticks_us()) เพื่อให้โฮสต์สามารถวางชิ้นข้อมูลนี้บนแกนเวลาได้

poll() → bool#: เมธอดอินเทอร์เฟซแบ็กเอนด์ ส่งคืน True เมื่อมีข้อมูลที่จัดลำดับแล้วพร้อมให้โฮสต์

size() → int#: เมธอดอินเทอร์เฟซแบ็กเอนด์ เรียกใช้ on_read (หากตั้งค่าไว้) และส่งคืนขนาดของบัฟเฟอร์ที่จัดลำดับแล้ว

read(offset: int, size: int) → bytes#: เมธอดอินเทอร์เฟซแบ็กเอนด์ ส่งคืนส่วนหนึ่งของบัฟเฟอร์ที่จัดลำดับแล้ว

write(offset: int, data: bytearray) → int#: เมธอดอินเทอร์เฟซแบ็กเอนด์ ถอดรหัสรายการอัปเดต CBOR และนำค่าไปใช้กับฟิลด์ที่มีชื่อที่ตรงกัน โดยเรียกใช้ on_write สำหรับแต่ละรายการ

ค่าคงที่#

บิตแฟล็กช่องสัญญาณ (รวมกันแบบ bitwise ส่งไปยัง protocol.register ผ่าน flags หรือตั้งค่าโดยอัตโนมัติตามเมธอดของแบ็กเอนด์)

protocol.CHANNEL_FLAG_READ: int#: ช่องสัญญาณรองรับการอ่าน

protocol.CHANNEL_FLAG_WRITE: int#: ช่องสัญญาณรองรับการเขียน

protocol.CHANNEL_FLAG_LOCK: int#: ช่องสัญญาณใช้งาน lock/unlock

protocol.CHANNEL_FLAG_PHYSICAL: int#: ช่องสัญญาณแทนการขนส่งทางกายภาพ (ตรงกันข้ามกับช่องสัญญาณข้อมูลเชิงตรรกะ)

ตัวระบุช่องสัญญาณในตัว

protocol.CHANNEL_ID_TRANSPORT: int#: ID ช่องสัญญาณสงวนไว้สำหรับการขนส่งที่ใช้งานอยู่

protocol.CHANNEL_ID_STDIN: int#: ID ช่องสัญญาณของช่อง stdin ในตัว

protocol.CHANNEL_ID_STDOUT: int#: ID ช่องสัญญาณของช่อง stdout ในตัว

protocol.CHANNEL_ID_STREAM: int#: ID ช่องสัญญาณของช่อง stream ในตัว

protocol.CHANNEL_ID_PROFILE: int#: ID ช่องสัญญาณของช่อง profiler ในตัว (มีอยู่เฉพาะเมื่อเฟิร์มแวร์ถูกสร้างพร้อมตัวสร้างโปรไฟล์ที่เปิดใช้งาน)

protocol --- ช่องสัญญาณโปรโตคอล OpenMV#