class UART -- ناقل اتصالات تسلسلية ثنائي الاتجاه

ينفّذ UART بروتوكول الاتصالات التسلسلية ثنائية الاتجاه القياسي UART/USART. على المستوى الفيزيائي يتكوّن من خطين: RX وTX. وحدة الاتصال هي محرف (لا يُخلط بينه وبين محرف السلسلة النصية) يمكن أن يكون بعرض 8 أو 9 بتات.

يمكن إنشاء كائنات UART وتهيئتها باستخدام:

from machine import UART

uart = UART(3, 9600)                         # init with given baudrate
uart.init(9600, bits=8, parity=None, stop=1) # init with given parameters

يمكن أن تكون البتات 7 أو 8 أو 9. ويمكن أن يكون التوقّف 1 أو 2. مع parity=None يُدعم فقط 8 و9 بتات. ومع تفعيل التماثل يُدعم فقط 7 و8 بتات.

يتصرّف كائن UART مثل كائن stream ، وتُجرى عمليتا القراءة والكتابة باستخدام أساليب التدفق القياسية:

uart.read(10)       # read 10 characters, returns a bytes object
uart.read()         # read all available characters
uart.readline()     # read a line
uart.readinto(buf)  # read and store into the given buffer
uart.write('abc')   # write the 3 characters

المُنشئات

class machine.UART(id: int, baudrate: int = 9600, bits: int = 8, parity: int | None = None, stop: int = 1, *, tx: Pin | None = None, rx: Pin | None = None, rts: Pin | None = None, cts: Pin | None = None, txbuf: int | None = None, rxbuf: int | None = None, timeout: int | None = None, timeout_char: int | None = None, invert: int = 0, flow: int = 0)

إنشاء كائن UART بالمعرّف المُعطى.

الأساليب

init(baudrate: int = 9600, bits: int = 8, parity: int | None = None, stop: int = 1, *, tx: Pin | None = None, rx: Pin | None = None, rts: Pin | None = None, cts: Pin | None = None, txbuf: int | None = None, rxbuf: int | None = None, timeout: int | None = None, timeout_char: int | None = None, invert: int = 0, flow: int = 0) → None

تهيئة ناقل UART بالمعاملات المُعطاة:

  • baudrate هو معدل الساعة.

  • bits هو عدد البتات لكل محرف، 7 أو 8 أو 9.

  • parity هو التماثل، None أو 0 (زوجي) أو 1 (فردي).

  • stop هو عدد بتات التوقّف، 1 أو 2.

المعاملات الإضافية المخصّصة للكلمات المفتاحية فقط والتي قد تدعمها المنفذ هي:

  • tx يحدّد دبوس TX المراد استخدامه.

  • rx يحدّد دبوس RX المراد استخدامه.

  • rts يحدّد دبوس RTS (الخرج) المراد استخدامه للتحكم في تدفق الاستقبال عبر العتاد.

  • cts يحدّد دبوس CTS (الدخل) المراد استخدامه للتحكم في تدفق الإرسال عبر العتاد.

  • txbuf يحدّد طول مخزن TX المؤقت بالمحارف.

  • rxbuf يحدّد طول مخزن RX المؤقت بالمحارف.

  • timeout يحدّد زمن انتظار المحرف الأول (بالميلي ثانية).

  • timeout_char يحدّد زمن الانتظار بين المحارف (بالميلي ثانية).

  • invert يحدّد الخطوط المراد عكسها.

    • 0 لن يعكس الخطوط (حالة الخمول لكلا الخطين هي منطقي مرتفع).

    • UART.INV_TX سيعكس خط TX (تصبح حالة خمول خط TX الآن منطقي منخفض).

    • UART.INV_RX سيعكس خط RX (تصبح حالة خمول خط RX الآن منطقي منخفض).

    • UART.INV_TX | UART.INV_RX سيعكس كلا الخطين (حالة الخمول عند منطقي منخفض).

  • flow يحدّد إشارات التحكم في التدفق عبر العتاد المراد استخدامها. القيمة هي قناع بتات.

    • 0 سيتجاهل إشارات التحكم في التدفق عبر العتاد.

    • UART.RTS سيفعّل التحكم في تدفق الاستقبال باستخدام دبوس خرج RTS للإشارة إلى ما إذا كان لدى مخزن FIFO الخاص بالاستقبال مساحة كافية لقبول مزيد من البيانات.

    • UART.CTS سيفعّل التحكم في تدفق الإرسال عبر إيقاف الإرسال مؤقتًا عندما يشير دبوس دخل CTS إلى أن مساحة المخزن المؤقت لدى جهاز الاستقبال آخذة في النفاد.

    • UART.RTS | UART.CTS سيفعّل كليهما، للتحكم الكامل في التدفق عبر العتاد.

ملاحظة

من الممكن استدعاء init() عدة مرات على الكائن نفسه من أجل إعادة تهيئة UART أثناء التشغيل. وهذا يتيح استخدام طرفية UART واحدة لخدمة أجهزة مختلفة متصلة بدبابيس GPIO مختلفة. ويمكن خدمة جهاز واحد فقط في كل مرة في تلك الحالة. كما يجب عدم استدعاء deinit() لأنه سيمنع استدعاء init() مرة أخرى.

deinit() → None

إيقاف تشغيل ناقل UART.

ملاحظة

لن تتمكن من استدعاء init() على الكائن بعد deinit(). يلزم إنشاء نسخة جديدة في تلك الحالة.

any() → int

