serialport
Advanced tools
Node.js package to access serial ports. Welcome your robotic JavaScript overlords. Better yet, program them!
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 very simple interface for the low-level serial port code necessary to program Arduino chipsets, X10 wireless communications, and even the rising Z-Wave and Zigbee standards. 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.
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-beta6 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.
In addition to reading the article mentioned above, these others might help you:
new SerialPort(path, [options], [openCallback]).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: "disconnect"Event: "close".Binding : BaseBinding.parsers : object.list([callback]) ⇒ Promisenew BaseBinding(options).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.list() ⇒ Promise~errorCallback : function~modemBitsCallback : function~openOptions : Object~listCallback : functionserialport 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;
| Platform / Arch | Node v4.x | Node v6.x | Node v8.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 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.
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
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 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 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.
npm install --save-dev electron-rebuildelectron-rebuild to your project's package.json's install hooknpm installFor an example project, check out electron-serialport.
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
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.
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 |
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
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
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".
var SerialPort = require('serialport');
var port = new SerialPort('/dev/tty-usbserial1', {
baudRate: 57600
});
When opening a serial port, specify (in this order)
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.
open event is always emitted when the port is opened..open(), if you haven't disabled the autoOpen option. If you have disabled it, the callback is ignored..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.
We use the debug package and log under the serialport namespace:
serialport:main for all high-level/main loggingserialport:binding for all low-level loggingYou 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");
All functions in Node-Serialport follow two conventions:
TypeError object. You'll see these when functions are called with invalid arguments.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.
Kind: Exported class
Emits: open, data, close, error, disconnect
Properties
| Name | Type | Description |
|---|---|---|
| baudRate | number | The port's baudRate. Use .update to change it. Read-only. |
| binding | object | The binding object backing the port. Read-only. |
| isOpen | boolean | true if the port is open, false otherwise. Read-only. (since 5.0.0) |
| path | string | The system path or name of the serial port. Read-only. |
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.| Param | Type | Description |
|---|---|---|
| path | string | The system path of the serial port you want to open. For example, /dev/tty.XXX on Mac/Linux, or COM1 on Windows. |
| [options] | openOptions | Port configuration options |
| [openCallback] | errorCallback | Called after a connection is opened. If this is not provided and an error occurs, it will be emitted on the port's error event. The callback will NOT be called if autoOpen is set to false in the openOptions as the open will not be performed. |
serialPort.open([callback])Opens a connection to the given serial port.
Kind: instance method of SerialPort
Emits: open
| Param | Type | Description |
|---|---|---|
| [callback] | errorCallback | Called after a connection is opened. If this is not provided and an error occurs, it will be emitted on the port's error event. |
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 supports baudRate. |
| [options.baudRate] | number | The baud rate of the port to be opened. This should match one of the commonly available baud rates, such as 110, 300, 1200, 2400, 4800, 9600, 14400, 19200, 38400, 57600, or 115200. The device connected to the serial port is not guaranteed to support the requested baud rate, even if the port itself supports that baud rate. |
| [callback] | errorCallback | Called once the port's baud rate changes. If .update is called without a callback, and there is an error, an error event is emitted. |
serialPort.write(data, [encoding], [callback]) ⇒ booleanWrites 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 disconnect event.
Even though serialport is a stream, when writing it can accept arrays of bytes in addition to strings and buffers. 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
| Param | Type | Description |
|---|---|---|
| data | string | array | buffer | Accepts a Buffer object, or a type that is accepted by the Buffer constructor (e.g. an array of bytes or a string). |
| [encoding] | string | The encoding, if chunk is a string. Defaults to 'utf8'. Also accepts 'ascii', 'base64', 'binary', and 'hex' See Buffers and Character Encodings for all available options. |
| [callback] | function | Called once the write operation finishes. Data may not yet be flushed to the underlying port. No arguments. |
serialPort.read([size]) ⇒ string | Buffer | nullRequest 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
| Param | Type | Description |
|---|---|---|
| [size] | number | Specify how many bytes of data to return, if available |
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
| Param | Type | Description |
|---|---|---|
| callback | errorCallback | Called once a connection is closed. |
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
| 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 is 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.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
| Param | Type | Description |
|---|---|---|
| [callback] | modemBitsCallback | Called once the modem bits are retrieved. |
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 is 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 finished transmitting to the target serial port before calling the callback.
function writeAndDrain (data, callback) {
sp.write(data, function () {
sp.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: "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. If a disconnect happens and there is no event handler for the disconnect event an error event will be emitted instead. The error will have the disconnected property set to true.
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 is triggered.
Kind: event emitted by SerialPort
SerialPort.Binding : BaseBindingThe 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 : objectThe 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
| Name | Type | Description |
|---|---|---|
| ByteLength | Class | is a transform stream that emits data as a buffer after a specific number of bytes are received. |
| Delimiter | Class | is a transform stream that emits data each time a byte sequence is received. |
| Readline | Class | is a transform stream that emits data after a newline delimiter is received. |
Example
var SerialPort = require('serialport');
var Readline = SerialPort.parsers.Readline;
var port = new SerialPort('/dev/tty-usbserial1');
var 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
var parser = port.pipe(new Readline());
To use the ByteLength parser, provide the length of the number of bytes:
var SerialPort = require('serialport');
var ByteLength = SerialPort.parsers.ByteLength
var port = new SerialPort('/dev/tty-usbserial1');
var 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:
var SerialPort = require('serialport');
var Delimiter = SerialPort.parsers.Delimiter;
var port = new SerialPort('/dev/tty-usbserial1');
var 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')
var SerialPort = require('serialport');
var Readline = SerialPort.parsers.Readline;
var port = new SerialPort('/dev/tty-usbserial1');
var parser = port.pipe(Readline({delimiter: '\r\n'}));
parser.on('data', console.log);
SerialPort.list([callback]) ⇒ PromiseRetrieves 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.
Kind: static method of SerialPort
Returns: Promise - Resolves with the list of available serial ports.
| Param | Type |
|---|---|
| [callback] | listCallback |
Example
// 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');
// 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) {...});
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
| Name | Type | Description |
|---|---|---|
| isOpen | boolean | Required property. true if the port is open, false otherwise. Should be read-only. |
new BaseBinding(options).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.list() ⇒ Promisenew BaseBinding(options)Throws:
TypeError When given invalid arguments, a TypeError is thrown.| Param | Type |
|---|---|
| options | object |
baseBinding.open(path, openOptions) ⇒ PromiseOpens 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.| Param | Type |
|---|---|
| path | string |
| openOptions | openOptions |
baseBinding.close() ⇒ PromiseCloses 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) ⇒ PromiseRequest 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.| Param | Type | Description |
|---|---|---|
| data | buffer | Accepts a Buffer object. |
| offset | integer | The offset in the buffer to start writing at. |
| length | integer | Specifies the maximum number of bytes to read. |
baseBinding.write(data) ⇒ PromiseWrite 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.| Param | Type | Description |
|---|---|---|
| data | buffer | Accepts a Buffer object. |
baseBinding.update([options]) ⇒ PromiseChanges 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.| Param | Type | Description |
|---|---|---|
| [options] | object | Only supports baudRate. |
| [options.baudRate] | number | If provided a baud rate that the bindings do not support, it should pass an error to the callback. |
baseBinding.set([options]) ⇒ PromiseSet 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.| 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. All options are always provided. | |
| [options.brk] | Boolean | false | |
| [options.cts] | Boolean | false | |
| [options.dsr] | Boolean | false | |
| [options.dtr] | Boolean | true | |
| [options.rts] | Boolean | true |
baseBinding.get() ⇒ PromiseGet 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() ⇒ PromiseFlush (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() ⇒ PromiseDrain waits until all output data is transmitted to the serial port.
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() ⇒ PromiseRetrieves 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 : functionA callback called with an error or null.
Kind: inner typedef of SerialPort
| Param | Type |
|---|---|
| error | error |
SerialPort~modemBitsCallback : functionA callback called with an error or an object with the modem line values (cts, dsr, dcd).
Kind: inner typedef of SerialPort
| Param | Type | Default |
|---|---|---|
| error | error | |
| status | object | |
| [status.cts] | boolean | false |
| [status.dsr] | boolean | false |
| [status.dcd] | boolean | false |
SerialPort~openOptions : ObjectKind: inner typedef of SerialPort
Properties
| Name | Type | Default | Description |
|---|---|---|---|
| autoOpen | boolean | true | Automatically opens the port on nextTick. |
| baudRate | number | 9600 | The baud rate of the port to be opened. This should match one of the commonly available baud rates, such as 110, 300, 1200, 2400, 4800, 9600, 14400, 19200, 38400, 57600, or 115200. The device connected to the serial port is not guaranteed to support the requested baud rate, even if the port itself supports that baud rate. |
| dataBits | number | 8 | Must be one of these: 8, 7, 6, or 5. |
| highWaterMark | number | 16384 | The size of the read and write buffers defaults to 16k. |
| lock | boolean | true | Prevent other processes from opening the port. Windows does not currently support false. |
| stopBits | number | 1 | Must be one of these: 1 or 2. |
| parity | string | "none" | Must be one of these: '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 |
| bindingOptions | object | sets binding-specific options | |
| Binding | module:serialport~Binding | The hardware access binding. Bindings are how Node-Serialport talks to the underlying system. By default we auto detect Windows (WindowsBinding), Linux (LinuxBinding) and OS X (DarwinBinding) and load the appropriate module for your system. | |
| bindingOptions.vmin | number | 1 | see man termios LinuxBinding and DarwinBinding |
| bindingOptions.vtime | number | 0 | see man termios LinuxBinding and DarwinBinding |
SerialPort~listCallback : functionThis callback type is called requestCallback.
Kind: inner typedef of SerialPort
| Param | Type | Description |
|---|---|---|
| error | error | |
| ports | array | an array of objects with port info |
If you install serialport globally (e.g., npm install -g serialport), you'll receive two command line tools.
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/cu.Bluetooth-Incoming-Port
/dev/cu.usbmodem1421 Arduino (www.arduino.cc)
$ serialport-list -f json
[{"comName":"/dev/cu.Bluetooth-Incoming-Port"},{"comName":"/dev/cu.usbmodem1421","manufacturer":"Arduino (www.arduino.cc)","serialNumber":"752303138333518011C1","locationId":"0x14200000","vendorId":"0x2341","productId":"0x0043"}]
$ serialport-list -f jsonline
{"comName":"/dev/cu.Bluetooth-Incoming-Port"}
{"comName":"/dev/cu.usbmodem1421","manufacturer":"Arduino (www.arduino.cc)","serialNumber":"752303138333518011C1","locationId":"0x14200000","vendorId":"0x2341","productId":"0x0043"}
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/cu.Bluetooth-Incoming-Port
/dev/cu.usbmodem1421 Arduino (www.arduino.cc)
SerialPort is MIT licensed and all it's dependencies are MIT or BSD licensed.
FAQs
Node.js package to access serial ports. Linux, OSX and Windows. Welcome your robotic JavaScript overlords. Better yet, program them!
The npm package serialport receives a total of 0 weekly downloads. As such, serialport popularity was classified as not popular.
We found that serialport demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.
Security News
vlt introduced its new package manager and a serverless registry this week, innovating in a space where npm has stagnated.