pyb --- دوال متعلقة باللوحة

تحذير

وحدة pyb مهملة. استخدم وحدة machine المتعددة المنافذ في الشيفرات الجديدة -- فهي توفر الوظائف نفسها على كل OpenMV Cam بغض النظر عن عائلة المتحكم الدقيق، بينما لا توجد pyb إلا على اللوحات المبنية على STM32. تُبقى pyb للحفاظ على التوافق مع البرامج النصية القديمة، ولن تُضاف إليها ميزات جديدة، وقد تُزال في إصدار مستقبلي.

تحتوي وحدة pyb على دوال خاصة بـ STM32 ومتعلقة باللوحة.

دوال متعلقة بالوقت

pyb.delay(ms: int) → None

تأخير لعدد المللي ثانية المحدد.

pyb.udelay(us: int) → None

تأخير لعدد الميكرو ثانية المحدد.

pyb.millis() → int

تُرجع عدد المللي ثانية منذ آخر إعادة تعيين للوحة.

تكون النتيجة دائمًا عددًا صحيحًا صغيرًا في MicroPython (عدد ذو إشارة بطول 31 بت)، لذا بعد 2^30 مللي ثانية (نحو 12.4 يومًا) ستبدأ هذه الدالة بإرجاع أعداد سالبة.

لاحظ أنه إذا تم استدعاء pyb.stop() فسيتوقف العداد العتادي الداعم لهذه الدالة طوال مدة حالة "السكون". وسيؤثر ذلك على نتيجة pyb.elapsed_millis().

pyb.micros() → int

تُرجع عدد الميكرو ثانية منذ آخر إعادة تعيين للوحة.

تكون النتيجة دائمًا عددًا صحيحًا صغيرًا في MicroPython (عدد ذو إشارة بطول 31 بت)، لذا بعد 2^30 ميكرو ثانية (نحو 17.8 دقيقة) ستبدأ هذه الدالة بإرجاع أعداد سالبة.

لاحظ أنه إذا تم استدعاء pyb.stop() فسيتوقف العداد العتادي الداعم لهذه الدالة طوال مدة حالة "السكون". وسيؤثر ذلك على نتيجة pyb.elapsed_micros().

pyb.elapsed_millis(start: int) → int

تُرجع عدد المللي ثانية التي انقضت منذ start.

تتولى هذه الدالة معالجة التفاف العداد، وتُرجع دائمًا عددًا موجبًا. وهذا يعني أنه يمكن استخدامها لقياس فترات تصل إلى نحو 12.4 يومًا.

مثال:

start = pyb.millis()
while pyb.elapsed_millis(start) < 1000:
    # Perform some operation

pyb.elapsed_micros(start: int) → int

تُرجع عدد الميكرو ثانية التي انقضت منذ start.

تتولى هذه الدالة معالجة التفاف العداد، وتُرجع دائمًا عددًا موجبًا. وهذا يعني أنه يمكن استخدامها لقياس فترات تصل إلى نحو 17.8 دقيقة.

مثال:

start = pyb.micros()
while pyb.elapsed_micros(start) < 1000:
    # Perform some operation
    pass

دوال متعلقة بإعادة التعيين

pyb.hard_reset() → None

تعيد تعيين OpenMV Cam بطريقة مشابهة للضغط على زر RESET الخارجي.

pyb.bootloader() → None

تعيد التعيين إلى محمّل إقلاع USB DFU الخاص بـ OpenMV، جاهزًا لتحديث البرنامج الثابت. هذه هي الطريقة الموصى بها لاستدعاء DFU من شيفرة قيد التشغيل -- لا حاجة لتأكيد دبوس BOOT عند إعادة التعيين.

غير متاح على OpenMV Cam N6 (طبقة التوافق القديمة pyb معطلة على تلك اللوحة)؛ استخدم machine.bootloader() بدلًا منها.

pyb.fault_debug(value: bool) → None

تفعيل أو تعطيل تصحيح أعطال النظام الجسيمة (hard-fault). العطل الجسيم هو حدوث خطأ قاتل في النظام الأساسي، مثل الوصول إلى ذاكرة غير صالحة.

إذا كانت قيمة الوسيط value هي False فستعيد اللوحة تعيين نفسها تلقائيًا عند حدوث عطل جسيم.

