kelas UART -- bus komunikasi serial dupleks¶

UART mengimplementasikan protokol komunikasi serial dupleks UART/USART standar. Pada tingkat fisik terdiri dari 2 jalur: RX dan TX. Unit komunikasi adalah sebuah karakter (jangan dikacaukan dengan karakter string) yang dapat berukuran 8 atau 9 bit.

Objek UART dapat dibuat dan diinisialisasi menggunakan:

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)

Bits dapat bernilai 7, 8 atau 9. Parity dapat berupa None, 0 (genap) atau 1 (ganjil). Stop dapat bernilai 1 atau 2.

Catatan: dengan parity=None, hanya 8 dan 9 bit yang didukung. Dengan parity diaktifkan, hanya 7 dan 8 bit yang didukung.

Objek UART berperilaku seperti objek stream dan pembacaan serta penulisan dilakukan menggunakan metode stream standar:

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

Karakter individual dapat dibaca/ditulis menggunakan:

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

Untuk memeriksa apakah ada data yang dapat dibaca, gunakan:

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

Catatan: Fungsi stream read, write, dll. merupakan fitur baru di MicroPython v1.3.4. Versi sebelumnya menggunakan uart.send dan uart.recv.

Konstruktor¶

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

Membuat objek UART pada bus yang diberikan (indeks periferal berupa integer, misalnya 3 untuk UART3). Tanpa parameter tambahan, objek dibuat namun tidak diinisialisasi (mempertahankan pengaturan bus sebelumnya, jika ada); jika argumen ekstra diberikan maka bus akan diinisialisasi. Lihat init() untuk parameter yang tersedia.

UART(3) terhubung ke pin header yang sama pada setiap STM32 OpenMV Cam:

Sinyal	Pin header
`TX`	`P4`
`RX`	`P5`

Bus UART tambahan tersedia pada beberapa board:

