nodemcu-firmware/docs/modules/uart.md

# UART Module
| Since  | Origin / Contributor  | Maintainer  | Source  |
| :----- | :-------------------- | :---------- | :------ |
| 2014-12-22 | [Zeroday](https://github.com/funshine) | [Zeroday](https://github.com/funshine) | [uart.c](../../components/base_nodemcu/uart.c)|

The [UART](https://en.wikipedia.org/wiki/Universal_asynchronous_receiver/transmitter) (Universal asynchronous receiver/transmitter) module allows configuration of and communication over the UART serial port.

If the UART is in use as the system console, it is unavailable for use by this
module. Instead, refer to the `console` module.

If your IDE does not yet support uploading files via the `console` module,
consider using the utility script `scripts/upload-file.py`, e.g.
`scripts/upload-file.py init.lua` (use `scripts/upload-file.py -h` for help).

Before using a UART, you must call `uart.setup` and `uart.start` to set it up.

## uart.on()

Sets the callback function to handle UART events. For a UART used by the
console, refer to the `console` module instead.

#### Syntax
`uart.on([id], method, [number/end_char], [function])`

#### Parameters
- `id` uart id, except console uart. Default value is uart 0.
- `method` "data", data has been received on the UART. "error", error occurred on the UART.
- `number/end_char`. Only for event `data`.
	- if pass in a number n, the callback will called when n chars are received.
	- if n=0, will receive every char in buffer.
	- if pass in a one char string "c", the callback will called when "c" is encounterd, or max n=255 received.
- `function` callback function. 
  - event "data" has a callback like this: `function(data) end`
  - event "error" has a callback like this: `function(err) end`. `err` could be one of "out_of_memory", "break", "rx_error".

To unregister the callback, provide only the "method" parameter.

#### Returns
`nil`

#### Example
```lua
-- when 4 chars is received.
uart.on("data", 4,
  function(data)
	print("receive from uart:", data)
	if data=="quit" then
	  uart.on("data") -- unregister callback function
	end
end)
-- when '\r' is received.
uart.on("data", "\r",
  function(data)
	print("receive from uart:", data)
	if data=="quit\r" then
	  uart.on("data") -- unregister callback function
	end
end)

-- uart 2
uart.on(2, "data", "\r",
  function(data)
	print("receive from uart:", data)
  end)
  
-- error handler
uart.on(2, "error",
  function(data)
	print("error from uart:", data)
  end)
```

## uart.setup()

(Re-)configures the communication parameters of the UART.

#### Syntax
`uart.setup(id, baud, databits, parity, stopbits, pins)`

#### Parameters
- `id` uart id, except console uart
- `baud` one of 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 74880, 115200, 230400, 256000, 460800, 921600, 1843200, 3686400
- `databits` one of 5, 6, 7, 8
- `parity` `uart.PARITY_NONE`, `uart.PARITY_ODD`, or `uart.PARITY_EVEN`
- `stopbits` `uart.STOPBITS_1`, `uart.STOPBITS_1_5`, or `uart.STOPBITS_2`
- `pins`
  - table with the following entries:
    - `tx` int. TX pin. Required
	- `rx` int. RX pin. Required
	- `cts` in. CTS pin. Optional
	- `rts` in. RTS pin. Optional
	- `tx_inverse` boolean. Inverse TX pin. Default: `false`
	- `rx_inverse` boolean. Inverse RX pin. Default: `false`
	- `cts_inverse` boolean. Inverse CTS pin. Default: `false`
	- `rts_inverse` boolean. Inverse RTS pin. Default: `false`
	- `flow_control` int. Combination of `uart.FLOWCTRL_NONE`, `uart.FLOWCTRL_CTS`, `uart.FLOWCTRL_RTS`. Default: `uart.FLOWCTRL_NONE`

#### Returns
configured baud rate (number)

#### Example
```lua
-- configure for 9600, 8N1, with echo
uart.setup(0, 9600, 8, uart.PARITY_NONE, uart.STOPBITS_1, 1)
```

```lua
uart.setup(2, 115200, 8, uart.PARITY_NONE, uart.STOPBITS_1, {tx = 17, rx = 16})
```

## uart.getconfig()

Returns the current configuration parameters of the UART. 

#### Syntax
`uart.getconfig(id)`

#### Parameters
- `id` uart id, except console uart

#### Returns
Four values as follows:

- `baud` one of 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 74880, 115200, 230400, 256000, 460800, 921600, 1843200, 3686400
- `databits` one of 5, 6, 7, 8
- `parity` `uart.PARITY_NONE`, `uart.PARITY_ODD`, or `uart.PARITY_EVEN`
- `stopbits` `uart.STOPBITS_1`, `uart.STOPBITS_1_5`, or `uart.STOPBITS_2`

#### Example
```lua
print (uart.getconfig(0))
-- prints 9600 8 0 1   for 9600, 8N1
```

## uart.start()
Start the UART.

#### Syntax
`uart.start(id)`

#### Parameters
- `id` uart id, except console uart

#### Returns
Boolean. `true` if uart is started.


## uart.stop()
Stop the UART.

#### Syntax
`uart.stop(id)`

#### Parameters
- `id` uart id, except console uart

#### Returns
`nil`


## uart.setmode()

Set UART controllers communication mode

#### Syntax

`uart.setmode(id, mode)`

#### Parameters
- `id` uart id, except console uart
- `mode` value should be one of
    - `uart.MODE_UART` default UART mode, is set after uart.setup() call
    - `uart.MODE_RS485_COLLISION_DETECT` receiver must be always enabled, transmitter is automatically switched using RTS pin, collision is detected by UART hardware (note: no event is generated on collision, limitation of esp-idf)
    - `uart.MODE_RS485_APP_CONTROL` receiver/transmitter control is left to the application
    - `uart.MODE_RS485_HALF_DUPLEX` receiver/transmitter are controlled by RTS pin
    - `uart.MODE_IRDA`
    
#### Returns
`nil`


## uart.txflush()

Wait for any data currently in the UART transmit buffers to be written out. It can be useful to call this immediately before a call to [`node.sleep()`](node.md#nodesleep) because otherwise data might not get written until after wakeup.

#### Syntax
`uart.txflush(id)`

#### Parameters
- `id` uart id, except console uart

#### Returns
`nil`

#### Example
```lua
uart.write(0, "I want this to show up now not in 5 seconds")
uart.txflush(0)
node.sleep({secs=5})
```

#### See also
[`node.sleep()`](node.md#nodesleep)


## uart.wakeup()

Configure the light sleep wakeup threshold. This is the number of positive edges that must be seen on the UART RX pin before a light sleep wakeup will be triggered. The minimum value is 3. The default value is undefined, therefore you should always call this function before the first time you call `node.sleep()` with the uart option set.

#### Syntax
`uart.wakeup(id, val)`

#### Parameters
- `id` uart id, except console uart
- `val` the new value 

#### Returns
`nil`

#### Example
```lua
uart.wakeup(0, 5)
```

#### See also
[`node.sleep()`](node.md#nodesleep)


## uart.write()

Write string or byte to the UART.

#### Syntax
`uart.write(id, data1 [, data2, ...])`

#### Parameters
- `id` uart id, except console uart
- `data1`... string or byte to send via UART

#### Returns
`nil`

#### Example
```lua
uart.write(0, "Hello, world\n")
```