ms-iot/node-serialport

Name: node-serialport

Owner: ms-iot

Description: Node.js package to access serial ports for reading and writing OR Welcome your robotic JavaScript overlords. Better yet, program them!

Created: 2015-09-01 21:35:23.0

Updated: 2017-04-07 18:12:05.0

Pushed: 2016-09-23 15:11:43.0

Homepage:

Size: 1257

Language: C++

GitHub Committers

UserMost Recent Commit# Commits

Other Committers

UserEmailMost Recent Commit# Commits

README

Node Serialport

npm Gitter chat Dependency Status Dependency Status Coverage Status Build Status Build status

For support you can open a github issue, for discussions, designs, and clarifications, we recommend you join our Gitter Chat room. We have two related projects Browser Serialport “just like Node Serialport but for browser apps”, and Serialport Test Piliot which helps us test serialport.

If you'd like to contribute please take a look at contribution guide and code of conduct. You also might want to see the road map. 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 your PR is merged.

Which version of Serialport would you like documentation for?

You're reading the README for the master branch of serialport. You probably want to be looking at the README of our latest release. See our change log for what's new and our upgrade guide for a walk through on what to look out for between major versions.

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:

Platform Support

serialport supports and tests against the following platforms, architectures and node versions.

| Platform / Arch | Node v0.10.x | Node v0.12.x | Node v4.x | Node v6.x | | — | — | — | — | — | | Linux / ia32 | ? | ? | ? | ? | | Linux / x64 | ? | ? | ? | ? | | Linux / ARM v6¹ | ? | ? | ? | ? | | Linux / ARM v7¹ | ? | ? | ? | ? | | Linux / ARM v8¹ | ? | ? | ? | ? | | Linux / MIPSel¹ | ? | ? | ? | ? | | Linux / PPC64¹ | ? | ? | ? | ? | | Windows² / x86 | ? | ? | ? | ? | | Windows² / x64 | ? | ? | ? | ? | | OSX³ / x64 | ? | ? | ? | ? |

¹ ARM, MIPSel and PPC64¹ platforms are known to work but are not currently part of our test or build matrix. #846 ARM v4 and v5 was dropped from NodeJS after Node v0.10.

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

³ OSX 10.4 Tiger and above are supported but only 10.9.5 Mavericks with Xcode 6.1 is tested in our CI.

Installation Instructions

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

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 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.

Ubuntu/Debian Linux

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

The package build-essential is necessary to compile serialport. If there's a binary for your platform you won't need it. Keep rocking!

ing Ubuntu and node 6
 -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
 apt-get install -y nodejs

ing Debian and node 6, as root
 -sL https://deb.nodesource.com/setup_6.x | bash -
get install -y nodejs
Alpine Linux

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.

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

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

en we can install serialport, forcing it to compile
install serialport --build-from-source=serialport
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.

| Revision | CPU | Arm Version | | —- | — | — | | A, A+, B, B+ | 32-bit ARM1176JZF-S | ARMv6 | | Compute Module | 32-bit ARM1176JZF-S | ARMv6 | | Zero | 32-bit ARM1176JZF-S | ARMv6 | | B2 | 32-bit ARM Cortex-A7 | ARMv7 | | B3 | 32-bit ARM Cortex-A53 | ARMv8 |

Illegal Instruction

The pre-compiled binaries assume a fully capable chip. The Galileo 2 for example lacks a few instruction sets from the ia32 architecture. A few other platforms have similar issues. So if you get Illegal Instruction when trying to run serialport you'll need to rebuild the serialport binary by asking npm to rebuild it.

ll ask npm to build serialport during install time
install serialport --build-from-source

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

 leave out the package name to rebuild everything.
rebuild --build-from-source
License

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

Usage

Opening a serial port:

