class UART -- ناقل اتصال تسلسلي مزدوج الاتجاه¶

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

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

from pyb import UART

# init with the given baudrate
uart = UART(3, 9600, timeout_char=1000)

# init with explicit parameters
uart.init(9600, bits=8, parity=None, stop=1, timeout_char=1000)

يمكن أن تكون البتات 7 أو 8 أو 9. يمكن أن يكون التماثل (Parity) None أو 0 (زوجي) أو 1 (فردي). يمكن أن يكون Stop بقيمة 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

يمكن قراءة/كتابة الأحرف المفردة باستخدام:

uart.readchar()     # read 1 character and returns it as an integer
uart.writechar(42)  # write 1 character

للتحقق مما إذا كان هناك أي شيء للقراءة، استخدم:

uart.any()          # returns the number of characters waiting

ملاحظة: دوال التدفق read وwrite وغيرها جديدة في MicroPython v1.3.4. تستخدم الإصدارات الأقدم uart.send وuart.recv.

المُنشئات¶

class pyb.UART(bus: int | str, *args, **kwargs)¶

ينشئ كائن UART على الناقل bus المحدد (فهرس طرفية عددي صحيح، مثل 3 لـ UART3). بدون معاملات إضافية يُنشأ الكائن لكن لا تتم تهيئته (يحتفظ بإعدادات الناقل السابقة، إن وُجدت)؛ وإذا أُعطيت معاملات إضافية فإن الناقل يُهيّأ. راجع init() للاطلاع على المعاملات المتاحة.

UART(3) موصول بنفس دبابيس الترويسة على كل OpenMV Cam من نوع STM32:

الإشارة	دبوس الترويسة
`TX`	`P4`
`RX`	`P5`

تتوفر نواقل UART إضافية على بعض اللوحات:

الناقل	دبوس TX	دبوس RX	متوفر على
`UART(1)`	`P1`	`P0`	OpenMV Cam M7 / H7 / H7 Plus / Pure Thermal
`UART(4)`	`P2`	`P3`	OpenMV Cam N6
`UART(7)`	`P14`	`P13`	OpenMV Cam N6

الأساليب¶

init(baudrate: int, bits: int = 8, parity: int | None = None, stop: int = 1, *, timeout: int = 1000, flow: int = 0, timeout_char: int = 0, read_buf_len: int = 64) → None¶

تهيئة ناقل UART بالمعاملات المحددة:

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

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

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

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

flow يضبط نوع التحكم في التدفق. يمكن أن يكون 0 أو UART.RTS أو UART.CTS أو UART.RTS | UART.CTS.

timeout هو زمن الانتظار بالميلي ثانية لكتابة/قراءة أول حرف.

timeout_char هو زمن الانتظار بالميلي ثانية بين الأحرف أثناء الكتابة أو القراءة.

read_buf_len هو طول مخزن القراءة المؤقت بالأحرف (0 لتعطيله).

سيُطلق هذا الأسلوب استثناءً إذا تعذّر ضبط معدل الباود ضمن نسبة 5% من القيمة المطلوبة.

ملاحظة: مع parity=None، يُدعم 8 و9 بتات فقط. ومع تمكين التماثل، يُدعم 7 و8 بتات فقط.

deinit() → None¶: إيقاف تشغيل ناقل UART.

any() → int¶: يُرجع عدد البايتات المنتظرة (قد يكون 0).

read(nbytes: int | None = None) → bytes | None¶

قراءة الأحرف. إذا حُدِّد nbytes فاقرأ على الأكثر ذلك العدد من البايتات. إذا كان nbytes متاحًا في المخزن المؤقت، يعود فورًا، وإلا فإنه يعود عند وصول عدد كافٍ من الأحرف أو انقضاء زمن الانتظار.

إذا لم يُعطَ nbytes فإن الأسلوب يقرأ أكبر قدر ممكن من البيانات. ويعود بعد انقضاء زمن الانتظار.

ملاحظة: بالنسبة للأحرف ذات 9 بتات يأخذ كل حرف بايتين، ويجب أن يكون nbytes زوجيًا، ويكون عدد الأحرف nbytes/2.

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

readchar() → int¶

استقبال حرف واحد على الناقل.

القيمة المُرجَعة: الحرف المقروء، كعدد صحيح. يُرجع -1 عند انقضاء زمن الانتظار.

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

قراءة البايتات إلى buf. إذا حُدِّد nbytes فاقرأ على الأكثر ذلك العدد من البايتات. وإلا فاقرأ على الأكثر len(buf) بايت.

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

readline() → bytes | None¶

قراءة سطر ينتهي بحرف سطر جديد. إذا وُجد مثل هذا السطر، يكون الإرجاع فوريًا. وإذا انقضى زمن الانتظار، تُرجَع جميع البيانات المتاحة بغض النظر عن وجود سطر جديد من عدمه.

القيمة المُرجَعة: السطر المقروء أو None عند انقضاء زمن الانتظار إذا لم تكن هناك بيانات متاحة.

write(buf: bytes | bytearray | str) → int | None¶

