clase UART – bus de comunicación serie dúplex¶

UART implementa el protocolo estándar de comunicaciones serie dúplex UART/USART. A nivel físico consta de 2 líneas: RX y TX. La unidad de comunicación es un carácter (que no debe confundirse con un carácter de cadena) que puede tener 8 o 9 bits de ancho.

Los objetos UART se pueden crear e inicializar 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

Bits puede ser 7, 8 o 9. Stop puede ser 1 o 2. Con parity=None, solo se admiten 8 y 9 bits. Con la paridad habilitada, solo se admiten 7 y 8 bits.

Un objeto UART actúa como un objeto stream y la lectura y escritura se realizan mediante los métodos estándar 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

Constructores¶

Construye un objeto UART con el id indicado.

Métodos¶

Inicializa el bus UART con los parámetros indicados:

baudrate es la velocidad de reloj.

bits es el número de bits por carácter, 7, 8 o 9.

parity es la paridad, None, 0 (par) o 1 (impar).

stop es el número de bits de parada, 1 o 2.

Parámetros adicionales solo por palabra clave que pueden estar admitidos por un puerto son:

tx especifica el pin TX a utilizar.

rx especifica el pin RX a utilizar.

rts especifica el pin RTS (salida) a utilizar para el control de flujo de recepción por hardware.

cts especifica el pin CTS (entrada) a utilizar para el control de flujo de transmisión por hardware.

txbuf especifica la longitud en caracteres del búfer de TX.

rxbuf especifica la longitud en caracteres del búfer de RX.

timeout especifica el tiempo de espera del primer carácter (en ms).

timeout_char especifica el tiempo de espera entre caracteres (en ms).

invert especifica qué líneas se deben invertir.

0 no invertirá ninguna línea (el estado de reposo de ambas líneas es nivel lógico alto).

UART.INV_TX invertirá la línea TX (el estado de reposo de la línea TX pasa a ser nivel lógico bajo).

UART.INV_RX invertirá la línea RX (el estado de reposo de la línea RX pasa a ser nivel lógico bajo).

UART.INV_TX | UART.INV_RX invertirá ambas líneas (estado de reposo en nivel lógico bajo).

flow especifica qué señales de control de flujo por hardware utilizar. El valor es una máscara de bits.

0 ignorará las señales de control de flujo por hardware.

UART.RTS habilitará el control de flujo de recepción usando el pin de salida RTS para indicar si la FIFO de recepción tiene espacio suficiente para aceptar más datos.

UART.CTS habilitará el control de flujo de transmisión pausando la transmisión cuando el pin de entrada CTS indique que al receptor le queda poco espacio en el búfer.

UART.RTS | UART.CTS habilitará ambos, para un control de flujo por hardware completo.

Nota

Es posible llamar a init() varias veces sobre el mismo objeto para reconfigurar la UART sobre la marcha. Esto permite usar un único periférico UART para atender distintos dispositivos conectados a diferentes pines GPIO. En ese caso, solo se puede atender un dispositivo a la vez. Tampoco llames a deinit(), ya que impedirá volver a llamar a init().

deinit() → None¶: Apaga el bus UART.

Nota

No podrás llamar a init() sobre el objeto después de deinit(). En ese caso es necesario crear una nueva instancia.

any() → int¶

Devuelve un entero que cuenta el número de caracteres que se pueden leer sin bloqueo. Devolverá 0 si no hay caracteres disponibles y un número positivo si los hay. El método puede devolver 1 incluso si hay más de un carácter disponible para leer.

Para una consulta más sofisticada de los caracteres disponibles, usa select.poll:

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

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

Lee caracteres. Si se especifica nbytes, lee como máximo esa cantidad de bytes; de lo contrario, lee tantos datos como sea posible. Puede regresar antes si se alcanza un tiempo de espera. El tiempo de espera es configurable en el constructor.

Valor de retorno: un objeto bytes que contiene los bytes leídos. Devuelve None si se agota el tiempo de espera.

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

Lee bytes en buf. Si se especifica nbytes, lee como máximo esa cantidad de bytes. De lo contrario, lee como máximo len(buf) bytes. Puede regresar antes si se alcanza un tiempo de espera. El tiempo de espera es configurable en el constructor.

Valor de retorno: número de bytes leídos y almacenados en buf, o None si se agota el tiempo de espera.

readline() → bytes | None¶

Lee una línea, terminada en un carácter de nueva línea. Puede regresar antes si se alcanza un tiempo de espera. El tiempo de espera es configurable en el constructor.

Valor de retorno: la línea leída o None si se agota el tiempo de espera.

write(buf: bytes) → int | None¶

Escribe el búfer de bytes en el bus.

Valor de retorno: número de bytes escritos o None si se agota el tiempo de espera.

sendbreak() → None¶: Envía una condición de break en el bus – pone TX a nivel bajo durante más tiempo que el de un carácter. Disponible en STM32 y mimxrt; no expuesto en alif.

readchar() → int¶: Lee un único carácter de la UART y lo devuelve como un entero (o -1 si se agota el tiempo de espera). Menor sobrecarga que read(1) ya que no se asigna ningún objeto bytes. Solo STM32.

writechar(char: int) → None¶: Escribe el único carácter char (un entero en el rango 0 – 255) en la UART. Menor sobrecarga que write() para envíos de un solo byte. Solo STM32.

flush() → None¶: Se bloquea hasta que cada byte que hay actualmente en el búfer de transmisión haya salido por TX. Lanza OSError si se agota el tiempo de espera; el tiempo de espera se deriva del tamaño del búfer de TX y de la velocidad en baudios configurada, por lo que, a menos que el control de flujo esté habilitado y el receptor se detenga, la llamada regresa bastante antes del tiempo de espera.

txdone() → bool¶: Devuelve True cuando no hay ninguna transmisión en curso (el búfer de TX está vacío y el registro de desplazamiento se ha vaciado), y False en caso contrario. Útil como alternativa no bloqueante a flush().

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

Instala una función de retorno (callback) para que se active en eventos de la UART.

handler es la función a invocar. Recibe la instancia de UART como su único argumento. Pasa None para eliminar un manejador instalado previamente.

trigger es una máscara de bits de una o más constantes IRQ_* (ver Constantes más abajo) que selecciona qué eventos activan la función de retorno (callback).

hard=True registra un manejador de interrupción dura (menor latencia, pero el manejador no debe asignar memoria). El valor predeterminado es una función de retorno (callback) programada.

Devuelve un objeto irq.

No todas las fuentes de IRQ están disponibles en todos los puertos – consulta las constantes IRQ_* individuales para conocer la disponibilidad por puerto.

Constantes¶

RTS: int¶: Pásalo a flow para habilitar el control de flujo por hardware RTS en el lado de recepción. Combínalo con CTS mediante OR para habilitar ambos.

CTS: int¶: Pásalo a flow para habilitar el control de flujo por hardware CTS en el lado de transmisión.

IRQ_RXIDLE: int¶: Indicador de activación de irq(): se activa una vez después de que se hayan recibido uno o más caracteres y la línea RX pase entonces a reposo. Disponible en todos los puertos de OpenMV.

IRQ_RX: int¶: Indicador de activación de irq(): se activa tras cada carácter recibido. Disponible en STM32 y alif.

IRQ_TXIDLE: int¶: Indicador de activación de irq(): se activa cuando el último carácter de una transmisión ha salido. Disponible en mimxrt y alif.

IRQ_BREAK: int¶: Indicador de activación de irq(): se activa cuando se detecta una condición de break en RX. No disponible en ningún puerto de OpenMV.