12. UART

The UART object is a built-in object that provides UART communication functions.

---

Abstracts

Methods()/Properties	Summary	Version	Note
new UART()	Creates a UART instance.	01.00.00+

{UART} Instance

Methods()/Properties	Summary	Version	Note
.open()	Starts the communication.	01.00.00+
.close()	Ends the communication.	01.00.00+
.send()	Sends the data.	01.00.00+
.receive()	Receives the data.	01.00.00+
.setRecvEvent()	Registers the data reception callback process.	01.00.00+
.setBufRecvEvent()	Registers the buffering type data reception callback process.	01.00.00+
.releaseRecvEvent()	Releases the data reception callback process registered by .setRecvEvent() or .setBufRecvEvent().	01.00.00+
.checkSendComp()	Confirms that data transmission is completed.	01.00.00+
.waitSendComp()	Waits (blocks) until the data transmission is completed.	02.00.00+
.checkRecvData()	Checks if there is receivable data.	01.00.00+
.checkRecvError()	Checks the reception errors.	02.00.00+

---

Details

new UART(nodeNo)

Creates a UART instance.

Name	Type	M/O	Summary	Note
nodeNo	number	mandatory	Specifies the node number of the UART interface to be used. Please refer to Pinout.
return	{UART}	-	{UART} : Generated {UART}

.open(baudrate,flow,parity[,dataBit[,stopBit]])

Starts the communication.

Name	Type	M/O	Summary	Note
baudrate	number	mandatory	Communication speed Specify the communication baudrate [bps]. Range: 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400, 460800, 921600
flow	boolean	mandatory	Hardware flow true: Valid false: Invalid
parity	number	mandatory	Parity bit 0: None 1: Even 2: Odd
dataBit	number	optional	Data bit 0: 8-bit 1: 7-bit The default value is 0.	Version 02.00.00+
stopBit	number	optional	Stop bit 0: 1-bit 1: 2-bit The default value is 0.	Version 02.00.00+
return	boolean	-	true: Success false: Failure

.close()

Ends the communication.

Name	Type	M/O	Summary	Note
return	boolean	-	true: Success false: Failure

.send(data,block)

Sends the data.

Name	Type	M/O	Summary	Note
data	ArrayBuffer, string	mandatory	Transmission data ArrayBuffer : ArrayBuffer size will be sent. string : The specified string is sent.	The maximum size that can be sent at one time is 512 bytes.
block	boolean	mandatory	Specify the transmission blocking process. true: Enable blocking false: Disable blocking	If disabled, all data specified in one process may not be sent. Please check the size of the transmitted data, and if necessary, retransmit from the continuination of the data.
return	number	-	Transmitted data size	Returns -1 if the transmission failed.

.receive(isBin,recvLen)

Receives the data.
Since it is executed in non-block processing, the reception is not awaited.

Name	Type	M/O	Summary	Note
isBin	boolean	mandatory	Specify the format of the received data. true: Receive in binary data format false: Receive in string format
recvLen	number	optional	Specify the maximum receiving size [byte]. Range: 1 - 512 The default value is 512 bytes.
return	ArrayBuffer, string	-	Received data The return type is determined by isBin. If isBin is true, the type is ArrayBuffer; otherwise, the type is string.	Data length will be less than or equal to the size specified in recvLen. If there is no data received, the size will be 0.

.setRecvEvent(callback,isBin,recvLen)

Registers the data reception callback process.
Executes callback processing when data is received. When there is no data received, the callback processing does not occur.
In addition, it is not possible to re-register the callback process within the data reception callback process execution.

Cannot be used simultaneously with .setBufRecvEvent(), and should be used exclusively.

Name	Type	M/O	Summary	Note
callback(data)	function	mandatory	Executes callback processing when data is received. data : {ArrayBuffer|string} Received data The type of the argument is determined by isBin. If isBin is true, the type is ArrayBuffer; otherwise, the type is string.	Data length will be less than or equal to the size specified in recvLen.
isBin	boolean	mandatory	Specifies the format of the received data. true: Receive in binary data format false: Receive in string format
recvLen	number	optional	Specifies the maximum receiving size in Bytes. Range: 1 - 512 The default value is 512 bytes.
return	boolean	-	true: Success false: Failure

.setBufRecvEvent(callback,buff)

Registers the buffering type data reception callback process.
Executes the callback process when the received data accumulates for the specified buffer size.
After the callback, the data reception callback process will be released. To continue waiting for data reception, register the callback process again.
In addition, it is not possible to re-register the callback process within the data reception callback process execution.

