Skip to main content

uart.configure(baudRate, wordSize, parity, stopBits, flags, callback)

Configures the UART serial bus

Availability

Device

Returns

Integer — the actual connection speed in bits per second

Parameters

Name Type Description
baudRate Integer Baud rate (bits per second)
wordSize Integer Word size in bits (7 or 8)
parity Integer Parity (PARITY_NONE, PARITY_EVEN or PARITY_ODD)
stopBits integer Stop bits (1 or 2)
flags Integer (bitfield) Control flags
callback Function Optional callback function for UART events. See ‘Callback Function’, below, for this function’s optional parameters (none by default)

Description

This method configures the UART data format and rate, and enables the port. If a callback function is nominated — this is optional — it will be called whenever UART events occur (see ‘Callback Function’ below).

The range of available baud rates depend on which UART is in use on what imp:

imp UART Minimum baud rate Maximum baud rate
imp001/002 uart1289 or uart6E
All other UARTs
916
7,500,000 (7.5Mbaud)
3,750,000 (3.75Mbaud)
imp003 All UARTs 550 4,500,000 (4.5Mbaud)
imp004m uartBCAW
uartFGJH
uartHJ
uartQ
366
732
732
366
3,000,000 (3Mbaud)
6,000,000 (6Mbaud)
6,000,000 (6Mbaud)
3,000,000 (3Mbaud)
imp005 uart1
uart0, uart2
35
9160
2,337,500 (2.34Mbaud)
4,000,000 (4Mbaud)
impC001 All UARTs 1526 12,500,000 (12.5Mbaud)

Not all baud rates can be achieved precisely; the uart.configure() call will round the requested rate to the nearest available value, and return the actual baud rate selected as an integer. All the common rates are either exact or very close to exact. Note hardware constraints might limit the usability of really fast rates.

As serial ports typically resynchronize after each character, they can lock to rates that are several percentage points away from the nominal rate.

The UARTs provided by the impC001 initially have a minimum speed of 1526 baud and a theoretical maximum of 12.5 Mbaud, though it is likely that you will encounter signal integrity problems at this level of speed.

Parity Constants

One of the following constants should be used as the third parameter of the call:

Constant Value Description Notes
PARITY_NONE 0 No parity bit Not supported with a 7-bit word size
PARITY_EVEN 1 Even parity bit
PARITY_ODD 2 Odd parity bit

The values assigned to the constants may change in a future impOS™ release.

Control Flag Constants

The following flags can be used for the fifth parameter of the call:

Constant Value Description Notes
NO_TX 1 Disable transmitter Implicit on uartB (imp002)
NO_RX 2 Disable receiver
NO_CTSRTS 4 Disable flow control Implicit except on uart1289 (imp001/imp002), uartQRPW and uartUVGD (imp003), uartFGJH (imp004m) and uart0 (imp005)
CALLBACK_WITH_FLAGS 8 Enable extended callback From impOS release 30 onwards
TIMING_ENABLED 16 Enable timing From impOS release 34 onwards

The values assigned to the constants may change in a future impOS release.

Only uart1289 on imp001/imp002 has control signals (CTS and RTS); all other imp001/imp002 UARTs behave as if NO_CTSRTS is always set.

On the imp002e, uartB has no TX signal, and behaves as if NO_TX is always set.

On the imp003, uartQRPW and uartUVGD provide CTS and RTS pins; uartDM, uartFG and uartWJ do not.

On the imp004m, uartFGJH provides CTS and RTS pins; all other UARTs do not.

On the imp005, uart0 provides CTS and RTS pins; all other UARTs do not.

UART timing and Modbus-RTU

The TIMING_ENABLED flag instructs the imp to keep track of the intervals (in microseconds) between the receipt of two consecutive bytes, ie. the interval between the “previous” byte and the one being reported. The main purpose of this facility is to provide detection of interframe gaps and thus frame boundaries in Modbus-RTU applications.

Such intervals are returned to Squirrel when uart.read() is called. For the first byte received the interval is calculated from the time uart.configure() is called.

For baud rates up to 38,400, the accuracy of the interval timings should be taken to be within the duration of the transmission of half a byte. For example, with an 8-bit word size, no parity bit and a single stop bit (ten bits in all) and running at 19,200 baud, the accuracy is 260μs (10 * 0.5 / 19200).

The Callback Function

By default, the callback is a function taking no parameters and is called whenever data is available to be read.

If new data arrives while the callback is running, then the function will be called again — even if that new data was consumed by the first call. Callback functions should therefore be designed to cope with being called when there is nothing left to read.

When the CALLBACK_WITH_FLAGS control flag constant is specified, the callback takes one parameter: one or more of the following bitfield event flags.

Event Flag Constant Value Description Notes
READ_READY 1 Data is available to be read As per the default callback
WRITE_DONE 2 Transmit completed An asynchronous alternative to uart.flush()
NOISE_ERROR 4 Noise was detected in the start bit
FRAME_ERROR 8 A framing error occurred The designated start and stop bits could not be found
PARITY_ERROR 16 A parity error occurred The parity of the number of 1 bits disagrees with that specified by the parity bit
OVERRUN_ERROR 32 An over-run error occurred The receive buffer was full when another character arrived
LINE_IDLE 64 Line idle was detected This is triggered by an entire frame of 1s followed by the start bit of the next frame which contains data
WRITE_HALF_DONE 128 TX FIFO half full This is triggered when the UART transmission buffer crosses the half-full point. From impOS release 32 onwards

The values assigned to the constants may change in a future impOS release.

Note No imp005 UART can return NOISE_ERROR or LINE_IDLE. In addition, the imp005’s hardware.uart2 is currently incapable of generating PARITY_ERROR and FRAME_ERROR.

Example Code

The following imp device code sends an alternating signal onto the UART bus configured using uart.configure(). Note the registration of the optional callback function arduinoData() which is called if and when data arrives on the UART bus.

The following code includes a function you can use to check whether your code is running on an imp005, imp003, imp002 or imp001. The code makes this check, and aliases the correct UART bus pins (as serial) accordingly.