Node Serialport

Intro to Node-Serialport

Imagine a world in which you can write JavaScript to control blenders, lights, security systems, or even robots. That's right—robots! Thanks to Node Serialport, that world is here.

Node-Serialport provides a stream interface for the low-level serial port code necessary to controll Arduino chipsets, X10 interfaces, Zigbee radios, highway signs, lcd screens, cash drawers, motor controllers, sensor packages, fork lifts, modems, drones, CNC machines, plotters, vending machines, ccTalk coin accecptors, SMS Gateways, RFID scanners and much more. If if you have a hardware device with an UART we can speak to it. The physical world is your oyster with this goodie.

For a full breakdown of why we made Node-Serialport, please read NodeBots - The Rise of JS Robotics. It explains why one would want to program robots in JS in the first place.

We're not against firmware but we're better than it.

Quick Answers to Important Questions

• For support, open a GitHub issue.
• For discussions, design ideas, and clarifications, please join our Gitter chat room.
• To test Node-Serialport, we recommend two related projects—Browser Serialport ("just like Node Serialport, but for browser apps") and Serialport Test Piliot.
• To contribute, please review our contribution guide and Code of Conduct. You might want to check out our roadmap. We also have issues tagged "good first PR", if you'd like to start somewhere specific. We'll do our best to support you until we merge your PR.

For which version of Node-Serialport would you like documentation?

You're reading the README for Node-Serialport's master branch. You probably want to see the README for our most recent release. See our changelog for what's new, and our upgrade guide for a walk-through on differences between major versions.

• serialport@5.0.0 docs the latest 5.x release. 🎉
• serialport@4.0.7 docs the latest 4.x release.
• serialport@3.1.2 docs the last 3.x release.

Older versions are no longer supported.

Helpful Resources for Getting Started with Node-Serialport

In addition to reading the article mentioned above, these others might help you:

• Johnny-Five: The Johnny-Five Robotics and IoT platform's six-line "Hello World" (awesome).
• Arduino Node Security Sensor Hacking: A great all-around "how do I use this" article.

Table of Contents

• Platform Support
• Installation
• Installation Special Cases
  • Alpine Linux
  • Electron
  • Illegal Instruction
  • Mac OS X
  • Raspberry Pi Linux
  • sudo / root
  • Ubuntu/Debian Linux
  • Windows
• Usage
  • Opening a Port
  • Testing
  • Debugging
  • Error Handling
• SerialPort ⏏
  • new SerialPort(path, [options], [openCallback])
  • instance
    • .open([callback])
    • .update([options], [callback])
    • .write(data, [encoding], [callback]) ⇒ boolean
    • .read([size]) ⇒ string | Buffer | null
    • .close(callback)
    • .set([options], [callback])
    • .get([callback])
    • .flush([callback])
    • .drain([callback])
    • .pause() ⇒
    • .resume() ⇒
    • Event: "error"
    • Event: "open"
    • Event: "data"
    • Event: "close"
  • static
    • .Binding : BaseBinding
    • .parsers : object
    • .list([callback]) ⇒ Promise
  • inner
    • ~BaseBinding
      • new BaseBinding(options)
      • instance
        • .open(path, openOptions) ⇒ Promise
        • .close() ⇒ Promise
        • .read(data, offset, length) ⇒ Promise
        • .write(data) ⇒ Promise
        • .update([options]) ⇒ Promise
        • .set([options]) ⇒ Promise
        • .get() ⇒ Promise
        • .flush() ⇒ Promise
        • .drain() ⇒ Promise
      • static
        • .list() ⇒ Promise
    • ~errorCallback : function
    • ~modemBitsCallback : function
    • ~openOptions : Object
    • ~listCallback : function
• Command Line Tools
  • Serial Port List
  • Serial Port Terminal
  • Serial Port Repl
• License

Platform Support

serialport supports NodeJS v4 and upwards. For versions 0.10 and 0.12, use serialport@4. The platforms, architectures and Node versions that serialport supports are the following;

¹ ARM, MIPSel and PPC64¹ platforms are not currently part of our testing or build matrix, but are known to work.

² Windows 7, 8, 10, and 10 IoT are supported, but our CI tests only Windows Server 2012 R2.

³ OSX 10.4 Tiger and above are supported, but our CI tests only 10.9.5 Mavericks with Xcode 6.1.

Installation Instructions

For most "standard" use cases (Node v4.x on Mac, Linux, or Windows on a x86 or x64 processor), Node-Serialport will install nice and easy with:

npm install serialport

Installation Special Cases

We use node-pre-gyp to compile and post binaries of the library for most common use cases (Linux, Mac, Windows on standard processor platforms). If you have a special case, Node-Serialport will work, but it will compile the binary when you install. node-gyp requires Python 2.x, so please ensure you have it installed and in your path for all operating systems. Python 3.x will not work.

This assumes you have everything on your system necessary to compile ANY native module for Node.js. If you don't, then please ensure the following are true for your system before filing a "Does not install" issue.

Alpine Linux

Alpine is a (very) small distro, but it uses the musl standard library instead of glibc (used by most other Linux distros) so it requires compilation. It's commonly used with Docker. A user has confirmed that Node-Serialport works with alpine-node.

# If you don't have node/npm already, add that first
sudo apk add --no-cache nodejs

# Add the necessary build and runtime dependencies
sudo apk add --no-cache make gcc g++ python linux-headers udev

# Then we can install serialport, forcing it to compile
npm install serialport --build-from-source

