Configures the UART serial bus
Device
| 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)
|
Integer — the actual connection speed in bits per second
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 | Min. baud rate | Max. 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) |
| imp006 | uartYEFGH, uartYJKLM All other UARTs |
732 366 |
6,291,456 (6Mbaud) 3,145,728 (3Mbaud) |
| 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.
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.
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 on all one- and two-pin UARTs |
| CALLBACK_WITH_FLAGS | 8 | Enable extended callback | |
| TIMING_ENABLED | 16 | Enable timing | See UART timing and Modbus-RTU |
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.
On the impC001, uartDCAB, uartEVMT, uartHJKL, uartPQSR, uartXBADC and uartYABCD provide CTS and RTS pins; all other UARTs do not.
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).
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 |
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 uart2 is currently incapable of generating PARITY_ERROR and FRAME_ERROR.
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.