إذا كانت قيمة value هي True فعند حدوث عطل جسيم في اللوحة، ستطبع السجلات وتتبع المكدس، ثم تومض مصابيح LED بصورة لا نهائية.

القيمة الافتراضية هي التعطيل، أي إعادة التعيين تلقائيًا.

دوال متعلقة بالمقاطعات

pyb.disable_irq() → bool

تعطيل طلبات المقاطعة. تُرجع حالة المقاطعة (IRQ) السابقة: False/True للمقاطعات المعطلة/المفعّلة على التوالي. يمكن تمرير هذه القيمة المُرجَعة إلى enable_irq لاستعادة المقاطعة إلى حالتها الأصلية.

pyb.enable_irq(state: bool = True) → None

تفعيل طلبات المقاطعة. إذا كانت state هي True (القيمة الافتراضية) فستُفعّل المقاطعات. وإذا كانت state هي False فستُعطّل المقاطعات. أشيع استخدام لهذه الدالة هو تمرير القيمة المُرجَعة من disable_irq إليها للخروج من قسم حرج.

pyb.freq(sysclk: int | None = None, hclk: int | None = None, pclk1: int | None = None, pclk2: int | None = None) → Tuple[int, int, int, int] | None

إذا استُدعيت دون وسائط، تُرجع صفًا (tuple) من ترددات الساعة (sysclk, hclk, pclk1, pclk2) بالهرتز:

الحقل	المعنى
sysclk	تردد وحدة المعالجة المركزية
hclk	تردد ناقل AHB والذاكرة الأساسية وDMA
pclk1	تردد ناقل APB1
pclk2	تردد ناقل APB2

إذا استُدعيت بأي وسائط فستضبط الدالة تردد وحدة المعالجة المركزية (وترددات النواقل أيضًا إذا قُدّمت وسائط إضافية). الترددات بالهرتز؛ ويُختار أكبر تردد مدعوم لا يتجاوز القيمة المعطاة. تعتمد مجموعة قيم sysclk الصالحة والقيم القصوى لـ hclk / pclk1 / pclk2 على المتحكم الدقيق -- راجع دليل مرجع STM32 ذا الصلة لـ OpenMV Cam المستخدمة. تُشتق ترددات النواقل من sysclk عبر مقسّمات يختارها المشغّل ليطابق على أفضل وجه القيم المطلوبة.

تحذير

قد يؤدي تغيير التردد أثناء تفعيل USB إلى جعل USB غير موثوق. غيّره من boot.py قبل بدء تشغيل الطرفية USB، ولا تختر قيمة sysclk منخفضة جدًا بحيث لا تفي بمتطلبات ساعة USB للمتحكم الدقيق.

دوال متعلقة بالطاقة

pyb.wfi() → None

الانتظار لمقاطعة داخلية أو خارجية.

ينفّذ هذا تعليمة wfi التي تقلل استهلاك الطاقة للمتحكم الدقيق حتى تحدث أي مقاطعة (داخلية كانت أم خارجية)، وعند ذلك يستمر التنفيذ. لاحظ أن مقاطعة نبضة النظام تحدث مرة كل مللي ثانية (1000 هرتز)، لذا ستحجب هذه الدالة لمدة 1 مللي ثانية على الأكثر.

pyb.stop() → None

تضع OpenMV Cam في حالة الطاقة المنخفضة stop الخاصة بـ STM32. يستمر التنفيذ من هذه النقطة عند الاستيقاظ. يتطلب الاستيقاظ مقاطعة خارجية أو حدثًا من ساعة الوقت الحقيقي؛ راجع pyb.RTC.wakeup() لإعداد أحدها. يعتمد سحب التيار الفعلي القابل للتحقيق على اللوحة وعلى الطرفيات المتروكة بساعة عاملة.

pyb.standby() → None

تضع OpenMV Cam في حالة السكون العميق standby الخاصة بـ STM32. هذا هو أدنى مستوى لإطفاء الطاقة؛ يخرج الجهاز عبر إعادة تعيين جسيمة عند إيقاظه، لذا لا يُستأنف التنفيذ في مكانه. يتطلب الاستيقاظ حدثًا من ساعة الوقت الحقيقي؛ راجع pyb.RTC.wakeup() لإعداد أحدها. يعتمد سحب التيار الفعلي القابل للتحقيق على اللوحة.

دوال متنوعة

pyb.have_cdc() → bool

تُرجع True إذا كان USB متصلًا كجهاز تسلسلي، وإلا False.

