For support you can open a github issue, for discussions, designs, and clarifications, we recommend you join our Gitter Chat room
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:
- Arduino Node Security Sensor Hacking - A great all around "how do I use this" article.
- NodeBots - The Rise of JS Robotics - A survey article of why one would want to program robots in JS.
- Johnny-Five - The Johnny-Five Robotics and IoT library's introduction "Hello Johnny" (awesome).
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
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 7, Windows 8.1, and Windows 10 are supported.
- Might just download and install with no extra steps. If the downloaded binary fails you'll have to build it with the following steps.
- 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.
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.
You know what you need for your 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
Alpine is a (very) small distro, but it uses the musl standard library instead of glibc (that most other Linux distros use), so it requires compilation.
# 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=serialport
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.
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).
- Path to Serial Port - required.
- Options - optional and described below.
Constructing a SerialPort
object will open a port, eventually. You can bind events while the port is opening but you must wait until it is open to write()
to it. (Most port functions require an open port.) You can call code when a port is opened in three ways.
- The
open
event is always emitted when the port is opened - The constructor callback is called when the port is opened and you haven't disabled the
openImmediately
option, if you have disabled it, the callback is only used for errors. - The
.open()
function takes a callback that is called when the port is opened. This can be used if you disabled theopenImmediately
option or have previously closed an open port.
var SerialPort = require('serialport').SerialPort;
var port = new SerialPort('/dev/tty-usbserial1');
port.on('open', function () {
port.write('main screen turn on', function(err, bytesWritten) {
if (err) {
return console.log('Error: ', err.message);
}
console.log(bytesWritten, 'bytes written');
});
});
This could be moved to the constructor's callback.
var SerialPort = require('serialport').SerialPort;
var port = new SerialPort('/dev/tty-usbserial1', function () {
port.write('main screen turn on', function(err, bytesWritten) {
if (err) {
return console.log('Error: ', err.message);
}
console.log(bytesWritten, 'bytes written');
});
});
When disabling the openImmediately
flag you'll need to open the port on your own. Note, in order to disable the openImmediately
flag, we have to pass an options object.
var SerialPort = require('serialport').SerialPort;
var port = new SerialPort('/dev/tty-usbserial1', {}, false);
port.open(function (err) {
if (err) {
return console.log('Error opening port: ', err.message);
}
// errors will be emitted on the port since there is no callback to write
port.write('main screen turn on');
});
.list(callback)
Retrieves a list of available serial ports with metadata.
callback
is a required function that looks should look like:function (err, ports) { ... }
.ports
will be an array of objects with port info. Only thecomName
is guaranteed, all the other fields undefined if unavailable. ThecomName
is either the path or identifier (egCOM1
) used to open the serialport.
// example port information
{
comName: '/dev/cu.usbmodem1421',
manufacturer: 'Arduino (www.arduino.cc)',
serialNumber: '757533138333964011C1',
pnpId: undefined,
locationId: '0x14200000',
vendorId: '0x2341',
productId: '0x0043'
}
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);
});
});
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;
var port = 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;
var port = new SerialPort('/dev/tty-usbserial1', {
parser: serialport.parsers.raw
});
You can get updates of new data from the Serial Port as follows:
port.on('data', function (data) {
console.log('Data: ' + data);
});
You can write to the serial port by sending a string or buffer to the write method as follows:
port.write('Hi Mom!');
port.write(new Buffer('Hi Mom!'));
Enjoy and do cool things with this code.
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
defaults to falsexon
defaults to falsexoff
defaults to falsexany
defaults to falseflowControl
true
forrtscts
or an array with one or more of the following strings to enable themxon
,xoff
,xany
,rtscts
. Overwrites any individual settings.bufferSize
Size of read buffer, defaults to 65536. 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.platformOptions
- sets platform specific options, see below.
These properties are ignored for windows. An object with the following properties:
vmin
(default: 1) - seeman termios
vtime
(default: 0) - seeman termios
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) { ... }
Note: The callback will NOT be called if openImmediately is set to false as the open will not be performed.
Opens a connection to the given serial port.
callback (optional)
Called when a connection has been opened. The callback should be a function that looks like: function (error) { ... }
Returns true
if the port is open.
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, bytesWritten) { ... }
Note: The write operation is non-blocking. When it returns, data may still have not actually been written to the serial port. See drain()
.
Note: Some devices like the Arduino reset when you open a connection to them. In these cases if you immediately write to the device 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.
Pauses an open connection.
Resumes a paused connection.
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) { ... }
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);
});
}
Closes an open connection.
callback (optional)
Called once a connection is closed. The callback should be a function that looks like: function (error) { ... }
If called without an callback and there is an error, an error event will be emitted.
Note: Currently closing a connection will also remove all event listeners.
Sets flags on an open port. Uses SetCommMask
for windows and ioctl
for mac and linux.
options (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 will be used.
brk
optional boolean, defaults to falsects
optional boolean, defaults to falsedsr
optional boolean, defaults to falsedtr
optional boolean, defaults to truerts
optional boolean, defaults to true
callback (optional)
callback: function(err, results)
Called once the port's flags have been set. results
are the return of the underlying system command. If .set
is called without an callback and there is an error, an error event will be emitted.
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/Open Event for more information.
Callback is called with data depending on your chosen parser. The default raw
parser will have a Buffer
object with a varying amount of data in it. The readLine
parser will provide a string of your line. See the parsers section for more information
Callback is called with no arguments when the port is closed. In the event of an error, an error event will be triggered
Callback is called with an error object whenever there is an error.
Callback is called with an error object.
Note: Currently disconnections will also remove all event listeners on some platforms.
If you install serialport
globally. (eg, npm install -g serialport
) you'll receive two command line tools.
serialportlist
will list all available serialports
serialportterm
provides a basic terminal interface for a serialport. ctrl+c
will exit.