classe UART – bus di comunicazione seriale duplex¶

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

Gli oggetti UART possono essere creati e inizializzati usando:

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

I bit possono essere 7, 8 o 9. Lo stop può essere 1 o 2. 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

Costruttori¶

Costruisce un oggetto UART con l’id specificato.

Metodi¶

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.

Parametri aggiuntivi solo a parole chiave che possono essere supportati da una porta sono:

tx specifica il pin TX da usare.

rx specifica il pin RX da usare.

rts specifica il pin RTS (output) da usare per il controllo di flusso hardware in ricezione.

cts specifica il pin CTS (input) da usare per il controllo di flusso hardware in trasmissione.

txbuf specifica la lunghezza in caratteri del buffer TX.

rxbuf specifica la lunghezza in caratteri del buffer RX.

timeout specifica il tempo di attesa per il primo carattere (in ms).

timeout_char specifica il tempo di attesa tra i caratteri (in ms).

invert specifica quali linee invertire.

0 non invertirà le linee (lo stato di riposo di entrambe le linee è il livello logico alto).

UART.INV_TX invertirà la linea TX (lo stato di riposo della linea TX è ora il livello logico basso).

UART.INV_RX invertirà la linea RX (lo stato di riposo della linea RX è ora il livello logico basso).

UART.INV_TX | UART.INV_RX invertirà entrambe le linee (stato di riposo al livello logico basso).

flow specifica quali segnali di controllo di flusso hardware usare. Il valore è una maschera di bit.

0 ignorerà i segnali di controllo di flusso hardware.

UART.RTS abiliterà il controllo di flusso in ricezione usando il pin di output RTS per segnalare se il FIFO di ricezione ha spazio sufficiente per accettare altri dati.

UART.CTS abiliterà il controllo di flusso in trasmissione mettendo in pausa la trasmissione quando il pin di input CTS segnala che il ricevitore sta esaurendo lo spazio di buffer.

UART.RTS | UART.CTS abiliterà entrambi, per un controllo di flusso hardware completo.

Nota

È possibile chiamare init() più volte sullo stesso oggetto per riconfigurare la UART al volo. Questo consente di usare una singola periferica UART per servire dispositivi diversi collegati a pin GPIO diversi. In tal caso può essere servito un solo dispositivo alla volta. Inoltre non chiamare deinit() poiché impedirebbe di chiamare di nuovo init().

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

Nota

Non sarà possibile chiamare init() sull’oggetto dopo deinit(). In tal caso è necessario creare una nuova istanza.

any() → int¶

Restituisce un intero che conta il numero di caratteri leggibili senza bloccarsi. Restituirà 0 se non ci sono caratteri disponibili e un numero positivo se ci sono caratteri. Il metodo può restituire 1 anche se è disponibile più di un carattere per la lettura.

Per un’interrogazione più sofisticata dei caratteri disponibili usare select.poll:

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

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

Legge caratteri. Se nbytes è specificato legge al massimo quel numero di byte, altrimenti legge quanti più dati possibile. Può ritornare prima se viene raggiunto un timeout. Il timeout è configurabile nel costruttore.

Valore di ritorno: un oggetto bytes contenente i byte letti. Restituisce None in caso di timeout.

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

Legge byte nel buf. Se nbytes è specificato legge al massimo quel numero di byte. Altrimenti, legge al massimo len(buf) byte. Può ritornare prima se viene raggiunto un timeout. Il timeout è configurabile nel costruttore.

Valore di ritorno: numero di byte letti e memorizzati in buf oppure None in caso di timeout.

readline() → bytes | None¶

Legge una riga, terminante con un carattere di newline. Può ritornare prima se viene raggiunto un timeout. Il timeout è configurabile nel costruttore.

Valore di ritorno: la riga letta oppure None in caso di timeout.

write(buf: bytes) → int | None¶

Scrive il buffer di byte sul bus.

Valore di ritorno: numero di byte scritti oppure None in caso di timeout.

sendbreak() → None¶: Invia una condizione di break sul bus – mantiene TX basso per più del tempo di un carattere. Disponibile su STM32 e mimxrt; non esposto su alif.

readchar() → int¶: Legge un singolo carattere dalla UART e lo restituisce come intero (oppure -1 in caso di timeout). Overhead inferiore rispetto a read(1) poiché non viene allocato alcun oggetto bytes. Solo STM32.

writechar(char: int) → None¶: Scrive il singolo carattere char (un intero nell’intervallo 0 – 255) sulla UART. Overhead inferiore rispetto a write() per invii di un singolo byte. Solo STM32.

flush() → None¶: Si blocca finché ogni byte attualmente presente nel buffer di trasmissione non è stato inviato su TX. Solleva OSError in caso di timeout; il timeout è derivato dalla dimensione del buffer TX e dal baudrate configurato, quindi a meno che il controllo di flusso non sia abilitato e il ricevitore non si blocchi, la chiamata ritorna ben prima del timeout.

txdone() → bool¶: Restituisce True quando non è in corso alcuna trasmissione (il buffer TX è vuoto e il registro di shift è stato svuotato), False altrimenti. Utile come alternativa non bloccante a flush().

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

Installa una callback da attivare sugli eventi UART.

handler è la funzione da invocare. Riceve l’istanza UART come unico argomento. Passare None per rimuovere un handler installato in precedenza.

trigger è una maschera di bit di una o più costanti IRQ_* (vedere Costanti più sotto) che seleziona quali eventi attivano la callback.

hard=True registra un handler di interrupt hardware (latenza inferiore, ma l’handler non deve allocare). Il valore predefinito è una callback pianificata.

Restituisce un oggetto irq.

Non tutte le sorgenti IRQ sono disponibili su tutte le porte – vedere le singole costanti IRQ_* per la disponibilità per porta.

Costanti¶

RTS: int¶: Da passare a flow per abilitare il controllo di flusso hardware RTS sul lato di ricezione. Combinare con CTS tramite OR per abilitare entrambi.

CTS: int¶: Da passare a flow per abilitare il controllo di flusso hardware CTS sul lato di trasmissione.

IRQ_RXIDLE: int¶: Flag di trigger di irq(): si attiva una volta dopo che uno o più caratteri sono stati ricevuti e la linea RX passa quindi allo stato di riposo. Disponibile su tutte le porte OpenMV.

IRQ_RX: int¶: Flag di trigger di irq(): si attiva dopo ogni carattere ricevuto. Disponibile su STM32 e alif.

IRQ_TXIDLE: int¶: Flag di trigger di irq(): si attiva quando l’ultimo carattere di una trasmissione è stato inviato. Disponibile su mimxrt e alif.

IRQ_BREAK: int¶: Flag di trigger di irq(): si attiva quando viene rilevata una condizione di break su RX. Non disponibile su nessuna porta OpenMV.