# If you're installing as root, you'll also need to use the --unsafe-perm flag

Electron

Electron is a framework for creating cross-platform desktop applications. It comes with its own version of the Node.js runtime.

If you require serialport as a dependency for an Electron project, you must compile it for the version of Electron your project's using.

When you first install serialport it will compile against the version of Node.js on your machine, not against the Node.js runtime bundled with Electron.

To recompile serialport (or any native Node.js module) for Electron, you can use electron-rebuild; more info at Electron's README.

1. npm install --save-dev electron-rebuild
2. Add electron-rebuild to your project's package.json's install hook
3. Run npm install

For an example project, check out electron-serialport.

Illegal Instruction

The pre-compiled binaries assume a fully capable chip. Intel's Galileo 2, for example, lacks a few instruction sets from the ia32 architecture. A few other platforms have similar issues. If you get Illegal Instruction when trying to run Node-Serialport, you'll need to ask npm to rebuild the Serialport binary.

# Will ask npm to build serialport during install time
npm install serialport --build-from-source

# If you have a package that depends on serialport, you can ask npm to rebuild it specifically...
npm rebuild serialport --build-from-source

Mac OS X

Ensure that you have at a minimum the xCode Command Line Tools installed appropriate for your system configuration. If you recently upgraded the OS, it probably removed your installation of Command Line Tools, please verify before submitting a ticket. To compile node-serialport with Node.js 4.x+, you will need to use g++ v4.8 or higher.

Raspberry Pi Linux

Follow the instructions for setting up a Raspberry pi for use with Johnny-Five and Raspi IO. These projects use Node Serialport under the hood.

sudo / root

If you're going to use sudo or root to install Node-Serialport, npm will require you to use the unsafe parameters flag.

sudo npm install serialport --unsafe-perm --build-from-source

Failure to use the flag results in an error like this:

root@rpi3:~# npm install -g serialport
/usr/bin/serialport-list -> /usr/lib/node_modules/serialport/bin/serialport-list.js
/usr/bin/serialport-term -> /usr/lib/node_modules/serialport/bin/serialport-terminal.js

> serialport@4.0.3 install /usr/lib/node_modules/serialport
> node-pre-gyp install --fallback-to-build

gyp WARN EACCES user "root" does not have permission to access the dev dir "/root/.node-gyp/6.9.1"
gyp WARN EACCES attempting to reinstall using temporary dev dir "/usr/lib/node_modules/serialport/.node-gyp"
make: Entering directory '/usr/lib/node_modules/serialport/build'
make: *** No rule to make target '../.node-gyp/6.9.1/include/node/common.gypi', needed by 'Makefile'.  Stop.
make: Leaving directory '/usr/lib/node_modules/serialport/build'
gyp ERR! build error
gyp ERR! stack Error: `make` failed with exit code: 2

Ubuntu/Debian Linux

The best way to install any version of Node.js is to use the NodeSource Node.js binary distributions. Older versions of Ubuntu install Node.js with the wrong version and binary name. If your Node binary is nodejs instead of node, or if your Node version is v0.10.29, then you should follow these instructions.

You'll need the package build-essential to compile serialport. If there's a binary for your platform, you won't need it. Keep rocking!

# Using Ubuntu and Node 6
curl -sL https://deb.nodesource.com/setup_7.x | sudo -E bash -
sudo apt-get install -y nodejs

# Using Debian and Node 6 as root
curl -sL https://deb.nodesource.com/setup_7.x | bash -
apt-get install -y nodejs

Windows

Node-Serialport supports Windows 7, 8.1, 10, and 10 IoT. Precompiled binaries are available, but if you want to build it from source you'll need to follow the node-gyp installation instructions. Once you've got things working, you can install Node-Serialport from source with:

npm install serialport --build-from-source

Node-gyp's documentation doesn't mention it, but it sometimes helps to create a C++ project in Visual Studio so that it will install any necessary components not already installed during the past two hours of setup. This will solve some instances of Failed to locate: "CL.exe".

Usage

Opening a Port

var SerialPort = require('serialport');
var port = new SerialPort('/dev/tty-usbserial1', {
  baudRate: 57600
});

When opening a serial port, specify (in this order)

1. Path to Serial Port - required.
2. Options - optional and described below.

Constructing a SerialPort object immediately opens a port. While you can read and write at any time (it will be queued until the port is open), most port functions require an open port. There are three ways to detect when a port is opened.

• The open event is always emitted when the port is opened.
• The constructor's openCallback is passed to .open(), if you haven't disabled the autoOpen option. If you have disabled it, the callback is ignored.
• The .open() function takes a callback that is called after the port is opened. You can use this if you've disabled the autoOpen option or have previously closed an open port.

var SerialPort = require('serialport');
var port = new SerialPort('/dev/tty-usbserial1');

port.write('main screen turn on', function(err) {
  if (err) {
    return console.log('Error on write: ', err.message);
  }
  console.log('message written');
});

// Open errors will be emitted as an error event
port.on('error', function(err) {
  console.log('Error: ', err.message);
})

Detecting open errors can be moved to the constructor's callback.

var SerialPort = require('serialport');
var port = new SerialPort('/dev/tty-usbserial1', function (err) {
  if (err) {
    return console.log('Error: ', err.message);
  }
});

port.write('main screen turn on', function(err) {
  if (err) {
    return console.log('Error on write: ', err.message);
  }
  console.log('message written');
});

When disabling the autoOpen option you'll need to open the port on your own.

