classe UART – bus de comunicação série duplex#

A UART implementa o protocolo de comunicação série duplex UART/USART padrão. A nível físico é composto por 2 linhas: RX e TX. A unidade de comunicação é um carácter (não confundir com um carácter de string) que pode ter 8 ou 9 bits de largura.

Os objectos UART podem ser criados e inicializados da seguinte forma:

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

Os bits podem ser 7, 8 ou 9. O stop pode ser 1 ou 2. Com parity=None, apenas 8 e 9 bits são suportados. Com paridade activada, apenas 7 e 8 bits são suportados.

Um objecto UART comporta-se como um objecto stream e a leitura e escrita são feitas utilizando os métodos padrão de 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

Construtores#

Constrói um objecto UART com o id fornecido.

Métodos#

Inicializa o bus UART com os parâmetros fornecidos:

baudrate é a taxa de clock.
bits é o número de bits por carácter, 7, 8 ou 9.
parity é a paridade, None, 0 (par) ou 1 (ímpar).
stop é o número de bits de paragem, 1 ou 2.

Parâmetros adicionais apenas por palavra-chave que podem ser suportados por um port são:

tx especifica o pino TX a utilizar.
rx especifica o pino RX a utilizar.
rts especifica o pino RTS (saída) a utilizar para controlo de fluxo de recepção por hardware.
cts especifica o pino CTS (entrada) a utilizar para controlo de fluxo de transmissão por hardware.
txbuf especifica o comprimento em caracteres do buffer TX.
rxbuf especifica o comprimento em caracteres do buffer RX.
timeout especifica o tempo de espera pelo primeiro carácter (em ms).
timeout_char especifica o tempo de espera entre caracteres (em ms).
invert especifica quais as linhas a inverter.

0 não invertirá as linhas (o estado inactivo de ambas as linhas é lógico alto).
UART.INV_TX invertirá a linha TX (o estado inactivo da linha TX passa a lógico baixo).
UART.INV_RX invertirá a linha RX (o estado inactivo da linha RX passa a lógico baixo).
UART.INV_TX | UART.INV_RX invertirá ambas as linhas (estado inactivo em lógico baixo).
flow especifica os sinais de controlo de fluxo por hardware a utilizar. O valor é uma máscara de bits.

0 ignorará os sinais de controlo de fluxo por hardware.
UART.RTS activará o controlo de fluxo de recepção utilizando o pino de saída RTS para sinalizar se o FIFO de recepção tem espaço suficiente para aceitar mais dados.
UART.CTS activará o controlo de fluxo de transmissão pausando a transmissão quando o pino de entrada CTS sinalizar que o receptor está com pouco espaço no buffer.
UART.RTS | UART.CTS activará ambos, para controlo de fluxo por hardware completo.

Nota

É possível chamar init() várias vezes no mesmo objecto para reconfigurar a UART em tempo de execução. Isso permite utilizar um único periférico UART para servir diferentes dispositivos ligados a diferentes pinos GPIO. Apenas um dispositivo pode ser servido de cada vez nesse caso. Também não deve chamar deinit() pois impedirá a chamada de init() novamente.

deinit() → None#: Desliga o bus UART.

Nota
Não será possível chamar init() no objecto após deinit(). Nesse caso, é necessário criar uma nova instância.

any() → int#

Devolve um inteiro que conta o número de caracteres que podem ser lidos sem bloquear. Devolverá 0 se não houver caracteres disponíveis e um número positivo se houver caracteres. O método pode devolver 1 mesmo que haja mais de um carácter disponível para leitura.

Para consultas mais sofisticadas sobre caracteres disponíveis, utilize select.poll:

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

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

Lê caracteres. Se nbytes for especificado, lê no máximo esse número de bytes; caso contrário, lê o máximo de dados possível. Pode retornar mais cedo se for atingido um timeout. O timeout é configurável no construtor.

Valor de retorno: um objecto bytes contendo os bytes lidos. Devolve None em caso de timeout.

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

Lê bytes para o buf. Se nbytes for especificado, lê no máximo esse número de bytes. Caso contrário, lê no máximo len(buf) bytes. Pode retornar mais cedo se for atingido um timeout. O timeout é configurável no construtor.

Valor de retorno: número de bytes lidos e armazenados em buf ou None em caso de timeout.

readline() → bytes | None#

Lê uma linha, terminando num carácter de nova linha. Pode retornar mais cedo se for atingido um timeout. O timeout é configurável no construtor.

Valor de retorno: a linha lida ou None em caso de timeout.

write(buf: bytes) → int | None#

Escreve o buffer de bytes no bus.

Valor de retorno: número de bytes escritos ou None em caso de timeout.

sendbreak() → None#: Envia uma condição de break no bus – mantém TX em baixo durante mais tempo do que um carácter. Disponível em STM32 e mimxrt; não exposto em alif.

readchar() → int#: Lê um único carácter da UART e devolve-o como um inteiro (ou -1 em caso de timeout). Menor overhead do que read(1) pois não é alocado nenhum objecto bytes. Apenas STM32.

writechar(char: int) → None#: Escreve o único carácter char (um inteiro no intervalo 0 – 255) na UART. Menor overhead do que write() para envios de byte único. Apenas STM32.

flush() → None#: Bloqueia até que todos os bytes actualmente no buffer de transmissão tenham sido enviados em TX. Lança OSError em caso de timeout; o timeout é derivado do tamanho do buffer TX e da taxa de baud configurada, pelo que, salvo se o controlo de fluxo estiver activado e o receptor estiver parado, a chamada retorna muito antes do timeout.

txdone() → bool#: Devolve True quando não há transmissão em curso (o buffer TX está vazio e o registo de deslocamento foi drenado), False caso contrário. Útil como alternativa não bloqueante a flush().

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

Instala um callback para disparar em eventos UART.

handler é a função a invocar. Recebe a instância UART como único argumento. Passe None para remover um handler previamente instalado.

trigger é uma máscara de bits de uma ou mais constantes IRQ_* (ver Constantes abaixo) que seleccionam quais os eventos que disparam o callback.

hard=True regista um handler de interrupção rígida (menor latência, mas o handler não deve alocar memória). O padrão é um callback agendado.

Devolve um objecto irq.

Nem todas as fontes IRQ estão disponíveis em todos os ports – consulte as constantes IRQ_* individuais para disponibilidade por port.

Constantes#

RTS: int#: Passar a flow para activar o controlo de fluxo por hardware RTS no lado de recepção. Combinar com CTS via OR para activar ambos.

CTS: int#: Passar a flow para activar o controlo de fluxo por hardware CTS no lado de transmissão.

IRQ_RXIDLE: int#: Flag de disparo de irq(): dispara uma vez após um ou mais caracteres terem sido recebidos e a linha RX ficar inactiva. Disponível em todos os ports OpenMV.

IRQ_RX: int#: Flag de disparo de irq(): dispara após cada carácter recebido. Disponível em STM32 e alif.

IRQ_TXIDLE: int#: Flag de disparo de irq(): dispara quando o último carácter de uma transmissão é enviado. Disponível em mimxrt e alif.

IRQ_BREAK: int#: Flag de disparo de irq(): dispara quando uma condição de break é detectada em RX. Não disponível em nenhum port OpenMV.