class UART -- บัสสื่อสารอนุกรมแบบดูเพล็กซ์

UART ใช้งานโปรโตคอลสื่อสารอนุกรมแบบดูเพล็กซ์มาตรฐาน UART/USART ในระดับกายภาพประกอบด้วยสาย 2 เส้นคือ 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

Bits สามารถเป็น 7, 8 หรือ 9 ได้ Stop สามารถเป็น 1 หรือ 2 ได้ เมื่อ parity=None จะรองรับเพียง 8 และ 9 บิตเท่านั้น เมื่อเปิดใช้งาน parity จะรองรับเพียง 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 ตาม id ที่กำหนด

เมธอด

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 คือ parity ได้แก่ None, 0 (คู่) หรือ 1 (คี่)

  • stop คือจำนวนบิตหยุด ได้แก่ 1 หรือ 2

พารามิเตอร์แบบ keyword-only เพิ่มเติมที่อาจรองรับโดยพอร์ต:

  • tx ระบุพิน TX ที่ใช้งาน

  • rx ระบุพิน RX ที่ใช้งาน

  • rts ระบุพิน RTS (เอาต์พุต) สำหรับการควบคุมการไหลของการรับด้วยฮาร์ดแวร์

  • cts ระบุพิน CTS (อินพุต) สำหรับการควบคุมการไหลของการส่งด้วยฮาร์ดแวร์

  • txbuf ระบุความยาวของบัฟเฟอร์ TX เป็นจำนวนตัวอักษร

  • rxbuf ระบุความยาวของบัฟเฟอร์ RX เป็นจำนวนตัวอักษร

  • timeout ระบุเวลารอตัวอักษรแรก (หน่วย ms)

  • timeout_char ระบุเวลารอระหว่างตัวอักษร (หน่วย ms)

  • invert ระบุสายที่ต้องการกลับสัญญาณ

    • 0 จะไม่กลับสัญญาณสายใด (สถานะ idle ของทั้งสองสายเป็น logic high)

    • UART.INV_TX จะกลับสัญญาณสาย TX (สถานะ idle ของสาย TX กลายเป็น logic low)

    • UART.INV_RX จะกลับสัญญาณสาย RX (สถานะ idle ของสาย RX กลายเป็น logic low)

    • UART.INV_TX | UART.INV_RX จะกลับสัญญาณทั้งสองสาย (สถานะ idle เป็น logic low)

  • flow ระบุสัญญาณควบคุมการไหลของฮาร์ดแวร์ที่จะใช้ ค่าเป็น bitmask

    • 0 จะละเว้นสัญญาณควบคุมการไหลของฮาร์ดแวร์

    • UART.RTS จะเปิดใช้งานการควบคุมการไหลของการรับโดยใช้พิน RTS เอาต์พุตเพื่อส่งสัญญาณว่า FIFO รับมีพื้นที่เพียงพอสำหรับรับข้อมูลเพิ่มเติม

    • UART.CTS จะเปิดใช้งานการควบคุมการไหลของการส่งโดยหยุดการส่งชั่วคราวเมื่อพิน CTS อินพุตส่งสัญญาณว่าผู้รับมีพื้นที่บัฟเฟอร์ต่ำ

    • UART.RTS | UART.CTS จะเปิดใช้งานทั้งสองอย่างเพื่อการควบคุมการไหลของฮาร์ดแวร์แบบเต็มรูปแบบ

Note

สามารถเรียก init() หลายครั้งบนออบเจ็กต์เดียวกันเพื่อกำหนดค่า UART ใหม่ขณะรันได้ ซึ่งช่วยให้ใช้อุปกรณ์ต่อพ่วง UART ตัวเดียวในการให้บริการอุปกรณ์หลายชนิดที่ต่อกับพิน GPIO ต่างกัน อย่างไรก็ตาม ในกรณีนี้สามารถให้บริการได้เพียงอุปกรณ์เดียวในแต่ละเวลา และห้ามเรียก deinit() เนื่องจากจะทำให้ไม่สามารถเรียก init() ได้อีก

deinit() → None

ปิดบัส UART

Note

หลังจาก deinit() แล้วจะไม่สามารถเรียก init() บนออบเจ็กต์นั้นได้อีก จำเป็นต้องสร้างอินสแตนซ์ใหม่ในกรณีนี้

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 จะอ่านได้สูงสุดไม่เกินจำนวนไบต์นั้น มิเช่นนั้นจะอ่านข้อมูลให้ได้มากที่สุดเท่าที่เป็นไปได้ อาจคืนค่าก่อนเวลาหากหมดเวลา โดยค่า timeout สามารถกำหนดได้ในตัวสร้าง