var SerialPort = require('serialport');
var port = new SerialPort('/dev/tty-usbserial1', { autoOpen: false });

port.open(function (err) {
  if (err) {
    return console.log('Error opening port: ', err.message);
  }

  // Because there's no callback to write, write errors will be emitted on the port:
  port.write('main screen turn on');
});

// The open event is always emitted
port.on('open', function() {
  // open logic
});

Get updates of new data from the serial port as follows:

// Switches the port into "flowing mode"
port.on('data', function (data) {
  console.log('Data:', data);
});

// Read data that is available but keep the stream from entering "flowing mode"
port.on('readable', function () {
  console.log('Data:', port.read());
});

You can write to the serial port by sending a string or buffer to the write method:

port.write('Hi Mom!');
port.write(Buffer.from('Hi Mom!'));

Enjoy and do cool things with this code.

Testing

Testing is an important feature of any library. To aid in our own tests we've developed a MockBinding a fake hardware binding that doesn't actually need any hardware to run. This class passes all of the same tests as our hardware based bindings and provides a few additional test related interfaces. To use the mock binding check out the example here.

const SerialPort = require('serialport/test');
const MockBinding = SerialPort.Binding;

// Create a port and enable the echo and recording.
MockBinding.createPort('/dev/ROBOT', { echo: true, record: true })
const port = new SerialPort('/dev/ROBOT')

Debugging

We use the debug package and log under the serialport namespace:

• serialport:main for all high-level/main logging
• serialport:binding for all low-level logging

You can enable logging through environment variables. Check the debug docs for info.

DEBUG=serialport:main node myapp.js
DEBUG=serialport:* node myapp.js
DEBUG=* node myapp.js

You can enable core dumps on osx with;

ulimit -c unlimited for core dumps

You can "console.log" from c++ with;

fprintf(stdout, "Hellow World num=%d str=%s\n", 4, "hi");

You can make use of the serialport-repl command with;

serialport-repl # to auto detect an arduino
serialport-repl /path/name # to connect to a specific port

It will load a serialport object with debugging turned on.

Error Handling

All functions in Node-Serialport follow two conventions:

• Argument errors throw a TypeError object. You'll see these when functions are called with invalid arguments.
• Runtime errors provide Error objects to the function's callback or emit an error event if no callback is provided. You'll see these when a runtime error occurs, like trying to open a bad port or setting an unsupported baud rate.

You should never have to wrap a Node-Serialport object in a try/catch statement if you call the functions with the correct arguments.

SerialPort ⏏

Kind: Exported class
Emits: open, data, close, error
Properties

new SerialPort(path, [options], [openCallback])

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.

Throws:

• TypeError When given invalid arguments, a TypeError will be thrown.

serialPort.open([callback])

Opens a connection to the given serial port.

Kind: instance method of SerialPort
Emits: open

serialPort.update([options], [callback])

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.

Kind: instance method of SerialPort

serialPort.write(data, [encoding], [callback]) ⇒ boolean

Writes data to the given serial port. Buffers written data if the port is not open.

The write operation is non-blocking. When it returns, data might still not have been written to the serial port. See drain().

Some devices, like the Arduino, reset when you open a connection to them. In such cases, immediately writing to the device will cause lost data as they wont be ready to receive the data. This is often worked around by having the Arduino send a "ready" byte that your Node program waits for before writing. You can also often get away with waiting around 400ms.

If a port is disconnected during a write, the write will error in addition to the close event.

From the stream docs write errors don't always provide the error in the callback, sometimes they use the error event.

If an error occurs, the callback may or may not be called with the error as its first argument. To reliably detect write errors, add a listener for the 'error' event.

In addition to the usual stream.write arguments (String and Buffer), write() can accept arrays of bytes (positive numbers under 256) which is passed to Buffer.from([]) for conversion. This extra functionality is pretty sweet.

Kind: instance method of SerialPort
Returns: boolean - false if the stream wishes for the calling code to wait for the 'drain' event to be emitted before continuing to write additional data; otherwise true.
Since: 5.0.0

serialPort.read([size]) ⇒ string | Buffer | null

Request a number of bytes from the SerialPort. The read() method pulls some data out of the internal buffer and returns it. If no data is available to be read, null is returned. By default, the data is returned as a Buffer object unless an encoding has been specified using the .setEncoding() method.

Kind: instance method of SerialPort
Returns: string | Buffer | null - The data from internal buffers
Since: 5.0.0

serialPort.close(callback)

Closes an open connection.

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

Kind: instance method of SerialPort
Emits: close

serialPort.set([options], [callback])

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

Kind: instance method of SerialPort
Since: 5.0.0

serialPort.get([callback])

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

Kind: instance method of SerialPort

serialPort.flush([callback])

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.

Kind: instance method of SerialPort

serialPort.drain([callback])

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

Kind: instance method of SerialPort

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.

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

serialPort.pause() ⇒

The pause() method causes a stream in flowing mode to stop emitting 'data' events, switching out of flowing mode. Any data that becomes available remains in the internal buffer.

Kind: instance method of SerialPort
Returns: this
See: module:serialport#resume
Since: 5.0.0

serialPort.resume() ⇒

The resume() method causes an explicitly paused, Readable stream to resume emitting 'data' events, switching the stream into flowing mode.

Kind: instance method of SerialPort
Returns: this
See: module:serialport#pause
Since: 5.0.0

Event: "error"

The error event's callback is called with an error object whenever there is an error.

Kind: event emitted by SerialPort

Event: "open"

