klasa UART – magistrala szeregowej komunikacji dwukierunkowej¶

UART implementuje standardowy protokół szeregowej komunikacji dwukierunkowej UART/USART. Na poziomie fizycznym składa się z 2 linii: RX i TX. Jednostką komunikacji jest znak (nie mylić ze znakiem łańcucha tekstowego), który może mieć szerokość 8 lub 9 bitów.

Obiekty UART można tworzyć i inicjalizować w następujący sposób:

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

Liczba bitów może wynosić 7, 8 lub 9. Liczba bitów stopu może wynosić 1 lub 2. Przy parity=None obsługiwane są tylko 8 i 9 bitów. Przy włączonej kontroli parzystości obsługiwane są tylko 7 i 8 bitów.

Obiekt UART zachowuje się jak obiekt stream, a odczyt i zapis odbywają się przy użyciu standardowych metod strumienia:

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

Konstruktory¶

Tworzy obiekt UART o podanym id.

Metody¶

Inicjalizuje magistralę UART z podanymi parametrami:

baudrate to szybkość zegara.

bits to liczba bitów na znak: 7, 8 lub 9.

parity to parzystość, None, 0 (parzysta) lub 1 (nieparzysta).

stop to liczba bitów stopu, 1 lub 2.

Dodatkowe parametry przekazywane wyłącznie jako słowa kluczowe, które mogą być obsługiwane przez dany port, to:

tx określa pin TX, który ma zostać użyty.

rx określa pin RX, który ma zostać użyty.

rts określa pin RTS (wyjściowy), który ma zostać użyty do sprzętowej kontroli przepływu odbioru.

cts określa pin CTS (wejściowy), który ma zostać użyty do sprzętowej kontroli przepływu transmisji.

txbuf określa długość bufora TX wyrażoną w znakach.

rxbuf określa długość bufora RX wyrażoną w znakach.

timeout określa czas oczekiwania na pierwszy znak (w ms).

timeout_char określa czas oczekiwania między znakami (w ms).

invert określa, które linie należy odwrócić.

0 nie odwraca linii (stanem spoczynkowym obu linii jest poziom wysoki).

UART.INV_TX odwróci linię TX (stanem spoczynkowym linii TX będzie teraz poziom niski).

UART.INV_RX odwróci linię RX (stanem spoczynkowym linii RX będzie teraz poziom niski).

UART.INV_TX | UART.INV_RX odwróci obie linie (stan spoczynkowy na poziomie niskim).

flow określa, które sprzętowe sygnały kontroli przepływu mają być używane. Wartość jest maską bitową.

0 zignoruje sprzętowe sygnały kontroli przepływu.

UART.RTS włączy kontrolę przepływu odbioru, używając pinu wyjściowego RTS do sygnalizowania, czy odbiorczy bufor FIFO ma wystarczająco dużo miejsca, aby przyjąć więcej danych.

UART.CTS włączy kontrolę przepływu transmisji, wstrzymując transmisję, gdy pin wejściowy CTS sygnalizuje, że odbiornikowi zaczyna brakować miejsca w buforze.

UART.RTS | UART.CTS włączy oba mechanizmy, zapewniając pełną sprzętową kontrolę przepływu.

Informacja

Możliwe jest wielokrotne wywołanie init() na tym samym obiekcie w celu rekonfiguracji UART w locie. Pozwala to wykorzystać pojedyncze urządzenie peryferyjne UART do obsługi różnych urządzeń podłączonych do różnych pinów GPIO. W takim przypadku jednocześnie można obsługiwać tylko jedno urządzenie. Nie należy także wywoływać deinit(), ponieważ uniemożliwi to ponowne wywołanie init().

deinit() → None¶: Wyłącza magistralę UART.

Informacja

Po wywołaniu deinit() nie będzie można wywołać init() na tym obiekcie. W takim przypadku należy utworzyć nową instancję.

any() → int¶

Zwraca liczbę całkowitą określającą liczbę znaków, które można odczytać bez blokowania. Zwraca 0, jeśli nie ma dostępnych znaków, oraz liczbę dodatnią, jeśli znaki są dostępne. Metoda może zwrócić 1, nawet jeśli do odczytu dostępny jest więcej niż jeden znak.

Aby uzyskać bardziej zaawansowane sprawdzanie dostępnych znaków, użyj select.poll:

poll = select.poll()
poll.register(uart, select.POLLIN)
poll.poll(timeout)

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

Odczytuje znaki. Jeśli podano nbytes, odczytuje co najwyżej tyle bajtów, w przeciwnym razie odczytuje tyle danych, ile to możliwe. Może zwrócić wartość wcześniej, jeśli zostanie osiągnięty limit czasu. Limit czasu można skonfigurować w konstruktorze.