ملاحظة

هذه الدالة مهملة. استخدم pyb.USB_VCP().isconnected() بدلًا منها.

pyb.hid(data: Tuple[int, int, int, int]) → None

تأخذ صفًا رباعيًا (أو قائمة) وترسله إلى مضيف USB (الحاسوب) للإشارة إلى حدث حركة ماوس HID.

ملاحظة

هذه الدالة مهملة. استخدم pyb.USB_HID.send() بدلًا منها.

pyb.info(dump_alloc_table: bool | None = None) → None

تطبع الكثير من المعلومات عن اللوحة.

pyb.main(filename: str) → None

تضبط اسم ملف البرنامج النصي الرئيسي الذي سيُشغّل بعد انتهاء boot.py. إذا لم تُستدعَ هذه الدالة فسيُنفَّذ الملف الافتراضي main.py.

لا معنى لاستدعاء هذه الدالة إلا من داخل boot.py.

pyb.mount(device: Any, mountpoint: str, *, readonly: bool = False, mkfs: bool = False) → None

ملاحظة

هذه الدالة مهملة. استخدم vfs.mount() / vfs.umount() وجهاز كتل مشتقًا من vfs.AbstractBlockDev بدلًا منها.

تركّب جهاز كتل تحت mountpoint. يجب أن يطبّق device بروتوكول جهاز الكتل القديم الخاص بـ pyb (وهو مهمل أيضًا -- راجع vfs.AbstractBlockDev للواجهة الحديثة):

الدالة	الغرض
readblocks(self, blocknum, buf)	تنسخ ما يعادل buf من البايتات من الجهاز بدءًا من الكتلة blocknum. طول buf مضاعف للعدد 512.
writeblocks(self, blocknum, buf) (اختياري)	تكتب buf إلى الجهاز بدءًا من الكتلة blocknum. إذا حُذفت، يُركّب الجهاز للقراءة فقط.
count(self)	تُرجع عدد الكتل ذات الحجم 512 بايت على الجهاز.
sync(self) (اختياري)	تُفرّغ أي عمليات كتابة مخزّنة مؤقتًا.

mountpoint هو المسار في جذر نظام الملفات الذي يُركّب عنده الجهاز؛ ويجب أن يبدأ بشرطة مائلة أمامية. تفرض readonly تركيبًا للقراءة فقط. تنشئ mkfs نظام ملفات جديدًا إذا لم يكن هناك أي نظام موجود.

pyb.repl_uart(uart: UART | None = None) → UART | None

تحصل على كائن UART الذي يتكرر عليه REPL أو تضبطه.

pyb.rng() → int

تُرجع عددًا عشوائيًا بطول 30 بت مولّدًا عتاديًا.

pyb.sync() → None

تزامن جميع أنظمة الملفات.

pyb.unique_id() → bytes

تُرجع سلسلة من 12 بايت (96 بت)، وهي المعرّف الفريد للمتحكم الدقيق.

pyb.usb_mode(modestr: str | None = None, port: int = -1, vid: int = 0xf055, pid: int = -1, msc: Tuple = (), hid: Tuple = pyb.hid_mouse, high_speed: bool = False) → str | None

إذا استُدعيت دون وسائط، تُرجع وضع USB الحالي كسلسلة نصية.

إذا استُدعيت مع توفير modestr، فإنها تحاول ضبط وضع USB. القيم التالية لـ modestr مفهومة:

modestr	يضبط
None	يعطّل USB.
'VCP'	VCP (منفذ COM افتراضي) فقط.
'MSC'	MSC (فئة التخزين الكتلي لـ USB) فقط.
'VCP+MSC'	VCP وMSC.
'VCP+HID'	VCP وHID (جهاز واجهة بشرية).
'VCP+MSC+HID'	VCP وMSC وHID معًا. غير مدعوم على كل OpenMV Cam.

للحفاظ على التوافق مع الإصدارات السابقة، تُفهم 'CDC' بمعنى 'VCP' (وكذلك 'CDC+MSC' و'CDC+HID').

ينبغي أن يكون المعامل port عددًا صحيحًا (0، 1، ...) ويحدد منفذ USB المراد استخدامه إذا كانت اللوحة تدعم منافذ متعددة. القيمة -1 تستخدم المنفذ الافتراضي أو المُختار تلقائيًا.