The open event's callback is called with no arguments when the port is opened and ready for writing. This happens if you have the constructor open immediately (which opens in the next tick) or if you open the port manually with open(). See Useage/Opening a Port for more information.

Kind: event emitted by SerialPort

Event: "data"

The data event puts the port in flowing mode. Data is emitted as soon as it's received. Data is a Buffer object with a varying amount of data in it. The readLine parser converts the data into string lines. See the parsers section for more information on parsers, and the Node.js stream documentation for more information on the data event.

Kind: event emitted by SerialPort

Event: "close"

The close event's callback is called with no arguments when the port is closed. In the case of a disconnect it will be called with a Disconnect Error object (err.disconnected == true). In the event of a close error (unlikely), an error event is triggered.

Kind: event emitted by SerialPort

SerialPort.Binding : BaseBinding

The Binding is how Node-SerialPort talks to the underlying system. By default, we auto detect Windows, Linux and OS X, and load the appropriate module for your system. You can assign SerialPort.Binding to any binding you like. Find more by searching at npm. Prevent auto loading the default bindings by requiring SerialPort with:

  var SerialPort = require('serialport/lib/serialport');
  SerialPort.Binding = MyBindingClass;

Kind: static property of SerialPort
Since: 5.0.0

SerialPort.parsers : object

The default Parsers are Transform streams that parse data in different ways to transform incoming data.

To use the parsers, you must create them and then pipe the Serialport to the parser. Be careful to only write to the SerialPort object and not the parser.

Kind: static property of SerialPort
Since: 5.0.0
Properties

Example

const SerialPort = require('serialport');
const Readline = SerialPort.parsers.Readline;
const port = new SerialPort('/dev/tty-usbserial1');
const parser = new Readline();
port.pipe(parser);
parser.on('data', console.log);
port.write('ROBOT PLEASE RESPOND\n');

// Creating the parser and piping can be shortened to
// const parser = port.pipe(new Readline());

To use the ByteLength parser, provide the length of the number of bytes:

const SerialPort = require('serialport');
const ByteLength = SerialPort.parsers.ByteLength
const port = new SerialPort('/dev/tty-usbserial1');
const parser = port.pipe(new ByteLength({length: 8}));
parser.on('data', console.log);

To use the Delimiter parser, provide a delimiter as a string, buffer, or array of bytes:

const SerialPort = require('serialport');
const Delimiter = SerialPort.parsers.Delimiter;
const port = new SerialPort('/dev/tty-usbserial1');
const parser = port.pipe(new Delimiter({ delimiter: Buffer.from('EOL') }));
parser.on('data', console.log);

To use the Readline parser, provide a delimiter (defaults to '\n'). Data is emitted as string controllable by the encoding option (defaults to utf8).

const SerialPort = require('serialport');
const Readline = SerialPort.parsers.Readline;
const port = new SerialPort('/dev/tty-usbserial1');
const parser = port.pipe(new Readline({ delimiter: '\r\n' }));
parser.on('data', console.log);

To use the Ready parser provide a byte start sequence. After the bytes have been received data events are passed through.

const SerialPort = require('serialport');
const Ready = SerialPort.parsers.Ready;
const port = new SerialPort('/dev/tty-usbserial1');
const parser = port.pipe(new Ready({ data: 'READY' }));
parser.on('ready', () => console.log('the ready byte sequence has been received'))
parser.on('data', console.log); // all data after READY is received

To use the Regex parser provide a regular expression to split the incoming text upon. Data is emitted as string controllable by the encoding option (defaults to utf8).

const SerialPort = require('serialport');
const Regex = SerialPort.parsers.Regex;
const port = new SerialPort('/dev/tty-usbserial1');
const parser = port.pipe(new Regex({ regex: /[\r\n]+/ }));
parser.on('data', console.log);

SerialPort.list([callback]) ⇒ 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.

Kind: static method of SerialPort
Returns: Promise - Resolves with the list of available serial ports.

Example

// 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'
}

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) {...});

SerialPort~BaseBinding

You never have to use Binding objects directly. SerialPort uses them to access the underlying hardware. This documentation is geared towards people who are making bindings for different platforms. This class can be inherited from to get type checking for each method.

Kind: inner class of SerialPort
Since: 5.0.0
Properties

• ~BaseBinding
  • new BaseBinding(options)
  • instance
    • .open(path, openOptions) ⇒ Promise
    • .close() ⇒ Promise
    • .read(data, offset, length) ⇒ Promise
    • .write(data) ⇒ Promise
    • .update([options]) ⇒ Promise
    • .set([options]) ⇒ Promise
    • .get() ⇒ Promise
    • .flush() ⇒ Promise
    • .drain() ⇒ Promise
  • static
    • .list() ⇒ Promise

new BaseBinding(options)

Throws:

• TypeError When given invalid arguments, a TypeError is thrown.

baseBinding.open(path, openOptions) ⇒ Promise

Opens a connection to the serial port referenced by the path.

Kind: instance method of BaseBinding
Returns: Promise - Resolves after the port is opened and configured.
Throws:

• TypeError When given invalid arguments, a TypeError is thrown.

baseBinding.close() ⇒ Promise

Closes an open connection

Kind: instance method of BaseBinding
Returns: Promise - Resolves once the connection is closed.
Throws:

• TypeError When given invalid arguments, a TypeError is thrown.

baseBinding.read(data, offset, length) ⇒ Promise

Request a number of bytes from the SerialPort. This function is similar to Node's fs.read except it will always return at least one byte.