Received data is written directly to the specified buffer. Although efficient, as the writing and reading will conflict, this can be used for synchronous control where the receive data length is fixed and the receive timing is guaranteed.

Cannot be used simultaneously with .setRecvEvent(), and should be used exclusively.

Name	Type	M/O	Summary	Note
callback(dataLen)	function	mandatory	Executes the callback process when the received data accumulates for the specified buffer size. dataLen : {number} Receive data length	dataLen will be always specified buffer size.
buff	ArrayBuffer	mandatory	Specifies the buffer for writing the received data.	Received data is written directly to the specified buffer.
return	boolean	-	true: Success false: Failure

.releaseRecvEvent()

Releases the data reception callback process registered by .setRecvEvent() or .setBufRecvEvent().

Name	Type	M/O	Summary	Note
return	boolean	-	true: Success false: Failure

.checkSendComp()

Confirms that data transmission is completed.

Name	Type	M/O	Summary	Note
return	boolean	-	Transmission status true: Transmission complete false: Transmission in progress	When the UART send buffer is empty and the hardware is in the send complete state, it is determined that the transmission is complete. Version 01.03.02 or older: Number type is returned. 1: Transmission complete 0: Transmission in progress When the UART send buffer is empty, it is determined that the transmission is complete.

.waitSendComp()

Waits (blocks) until the data transmission is completed.

Name	Type	M/O	Summary	Note
return	undefined	-		When the UART send buffer is empty and the hardware is in the send complete state, it is determined that the transmission is complete.

.checkRecvData()

Checks if there is receivable data.

Name	Type	M/O	Summary	Note
return	boolean	-	true: With received data false: Without received data

.checkRecvError()

Checks the reception errors.
Error causes are represented by bit flags.
When a receive error is detected, the target bit flag is set to 1.
In addition, after this method is called, all bit flags are cleared to 0 once.

This function is not supported. 0 is always returned.

Name	Type	M/O	Summary	Note
return	number	-	Error causes bit 0: Parity error bit 1: Framing error bit 2: Noise detection flag bit 3: Overrun error	The value is always 0 when no receive error has occurred.

---

Object Usage Examples

Sample 1

This is a sample that sends and receives string data.
Displays the received data using the .setRecvEvent() method.

var NODE_NO = 2;
var BAUDRATE = 115200;

var uart = new UART(NODE_NO);
uart.open(BAUDRATE, false, 0);

uart.setRecvEvent(function(data) {
    print('recv: ' + data);
}, false, 128);

while(1) {
    uart.send('Hello World!\r\n', true);
    setTimeout(1000).wait();
}

uart.releaseRecvEvent();
uart.close();

Sample 2

This is a sample that sends and receives binary data.
Displays the received data using the .setRecvEvent() method.

var NODE_NO = 2;
var BAUDRATE = 115200;

var uart = new UART(NODE_NO);
uart.open(BAUDRATE, false, 0);

var sendCnt = 0;
var sendBuff = new ArrayBuffer(1);
var sendArr = new Uint8Array(sendBuff);

uart.setRecvEvent(function(buff) {
    var arr = new Uint8Array(buff);
    var dump = '';
    for(var i=0; i<arr.length; i++) {
        dump += ('00' + arr[i].toString(16).toUpperCase()).substr(-2) + ' ';
    }
    print('recv(' + arr.length + '): ' + dump);
}, true, 128);

while(1) {
    sendArr[0] = sendCnt;
    uart.send(sendBuff, true);
    setTimeout(1000).wait();
    sendCnt++;
    sendCnt &= 255;
}

uart.releaseRecvEvent();
uart.close();

Sample 3

This is a sample that sends and receives data.
Waits for data reception to the receive buffer to complete using the .setBufRecvEvent() method.

var NODE_NO = 2;
var BAUDRATE = 115200;

var uart = new UART(NODE_NO);
uart.open(BAUDRATE, false, 0);

var received = false;
var recvBuff = new ArrayBuffer(8);

uart.setBufRecvEvent(function(dataLen) { //one-shot
    var arr = new Uint8Array(recvBuff);
    var dump = '';
    for(var i=0; i<arr.length; i++) {
        dump += ('00' + arr[i].toString(16).toUpperCase()).substr(-2) + ' ';
    }
    print('recv(' + dataLen + '): ' + dump);
    received = true
}, recvBuff);

while(!received) {
    uart.send('Waiting for ' + recvBuff.byteLength + ' bytes of data to be received.\r\n', true);
    setTimeout(1000).wait();
}

print('finished');

uart.close();

---

Updated: 2022-06-02