يُرجع عددًا صحيحًا يحصي عدد المحارف التي يمكن قراءتها دون حجب. سيُرجع 0 إذا لم تكن هناك محارف متاحة وعددًا موجبًا إذا كانت هناك محارف. قد يُرجع الأسلوب 1 حتى لو كان هناك أكثر من محرف واحد متاح للقراءة.

للاستعلام الأكثر تطورًا عن المحارف المتاحة استخدم select.poll:

poll = select.poll()
poll.register(uart, select.POLLIN)
poll.poll(timeout)
read(nbytes: int | None = None, /) → bytes | None

قراءة المحارف. إذا حُدّد nbytes فاقرأ بحدٍّ أقصى ذلك العدد من البايتات، وإلا فاقرأ أكبر قدر ممكن من البيانات. وقد يعود الأسلوب أبكر إذا بلغ زمن الاستجابة حدّه. زمن الاستجابة قابل للضبط في المُنشئ.

القيمة المُرجعة: كائن bytes يحتوي على البايتات التي قُرئت. يُرجع None عند انتهاء المهلة.

readinto(buf: bytearray, nbytes: int | None = None, /) → int | None

قراءة البايتات إلى buf. إذا حُدّد nbytes فاقرأ بحدٍّ أقصى ذلك العدد من البايتات. وإلا فاقرأ بحدٍّ أقصى len(buf) بايت. وقد يعود الأسلوب أبكر إذا بلغ زمن الاستجابة حدّه. زمن الاستجابة قابل للضبط في المُنشئ.

القيمة المُرجعة: عدد البايتات التي قُرئت وخُزّنت في buf أو None عند انتهاء المهلة.

readline() → bytes | None

قراءة سطر ينتهي بمحرف سطر جديد. وقد يعود الأسلوب أبكر إذا بلغ زمن الاستجابة حدّه. زمن الاستجابة قابل للضبط في المُنشئ.

القيمة المُرجعة: السطر الذي قُرئ أو None عند انتهاء المهلة.

write(buf: bytes) → int | None

كتابة مخزن البايتات المؤقت إلى الناقل.

القيمة المُرجعة: عدد البايتات التي كُتبت أو None عند انتهاء المهلة.

sendbreak() → None

إرسال حالة قطع (break) على الناقل -- إبقاء TX منخفضًا لمدة أطول من زمن محرف واحد. متاح على STM32 وmimxrt؛ وغير متاح على alif.

readchar() → int

قراءة محرف واحد من UART وإرجاعه كعدد صحيح (أو -1 عند انتهاء المهلة). أقل عبئًا من read(1) لأنه لا يُخصَّص كائن bytes. على STM32 فقط.

writechar(char: int) → None

كتابة المحرف الواحد char (عدد صحيح في النطاق 0 -- 255) إلى UART. أقل عبئًا من write() للإرسالات أحادية البايت. على STM32 فقط.

flush() → None

الحجب حتى يخرج كل بايت موجود حاليًا في مخزن الإرسال المؤقت عبر TX. يطلق OSError عند انتهاء المهلة؛ تُشتق المهلة من حجم مخزن TX المؤقت ومعدل الباود المضبوط، لذا فما لم يكن التحكم في التدفق مفعّلًا ويتوقف جهاز الاستقبال، يعود الاستدعاء قبل انتهاء المهلة بكثير.

txdone() → bool

يُرجع True عندما لا يكون هناك إرسال جارٍ (مخزن TX المؤقت فارغ وقد فرغ سجل الإزاحة)، وFalse خلاف ذلك. مفيد كبديل غير حاجب عن flush().

irq(handler: Callable[[UART], None] | None = None, trigger: int = 0, hard: bool = False) → None

تثبيت دالة رد نداء لإطلاقها عند أحداث UART.

handler هي الدالة المراد استدعاؤها. تتلقى نسخة UART كوسيطها الوحيد. مرّر None لإزالة معالج مُثبّت سابقًا.

trigger هو قناع بتات لواحد أو أكثر من ثوابت IRQ_* (انظر الثوابت أدناه) يحدّد أي الأحداث يطلق دالة رد النداء.

hard=True يسجّل معالج مقاطعة صلبة (زمن استجابة أقل، ولكن يجب ألا يخصّص المعالج ذاكرة). الافتراضي هو دالة رد نداء مجدولة.

يُرجع كائن irq.

ليس كل مصدر IRQ متاحًا على كل منفذ -- انظر ثوابت IRQ_* الفردية لمعرفة التوفر لكل منفذ.

الثوابت

RTS: int

مرّر إلى flow لتفعيل التحكم في تدفق العتاد RTS على جانب الاستقبال. ادمجه مع CTS عبر OR لتفعيل كليهما.

CTS: int

مرّر إلى flow لتفعيل التحكم في تدفق العتاد CTS على جانب الإرسال.

IRQ_RXIDLE: int

علامة إطلاق irq() : تُطلق مرة واحدة بعد استقبال محرف واحد أو أكثر ثم انتقال خط RX إلى الخمول. متاحة على جميع منافذ OpenMV.

IRQ_RX: int

علامة إطلاق irq() : تُطلق بعد كل محرف مُستقبَل. متاحة على STM32 وalif.

IRQ_TXIDLE: int

علامة إطلاق irq() : تُطلق عند خروج آخر محرف من الإرسال عبر الساعة. متاحة على mimxrt وalif.

IRQ_BREAK: int

علامة إطلاق irq() : تُطلق عند كشف حالة قطع (break) على RX. غير متاحة على أي منفذ من منافذ OpenMV.