The in progress reads must error when the port is closed with an error object that has the property canceled equal to true. Any other error will cause a disconnection.

Kind: instance method of BaseBinding
Returns: Promise - Resolves with the number of bytes read after a read operation.
Throws:

• TypeError When given invalid arguments, a TypeError is thrown.

baseBinding.write(data) ⇒ Promise

Write bytes to the SerialPort. Only called when there is no pending write operation.

The in progress writes must error when the port is closed with an error object that has the property canceled equal to true. Any other error will cause a disconnection.

Kind: instance method of BaseBinding
Returns: Promise - Resolves after the data is passed to the operating system for writing.
Throws:

• TypeError When given invalid arguments, a TypeError is thrown.

baseBinding.update([options]) ⇒ Promise

Changes connection settings on an open port. Only baudRate is supported.

Kind: instance method of BaseBinding
Returns: Promise - Resolves once the port's baud rate changes.
Throws:

• TypeError When given invalid arguments, a TypeError is thrown.

baseBinding.set([options]) ⇒ Promise

Set control flags on an open port.

Kind: instance method of BaseBinding
Returns: Promise - Resolves once the port's flags are set.
Throws:

• TypeError When given invalid arguments, a TypeError is thrown.

baseBinding.get() ⇒ Promise

Get the control flags (CTS, DSR, DCD) on the open port.

Kind: instance method of BaseBinding
Returns: Promise - Resolves with the retrieved flags.
Throws:

• TypeError When given invalid arguments, a TypeError is thrown.

baseBinding.flush() ⇒ Promise

Flush (discard) data received but not read, and written but not transmitted.

Kind: instance method of BaseBinding
Returns: Promise - Resolves once the flush operation finishes.
Throws:

• TypeError When given invalid arguments, a TypeError is thrown.

baseBinding.drain() ⇒ Promise

Drain waits until all output data is transmitted to the serial port. An in progress write should be completed before this returns.

Kind: instance method of BaseBinding
Returns: Promise - Resolves once the drain operation finishes.
Throws:

• TypeError When given invalid arguments, a TypeError is thrown.

BaseBinding.list() ⇒ Promise

Retrieves a list of available serial ports with metadata. The comName must be guaranteed, and all other fields should be undefined if unavailable. The comName is either the path or an identifier (eg COM1) used to open the serialport.

Kind: static method of BaseBinding
Returns: Promise - resolves to an array of port info objects.

SerialPort~errorCallback : function

A callback called with an error or null.

Kind: inner typedef of SerialPort

SerialPort~modemBitsCallback : function

A callback called with an error or an object with the modem line values (cts, dsr, dcd).

Kind: inner typedef of SerialPort

SerialPort~openOptions : Object

Kind: inner typedef of SerialPort
Properties

SerialPort~listCallback : function

This callback type is called requestCallback.

Kind: inner typedef of SerialPort

Command Line Tools

If you install serialport globally (e.g., npm install -g serialport), you'll receive two command line tools.

Serial Port List

serialport-list will list all available serial ports in different formats.

$ serialport-list -h

  Usage: serialport-list [options]

  List available serial ports

  Options:

    -h, --help           output usage information
    -V, --version        output the version number
    -f, --format <type>  Format the output as text, json, or jsonline. default: text


$ serialport-list
/dev/tty.Bluetooth-Incoming-Port
/dev/tty.usbmodem1421    Arduino (www.arduino.cc)

$ serialport-list -f json
[{"comName":"/dev/tty.Bluetooth-Incoming-Port"},{"comName":"/dev/tty.usbmodem1421","manufacturer":"Arduino (www.arduino.cc)","serialNumber":"752303138333518011C1","locationId":"14200000","vendorId":"2341","productId":"0043"}]

$ serialport-list -f jsonline
{"comName":"/dev/tty.Bluetooth-Incoming-Port"}
{"comName":"/dev/tty.usbmodem1421","manufacturer":"Arduino (www.arduino.cc)","serialNumber":"752303138333518011C1","locationId":"14200000","vendorId":"2341","productId":"0043"}

Serial Port Terminal

serialport-term provides a basic terminal interface for communicating over a serial port. ctrl+c will exit.

$ serialport-term -h

  Usage: serialport-term -p <port> [options]

  A basic terminal interface for communicating over a serial port. Pressing ctrl+c exits.

  Options:

    -h, --help                     output usage information
    -V, --version                  output the version number
    -l --list                      List available ports then exit
    -p, --port, --portname <port>  Path or name of serial port
    -b, --baud <baudrate>          Baud rate default: 9600
    --databits <databits>          Data bits default: 8
    --parity <parity>              Parity default: none
    --stopbits <bits>              Stop bits default: 1
    --echo --localecho             Print characters as you type them

$ serialport-term -l
/dev/tty.Bluetooth-Incoming-Port
/dev/tty.usbmodem1421    Arduino (www.arduino.cc)

Serial Port Repl

serialport-repl provides a nodejs repl for working with serialport. This is valuable when debugging.

You can make use of the serialport-repl command with;

$ serialport-repl # to auto detect an arduino
$ serialport-repl /dev/tty.usbmodem1421 # to connect to a specific port

It will load a serialport object with debugging turned on.

  serialport:binding:auto-detect loading DarwinBinding +0ms
port = SerialPort("/dev/tty.usbmodem1421", { autoOpen: false })
globals { SerialPort, portName, port }
> SerialPort.list()
  serialport:main .list +6s