Wartość zwracana: obiekt bytes zawierający odczytane bajty. Zwraca None w przypadku przekroczenia limitu czasu.

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

Odczytuje bajty do buf. Jeśli podano nbytes, odczytuje co najwyżej tyle bajtów. W przeciwnym razie odczytuje co najwyżej len(buf) bajtów. Może zwrócić wartość wcześniej, jeśli zostanie osiągnięty limit czasu. Limit czasu można skonfigurować w konstruktorze.

Wartość zwracana: liczba bajtów odczytanych i zapisanych do buf lub None w przypadku przekroczenia limitu czasu.

readline() → bytes | None¶

Odczytuje linię zakończoną znakiem nowej linii. Może zwrócić wartość wcześniej, jeśli zostanie osiągnięty limit czasu. Limit czasu można skonfigurować w konstruktorze.

Wartość zwracana: odczytana linia lub None w przypadku przekroczenia limitu czasu.

write(buf: bytes) → int | None¶

Zapisuje bufor bajtów na magistralę.

Wartość zwracana: liczba zapisanych bajtów lub None w przypadku przekroczenia limitu czasu.

sendbreak() → None¶: Wysyła na magistralę warunek break – ustawia linię TX na poziom niski na czas dłuższy niż czas trwania jednego znaku. Dostępne na STM32 i mimxrt; nieudostępnione na alif.

readchar() → int¶: Odczytuje pojedynczy znak z UART i zwraca go jako liczbę całkowitą (lub -1 w przypadku przekroczenia limitu czasu). Mniejszy narzut niż read(1), ponieważ nie jest alokowany obiekt bytes. Tylko STM32.

writechar(char: int) → None¶: Zapisuje pojedynczy znak char (liczbę całkowitą z zakresu 0 – 255) do UART. Mniejszy narzut niż write() przy wysyłaniu pojedynczych bajtów. Tylko STM32.

flush() → None¶: Blokuje wykonanie do momentu, aż każdy bajt znajdujący się obecnie w buforze nadawczym zostanie wytaktowany na linię TX. Zgłasza OSError w przypadku przekroczenia limitu czasu; limit ten jest wyliczany na podstawie rozmiaru bufora TX oraz skonfigurowanej szybkości transmisji (baud), więc o ile nie jest włączona kontrola przepływu i odbiornik się nie zatnie, wywołanie zwraca wartość na długo przed upływem limitu czasu.

txdone() → bool¶: Zwraca True, gdy nie jest realizowana żadna transmisja (bufor TX jest pusty, a rejestr przesuwny został opróżniony), oraz False w przeciwnym razie. Przydatne jako nieblokująca alternatywa dla flush().

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

Instaluje wywołanie zwrotne uruchamiane przy zdarzeniach UART.

handler to funkcja, która ma zostać wywołana. Otrzymuje instancję UART jako jedyny argument. Przekaż None, aby usunąć wcześniej zainstalowany handler.

trigger to maska bitowa jednej lub więcej stałych IRQ_* (zobacz Stałe poniżej), wybierająca, które zdarzenia uruchamiają wywołanie zwrotne.

hard=True rejestruje handler sprzętowego przerwania (mniejsze opóźnienie, ale handler nie może alokować pamięci). Domyślnie używane jest zaplanowane wywołanie zwrotne.

Zwraca obiekt irq.

Nie każde źródło IRQ jest dostępne na każdym porcie – zobacz poszczególne stałe IRQ_*, aby poznać dostępność dla danego portu.

Stałe¶

RTS: int¶: Przekaż do flow, aby włączyć sprzętową kontrolę przepływu RTS po stronie odbioru. Połącz z CTS operatorem OR, aby włączyć oba mechanizmy.

CTS: int¶: Przekaż do flow, aby włączyć sprzętową kontrolę przepływu CTS po stronie transmisji.

IRQ_RXIDLE: int¶: Flaga wyzwalania irq(): uruchamiana raz po odebraniu jednego lub więcej znaków, gdy linia RX przejdzie następnie w stan spoczynku. Dostępna na wszystkich portach OpenMV.

IRQ_RX: int¶: Flaga wyzwalania irq(): uruchamiana po każdym odebranym znaku. Dostępna na STM32 i alif.

IRQ_TXIDLE: int¶: Flaga wyzwalania irq(): uruchamiana, gdy ostatni znak transmisji zostanie wytaktowany. Dostępna na mimxrt i alif.

IRQ_BREAK: int¶: Flaga wyzwalania irq(): uruchamiana, gdy na linii RX zostanie wykryty warunek break. Niedostępna na żadnym porcie OpenMV.