Skip to content

Latest commit

 

History

History
97 lines (73 loc) · 4.67 KB

uart.md

File metadata and controls

97 lines (73 loc) · 4.67 KB
Raw

UART API

The UART API supports the Universal Asynchronous Receiver/Transmitter that allows the board to communicate with other external devices. It uses 2 pins, RX for receiving and TX for transmitting. UART ports are usually referred by string names, but numbers may also be accepted, as defined in the board documentation. This API uses a Buffer object for both read and write.

The UART API object

UART functionality is exposed by an object that can be obtained by using the uart() method of the Board API. See also the Web IDL. The API object exposes the following method:

Method Description
open() synchronous open

The UART open(options) method

Configures an UART port using data provided by the options argument. It runs the following steps:

  • Let uart be an UART object.
  • For all uart properties, if the options dictionary defines the same property with a valid value, let the uart property take that value, otherwise the default value.
  • Request the underlying platform to initialize the UART with the parameters provided by uart.
  • In case of failure, throw SystemError and abort these steps.
  • Invoke the uart.setReadRange(min, max) method with min = 1, and max taking a value determined by the platform that is greater than or equal to 1.
  • Return uart.

The UART interface

Represents the properties, methods and event that expose UART functionality. The UART interface implements the EventEmitter interface.

Event name Event callback argument
read Buffer
Property Type Optional Default value Represents
port String no undefined UART port
speed number yes 115200 UART baud rate
dataBits number yes 8 number of data bits
stopBits number yes 1 number of stop bits
parity enum yes 'none' 'none', 'even', 'odd'
flowControl boolean yes false if flow control is on
Method Description
write() write a buffer
setReadRange() set buffer sizes for read notifications
close() close the UART port

The port property denotes the UART port as a string defined by the board documentation, such as "tty0", "serialUSB0", etc.

The speed property represents the baud rate and its value can be 9600, 19200, 38400, 57600, 115200 (by default).

The dataBits property represents the number of data bits (word size), and it can be between 5 and 8 (by default).

The stopBits property represents the number of stop bits and can take the value 1 (by default) or 2.

The parity property can take the following values: "none" (by default), "even", and "odd".

The flowControl boolean property denotes if flow control is used. By default it is false.

The write(buffer) method

Transmits a Buffer using UART. The method runs the following steps:

  • Request the underlying platform to send the bytes specified in buffer. If the operation fails, throw SystemError and abort these steps.

The setReadRange(min, max) method

Sets the minimum and maximum number of bytes for triggering the onread event. Whenever at least min number of bytes is available, the read event is fired with a Buffer containing at maximum max number of bytes.

The close() method

Closes the current UART port and interrupts all pending operations.

Examples

try {
  var uart = require("board").uart("serialUSB0");

  console.log("UART port " + uart.port);
  console.log("Speed [bps]: " + uart.speed);
  console.log("Data bits: " + uart.dataBits);
  console.log("Stop bits: " + uart.stopBits);
  console.log("Parity: " + uart.parity);
  console.log("Flow control " + (uart.flowControl ? "on." : "off.");

  uart.setReadRange(8, 16);  // min 8 byes, max 16 bytes in one read event

  uart.on("read", function(buffer) {
    console.log("UART received: " + buffer.toString());
  });

  uart.write([1, 2, 3]);

} catch(err) {
  console.log("UART error: " + err.message);
}