Libraries
Class Port
The UART port exposes the hardware features for communicating with an external peripheral using asynchronous communication.
Class summary
| constructor --tx/any= --rx/any= --rts/any= --cts/any= --baud-rate/int --data-bits/int= --stop-bits/StopBits= --invert-tx/bool= --invert-rx/bool= --parity/int= --mode/int= --high-priority/bool= --large-buffers/bool= | Constructs a UART port using the given tx for transmission and rx for read. |
|---|---|
| constructor device/string --baud-rate/int --data-bits/int= --stop-bits/StopBits= --parity/int= | Constructs a UART port using a device path. |
Constructors
constructor --tx/any=null --rx/any=null --rts/any=null --cts/any=null --baud-rate/int --data-bits/int=8 --stop-bits/StopBits=STOP-BITS-1 --invert-tx/bool=false --invert-rx/bool=false --parity/int=PARITY-DISABLED --mode/int=MODE-UART --high-priority/bool=null --large-buffers/bool=null
Constructs a UART port using the given tx for transmission and rx for read.
The pins use the given baud-rate. The baud rate must match the baud rate of the device.
The rts and cts pins are optional flow-control pins. The host can signal on rts that whether it is ready to receive data. The peripheral can signal the host on cts whether it is ready to receive data.
The data-bits, parity, and stop-bits define the data framing of the UART messages.
The mode parameter must be one of:
- MODE-UART (default)
- Disables flow control, and cts must be null.
Some pins are preferred (more efficient) for use as UART pins on the ESP 32:
tx = 17, rx = 16 rts = 7 and cts = 8
(Note that pins 16 and 17 are used for PSRAM on some modules, so they cannot be used for UART0.)
Setting a high-priority increases the interrupt priority to level 3 on the ESP32. If you do not specify true or false for this argument, the high priority is automatically selected for baud rates of 460800 or above. (To avoid system hangs, the maximum priority on the ESP32C3 is limited to level 2.)
For regular priority, the buffer sizes are set to 256 bytes for tx, 768 for rx, and can be doubled with
--large-buffers.For high priority, the buffer sizes are set to 4096 bytes for tx, 4096 for rx, and can be halved with
--no-large-buffers.These are the software buffers, which are used by the interrupt to refill the hardware FIFO. The hardware FIFO is 128 bytes for tx and 128 bytes for rx.
The ESP32 has hardware support for up to two UART ports (the third one is normally already taken for the USB connection/debugging console.
The tx, rx, rts, and cts are GPIO numbers. The port reserves the pins and releases them again when the port is closed. At least one of tx and rx must be given.
constructor device/string --baud-rate/int --data-bits/int=8 --stop-bits/StopBits=STOP-BITS-1 --parity/int=PARITY-DISABLED
Constructs a UART port using a device path.
This constructor does not work on embedded devices, such as the ESP32.
On some platforms the baud-rate must match one that is supported by the operating system. See Port.baud-rate=.
Statics
Constructs a UART port for the console UART.
The console UART is the UART the system uses for logging and for the output of print. Opening it gives access to the data that is received on that UART, which the system otherwise discards. This makes it possible for a program to take input from the same serial connection that shows its output.
The port keeps the configuration (such as the baud rate) that the console was set up with during boot. System output is unaffected by opening the port: it continues to be written directly to the console. Data written to this port may thus interleave with system output.
Changing this port's baud rate also changes the baud rate used for system output.
Use large-buffers to increase the receive buffer from 768 bytes to 4096 bytes.
Only one console port can be open at a time.
Only supported on ESP32 variants, and only if the console is on a UART (the default). Throws "UNSUPPORTED" otherwise.
IRDA UART mode.
Uses the RTS pin to reserve the RS485 line when sending.
Normal UART mode.
Methods
Sets the baud rate to the given new-rate.
The receiver should be ready to read and write data at the specified baud rate.
Some platforms only support a fixed set of baud rates. For example, on Linux only the following baud rates are supported: 50, 75, 110, 134, 150, 200, 300, 600, 1200, 1800, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400, 460800, 576000, 921600, 1152000, 1500000, 2000000, 2500000, 3000000, 3500000, 4000000.
On macOS the baud rate can be set to arbitrary values.
Closes this UART port and releases all associated resources.
Number of encountered errors.
Typically, this number is incremented if received data wasn't processed in time, and the UART hardware has lost data.
Whether this object is equal to the other.
Inheritance
Classes overwrite this operator to get an equality specific to their needs. Equality operators often compare the type and field contents. For example:
class Pin:
number/int
constructor .number:
operator == other:
if other is not Pin: return false
return number == other.number
A class doesn't have to follow the above format, but it must keep the operator in sync with any
hash-code method. That is, if a class has a hash-code member, then the equality and hash-code must agree. If two instances are equal (a == b), then their hash codes must also be equal (a.hash-code == b.hash-code).Reads data from the port.
This method blocks until data is available.
Returns null if closed.
Stringifies this object.
Inheritance
Objects that need a human-friendly string representation should overwrite this method. The default string is based on the internal class-ID.
Waits for a break signal to be received.
A break signal is a continuous low signal on the RX pin for a duration of at least one byte.
Not supported on all platforms.
Writes data to the Port.
If break-length is greater than 0, an additional break signal is added after the data is written. The duration of the break signal is bit-duration * break-length, where bit-duration is the duration it takes to write one bit at the current baud rate.
If not all bytes could be written without blocking, this will be indicated by the return value. In this case the break is not written even if requested. The easiest way to handle this by using the writer.Writer class. Alternatively, something like the following could be used.
for position := 0; position < data.byte-size; null:
position += my-uart.write (data.byte-slice position data.byte-size)
If wait is true, the method blocks until all bytes that were written have been emitted to the physical pins. This is equivalent to calling flush. Otherwise, returns as soon as the data is buffered.
Returns the number of bytes written.