Bus	Pin TX	Pin RX	Tersedia di
`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

Metode¶

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¶

Menginisialisasi bus UART dengan parameter yang diberikan:

baudrate adalah laju clock.

bits adalah jumlah bit per karakter, 7, 8 atau 9.

parity adalah parity, None, 0 (genap) atau 1 (ganjil).

stop adalah jumlah stop bit, 1 atau 2.

flow mengatur jenis flow control. Dapat berupa 0, UART.RTS, UART.CTS atau UART.RTS | UART.CTS.

timeout adalah waktu tunggu dalam milidetik untuk menunggu penulisan/pembacaan karakter pertama.

timeout_char adalah waktu tunggu dalam milidetik untuk menunggu antar karakter saat menulis atau membaca.

read_buf_len adalah panjang karakter dari buffer baca (0 untuk menonaktifkan).

Metode ini akan melempar pengecualian jika laju baud tidak dapat diatur dalam 5% dari nilai yang diinginkan.

Catatan: dengan parity=None, hanya 8 dan 9 bit yang didukung. Dengan parity diaktifkan, hanya 7 dan 8 bit yang didukung.

deinit() → None¶: Mematikan bus UART.

any() → int¶: Mengembalikan jumlah byte yang menunggu (mungkin 0).

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

Membaca karakter. Jika nbytes ditentukan maka baca maksimal sebanyak itu byte. Jika nbytes tersedia dalam buffer, langsung mengembalikan nilai, jika tidak mengembalikan nilai ketika karakter yang cukup tiba atau waktu tunggu habis.

Jika nbytes tidak diberikan maka metode membaca sebanyak mungkin data. Mengembalikan nilai setelah waktu tunggu habis.

Catatan: untuk karakter 9 bit setiap karakter membutuhkan dua byte, nbytes harus genap, dan jumlah karakter adalah nbytes/2.

Nilai kembalian: objek bytes yang berisi byte yang dibaca. Mengembalikan None saat waktu tunggu habis.

readchar() → int¶

Menerima satu karakter pada bus.

Nilai kembalian: karakter yang dibaca, sebagai integer. Mengembalikan -1 saat waktu tunggu habis.

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

Membaca byte ke dalam buf. Jika nbytes ditentukan maka baca maksimal sebanyak itu byte. Jika tidak, baca maksimal len(buf) byte.

Nilai kembalian: jumlah byte yang dibaca dan disimpan ke dalam buf atau None saat waktu tunggu habis.

readline() → bytes | None¶

Membaca satu baris, diakhiri dengan karakter baris baru. Jika baris tersebut ada, langsung dikembalikan. Jika waktu tunggu habis, semua data yang tersedia dikembalikan terlepas dari ada tidaknya karakter baris baru.

Nilai kembalian: baris yang dibaca atau None saat waktu tunggu habis jika tidak ada data yang tersedia.

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

Menulis buffer byte ke bus. Jika karakter berukuran 7 atau 8 bit maka setiap byte adalah satu karakter. Jika karakter berukuran 9 bit maka dua byte digunakan untuk setiap karakter (little endian), dan buf harus berisi jumlah byte yang genap.

Nilai kembalian: jumlah byte yang ditulis. Jika terjadi waktu tunggu dan tidak ada byte yang ditulis mengembalikan None.

writechar(char: int) → None¶: Menulis satu karakter pada bus. char adalah integer yang akan ditulis. Lihat bagian CTS flow control di bawah untuk semantik pemblokiran saat CTS flow control diaktifkan.

sendbreak() → None¶: Mengirim kondisi break pada bus. Ini mendorong bus ke kondisi rendah selama durasi 13 bit.

Konstanta¶

RTS: int¶: Flag bit untuk argumen flow dari init(); mengaktifkan RTS (request-to-send) hardware flow control pada jalur penerimaan.

CTS: int¶: Flag bit untuk argumen flow dari init(); mengaktifkan CTS (clear-to-send) hardware flow control pada jalur transmisi. Dapat di-OR dengan RTS untuk mengaktifkan kedua arah.

Flow Control¶

UART(3) mendukung RTS/CTS hardware flow control. Pada OpenMV Cam M7, H7, H7 Plus dan Pure Thermal pin flow-control adalah:

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

Pada OpenMV Cam N6 hanya nRTS yang diekspos (pada pin header P7); nCTS tidak diarahkan ke header I/O.

Dalam paragraf berikut istilah "target" mengacu pada perangkat yang terhubung ke UART.

Ketika metode init() UART dipanggil dengan flow diatur ke satu atau keduanya dari UART.RTS dan UART.CTS, pin flow-control yang relevan dikonfigurasi. nRTS adalah output aktif-rendah dan nCTS adalah input aktif-rendah dengan pull-up diaktifkan. Untuk menghubungkan flow control, sambungkan nCTS OpenMV Cam ke nRTS target dan nRTS OpenMV Cam ke nCTS target.

CTS: target mengontrol pemancar OpenMV Cam¶

Jika CTS flow control diaktifkan perilaku penulisan adalah sebagai berikut:

Jika metode UART.write(buf) OpenMV Cam dipanggil, transmisi akan berhenti sementara pada periode-periode ketika nCTS bernilai False. Hal ini akan mengakibatkan waktu tunggu habis jika seluruh buffer tidak ditransmisikan dalam periode waktu tunggu. Metode mengembalikan jumlah byte yang ditulis, memungkinkan pengguna untuk menulis sisa data jika diperlukan. Jika terjadi waktu tunggu, sebuah karakter akan tetap berada di UART menunggu nCTS. Jumlah byte yang menyusun karakter ini akan disertakan dalam nilai kembalian.

Jika UART.writechar() dipanggil ketika nCTS bernilai False metode akan mengalami waktu tunggu kecuali jika target menegaskan nCTS tepat waktu. Jika waktu tunggu habis OSError 116 akan dilempar. Karakter akan ditransmisikan segera setelah target menegaskan nCTS.

RTS: OpenMV Cam mengontrol pemancar target¶

Jika RTS flow control diaktifkan, perilakunya adalah sebagai berikut:

Jika input dengan buffer digunakan (read_buf_len > 0), karakter yang masuk di-buffer. Jika buffer penuh, karakter berikutnya yang tiba akan menyebabkan nRTS menjadi False: target harus menghentikan transmisi. nRTS akan menjadi True ketika karakter dibaca dari buffer.

Perhatikan bahwa metode any() mengembalikan jumlah byte dalam buffer. Asumsikan panjang buffer N byte. Jika buffer menjadi penuh, dan karakter lain tiba, nRTS akan diatur False, dan any() akan mengembalikan jumlah N. Ketika karakter dibaca, karakter tambahan akan ditempatkan di buffer dan akan disertakan dalam hasil dari panggilan any() berikutnya.

Jika input dengan buffer tidak digunakan (read_buf_len == 0) kedatangan sebuah karakter akan menyebabkan nRTS menjadi False sampai karakter tersebut dibaca.