class UART – bus di comunicazione seriale duplex¶

UART implementa il protocollo standard di comunicazione seriale duplex UART/USART. A livello fisico è composto da 2 linee: RX e TX. L’unità di comunicazione è un carattere (da non confondere con un carattere di una stringa) che può essere largo 8 o 9 bit.

Gli oggetti UART possono essere creati e inizializzati usando:

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)

I bit possono essere 7, 8 o 9. La parità può essere None, 0 (pari) o 1 (dispari). Stop può essere 1 o 2.

Nota: con parity=None, sono supportati solo 8 e 9 bit. Con la parità abilitata, sono supportati solo 7 e 8 bit.

Un oggetto UART si comporta come un oggetto stream e la lettura e la scrittura vengono eseguite usando i metodi standard degli 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

I singoli caratteri possono essere letti/scritti usando:

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

Per verificare se c’è qualcosa da leggere, usa:

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

Nota: le funzioni di stream read, write, ecc. sono nuove in MicroPython v1.3.4. Le versioni precedenti usano uart.send e uart.recv.

Costruttori¶

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

Costruisce un oggetto UART sul bus specificato (un indice intero della periferica, ad es. 3 per UART3). Senza parametri aggiuntivi l’oggetto viene creato ma non inizializzato (mantiene le impostazioni precedenti del bus, se presenti); se vengono forniti argomenti extra il bus viene inizializzato. Vedi init() per i parametri disponibili.

UART(3) è cablato agli stessi pin dell’header su ogni OpenMV Cam STM32:

Segnale	Pin dell’header
`TX`	`P4`
`RX`	`P5`

Su alcune schede sono disponibili bus UART aggiuntivi:

