SerialPort

stream/stream~ SerialPort

new SerialPort(path, optionsopt, openCallbackopt)

Create a new serial port object for the path. In the case of invalid arguments or invalid options, when constructing a new SerialPort it will throw an error. The port will open automatically by default, which is the equivalent of calling port.open(openCallback) in the next tick. You can disable this by setting the option autoOpen to false.

Parameters:
Name Type Attributes Description
path string

The system path of the serial port you want to open. For example, /dev/tty.XXX on Mac/Linux, or COM1 on Windows.

options openOptions <optional>

Port configuration options

openCallback errorCallback <optional>

Called after a connection is opened. If this is not provided and an error occurs, it will be emitted on the port's error event. The callback will NOT be called if autoOpen is set to false in the openOptions as the open will not be performed.

Properties:
Name Type Description
baudRate number

The port's baudRate. Use .update to change it. Read-only.

binding object

The binding object backing the port. Read-only.

isOpen boolean

true if the port is open, false otherwise. Read-only. (since 5.0.0)

path string

The system path or name of the serial port. Read-only.

Source:
Fires:
Throws:

When given invalid arguments, a TypeError will be thrown.

Type
TypeError

Methods

(static) list(callbackopt) → {Promise}

Retrieves a list of available serial ports with metadata. Only the comName is guaranteed. If unavailable the other fields will be undefined. The comName is either the path or an identifier (eg COM1) used to open the SerialPort.

We make an effort to identify the hardware attached and have consistent results between systems. Linux and OS X are mostly consistent. Windows relies on 3rd party device drivers for the information and is unable to guarantee the information. On windows If you have a USB connected device can we provide a serial number otherwise it will be undefined. The pnpId and locationId are not the same or present on all systems. The examples below were run with the same Arduino Uno.

Parameters:
Name Type Attributes Description
callback listCallback <optional>

Called with a list of available serial ports.

Source:
Returns:

Resolves with the list of available serial ports.

Type
Promise
Example
```js
// OSX example port
{
  comName: '/dev/tty.usbmodem1421',
  manufacturer: 'Arduino (www.arduino.cc)',
  serialNumber: '752303138333518011C1',
  pnpId: undefined,
  locationId: '14500000',
  productId: '0043',
  vendorId: '2341'
}

// Linux example port
{
  comName: '/dev/ttyACM0',
  manufacturer: 'Arduino (www.arduino.cc)',
  serialNumber: '752303138333518011C1',
  pnpId: 'usb-Arduino__www.arduino.cc__0043_752303138333518011C1-if00',
  locationId: undefined,
  productId: '0043',
  vendorId: '2341'
}

// Windows example port
{
  comName: 'COM3',
  manufacturer: 'Arduino LLC (www.arduino.cc)',
  serialNumber: '752303138333518011C1',
  pnpId: 'USB\\VID_2341&PID_0043\\752303138333518011C1',
  locationId: 'Port_#0003.Hub_#0001',
  productId: '0043',
  vendorId: '2341'
}
```

```js
var SerialPort = require('serialport');
// callback approach
SerialPort.list(function (err, ports) {
  ports.forEach(function(port) {
    console.log(port.comName);
    console.log(port.pnpId);
    console.log(port.manufacturer);
  });
});

// promise approach
SerialPort.list()
  .then(ports) {...});
  .catch(err) {...});
```

close(callback, disconnectError) → {undefined}

Closes an open connection.

If there are in progress writes when the port is closed the writes will error.

Parameters:
Name Type Description
callback errorCallback

Called once a connection is closed.

disconnectError Error

used internally to propagate a disconnect error

Source:
Fires:
Returns:
Type
undefined

drain(callbackopt) → {undefined}

Waits until all output data is transmitted to the serial port. After any pending write has completed it calls tcdrain() or FlushFileBuffers().aspx) to ensure it has been written to the device.

Parameters:
Name Type Attributes Description
callback errorCallback <optional>

Called once the drain operation returns.

Source:
Returns:
Type
undefined
Example
Write the `data` and wait until it has finished transmitting to the target serial port before calling the callback. This will queue until the port is open and writes are finished.

```js
function writeAndDrain (data, callback) {
  port.write(data);
  port.drain(callback);
}
```

flush(callbackopt) → {undefined}

Flush discards data received but not read, and written but not transmitted by the operating system. For more technical details, see tcflush(fd, TCIOFLUSH) for Mac/Linux and FlushFileBuffers for Windows.

Parameters:
Name Type Attributes Description
callback errorCallback <optional>

Called once the flush operation finishes.

Source:
Returns:
Type
undefined

get(callbackopt) → {undefined}

Returns the control flags (CTS, DSR, DCD) on the open port.
Uses GetCommModemStatus.aspx) for Windows and ioctl for mac and linux.

Parameters:
Name Type Attributes Description
callback modemBitsCallback <optional>

Called once the modem bits are retrieved.

Source:
Returns:
Type
undefined

open(openCallbackopt) → {undefined}

Opens a connection to the given serial port.

Parameters:
Name Type Attributes Description
openCallback errorCallback <optional>

Called after a connection is opened. If this is not provided and an error occurs, it will be emitted on the port's error event.

Source:
Fires:
Returns:
Type
undefined

set(optionsopt, callbackopt) → {undefined}

Set control flags on an open port. Uses SetCommMask.aspx) for Windows and ioctl for OS X and Linux.

Parameters:
Name Type Attributes Description
options object <optional>

All options are operating system default when the port is opened. Every flag is set on each call to the provided or default values. If options isn't provided default options is used.

Properties
Name Type Attributes Default Description
brk Boolean <optional>
false

sets the brk flag

cts Boolean <optional>
false

sets the cts flag

dsr Boolean <optional>
false

sets the dsr flag

dtr Boolean <optional>
true

sets the dtr flag

rts Boolean <optional>
true

sets the rts flag

callback errorCallback <optional>

Called once the port's flags have been set.

Since:
  • 5.0.0
Source:
Returns:
Type
undefined

update(optionsopt, callbackopt) → {undefined}

Changes the baud rate for an open port. Throws if you provide a bad argument. Emits an error or calls the callback if the baud rate isn't supported.

Parameters:
Name Type Attributes Description
options object <optional>

Only supports baudRate.

Properties
Name Type Attributes Description
baudRate number <optional>

The baud rate of the port to be opened. This should match one of the commonly available baud rates, such as 110, 300, 1200, 2400, 4800, 9600, 14400, 19200, 38400, 57600, or 115200. Custom rates are supported best effort per platform. The device connected to the serial port is not guaranteed to support the requested baud rate, even if the port itself supports that baud rate.

callback errorCallback <optional>

Called once the port's baud rate changes. If .update is called without a callback, and there is an error, an error event is emitted.

Source:
Returns:
Type
undefined