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.
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.
[email protected]
docs are here this is the latest5.x
releases.[email protected]
docs are here it is the latest4.x
releases.[email protected]
docs are here it was the last3.x
releases.[email protected]
docs are here it was the last2.x
release[email protected]
docs are here it was the last1.x
release
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:
- Johnny-Five - The Johnny-Five Robotics and IoT platform's 6 line "Hello World" (awesome).
- 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 and how this all started.
- Platform Support
- Installation
- Installation Special Cases
- License
- Usage
- 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: "disconnect"
Event: "close"
- static
.Binding
:BaseBinding
.parsers
:object
.list(callback)
:function
- inner
- ~BaseBinding
new BaseBinding(options)
- instance
.open(path, openOptions)
⇒Promise
.close()
⇒Promise
.read(data, 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
- ~BaseBinding
- Command Line Tools
serialport
supports NodeJS v4 and upwards. For versions 0.10 and 0.12 use serialport@4
. The platforms, architectures and node versions serialport
supports are the following;
Platform / Arch | Node v4.x | Node v6.x | Node v7.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.
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 standard;
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 operating systems, please ensure you have Python 2.x installed AND not 3.0, node-gyp (what we use to compile) requires Python 2.x.
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. It's commonly used with Docker. We have been confirmed to work with apline-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 need to use
Electron is a framework for creating cross-platform desktop applications. Electron comes with it's own version of the Node.js runtime.
If you require serialport
as a dependency for an Electron project you need to compile it for the version of Electron you're using in your project.
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
.
npm install --save-dev electron-rebuild
- Add
electron-rebuild
to your project's package.json's install hook. - Run
npm install
For more information on electron-rebuild
visit the official README.
For an example project check out electron-serialport
.
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.
# 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
# Or leave out the package name to rebuild everything.
npm rebuild --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
requires you to use the unsafe parameters flag. This is rarely required.
sudo npm install serialport --unsafe-perm --build-from-source
Failure to use the flag results in an error similar to the following;
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
> [email protected] 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 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!
# 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 7, Windows 8.1, Windows 10, and Windows 10 IoT are supported. Precompiled binaries are available but if you want to build it from source you'll need to follow the node-gyp installation instructions. Once those are finished and working you'll be able to install serialport from source with;
npm install serialport --build-from-source
It's not part of node-gyp's documenation but sometimes it helps if you creates a c++ project in visual studio so it will install necessary comonents that aren't installed during the two hours of setup you just sat through. This will solve some instances of Failed to locate: "CL.exe"
.
SerialPort is MIT licensed and all it's dependencies are MIT or BSD licensed.
Opening a serial port:
var SerialPort = require('serialport');
var port = 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 immediately. While you can read and write at any time (it will be queued into the port is open), 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's openCallback is passed to
.open()
when theautoOpen
option hasn't been disabled, if you have disabled it the callback is ignored. - The
.open()
function takes a callback that is called after the port is opened. This can be used if you disabled theautoOpen
option or have previously closed an open port.
var SerialPort = require('serialport');
var port = new SerialPort('/dev/tty-usbserial1');
port.on('open', function() {
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);
})
This could 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);
}
// write errors will be emitted on the port since there is no callback to write
port.write('main screen turn on');
});
// the open event will always be emitted
port.on('open', function() {
// open logic
});
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.
We make use of the debug package and log under the serialport
namespace. We log;
serialport:main
for all high level main loggingserialport:binding
for all low level logging
You can enable logging through environment variables. Check out the debug docs for more information.
DEBUG=serialport:main node myapp.js
DEBUG=serialport:* node myapp.js
DEBUG=* node myapp.js
All functions in SerialPort 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 anerror event
if no callback is provided. You'll see these when a runtime error occurs like trying to open a bad port, or set an unsupported baud rate.
It should never be necessary to wrap a 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. |
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:
TypeError
When given invalid arguments a TypeError will be thrown.
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. |
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. |
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. |
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 may still have not actually been written to the serial port. See drain()
.
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.
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 (ex. an array of bytes or a string). |
[encoding] | string |
The encoding, if chunk is a String. Defaults to 'utf8' . Also accepts 'ascii' , 'base64' , 'binary' , '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. |
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 available to be read, null is returned. By default, the data will be 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 |
size specify how many bytes of data to return if available. |
Closes an open connection
Kind: instance method of SerialPort
Emits: close
Param | Type | Description |
---|---|---|
callback | errorCallback |
Called once a connection is closed. |
Set control flags on an open port. Uses SetCommMask
for windows and ioctl
for mac 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 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. |
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 have been retrieved. |
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. |
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.
function writeAndDrain (data, callback) {
sp.write(data, function () {
sp.drain(callback);
});
}
The pause()
method will cause a stream in flowing mode to stop emitting 'data' events, switching out of flowing mode. Any data that becomes available will remain in the internal buffer.
Kind: instance method of SerialPort
Returns: this
See: module:serialport#resume
Since: 5.0.0
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
The error
event's callback is called with an error object whenever there is an error.
Kind: event emitted by SerialPort
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
The data
event puts the port in flowing mode. data will be emitted as soon as it's received. Data will be 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 NodeJS stream documentation for more information on the data event.
Kind: event emitted by SerialPort
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
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.Binding
: BaseBinding
The Binding is how node SerialPort talks to the underlying system. By default we auto detect windows, Linux and OSX and load the appropriate module for your system. You can assign SerialPort.Binding
to any binding you like. You can find more by searching on npm.
You can also avoid 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
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
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 byte length parser, you must 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 you must specify, you must provide a delimiter as a string, buffer, or an 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: new Buffer('EOL')}));
parser.on('data', console.log);
To use the Readline parser, you may 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);
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 method of SerialPort
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');
SerialPort.list(function (err, ports) {
ports.forEach(function(port) {
console.log(port.comName);
console.log(port.pnpId);
console.log(port.manufacturer);
});
});
You wont ever have to use Binding objects directly they'll be used by SerialPort to access the underlying hardware. This documentation is geared towards people 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. |
- ~BaseBinding
new BaseBinding(options)
- instance
.open(path, openOptions)
⇒Promise
.close()
⇒Promise
.read(data, length)
⇒Promise
.write(data)
⇒Promise
.update([options])
⇒Promise
.set([options])
⇒Promise
.get()
⇒Promise
.flush()
⇒Promise
.drain()
⇒Promise
- static
.list()
⇒Promise
Throws:
TypeError
When given invalid arguments a TypeError will be thrown.
Param | Type | Description |
---|---|---|
options | object |
|
options.disconnect | function |
function to be called when the bindings have detected a disconnected port. This function should be called during any operation instead of that operations usual callback. The SerialPort class will attempt to call close after a disconnection and ignore any errors. |
Opens a connection to the serial port referenced by the path.
Kind: instance method of BaseBinding
Returns: Promise
- Resolves after the port has been opened and configured.
Throws:
TypeError
When given invalid arguments a TypeError will be thrown.
Param | Type |
---|---|
path | string |
openOptions | openOptions |
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 will be thrown.
Request a number of bytes from the SerialPort. This function is similar to node's fs.read
.
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 will be thrown.
Params: integer
offset - is the offset in the buffer to start writing at.
Param | Type | Description |
---|---|---|
data | buffer |
Accepts a Buffer object. |
length | integer |
specifying the maximum number of bytes to read. |
Write a number of bytes to the SerialPort This will only be called when there isn't a pending write operation.
Kind: instance method of BaseBinding
Returns: Promise
- Resolves after the data has been passed to the operating system for writing.
Throws:
TypeError
When given invalid arguments a TypeError will be thrown.
Param | Type | Description |
---|---|---|
data | buffer |
Accepts a Buffer object. |
Changes connection settings on an open port. Currently only the baudRate is required.
Kind: instance method of BaseBinding
Returns: Promise
- Resolves once the port's baud rate has been changed.
Throws:
TypeError
When given invalid arguments a TypeError will be thrown.
Param | Type | Description |
---|---|---|
[options] | object |
Only baudRate is currently supported |
[options.baudRate] | number |
If provided a baudRate that isn't supported by the bindings it should pass an error to the callback |
Set control flags on an open port.
Kind: instance method of BaseBinding
Returns: Promise
- Resolves once the port's flags have been set.
Throws:
TypeError
When given invalid arguments a TypeError will be 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 will always be provided. | |
[options.brk] | Boolean |
false |
|
[options.cts] | Boolean |
false |
|
[options.dsr] | Boolean |
false |
|
[options.dtr] | Boolean |
true |
|
[options.rts] | Boolean |
true |
Get the control flags (CTS, DSR, DCD) on the open port.
Kind: instance method of BaseBinding
Returns: Promise
- Resolves with the flags that have been retrieved.
Throws:
-
TypeError
When given invalid arguments a TypeError will be thrown.
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 will be thrown.
Drain waits until all output data has been 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 will be thrown.
Retrieves a list of available serial ports with metadata. The comName
must be guaranteed and all the other fields should be undefined if they are 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.
A callback called with an error or null.
Kind: inner typedef of SerialPort
Param | Type |
---|---|
error | error |
A 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 |
Kind: inner typedef of SerialPort
Properties
Name | Type | Default | Description |
---|---|---|---|
Binding | module:serialport~Binding |
The hardware access binding, The Binding is how node SerialPort talks to the underlying system. By default we auto detect Windows (WindowsBinding ), Linux (LinuxBinding ) and OSX (DarwinBinding ) and load the appropriate module for your system. |
|
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. |
highWaterMark | number |
16384 |
The size of the read and write buffers defaults to 16k |
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 |
bindingOptions | object |
sets binding specific options | |
bindingOptions.vmin | number |
1 |
see man termios LinuxBinding and DarwinBinding |
bindingOptions.vtime | number |
0 |
see man termios LinuxBinding and DarwinBinding |
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. |
If you install serialport
globally. (eg, 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)