ค่าที่คืน: ออบเจ็กต์ bytes ที่มีไบต์ที่อ่านได้ คืนค่า None เมื่อหมดเวลา

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

อ่านไบต์ใส่ buf ถ้าระบุ nbytes จะอ่านสูงสุดไม่เกินจำนวนนั้น มิเช่นนั้นจะอ่านสูงสุดไม่เกิน len(buf) ไบต์ อาจคืนค่าก่อนเวลาหากหมดเวลา โดยค่า timeout สามารถกำหนดได้ในตัวสร้าง

ค่าที่คืน: จำนวนไบต์ที่อ่านและเก็บใน buf หรือ None เมื่อหมดเวลา

readline() → bytes | None

อ่านหนึ่งบรรทัดโดยสิ้นสุดที่อักขระขึ้นบรรทัดใหม่ อาจคืนค่าก่อนเวลาหากหมดเวลา โดยค่า timeout สามารถกำหนดได้ในตัวสร้าง

ค่าที่คืน: บรรทัดที่อ่านได้หรือ 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 เมื่อหมดเวลา โดย timeout ถูกคำนวณจากขนาดบัฟเฟอร์ TX และอัตราบอดที่กำหนด ดังนั้นหากไม่ได้เปิดใช้การควบคุมการไหลและผู้รับไม่ค้าง การเรียกจะสำเร็จก่อนหมดเวลามาก

txdone() → bool

คืนค่า True เมื่อไม่มีการส่งข้อมูลอยู่ (บัฟเฟอร์ TX ว่างและ shift register ระบายออกแล้ว) หรือ False มิฉะนั้น ใช้เป็นทางเลือกแบบไม่บล็อกแทน flush()

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

ติดตั้งคอลแบ็กเพื่อเรียกใช้งานตามเหตุการณ์ UART

handler คือฟังก์ชันที่จะเรียกใช้งาน รับอินสแตนซ์ UART เป็นอาร์กิวเมนต์เดียว ส่ง None เพื่อลบ handler ที่ติดตั้งไว้ก่อนหน้า

trigger คือ bitmask ของค่าคงที่ IRQ_* หนึ่งหรือหลายค่า (ดูหัวข้อ Constants ด้านล่าง) เพื่อเลือกเหตุการณ์ที่จะเรียกคอลแบ็ก

hard=True ลงทะเบียน hard-interrupt handler (เวลาแฝงต่ำกว่า แต่ handler ต้องไม่จัดสรรหน่วยความจำ) ค่าเริ่มต้นคือ scheduled callback

คืนค่าออบเจ็กต์ irq

ไม่ใช่ทุกแหล่ง IRQ จะพร้อมใช้งานในทุกพอร์ต -- ดูค่าคงที่ IRQ_* แต่ละตัวสำหรับความพร้อมใช้งานต่อพอร์ต

ค่าคงที่

RTS: int

ส่งให้ flow เพื่อเปิดใช้งานการควบคุมการไหลฮาร์ดแวร์ RTS ฝั่งรับ รวมกับ CTS ด้วย OR เพื่อเปิดใช้งานทั้งสองอย่าง

CTS: int

ส่งให้ flow เพื่อเปิดใช้งานการควบคุมการไหลฮาร์ดแวร์ CTS ฝั่งส่ง

IRQ_RXIDLE: int

แฟล็ก trigger ของ irq(): เรียกใช้งานหนึ่งครั้งหลังจากได้รับตัวอักษรหนึ่งตัวหรือมากกว่าแล้วสาย RX ว่าง ใช้ได้กับทุกพอร์ต OpenMV

IRQ_RX: int

แฟล็ก trigger ของ irq(): เรียกใช้งานหลังจากได้รับตัวอักษรแต่ละตัว ใช้ได้กับ STM32 และ alif

IRQ_TXIDLE: int

แฟล็ก trigger ของ irq(): เรียกใช้งานเมื่อตัวอักษรสุดท้ายของการส่งถูกส่งออกครบถ้วน ใช้ได้กับ mimxrt และ alif

IRQ_BREAK: int

แฟล็ก trigger ของ irq(): เรียกใช้งานเมื่อตรวจพบสภาวะ break บน RX ไม่พร้อมใช้งานบนพอร์ต OpenMV ใดๆ