# TTY : TTY device such as UART

This module is a UART operation module.

This module is designed in a synchronous mode, but with the iosched module can support asynchronous mode.

User can use the following code to import the Tty module.

var Tty = require('tty');

# Support

The following shows Tty module APIs available for each permissions.

# Tty Class

# new Tty(dev)

• dev {String} Device name.
• Returns: {Object} Returns tty object.

Open a tty file with the specified device name.

# Example

// Open /dev/ttyS0 tty device.
var tty = new Tty('S0');

# Tty.open(dev)

• dev {String} Device name.
• Returns: {Object} Returns tty object.

Open a tty file with the specified device name.

Same as new Tty(), but does not throw an exception, returning undefined means opening failed.

# Example

// Open /dev/ttyS1 tty device.
var tty = Tty.open('S1');

# Tty Object

# tty.fd()

• Returns: {Integer} Tty object file descriptor.

Get current tty object event file descriptor. Only for iosched readable and writable event detection in current tasks.

# Example

// Open /dev/ttyS1 tty device.
var tty = Tty.open('S1');

// Create a buffer.
var buf = new Buffer(1024);

var ioevent = iosched.event(iosched.READ, tty.fd(), () => {
  // Some data arrives.
  var num = tty.read(buf);
  if (num > 0) {
    // Echo the data.
    tty.write(buf, 0, num);
    return true;

  } else if (num < 0) {
    // has been closed, now remove from event set.
    return false;
  }
});

iosched.add(ioevent);

while (true) {
  iosched.poll();
}

# tty.close()

Close this tty and reclaiming file descriptors. If user forgets to call this function, the file descriptor is automatically reclaimed when the object is destroyed.

# tty.read(buffer[, offset[, length[, timeout]]])

• buffer {Buffer} Receive buffer.
• offset {Integer} Buffer offset. default:0.
• length {Integer} Receive length limit. default:buffer.length.
• timeout {Integer} Wait timeout in milliseconds. default: undefined means wait forever.
• Returns: {Integer} The number of bytes actually receive, negative error.

The tty.read() function shall receive bytes from tty device.

# Example

• Synchronize

var buf = new Buffer(1024);

while (true) {
  var num = tty.read(buf);
  if (num > 0) {
    console.log(buf.toString(num));
  }
}

• Asynchronize

var ioevent = iosched.event(iosched.READ, tty.fd(),
() => {
  var buf = new Buffer(1024);
  var num = tty.read(buf);
  if (num > 0) {
    console.log(buf.toString(num));
    return true;
  } else if (num < 0) {
    return false;
  }
});

iosched.add(ioevent);

while (true) {
  iosched.poll();
}

# tty.write(string[, timeout])

• string {String} String to be send.
• timeout {Integer} Wait timeout in milliseconds. default: undefined means wait forever.
• Returns: {Integer} The number of bytes actually sent, negative error.

The tty.write() function shall send string to tty device.

# Example

tty.write('Test string');

# tty.write(buffer[, offset[, length[, timeout]]])

• buffer {Buffer} Write data buffer.
• offset {Integer} Buffer offset. default:0.
• length {Integer} Write length. default:buffer.length.
• timeout {Integer} Wait timeout in milliseconds. default: undefined means wait forever.
• Returns: {Integer} The number of bytes actually sent, negative error.

The tty.write() function shall send data to tty device.

# Example

var buf = new Buffer([1, 2, 3]);
tty.write(buf);

# tty.flush([option])

• option {String} If 'r' means clear the receive buffer, if 'w' means clear the send buffer. default: undefined means clear receive and send buffer.

If the you need to discard the current tty driver send or receive queued data, you can use this function to clear.

# Example

tty.flush();

# tty.drain()

If there has data in the current send queue that has not been sent, the function returns after waiting for all packets in the send queue to be sent.

# Example

tty.drain(); // All queued data has been sent.

# tty.count()

• Returns: {Integer} Returns how many bytes in receive queue.

If there are unread bytes in the receive buffer, this function returns the number of bytes, otherwise it returns 0.

# Example

var cnt = tty.count();

# tty.getOption()

• Returns: {Object} Current option object.

Get tty current options. Options object includes following members:

• echo {Boolean} Echo input data.
• crmod {Boolean} Automatically add '\r' before '\n'.
• tandem {Boolean} XON / XOFF flow control protocol.
• ascii {Boolean} Use 7 bits ASCII mode.
• abort {Boolean} Kill current process when receiving a '^C' character.
• line {Boolean} Line mode, Trigger a readable event when the tty driver receives '\n' or internal buffer is full.

# Example

var opt = tty.getOption();

console.log(opt);

# tty.setOption(opt)

• opt {Object} New option object.
• Returns: {Boolean} Whether the operation was successful.

Set tty current options.

# Example

// Use tty in raw binary data send and receive.
tty.setOption({});

// Use tty in line mode.
tty.setOption({ line: true });

// Use tty in line & echo mode.
tty.setOption({ line: true, echo: true });

# tty.getHwOption()

• Returns: {Object} Current hardware option.

The hardware option is an object with following members:

• baud {Integer} Baudrate.
• data {Integer} Data bits, 5 ~ 8 bits.
• stop {Integer} Stop bits, 1 ~ 2 bits.
• parity {String} Parity, 'odd', 'even' or 'none'.

# Example

var hwOpt = tty.getHwOption();

// Show hardware options.
console.log(hwOpt);

# tty.setHwOption(hwOpt)

• hwOpt {Object | String} New hardware option.
• Returns: {Boolean} Whether the operation was successful.

# Example

tty.setHwOption({
  baud: 115200, data: 8, stop: 1, parity: 'none'
});

If hwOpt is of type String, the following specifications are followed: 'baud,parity,data,stop', parity values include 'n': none, 'o': odd, 'e': even.

# Example

tty.setHwOption('115200,n,8,1');

# tty.setRecvBufferSize(size)

• size {Integer} New receive buffer size. Must be between 64bytes and 8Kbytes.
• Returns: {Boolean} Whether the operation was successful.

Set the tty driver to receive buffer size.

# Example

tty.setRecvBufferSize(1024);

# tty.setSendBufferSize(size)

• size {Integer} New send buffer size. Must be between 64bytes and 8Kbytes.
• Returns: {Boolean} Whether the operation was successful.

Set the tty driver to send buffer size.

# Example

tty.setSendBufferSize(1024);