Bus	Pin TX	Pin RX	Disponibile su
`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

Metodi¶

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¶

Inizializza il bus UART con i parametri specificati:

baudrate è la frequenza di clock.

bits è il numero di bit per carattere, 7, 8 o 9.

parity è la parità, None, 0 (pari) o 1 (dispari).

stop è il numero di bit di stop, 1 o 2.

flow imposta il tipo di controllo di flusso. Può essere 0, UART.RTS, UART.CTS o UART.RTS | UART.CTS.

timeout è il timeout in millisecondi per attendere la scrittura/lettura del primo carattere.

timeout_char è il timeout in millisecondi per attendere tra i caratteri durante la scrittura o la lettura.

read_buf_len è la lunghezza in caratteri del buffer di lettura (0 per disabilitarlo).

Questo metodo solleverà un’eccezione se il baudrate non può essere impostato entro il 5% del valore desiderato.

Nota: con parity=None, sono supportati solo 8 e 9 bit. Con la parità abilitata, sono supportati solo 7 e 8 bit.

deinit() → None¶: Spegne il bus UART.

any() → int¶: Restituisce il numero di byte in attesa (può essere 0).

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

Legge dei caratteri. Se nbytes è specificato, legge al massimo quel numero di byte. Se nbytes sono disponibili nel buffer, restituisce immediatamente, altrimenti restituisce quando arrivano caratteri sufficienti o scade il timeout.

Se nbytes non è fornito, il metodo legge la maggior quantità di dati possibile. Restituisce dopo che è scaduto il timeout.

Nota: per i caratteri a 9 bit ogni carattere occupa due byte, nbytes deve essere pari e il numero di caratteri è nbytes/2.

Valore restituito: un oggetto bytes contenente i byte letti. Restituisce None al timeout.

readchar() → int¶

Riceve un singolo carattere sul bus.

Valore restituito: il carattere letto, come intero. Restituisce -1 al timeout.

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

Legge dei byte nel buf. Se nbytes è specificato, legge al massimo quel numero di byte. Altrimenti, legge al massimo len(buf) byte.

Valore restituito: numero di byte letti e memorizzati in buf oppure None al timeout.

readline() → bytes | None¶

Legge una riga, terminante con un carattere di nuova linea. Se tale riga esiste, il ritorno è immediato. Se il timeout scade, vengono restituiti tutti i dati disponibili indipendentemente dalla presenza di un carattere di nuova linea.

Valore restituito: la riga letta oppure None al timeout se non sono disponibili dati.

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

Scrive il buffer di byte sul bus. Se i caratteri sono larghi 7 o 8 bit, ogni byte è un carattere. Se i caratteri sono larghi 9 bit, vengono usati due byte per ogni carattere (little endian) e buf deve contenere un numero pari di byte.

Valore restituito: numero di byte scritti. Se si verifica un timeout e nessun byte è stato scritto, restituisce None.

writechar(char: int) → None¶: Scrive un singolo carattere sul bus. char è un intero da scrivere. Vedi la sezione Controllo di flusso CTS più avanti per la semantica di blocco quando il controllo di flusso CTS è abilitato.

sendbreak() → None¶: Invia una condizione di break sul bus. Questo porta il bus a livello basso per una durata di 13 bit.

Costanti¶

RTS: int¶: Flag di bit per l’argomento flow di init(); abilita il controllo di flusso hardware RTS (request-to-send) sul percorso di ricezione.

CTS: int¶: Flag di bit per l’argomento flow di init(); abilita il controllo di flusso hardware CTS (clear-to-send) sul percorso di trasmissione. Può essere combinato in OR con RTS per abilitare entrambe le direzioni.

Controllo di flusso¶

UART(3) supporta il controllo di flusso hardware RTS/CTS. Su OpenMV Cam M7, H7, H7 Plus e Pure Thermal i pin di controllo di flusso sono:

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

Su OpenMV Cam N6 è esposto solo nRTS (sul pin dell’header P7); nCTS non è instradato all’header di I/O.

Nei paragrafi seguenti il termine «target» si riferisce al dispositivo connesso all’UART.

Quando il metodo init() dell’UART viene chiamato con flow impostato su uno o entrambi i valori UART.RTS e UART.CTS, i relativi pin di controllo di flusso vengono configurati. nRTS è un’uscita attiva-bassa e nCTS è un ingresso attivo-basso con pull-up abilitato. Per cablare il controllo di flusso, collega il nCTS dell’OpenMV Cam al nRTS del target e il nRTS dell’OpenMV Cam al nCTS del target.

CTS: il target controlla il trasmettitore dell’OpenMV Cam¶

Se il controllo di flusso CTS è abilitato, il comportamento in scrittura è il seguente:

Se viene chiamato il metodo UART.write(buf) dell’OpenMV Cam, la trasmissione si bloccherà durante i periodi in cui nCTS è False. Questo risulterà in un timeout se l’intero buffer non è stato trasmesso entro il periodo di timeout. Il metodo restituisce il numero di byte scritti, permettendo all’utente di scrivere il resto dei dati se necessario. In caso di timeout, un carattere rimarrà nell’UART in attesa di nCTS. Il numero di byte che compongono questo carattere sarà incluso nel valore restituito.

Se UART.writechar() viene chiamato quando nCTS è False il metodo andrà in timeout a meno che il target non asserisca nCTS in tempo. Se va in timeout verrà sollevato OSError 116. Il carattere verrà trasmesso non appena il target asserisce nCTS.

RTS: l’OpenMV Cam controlla il trasmettitore del target¶

Se il controllo di flusso RTS è abilitato, il comportamento è il seguente:

Se viene usato l’input bufferizzato (read_buf_len > 0), i caratteri in arrivo vengono bufferizzati. Se il buffer si riempie, il carattere successivo in arrivo farà passare nRTS a False: il target dovrebbe cessare la trasmissione. nRTS passerà a True quando i caratteri vengono letti dal buffer.

Nota che il metodo any() restituisce il numero di byte nel buffer. Si supponga una lunghezza del buffer di N byte. Se il buffer si riempie e arriva un altro carattere, nRTS verrà impostato su False e any() restituirà il conteggio N. Quando i caratteri vengono letti, il carattere aggiuntivo verrà inserito nel buffer e sarà incluso nel risultato di una successiva chiamata ad any().

Se l’input bufferizzato non viene usato (read_buf_len == 0), l’arrivo di un carattere farà passare nRTS a False finché il carattere non viene letto.