SerialPort = require("serialport");
port = new SerialPort("/dev/tty-usbserial1", {
udRate: 57600

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

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

Constructing a SerialPort object will open a port on nextTick. 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.

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

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


pen errors will be emitted as an error event
.on('error', function(err) {
nsole.log('Error: ', err.message);

This could be moved to the constructor's callback.

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

rt.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.

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

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


 write errors will be emitted on the port since there is no callback to write
rt.write('main screen turn on');


he open event will always be emitted
.on('open', function() {
 open logic

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

.on('data', function (data) {
nsole.log('Data: ' + data);

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

.write('Hi Mom!');
.write(new Buffer('Hi Mom!'));

Enjoy and do cool things with this code.

SerialPort ?

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

| Name | Type | Description | | — | — | — | | path | string | The system path or name of the serial port. Read Only. | | isOpen | boolean | true if the port is open, false otherwise. Read Only. |

-

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. This can be disabled by setting the option autoOpen to false.

Throws:

| Param | Type | Description | | — | — | — | | path | string | The system path of the serial port to open. For example, /dev/tty.XXX on Mac/Linux or COM1 on Windows. | | [options] | openOptions | Port configuration options | | [openCallback] | errorCallback | Called when a connection has been opened. If this is not provided and an error occurs, it will be emitted on the ports error event. The callback will NOT be called if autoOpen is set to false in the openOptions as the open will not be performed. |

-

serialPort.open([callback])

Opens a connection to the given serial port.

Kind: instance method of SerialPort
Emits: open

| Param | Type | Description | | — | — | — | | [callback] | errorCallback | Called when a connection has been opened. If this is not provided and an error occurs, it will be emitted on the ports error event. |

-

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

| Param | Type | Description | | — | — | — | | [options] | object | Only baudRate is currently supported | | [options.baudRate] | number | The baud rate of the port to be opened. This should match one of commonly available baud rates, such as 110, 300, 1200, 2400, 4800, 9600, 14400, 19200, 38400, 57600, 115200. There is no guarantee, that the device connected to the serial port will support the requested baud rate, even if the port itself supports that baud rate. | | [callback] | errorCallback | Called once the port's baud rate has been changed. If .update is called without an callback and there is an error, an error event will be emitted. |

-

serialPort.write(data, [callback])

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.

Kind: instance method of SerialPort

| Param | Type | Description | | — | — | — | | data | string | array | buffer | Accepts a Buffer object, or a type that is accepted by the Buffer constructor (ex. an array of bytes or a string). | | [callback] | errorCallback | Called once the write operation returns. |

-

serialPort.pause()

Pauses an open connection (unix only)

Kind: instance method of SerialPort

-

serialPort.resume()

Resumes a paused connection (unix only)

Kind: instance method of SerialPort

-

serialPort.close(callback)

Closes an open connection

Kind: instance method of SerialPort
Emits: close

| Param | Type | Description | | — | — | — | | callback | errorCallback | Called once a connection is closed. |

-

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

Sets flags on an open port. Uses SetCommMask for windows and ioctl for mac and linux.

Kind: instance method of SerialPort

| Param | Type | Default | Description | | — | — | — | — | | [options] | object | | 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. | | [options.brk] | Boolean | false | | | [options.cts] | Boolean | false | | | [options.dsr] | Boolean | false | | | [options.dtr] | Boolean | true | | | [options.rts] | Boolean | true | | | [callback] | errorCallback | | Called once the port's flags have been set. |

-

serialPort.flush([callback])

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

Kind: instance method of SerialPort

| Param | Type | Description | | — | — | — | | [callback] | errorCallback | Called once the flush operation finishes. |

-

serialPort.drain([callback])

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

Kind: instance method of SerialPort

| Param | Type | Description | | — | — | — | | [callback] | errorCallback | Called once the drain operation returns. |

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

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

-

Event: "data"

The data event's callback is called received data as it's received. If you're using a parser you want to use your parser's data event or read() function. Data will be a Buffer object with a varying amount of data in it. The readLine parser will provide a string of a received ASCII or UTF8 line. See the parsers section for more information.

Kind: event emitted by SerialPort

-

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: "disconnect"

The disconnect event's callback is called with an error object. This will always happen before a close event if a disconnection is detected.

Kind: event emitted by SerialPort

-

Event: "close"

The close event's callback is called with no arguments when the port is closed. In the event of an error, an error event will be triggered

Kind: event emitted by SerialPort

-

SerialPort.parsers : object

The default Parsers are Transform streams that will parse data in a variety of ways and can be used to process incoming data.

To use any of the parsers you need to create them and then pipe the serialport to the parser. Be sure not to write to the parser but to the SerialPort object.

Kind: static property of SerialPort
Properties

| Name | Type | Description | | — | — | — | | ByteLength | Class | is a transform stream that emits data each time a byte sequence is received. | | Delimiter | Class | is a transform stream that emits data as a buffer after a specific number of bytes are received. | | ReadLine | Class | is a transform stream that emits data after a newline delimiter is received. |

Example

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

reating the parser and piping can be shortened to
parser = port.pipe(new ReadLine());

To use the byte length parser, you must provide the length of the number of bytes:

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

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

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

To use the ReadLine parser, you may provide a delimiter (defaults to '\n')

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

-

SerialPort.list : function

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

Kind: static property of SerialPort

| Param | Type | | — | — | | callback | listCallback |

Example

xample port information

mName: '/dev/cu.usbmodem1421',
nufacturer: 'Arduino (www.arduino.cc)',
rialNumber: '757533138333964011C1',
pId: undefined,
cationId: '0x14200000',
ndorId: '0x2341',
oductId: '0x0043'


s
SerialPort = require('serialport');
alPort.list(function (err, ports) {
rts.forEach(function(port) {
console.log(port.comName);
console.log(port.pnpId);
console.log(port.manufacturer);
;

-

SerialPort~errorCallback : function

A callback called with an error or null.

Kind: inner typedef of SerialPort

| Param | Type | | — | — | | error | error |

-

SerialPort~openOptions : Object

Kind: inner typedef of SerialPort
Properties

| Name | Type | Default | Description | | — | — | — | — | | autoOpen | boolean | true | Automatically opens the port on nextTick | | lock | boolean | true | Prevent other processes from opening the port. false is not currently supported on windows. | | baudRate | number | 9600 | The baud rate of the port to be opened. This should match one of commonly available baud rates, such as 110, 300, 1200, 2400, 4800, 9600, 14400, 19200, 38400, 57600, 115200. There is no guarantee, that the device connected to the serial port will support the requested baud rate, even if the port itself supports that baud rate. | | dataBits | number | 8 | Must be one of: 8, 7, 6, or 5. | | stopBits | number | 1 | Must be one of: 1 or 2. | | parity | string | "none" | Must be one of: 'none', 'even', 'mark', 'odd', 'space' | | rtscts | boolean | false | flow control setting | | xon | boolean | false | flow control setting | | xoff | boolean | false | flow control setting | | xany | boolean | false | flow control setting | | bufferSize | number | 65536 | Size of read buffer | | platformOptions | object | | sets platform specific options | | platformOptions.vmin | number | 1 | see man termios | | platformOptions.vtime | number | 0 | see man termios |

-

SerialPort~listCallback : function

This callback type is called requestCallback and is displayed as a global symbol.

Kind: inner typedef of SerialPort

| Param | Type | Description | | — | — | — | | error | error | | | ports | array | an array of objects with port info. |

-

Command Line Tools

If you install serialport globally. (eg, 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.

rialport-list -h

age: serialport-list [options]

st available serial ports

tions:

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


rialport-list
/cu.Bluetooth-Incoming-Port
/cu.usbmodem1421    Arduino (www.arduino.cc)

rialport-list -f json
omName":"/dev/cu.Bluetooth-Incoming-Port"},{"comName":"/dev/cu.usbmodem1421","manufacturer":"Arduino (www.arduino.cc)","serialNumber":"752303138333518011C1","locationId":"0x14200000","vendorId":"0x2341","productId":"0x0043"}]

rialport-list -f jsonline
mName":"/dev/cu.Bluetooth-Incoming-Port"}
mName":"/dev/cu.usbmodem1421","manufacturer":"Arduino (www.arduino.cc)","serialNumber":"752303138333518011C1","locationId":"0x14200000","vendorId":"0x2341","productId":"0x0043"}
Serial Port Terminal

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

rialport-term -h

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

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

tions:

-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.

rialport-term -l
/cu.Bluetooth-Incoming-Port
/cu.usbmodem1421    Arduino (www.arduino.cc)
This work is supported by the National Institutes of Health's National Center for Advancing Translational Sciences, Grant Number U24TR002306. This work is solely the responsibility of the creators and does not necessarily represent the official views of the National Institutes of Health.