[ { comName: '/dev/tty.usbmodem1421',
    manufacturer: 'Arduino (www.arduino.cc)',
    serialNumber: '752303138333518011C1',
    pnpId: undefined,
    locationId: '14200000',
    vendorId: '2341',
    productId: '0043' } ]
> port.write('Calling all Autobots!')
true
> port.read()
  serialport:main _read queueing _read for after open +1m
null
> port.open()
  serialport:main opening path: /dev/tty.usbmodem1421 +30s
  serialport:bindings open +1ms

License

SerialPort is MIT licensed and all it's dependencies are MIT or BSD licensed.

Version 5.0.0 🎉

Nearly a year in the making Node SerialPort 5.0.0 is a major rewrite that improves stability, compatibility and performance. The api surface is similar to version 4 there have been a number of changes to ensure consistent error handling and operation of a serial port. Notably we are now a Stream! We can also introduce a bindings layer. A small low level api to provide access to underlying hardware. External bindings written in other languages or targeting other platforms can now be used.

Some major cpu performance gains on unix platforms can be found and we're less buggy and better performing on Windows too.

With this release we are now only supporting LTS nodejs platforms and we are dropping NodeJS 0.10, 0.12, 5 and 7 support. We loved directly supporting so many platforms but it was getting in the way making a solid library.

See our upgrade guide for detail on what to change to upgrade your app to use `serialport@5.0.0`. It's not much!

Thank you to the 25 people who committed code and documentation and every person who submitted bug reports and tested changes!

Notable Changes

• [all] Streams rewrite, node serialport is now a node stream! 🎉
• [all] Drop NodeJS 0.10, 0.12, 5, and 7 support
• [all] Add node 8 support (we now only support LTS node versions)
• [all] Introduce a binding layer to provide a common low level interface to work with different platforms.
• [unix] New read/write subsystem. Write CPU dropped from 100% to 0-2%. @reconbot (Thanks to @indutny for getting me unstuck many times!)
• [windows] Rewrite reading so it's pausable thanks to @munyirik
• [docs] An overhaul how we document the api leveraging JSDOC
• [docs] An overhaul of the format and language in our docs thanks to @LappleApple

Features

• [all] isOpen is now a property #899
• [all] SerialPort.list now has more consistent output across all platforms.
• [all] SerialPort.list returns a promise if a callback is not provided thanks to @MikeKovarik for bug fixes
• [all] A promise aware serialport-repl script for debugging and testing.
• [all] add #get to retrieve modem status flags thanks to @jgillick!
• [all] Add a MockBinding object for testing serialports in your project. Used internally too!
• [all] Add electron precompiled binaries thanks to @Mike-Dax
• [all] Add regex stream parser and tests @jessicaquynh
• [all] Allow reopening after an open error #910
• [all] calls to .drain now queue behind port open and in progress writes reported by and with lots of testing help from @tuna-f1sh
• [all] Change parsers to be transform streams #922
• [all] Change the default highWaterMark to 64k to match fs.ReadStream
• [all] Conform to NodeJS error message formats
• [all] Exposed mocking serialport via require('serialport/test')
• [all] Have drain wait for pending JS write operations before calling system drain thanks to @digitalhack for reporting it
• [all] port.path is now read only #898
• [all] Refactor internals to make use of es6 and promises
• [all] Remove lowercase options #898
• [all] Remove the c++ write queue
• [all] Remove unnecessary dependencies and polyfills thanks to @mscdex
• [all] Remove v8 deprecation warnings thanks to @indutny again
• [all] Removed the disconnect event. The close event now fires with a disconnect error object in the event of a disconnection.
• [all] SerialPort can now be compressed with uglify-es thanks to @rwaldron
• [all] update bindings to version 1.3.0
• [all] Upgrade debug and node-pre-gyp
• [all] Upgrade to non deprecated buffer methods
• [docs] Add more installation notes on sudo, windows 10, electron and node 7
• [docs] Add socketio example @jessicaquynh
• [docs] Electron build docs #965 via @chalkers
• [docs] Mark new features in 5.0.0 with the fact they started in 5.0.0
• [docs] Update parser docs to be correct #970 via @jacobq
• [linux] SerialPort.list is now faster and less resource intensive thanks to @akaJes!
• [linux] Add the ttyAP subsystem to serialport list thanks to @fly19890211 for reporting it
• [osx] SerialPort.list now returns the tty instead of the cu thanks to @kishinmanglani
• [unix] Flush now gives errors and flushes tx and rx #900
• [unix] Move setting up the baudrate to the end of the open() to better support custom baudrates
• [windows] Refactoring of .list for Windows so it's significantly smaller thanks to @Zensey

Fixes

• [all] Fix baud rate parsing in serialport-terminal thanks to @radio-miskovice for reporting it!
• [all] Fix memory leak during opening a port thanks to @indutny
• [all] fixed a crash when pausing while reading thanks to @bminer and @baffo32 and others to debug and fix this
• [all] Upgrade nan to fix compile issues on some platforms thanks to @thom-nic
• [docs] fixed a typo thanks to @amilajack
• [docs] Spelling fixes via @Awk34
• [unix] fix a bug when poller errors would be unhandled thanks to @thiago-sylvain for reporting
• [windows] Fix file handle leak during opens when errors occur thanks to @enami
• [windows] Fix flush behavior using PurgeComm fixing #962 via @samisaham
• [windows] Fix unhandled promise rejection when calling read on Windows
• [windows] Remove read and write timeouts solving #781 via @giseburt