يتيح لك المعاملان vid وpid تحديد VID (معرّف المورّد) وPID (معرّف المنتج). قيمة pid تساوي -1 ستختار PID بناءً على قيمة modestr.

عند تفعيل وضع MSC، يمكن استخدام المعامل msc لتحديد قائمة بوحدات SCSI LUN المراد عرضها على واجهة التخزين الكتلي. على سبيل المثال msc=(pyb.Flash(), pyb.SDCard()).

عند تفعيل وضع HID، يمكنك أيضًا تحديد تفاصيل HID بتمرير المعامل المفتاحي hid. وهو يأخذ صفًا من (الفئة الفرعية، البروتوكول، أقصى طول حزمة، فترة الاستقصاء، واصف التقرير). افتراضيًا سيضبط قيمًا مناسبة لماوس USB. كما توجد ثابتة pyb.hid_keyboard وهي صف مناسب للوحة مفاتيح USB.

المعامل high_speed، عند ضبطه على True، يفعّل وضع USB HS إذا كان العتاد يدعمه.

الثوابت

كلا الثابتين أدناه عبارة عن صفوف خماسية جاهزة بالشكل

(subclass, protocol, max_packet_size, polling_interval_ms, report_descriptor)

صالحة للتمرير كوسيط hid لـ usb_mode() لجعل OpenMV Cam تظهر للمضيف كجهاز USB HID. subclass = 1 يعني "واجهة الإقلاع" ويختار protocol فئة جهاز الإقلاع (1 = لوحة مفاتيح، 2 = ماوس). العنصر الخامس هو كائن bytes يحمل واصف تقرير HID المستخدم عند تعداد المضيف للجهاز.

pyb.hid_mouse: tuple

واصف HID جاهز لماوس إقلاع بثلاثة أزرار مع حركة X/Y نسبية. الصف هو (1, 2, 4, 8, <mouse report descriptor>): فئة فرعية للإقلاع، بروتوكول ماوس، تقارير إدخال بطول 4 بايت (قناع الأزرار + X + Y + العجلة)، يُستقصى كل 8 مللي ثانية. واصف التقرير المدمج هو الذي يستخدمه pyb.USB_HID().send((buttons, dx, dy, wheel)).

pyb.hid_keyboard: tuple

واصف HID جاهز للوحة مفاتيح إقلاع USB. الصف هو (1, 1, 8, 8, <keyboard report descriptor>): فئة فرعية للإقلاع، بروتوكول لوحة مفاتيح، تقارير إدخال بطول 8 بايت (بايت المُعدِّل، بايت محجوز واحد، ستة رموز مفاتيح متزامنة)، يُستقصى كل 8 مللي ثانية. واصف التقرير المدمج يطابق التخطيط القياسي بطول 8 بايت للوحة مفاتيح إقلاع HID، لذا ينبغي أن يكون التقرير المرسل عبر USB_HID.send() من نوع bytes بالشكل (modifiers, 0, key1, key2, key3, key4, key5, key6).

الأصناف

• class ADC -- التحويل من التناظري إلى الرقمي
• class ADCAll -- الوصول إلى جميع قنوات ADC
• الفئة CAN -- ناقل اتصالات شبكة منطقة التحكم (controller area network)
• الفئة DAC -- التحويل من الرقمي إلى التناظري
• الفئة ExtInt -- تهيئة دبابيس الدخل/الخرج لتوليد مقاطعة عند الأحداث الخارجية
• الفئة Flash -- الوصول إلى تخزين الفلاش المدمج
• الفئة I2C -- بروتوكول تسلسلي ثنائي الأسلاك
• الفئة LED -- مؤشر LED على اللوحة
• الصنف Pin -- التحكم في دبابيس الإدخال/الإخراج
• الصنف PinAF -- الوظائف البديلة للدبوس
• الصنف RTC -- ساعة الوقت الحقيقي
• الصنف Servo -- مشغّل سيرفو هواية ثلاثي الأسلاك
• الصنف SPI -- بروتوكول تسلسلي تقوده وحدة تحكم
• class Timer -- التحكم في المؤقتات الداخلية
• class TimerChannel -- إعداد قناة لمؤقت
• class UART -- ناقل اتصال تسلسلي مزدوج الاتجاه
• class USB_HID -- جهاز واجهة بشرية عبر USB (HID)
• class USB_VCP -- منفذ اتصال افتراضي عبر USB