Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

bc-serialport

Welcome your robotic javascript overlords. Better yet, program them!

readme

Build Status Gitter chat Dependency Status

For all discussions, designs, and clarifications, we recommend you join our Gitter Chat room: https://gitter.im/voodootikigod/node-serialport


Imagine a world where you can write JavaScript to control blenders, lights, security systems, or even robots. Yes, I said robots. That world is here and now with node-serialport. It provides a very simple interface to the low level serial port code necessary to program Arduino chipsets, X10 wireless communications, or even the rising Z-Wave and Zigbee standards. The physical world is your oyster with this goodie. For a full break down of why we made this, please read NodeBots - The Rise of JS Robotics.


For getting started with node-serialport, we recommend you begin with the following articles:

To Install

For most "standard" use cases (node v0.10.x on mac, linux, windows on a x86 or x64 processor), node-serialport will install nice and easy with a simple

npm install serialport

Installation Special Cases

We are using 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 are on a special case, node-serialport will work, but it will compile the binary when you install.

This assumes you have everything on your system necessary to compile ANY native module for Node.js. This may not be the case, though, so please ensure the following are true for your system before filing an issue about "Does not install". For all operatings systems, please ensure you have Python 2.x installed AND not 3.0, node-gyp (what we use to compile) requires Python 2.x.

Windows:

  • Windows 7 or Windows 8.1 are supported.
  • Install Visual Studio Express 2013 for Windows Desktop.
  • If you are hacking on an Arduino, be sure to install the drivers.
  • Install node.js matching the bitness (32 or 64) of your operating system.
  • Install Python 2.7.6 matching the bitness of your operating system. For any questions, please refer to their FAQ. Default settings are perfect.
  • Open the 'Visual Studio Command Prompt' and add Python to the path.

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.

Desktop (Debian/Ubuntu) Linux:

You know what you need for you system, basically your appropriate analog of build-essential. Keep rocking! Ubuntu renamed the node binary nodejs which can cause problems building node-serialport. The fix is simple, install the nodejs-legacy package that symlinks /usr/bin/nodejs => /usr/bin/node or install the more up to date nodejs package from Chris Lea's PPA.

# Ubuntu node
sudo apt-get install nodejs nodejs-legacy

# Or Chris Lea's PPA Node (more up to date)
sudo add-apt-repository ppa:chris-lea/node.js
sudo apt-get update
sudo apt-get install nodejs

sudo apt-get install build-essential
npm install serialport

Raspberry Pi Linux:

  • Starting with a a vanilla New Out of the Box Software (NOOBS) Raspbian image
  • Log into your Raspberry Pi through whatever means works best and ensure you are on a terminal prompt for the remaining steps. This could be local or through an SSH (or a serial connection if you like).
  • Issue the following commands to ensure you are up to date:
   sudo apt-get update
   sudo apt-get upgrade -y
  • Download and install node.js:
   wget https://node-arm.herokuapp.com/node_archive_armhf.deb
   sudo dpkg -i node_archive_armhf.deb

More information can be found at node-arm.

  • Install using npm, note this will take a while as it is actually compiling code and that ARM processor is getting a workout.
   npm install serialport

To Use

Opening a serial port:

var SerialPort = require("serialport").SerialPort
var serialPort = new SerialPort("/dev/tty-usbserial1", {
  baudrate: 57600
});

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

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

open event

You MUST wait for the open event to be emitted before reading/writing to the serial port. The open happens asynchronously so installing 'data' listeners and writing before the open event might result in... nothing at all.

Assuming you are connected to a serial console, you would for example:

serialPort.on("open", function () {
  console.log('open');
  serialPort.on('data', function(data) {
    console.log('data received: ' + data);
  });
  serialPort.write("ls\n", function(err, results) {
    console.log('err ' + err);
    console.log('results ' + results);
  });
});

You can also call the open function, in this case instantiate the serialport with an additional flag.

var SerialPort = require("serialport").SerialPort
var serialPort = new SerialPort("/dev/tty-usbserial1", {
  baudrate: 57600
}, false); // this is the openImmediately flag [default is true]

serialPort.open(function (error) {
  if ( error ) {
    console.log('failed to open: '+error);
  } else {
    console.log('open');
    serialPort.on('data', function(data) {
      console.log('data received: ' + data);
    });
    serialPort.write("ls\n", function(err, results) {
      console.log('err ' + err);
      console.log('results ' + results);
    });
  }
});

List Ports