We also had help testing, debugging, and designing from; @alaq @arve0 @techninja @noopkat @HipsterBrown and more!

Version 4.0.7

• [all] Fix baud rate parsing in serialport-terminal thanks to @radio-miskovice for reporting it!
• [windows] Refactor SerialPort.list to be a lot smaller and pickup vendorId, productId and locationId thanks to @zensey for #877!

Version 4.0.6

• [all] Upgrade nan to fix compile issues on some platforms thanks to @thom-nic
• [all] Upgrade debug and node-pre-gyp

Version 4.0.5

• [windows] Fix file handle leak during opens when errors occur thanks to @enami
• [all] Fix memory leak during opening a port thanks to @indutny

Version 4.0.4

• Add precompiled binaries for node 7

Version 4.0.3

• Switch to the lie promise library as it's smaller and mimics nodejs's promise closer
• Fix a bug that prevented reopening a port after an open error

Version 4.0.2

• [unix] Fix a bug when we'd crash when pausing during a read

Version 4.0.1

• [linux] Do not replace the native Promise when it is available thanks to @zewish for the fix

Version 4.0.0

• Requiring serialport now returns the SerialPort constructor function instead of a factory object. SerialPort.SerialPort is now deprecated.
• SerialPort constructor now throws on argument errors immediately.
• .write(writeCallback) now only calls it's callback once after the entire write operation, it used to be called for each write cycle and return the bytes written. This reduces the number of callbacks by hundreds of thousands over a megabyte at low bandwidth.
• Disconnections now always attempt to close the port, and you'll always get a close event after a disconnect event
• All callbacks are called in the context of the port, this now equals the port.
• Removed openImmediately from the constructor's api, the functionality is now named autoOpen on the options object.
• Removed extraneous flow control settings from the flowControl option, use the specific options to set these flags now.
• Removed undocumented callbacks from the options object disconnectedCallback and dataCallback
• Renamed serialportlist to serialport-list
• Renamed serialportterm to serialport-term
• Added a contributors guide
• Added our first Arduino required integration tests
• [unix] .drain and .set now properly report errors
• [unix] Ports are now locked by default with the new lock options matches windows default behavior
• [windows] .update() now supports windows for changing baud rates
• [windows] Fixed a bug where we weren't properly opening ports (provides better support virtual com ports too) thanks to @RogerHardiman
• [windows] known issue lock: false doesn't work (no change in behavior)

Version 3.1.2

• Documentation around "Illegal Instruction" errors
• Resolve some ambiguities around publishing that was causing some issues on some versions and platforms of npm and node
• [linux] bug fix in .list() where we weren't filtering out non block devices that are named like serial ports
• [unix] Better unix error messages
• [unix] Refactor setBaudrate for Unix making it easier for custom baudRate support
• [unix] Update now has less memory leaks, documentation and better error messages
• [windows] Better error messages for opening ports

Version 3.1.1

• fix an issue with bundled deps for node-pre-gyp on npm

Version 3.1.0

• Upgrade nan and fix warnings for node 6.0
• Update the cli tools. serialport-term can now list ports, serialport-list can now output in different formats

Version 3.0.1

• Change from BlueBird to es6-promise to save 9.5MB from the package size (19M -> 9.5) and 130k bundle size (186.1kb -> 55.2kb)
• Experimental node 6 support

Version 3.0.0

• close and disconnect events no longer call removeAllListeners and removes your event listeners. This was particularly bad for the error event. This is the only change and if you didn't have a special code to deal with this behavior you should probably upgrade from v2.1.2

Version 2.1.2

• Start bundling node-pre-gyp but upgrade it to the latest as the previous version doesn't install

Version 2.1.1

• .list errors are consistent across platforms and no longer has blocking statSync calls
• Stop bundling node-pre-gyp to prevent issues when it's already installed
• Internal restructuring

Version 2.1.0

• Major refactor, bug fixes and docs improvements thanks to @ecksun, @fivdi, @gfcittolin, @jacobrosenthal, @mhart, @nebrius, @pabigot, @paulkaplan, @reconbot, @rodovich, @rwaldron, @sayanee, @tigoe and everyone who reported and helped debug issues!
• Fix binary paths to confirm with modern standards
• Integration tests on CI's that support it or for the folks at home with an arduino handy
• Upgrade to nan-2.2.1 for memory leak fixes and node 6 compatibility (still not supported)
• Confirm nw.js and electron compatibility
• Make the outpout of .list consistent between platforms and docs
• Define ambiguous flow control flags and document them
• Fix support systems who provide 0 as a valid file descriptor
• Fix race conditions when opening and closing ports that led to errors while reading and writing while closing or opening the port.
• [unix] Fix a double open bug on unix that would cause opening and closing ports repetitively to error.
• [unix] Listing serialports on linux now include more ports (including bluetooth devices eg. /dev/rfcommXX) and have less bugs in the output
• [windows] Remove deprecated BuildCommDCB for windows 10 support
• [windows] Fix a memory leak on windows
• [windows] Fix a 100% cpu and possible hang bug when ports were disconnected on windows.

Version 2.0.6

• Add 5.x build to matrix, thanks @deadprogram
• Re add nmpignore, thanks @rwaldron
• Swap to upstream version of node-pre-gyp-github

Version 2.0.5

• Fix linux port listing crash since 2.0.3 refactor, thanks @monkbroc

Version 2.0.4

• Fix heap corruption issue affecting windows users since 2.0.0, thanks @kunalspathak

Version 2.0.3