كتابة مخزن البايتات إلى الناقل. إذا كان عرض الأحرف 7 أو 8 بتات فإن كل بايت يمثل حرفًا واحدًا. وإذا كان عرض الأحرف 9 بتات فيُستخدم بايتان لكل حرف (ترتيب البايت الأصغر أولًا)، ويجب أن يحتوي buf على عدد زوجي من البايتات.

القيمة المُرجَعة: عدد البايتات المكتوبة. إذا حدث انقضاء لزمن الانتظار ولم تُكتب أي بايتات يُرجع None.

writechar(char: int) → None¶: كتابة حرف واحد على الناقل. char هو عدد صحيح للكتابة. راجع قسم التحكم في تدفق CTS أدناه لمعرفة دلالات الحجب عند تمكين التحكم في تدفق CTS.

sendbreak() → None¶: إرسال حالة قطع (break) على الناقل. هذا يدفع الناقل إلى المستوى المنخفض لمدة 13 بتة.

الثوابت¶

RTS: int¶: علم بتي لمعامل flow في init()؛ يُمكّن التحكم في تدفق الأجهزة RTS (طلب الإرسال) على مسار الاستقبال.

CTS: int¶: علم بتي لمعامل flow في init()؛ يُمكّن التحكم في تدفق الأجهزة CTS (جاهزية الإرسال) على مسار الإرسال. يمكن دمجه بعامل OR مع RTS لتمكين كلا الاتجاهين.

التحكم في التدفق¶

يدعم UART(3) التحكم في تدفق الأجهزة RTS/CTS. على OpenMV Cam M7 وH7 وH7 Plus وPure Thermal تكون دبابيس التحكم في التدفق هي:

(TX, RX, nRTS, nCTS) = (P4, P5, P1, P2)

على OpenMV Cam N6 يُكشف فقط nRTS (على دبوس الترويسة P7)؛ أما nCTS فغير موصول إلى ترويسة الإدخال/الإخراج.

في الفقرات التالية يشير المصطلح "الهدف" إلى الجهاز الموصول بـ UART.

عند استدعاء أسلوب init() الخاص بـ UART مع ضبط flow على واحد أو كلا القيمتين UART.RTS وUART.CTS، تُهيّأ دبابيس التحكم في التدفق ذات الصلة. nRTS هو خرج نشِط عند المستوى المنخفض وnCTS هو دخل نشِط عند المستوى المنخفض مع تمكين المقاومة الرافعة. لتوصيل التحكم في التدفق، صِل nCTS الخاص بـ OpenMV Cam إلى nRTS الخاص بالهدف، وnRTS الخاص بـ OpenMV Cam إلى nCTS الخاص بالهدف.

CTS: الهدف يتحكم في مُرسِل OpenMV Cam¶

إذا كان التحكم في تدفق CTS مُمكّنًا فإن سلوك الكتابة يكون كالتالي:

إذا استُدعي أسلوب UART.write(buf) الخاص بـ OpenMV Cam، فسيتوقف الإرسال مؤقتًا خلال أي فترات يكون فيها nCTS بقيمة False. سيؤدي هذا إلى انقضاء زمن الانتظار إذا لم يُرسَل المخزن بأكمله خلال فترة المهلة. يُرجع الأسلوب عدد البايتات المكتوبة، مما يمكّن المستخدم من كتابة بقية البيانات إذا لزم الأمر. في حالة انقضاء زمن الانتظار، سيبقى حرف في UART في انتظار nCTS. وسيُضمَّن عدد البايتات المكوّنة لهذا الحرف في القيمة المُرجَعة.

إذا استُدعي UART.writechar() بينما nCTS بقيمة False فإن الأسلوب سينقضي زمن انتظاره ما لم يؤكّد الهدف nCTS في الوقت المناسب. وإذا انقضى زمن الانتظار سيُطلق OSError 116. وسيُرسَل الحرف بمجرد أن يؤكّد الهدف nCTS.

RTS: OpenMV Cam يتحكم في مُرسِل الهدف¶

إذا كان التحكم في تدفق RTS مُمكّنًا، يكون السلوك كالتالي:

إذا استُخدم الدخل المخزّن مؤقتًا (read_buf_len > 0)، تُخزّن الأحرف الواردة مؤقتًا. إذا امتلأ المخزن المؤقت، فإن الحرف التالي الذي يصل سيتسبب في انتقال nRTS إلى False: ينبغي أن يتوقف الهدف عن الإرسال. سينتقل nRTS إلى True عند قراءة الأحرف من المخزن المؤقت.

لاحظ أن أسلوب any() يُرجع عدد البايتات في المخزن المؤقت. افترض طول مخزن مؤقت قدره N بايت. إذا امتلأ المخزن المؤقت، ووصل حرف آخر، فسيُضبط nRTS على False، وسيُرجع any() العدد N. وعند قراءة الأحرف سيوضع الحرف الإضافي في المخزن المؤقت وسيُضمَّن في نتيجة استدعاء any() لاحق.

إذا لم يُستخدم الدخل المخزّن مؤقتًا (read_buf_len == 0) فإن وصول حرف سيتسبب في انتقال nRTS إلى False حتى تتم قراءة الحرف.