You can also list the ports along with some metadata as well.

var serialPort = require("serialport");
serialPort.list(function (err, ports) {
  ports.forEach(function(port) {
    console.log(port.comName);
    console.log(port.pnpId);
    console.log(port.manufacturer);
  });
});

Parsers

Out of the box, node-serialport provides two parsers one that simply emits the raw buffer as a data event and the other which provides familiar "readline" style parsing. To use the readline parser, you must provide a delimiter as such:

var serialport = require("serialport");
var SerialPort = serialport.SerialPort; // localize object constructor

var sp = new SerialPort("/dev/tty-usbserial1", {
  parser: serialport.parsers.readline("\n")
});

To use the raw parser, you just provide the function definition (or leave undefined):

var serialport = require("serialport");
var SerialPort = serialport.SerialPort; // localize object constructor

var sp = new SerialPort("/dev/tty-usbserial1", {
  parser: serialport.parsers.raw
});

You can get updates of new data from the Serial Port as follows:

serialPort.on("data", function (data) {
  sys.puts("here: "+data);
});

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

serialPort.write("OMG IT WORKS\r");

Enjoy and do cool things with this code.

Reference Guide

Methods

SerialPort (path, options, openImmediately, callback)

Create a new serial port on path.

path

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

options (optional)

Port configuration options.

  • baudRate Baud Rate, defaults to 9600. Should be one of: 115200, 57600, 38400, 19200, 9600, 4800, 2400, 1800, 1200, 600, 300, 200, 150, 134, 110, 75, or 50. Custom rates as allowed by hardware is supported.
  • dataBits Data Bits, defaults to 8. Must be one of: 8, 7, 6, or 5.
  • stopBits Stop Bits, defaults to 1. Must be one of: 1 or 2.
  • parity Parity, defaults to 'none'. Must be one of: 'none', 'even', 'mark', 'odd', 'space'
  • rtscts
  • xon
  • xoff
  • xany
  • flowControl
  • bufferSize Size of read buffer, defaults to 255. Must be an integer value.
  • parser The parser engine to use with read data, defaults to rawPacket strategy which just emits the raw buffer as a "data" event. Can be any function that accepts EventEmitter as first parameter and the raw buffer as the second parameter.
  • encoding
  • dataCallback
  • disconnectedCallback
  • platformOptions - sets platform specific options, see below.

Note, we have added support for either all lowercase OR camelcase of the options (thanks @jagautier), use whichever style you prefer.

Unix Platform Options

An object with the following properties:

openImmediately (optional)

Attempts to open a connection to the serial port on process.nextTick. The default is true. Set to false to manually call open() at a later time, but note you'll need to use factory error listener in the case of constructor errors.

callback (optional)

Called when a connection has been opened. The callback should be a function that looks like: function (error) { ... }

.open (callback)

Opens a connection to the given serial port.

callback (optional)

Called when a connection has been opened. NOTE: Will NOT be called if openImmediately is set to false as open will not be performed. The callback should be a function that looks like: function (error) { ... }

.isOpen()

Returns true if the port is open.

.write (buffer, callback)

Writes data to the given serial port.

buffer

The buffer parameter accepts a Buffer object, or a type that is accepted by the Buffer constructor (ex. an array of bytes or a string).

callback (optional)

Called once the write operation returns. The callback should be a function that looks like: function (error) { ... } Note: The write operation is non-blocking. When it returns, data may still have not actually been written to the serial port. See drain().

.pause ()

Pauses an open connection.

.resume ()

Resumes a paused connection.

.flush (callback)

Flushes data received but not read. See tcflush() for Mac/Linux and FlushFileBuffers for Windows.

callback (optional)

Called once the flush operation returns. The callback should be a function that looks like: function (error) { ... }

.drain (callback)

Waits until all output data has been transmitted to the serial port. See tcdrain() for more information.

callback (optional)

Called once the drain operation returns. The callback should be a function that looks like: function (error) { ... }

Example

Writes data and waits until it has finish transmitting to the target serial port before calling the callback.

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

.close (callback)

Closes an open connection.

callback (optional)

Called once a connection is closed. Closing a connection will also remove all event listeners. The callback should be a function that looks like: function (error) { ... }

Events

.on('open', callback)

.on('data', callback)

.on('close', callback)

.on('error', callback)

   


   

changelog

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

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

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

Version 1.0.2

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

  • Upgraded to node v. 0.4.X compatibility

All other version are not recorded.