• Move node-pre-gyp binaries away from Amazon S3 to Github Releases page
• Fix for missing node-pre-gyp binaries, especially for windows users, since the 2.0.0 refactor which forced windows users to build from source -- generally failing due to lack of dependencies
• Unix port listing moved away from udev which was not available on all platforms, to whitelisting ttyS ttyACM ttyUSB ttyAMA devices, see #610

Version 2.0.2

• Cleanup minor Unix gcc warnings, Thanks @rwaldron

Version 2.0.1

• El Capitan Support, thanks @tmpvar

Version 2.0.0

• Upgrade to NAN2 to support Node 4 support. Technically not api breaking, though NAN2 requires gcc 4.8 which for Pi Wheezy users at the very least, would be breaking. For those affected users looking to utilize serialport 2.x.x and Node 4 see https://github.com/fivdi/onoff/wiki/Node.js-v4-and-native-addons

Version 1.7.4

• Fix OSX 10.10 build errors

Version 1.7.3

• Fix OSX 10.10 build errors

Version 1.7.2

• Fix OSX 10.10 build errors

Version 1.7.1

• Fixed breaking issues in underlying code. (@voodootikigod)

Version 1.7.0

• Fix for #518 and #498 If you pass to SerialPort function (constructor) the same object for argument "options", inside SerialPort will use it as internal object and adds handlers to it. That causes only one callback to work on different SerialPort instances. (@bullmastiffo)
• Update README.md #515 (@arahlf)
• Fix a memory leak in SerialportPoller::New (@jpilet)
• unix support for update baudrate #502 (@jacobrosenthal)
• set cloexec after open, possible fix for #468 (@jacobrosenthal)
• Added hang up on close option to constructor. #495 (@jbendes)
• Upgraded NAN to 1.8.4 due to complaints from io.js 2.x users. (@imyller)

Version 1.6.1

• Upgraded to NAN 1.7.0

• 476 adding break signal

Version 1.6.0

• Long standing issue resolved thanks to @jacobrosenthal for adding control signals into the serialport. YAY!
• Fix for #426
• Ability to return from inside loop #453
• Emits for close/disconnect. #452

Version 1.5.0

• Fixed to work with io.js and node 0.11.x by upgrading to recent nan 1.6.2

Version 1.4.8

• Simple bump for the binary.

Version 1.4.7

• Fix for Issue #398 - Dropped sent characters on OSX and Linux
• Fix for Issue #387 - added isOpen
• removed a residual comment
• Added osx control signalling
• Fix for Issue #401
• Fix for double write callbacks.
• detect a serialport disconnect on linux.

Version 1.4.6

• Emit error on serialport when explicit handler present. Fixes gh-369
• Fix for windows and Node 0.11.13 (atom-shell)
• Fix for broken Travis-CI build.

Version 1.4.5

• Identified and report issue to node.js core about recent 0.11.x system.
• Removed support for 0.8.x
• Updated dependencies

Version 1.4.4

• Fix for delete error.

Version 1.3.0

• Merged NAN integration for Node 0.8->0.11+ compatibility (#270)

Version 1.2.5

• Fixed an issue with pool handlers being global instead of instance isolation (Issue #252 and #255 thanks: foobarth !!! )

Version 1.2.4

• Resolved parity error under linux as reported here: https://github.com/voodootikigod/node-serialport/issues/219

Version 1.1.3

• Remove ATL dependency on Windows (added Visual Studio Pro requirement)
• Update build instructions
• Four small bugfixes

Version 1.0.7

• Guaranteed in-order delivery of messages thanks to Jay Beavers and bnoordhuis

Version 1.0.6

• Support higher baud rates in Mac OS X

Version 1.0.5

• Added flush support.

Version 1.0.4

• Fix for arduino firmata support on windows thanks to @jgautier.

Version 1.0.3

• Fixed issue 65 - https://github.com/voodootikigod/node-serialport/issues/65
• Added note in readme about what is required for the system to be able to compile module, should solve 90% of issues.

Version 1.0.2

• Fixed issue 59 - https://github.com/voodootikigod/node-serialport/issues/59

Version 1.0.1

• Fixed items from Firmata
• Added flexibility for options (camelcase or all lower)

Version 1.0.0

• Added Windows support thanks to Joe Ferner.
• Merged in the various underlying changes from node-serialport2 complete thanks to Joe Ferner for that!
• Verified against known installations.

Version 0.6.5

• Added SetBaudRate, SetDTR; Custom Baud Rates
• New "close" listener when device being disconnected

Version 0.2.8

• BufferSize fix for readstream (thanks jgautier, you rock)

Version 0.2.7

• Make no port available be an exception not error emitted - Ticket #12.

Version 0.2.5 - Version 0.2.6

• Debugging issue with IOWatcher not holding in the event loop in node.js.
• Converted to ReadStream instead of IOWatcher.

Version 0.2.4

• Integrated arduino tests (rwaldron)
• Integrated options bug fix (w1nk)
• Integrated hardware flow control for crazier serial port action (w1nk)

Version 0.2.3

• Something amazing that has since been lost and forgotten.

Version 0.2.2

• Integrated enhanced version of arduino/readline that actually buffers the data (epeli)

Version 0.2.1

• Refactored the parsing code upon data receipt, now allows for dynamic specification of how incoming data is handled.
• Revised creation interface to use named parameters as an object versions positional parameters.

Version 0.2.0

• Upgraded to node v. 0.4.X compatibility

All other version are not recorded.