Node Serialport
Intro to Node-Serialport
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 stream interface for the low-level serial port code necessary to controll Arduino chipsets, X10 interfaces, Zigbee radios, highway signs, lcd screens, cash drawers, motor controllers, sensor packages, fork lifts, modems, drones, CNC machines, plotters, vending machines, ccTalk coin accecptors, SMS Gateways, RFID scanners and much more. If if you have a hardware device with an UART we can speak to it. The physical world is your oyster with this goodie.
+Intro to Node-Serialport
Imagine a world where 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 stream interface for the low-level serial port code necessary to controll Arduino chipsets, X10 interfaces, Zigbee radios, highway signs, lcd screens, cash drawers, motor controllers, sensor packages, fork lifts, modems, drones, CNC machines, plotters, vending machines, ccTalk coin accecptors, SMS Gateways, RFID scanners and much more. If you have a hardware device with a UART we can speak to it. 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.
We're not against firmware but we're better than it.
Quick Answers to Important Questions
-
-
- API Docs +
- API Docs
- For support, open a GitHub issue.
- For discussions, design ideas, and clarifications, please join our Gitter chat room.
- To test Node-Serialport, we recommend two related projects—Browser Serialport ("just like Node Serialport, but for browser apps") and Serialport Test Piliot.
- To contribute, please review our contribution guide and Code of Conduct. You might want to check out our roadmap. 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 we merge your PR.
-
API Documentation
Can be found at https://doclets.io/node-serialport/node-serialport/
+API Documentation
Can be found at https://node-serialport.github.io/node-serialport/
See our changelog for what's new, and our upgrade guide for a walk-through on differences between major versions.
Older versions are no longer supported but their docs can be found by looking through release tags.
You can generate the docs by running
@@ -278,7 +278,8 @@sudo / root
If you're going to use sudo or root to insta
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
Ubuntu/Debian Linux
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.
Ubuntu/Debian Linux
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 -
@@ -329,7 +330,8 @@ Usage
Opening a Port
When disabling the autoOpen option you'll need to open the port on your own.
+});
+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 });
@@ -463,7 +465,7 @@ Serial Port List
serialport-list will list all available
diff --git a/packages/serialport-util/packages/node-serialport/docs/index.js.html b/packages/serialport-util/packages/node-serialport/docs/index.js.html
index d5d8036aa3..27735a9729 100644
--- a/packages/serialport-util/packages/node-serialport/docs/index.js.html
+++ b/packages/serialport-util/packages/node-serialport/docs/index.js.html
@@ -22,7 +22,7 @@
@@ -65,7 +65,7 @@ index.js
diff --git a/packages/serialport-util/packages/node-serialport/docs/parsers_byte-length.js.html b/packages/serialport-util/packages/node-serialport/docs/parsers_byte-length.js.html
index 1c5cf977e6..84bb0ff930 100644
--- a/packages/serialport-util/packages/node-serialport/docs/parsers_byte-length.js.html
+++ b/packages/serialport-util/packages/node-serialport/docs/parsers_byte-length.js.html
@@ -22,7 +22,7 @@
@@ -44,7 +44,7 @@ parsers/byte-length.js
/**
* A transform stream that emits data as a buffer after a specific number of bytes are received.
* @extends Transform
- * @param {Object} options
+ * @param {Object} options parser options object
* @param {Number} options.length the number of bytes on each data event
* @example
To use the `ByteLength` parser:
@@ -109,7 +109,7 @@ parsers/byte-length.js
diff --git a/packages/serialport-util/packages/node-serialport/docs/parsers_cctalk.js.html b/packages/serialport-util/packages/node-serialport/docs/parsers_cctalk.js.html
index 0cf084ddf2..aa1c883798 100644
--- a/packages/serialport-util/packages/node-serialport/docs/parsers_cctalk.js.html
+++ b/packages/serialport-util/packages/node-serialport/docs/parsers_cctalk.js.html
@@ -22,7 +22,7 @@
@@ -94,7 +94,7 @@ parsers/cctalk.js
diff --git a/packages/serialport-util/packages/node-serialport/docs/parsers_delimiter.js.html b/packages/serialport-util/packages/node-serialport/docs/parsers_delimiter.js.html
index 06bdee3684..8552ffab06 100644
--- a/packages/serialport-util/packages/node-serialport/docs/parsers_delimiter.js.html
+++ b/packages/serialport-util/packages/node-serialport/docs/parsers_delimiter.js.html
@@ -22,7 +22,7 @@
@@ -102,7 +102,7 @@ parsers/delimiter.js
diff --git a/packages/serialport-util/packages/node-serialport/docs/parsers_index.js.html b/packages/serialport-util/packages/node-serialport/docs/parsers_index.js.html
index abc65e0cd1..a4f88b0f17 100644
--- a/packages/serialport-util/packages/node-serialport/docs/parsers_index.js.html
+++ b/packages/serialport-util/packages/node-serialport/docs/parsers_index.js.html
@@ -22,7 +22,7 @@
@@ -86,7 +86,7 @@ parsers/index.js
diff --git a/packages/serialport-util/packages/node-serialport/docs/parsers_readline.js.html b/packages/serialport-util/packages/node-serialport/docs/parsers_readline.js.html
index bffbb9bfcf..557917c842 100644
--- a/packages/serialport-util/packages/node-serialport/docs/parsers_readline.js.html
+++ b/packages/serialport-util/packages/node-serialport/docs/parsers_readline.js.html
@@ -22,7 +22,7 @@
@@ -81,7 +81,7 @@ parsers/readline.js
diff --git a/packages/serialport-util/packages/node-serialport/docs/parsers_ready.js.html b/packages/serialport-util/packages/node-serialport/docs/parsers_ready.js.html
index a77cfadcb4..2dff1985e3 100644
--- a/packages/serialport-util/packages/node-serialport/docs/parsers_ready.js.html
+++ b/packages/serialport-util/packages/node-serialport/docs/parsers_ready.js.html
@@ -22,7 +22,7 @@
@@ -57,8 +57,8 @@ parsers/ready.js
class ReadyParser extends Transform {
/**
*
- * @param {object} options
- * @param {string|Buffer|array} options.delimiter
+ * @param {object} options options for the parser
+ * @param {string|Buffer|array} options.delimiter data to look for before emitted "ready"
*/
constructor(options) {
options = options || {};
@@ -116,7 +116,7 @@ parsers/ready.js
diff --git a/packages/serialport-util/packages/node-serialport/docs/parsers_regex.js.html b/packages/serialport-util/packages/node-serialport/docs/parsers_regex.js.html
index 5ba503ec71..5ca9dd5804 100644
--- a/packages/serialport-util/packages/node-serialport/docs/parsers_regex.js.html
+++ b/packages/serialport-util/packages/node-serialport/docs/parsers_regex.js.html
@@ -22,7 +22,7 @@
@@ -103,7 +103,7 @@ parsers/regex.js
diff --git a/packages/serialport-util/packages/node-serialport/docs/serialport.js.html b/packages/serialport-util/packages/node-serialport/docs/serialport.js.html
index 3560c43361..dea8cfee63 100644
--- a/packages/serialport-util/packages/node-serialport/docs/serialport.js.html
+++ b/packages/serialport-util/packages/node-serialport/docs/serialport.js.html
@@ -22,7 +22,7 @@
@@ -108,7 +108,7 @@ serialport.js
* @property {boolean} [xoff=false] flow control setting
* @property {boolean} [xany=false] flow control setting
* @property {object=} bindingOptions sets binding-specific options
- * @property {module:serialport~Binding=} 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.
+ * @property {Binding=} 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.
* @property {number} [bindingOptions.vmin=1] see [`man termios`](http://linux.die.net/man/3/termios) LinuxBinding and DarwinBinding
* @property {number} [bindingOptions.vtime=0] see [`man termios`](http://linux.die.net/man/3/termios) LinuxBinding and DarwinBinding
*/
@@ -117,26 +117,26 @@ serialport.js
* 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`.
* @class SerialPort
* @param {string} path - The system path of the serial port you want to open. For example, `/dev/tty.XXX` on Mac/Linux, or `COM1` on Windows.
- * @param {module:serialport~openOptions=} options - Port configuration options
- * @param {module:serialport~errorCallback=} openCallback - 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.
+ * @param {openOptions=} options - Port configuration options
+ * @param {errorCallback=} openCallback - 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.
* @property {number} baudRate The port's baudRate. Use `.update` to change it. Read-only.
* @property {object} binding The binding object backing the port. Read-only.
* @property {boolean} isOpen `true` if the port is open, `false` otherwise. Read-only. (`since 5.0.0`)
* @property {string} path The system path or name of the serial port. Read-only.
* @throws {TypeError} When given invalid arguments, a `TypeError` will be thrown.
- * @emits module:serialport#open
- * @emits module:serialport#data
- * @emits module:serialport#close
- * @emits module:serialport#error
+ * @emits open
+ * @emits data
+ * @emits close
+ * @emits error
* @alias module:serialport
*/
-function SerialPort(path, options, callback) {
+function SerialPort(path, options, openCallback) {
if (!(this instanceof SerialPort)) {
- return new SerialPort(path, options, callback);
+ return new SerialPort(path, options, openCallback);
}
if (options instanceof Function) {
- callback = options;
+ openCallback = options;
options = {};
}
@@ -207,7 +207,7 @@ serialport.js
this._kMinPoolSpace = 128;
if (this.settings.autoOpen) {
- this.open(callback);
+ this.open(openCallback);
}
}
@@ -230,7 +230,7 @@ serialport.js
/**
* The `error` event's callback is called with an error object whenever there is an error.
- * @event module:serialport#error
+ * @event error
*/
SerialPort.prototype._error = function(error, callback) {
@@ -247,21 +247,22 @@ serialport.js
/**
* 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](#opening-a-port) for more information.
- * @event module:serialport#open
+ * @event open
*/
/**
* Opens a connection to the given serial port.
- * @param {module:serialport~errorCallback=} callback - 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.
- * @emits module:serialport#open
+ * @param {errorCallback=} openCallback - 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.
+ * @emits open
+ * @returns {undefined}
*/
-SerialPort.prototype.open = function(callback) {
+SerialPort.prototype.open = function(openCallback) {
if (this.isOpen) {
- return this._asyncError(new Error('Port is already open'), callback);
+ return this._asyncError(new Error('Port is already open'), openCallback);
}
if (this.opening) {
- return this._asyncError(new Error('Port is opening'), callback);
+ return this._asyncError(new Error('Port is opening'), openCallback);
}
this.opening = true;
@@ -270,11 +271,11 @@ serialport.js
debug('opened', `path: ${this.path}`);
this.opening = false;
this.emit('open');
- if (callback) { callback.call(this, null) }
+ if (openCallback) { openCallback.call(this, null) }
}, (err) => {
this.opening = false;
debug('Binding #open had an error', err);
- this._error(err, callback);
+ this._error(err, openCallback);
});
};
@@ -282,7 +283,8 @@ serialport.js
* 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.
* @param {object=} options Only supports `baudRate`.
* @param {number=} [options.baudRate] 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. Custom rates are supported best effort per platform. 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.
- * @param {module:serialport~errorCallback=} [callback] 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.
+ * @param {errorCallback=} [callback] 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.
+ * @returns {undefined}
*/
SerialPort.prototype.update = function(options, callback) {
if (typeof options !== 'object') {
@@ -320,7 +322,7 @@ serialport.js
> If an error occurs, the callback may or may not be called with the error as its first argument. To reliably detect write errors, add a listener for the 'error' event.
In addition to the usual `stream.write` arguments (`String` and `Buffer`), `write()` can accept arrays of bytes (positive numbers under 256) which is passed to `Buffer.from([])` for conversion. This extra functionality is pretty sweet.
- * @method module:serialport#write
+ * @method SerialPort.prototype.write
* @param {(string|array|buffer)} data Accepts a [`Buffer` ](http://nodejs.org/api/buffer.html) object, or a type that is accepted by the `Buffer` constructor (e.g. an array of bytes or a string).
* @param {string=} encoding The encoding, if chunk is a string. Defaults to `'utf8'`. Also accepts `'ascii'`, `'base64'`, `'binary'`, and `'hex'` See [Buffers and Character Encodings](https://nodejs.org/api/buffer.html#buffer_buffers_and_character_encodings) for all available options.
* @param {function=} callback Called once the write operation finishes. Data may not yet be flushed to the underlying port. No arguments.
@@ -364,15 +366,15 @@ serialport.js
/**
* 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 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.
- * @method module:serialport#read
+ * @method SerialPort.prototype.read
* @param {number=} size Specify how many bytes of data to return, if available
* @returns {(string|Buffer|null)} The data from internal buffers
* @since 5.0.0
*/
/**
- * 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](#module_serialport--SerialPort.parsers) section for more information on parsers, and the [Node.js stream documentation](https://nodejs.org/api/stream.html#stream_event_data) for more information on the data event.
- * @event module:serialport#data
+ * Listening for 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](#module_serialport--SerialPort.parsers) section for more information on parsers, and the [Node.js stream documentation](https://nodejs.org/api/stream.html#stream_event_data) for more information on the data event.
+ * @event data
*/
SerialPort.prototype._read = function(bytesToRead) {
@@ -430,15 +432,17 @@ serialport.js
/**
* The `close` event's callback is called with no arguments when the port is closed. In the case of a disconnect it will be called with a Disconnect Error object (`err.disconnected == true`). In the event of a close error (unlikely), an error event is triggered.
- * @event module:serialport#close
+ * @event close
*/
/**
* Closes an open connection.
*
* If there are in progress writes when the port is closed the writes will error.
- * @param {errorCallback} callback Called once a connection is closed.
- * @emits module:serialport#close
+ * @param {errorCallback} callback Called once a connection is closed.
+ * @param {Error} disconnectError used internally to propagate a disconnect error
+ * @emits close
+ * @returns {undefined}
*/
SerialPort.prototype.close = function(callback, disconnectError) {
disconnectError = disconnectError || null;
@@ -465,13 +469,14 @@ serialport.js
/**
* Set control flags on an open port. Uses [`SetCommMask`](https://msdn.microsoft.com/en-us/library/windows/desktop/aa363257(v=vs.85).aspx) for Windows and [`ioctl`](http://linux.die.net/man/4/tty_ioctl) for OS X and Linux.
* @param {object=} options 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.
- * @param {Boolean} [options.brk=false]
- * @param {Boolean} [options.cts=false]
- * @param {Boolean} [options.dsr=false]
- * @param {Boolean} [options.dtr=true]
- * @param {Boolean} [options.rts=true]
- * @param {module:serialport~errorCallback=} callback Called once the port's flags have been set.
+ * @param {Boolean} [options.brk=false] sets the brk flag
+ * @param {Boolean} [options.cts=false] sets the cts flag
+ * @param {Boolean} [options.dsr=false] sets the dsr flag
+ * @param {Boolean} [options.dtr=true] sets the dtr flag
+ * @param {Boolean} [options.rts=true] sets the rts flag
+ * @param {errorCallback=} callback Called once the port's flags have been set.
* @since 5.0.0
+ * @returns {undefined}
*/
SerialPort.prototype.set = function(options, callback) {
if (typeof options !== 'object') {
@@ -497,7 +502,8 @@ serialport.js
/**
* Returns the control flags (CTS, DSR, DCD) on the open port.
* Uses [`GetCommModemStatus`](https://msdn.microsoft.com/en-us/library/windows/desktop/aa363258(v=vs.85).aspx) for Windows and [`ioctl`](http://linux.die.net/man/4/tty_ioctl) for mac and linux.
- * @param {module:serialport~modemBitsCallback=} callback Called once the modem bits are retrieved.
+ * @param {modemBitsCallback=} callback Called once the modem bits are retrieved.
+ * @returns {undefined}
*/
SerialPort.prototype.get = function(callback) {
if (!this.isOpen) {
@@ -517,7 +523,8 @@ serialport.js
/**
* Flush discards data received but not read, and written but not transmitted by the operating system. For more technical details, see [`tcflush(fd, TCIOFLUSH)`](http://linux.die.net/man/3/tcflush) for Mac/Linux and [`FlushFileBuffers`](http://msdn.microsoft.com/en-us/library/windows/desktop/aa364439) for Windows.
- * @param {module:serialport~errorCallback=} callback Called once the flush operation finishes.
+ * @param {errorCallback=} callback Called once the flush operation finishes.
+ * @returns {undefined}
*/
SerialPort.prototype.flush = function(callback) {
if (!this.isOpen) {
@@ -537,7 +544,8 @@ serialport.js
/**
* Waits until all output data is transmitted to the serial port. After any pending write has completed it calls [`tcdrain()`](http://linux.die.net/man/3/tcdrain) or [FlushFileBuffers()](https://msdn.microsoft.com/en-us/library/windows/desktop/aa364439(v=vs.85).aspx) to ensure it has been written to the device.
- * @param {module:serialport~errorCallback=} callback Called once the drain operation returns.
+ * @param {errorCallback=} callback Called once the drain operation returns.
+ * @returns {undefined}
* @example
Write the `data` and wait until it has finished transmitting to the target serial port before calling the callback. This will queue until the port is open and writes are finished.
@@ -567,16 +575,16 @@ serialport.js
/**
* 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.
- * @method module:serialport#pause
- * @see module:serialport#resume
+ * @method SerialPort.prototype.pause
+ * @see resume
* @since 5.0.0
* @returns `this`
*/
/**
* The `resume()` method causes an explicitly paused, `Readable` stream to resume emitting 'data' events, switching the stream into flowing mode.
- * @method module:serialport#resume
- * @see module:serialport#pause
+ * @method SerialPort.prototype.resume
+ * @see pause
* @since 5.0.0
* @returns `this`
*/
@@ -593,7 +601,7 @@ serialport.js
*
* We make an effort to identify the hardware attached and have consistent results between systems. Linux and OS X are mostly consistent. Windows relies on 3rd party device drivers for the information and is unable to guarantee the information. On windows If you have a USB connected device can we provide a serial number otherwise it will be `undefined`. The `pnpId` and `locationId` are not the same or present on all systems. The examples below were run with the same Arduino Uno.
* @type {function}
- * @param {listCallback=} callback
+ * @param {listCallback=} callback Called with a list of available serial ports.
* @returns {Promise} Resolves with the list of available serial ports.
* @example
```js
@@ -648,16 +656,16 @@ serialport.js
.catch(err) {...});
```
*/
-SerialPort.list = function(cb) {
+SerialPort.list = function(callback) {
if (!SerialPort.Binding) {
throw new TypeError('No Binding set on `SerialPort.Binding`');
}
debug('.list');
const promise = SerialPort.Binding.list();
- if (typeof cb === 'function') {
+ if (typeof callback === 'function') {
promise.then(
- ports => cb(null, ports),
- err => cb(err)
+ ports => callback(null, ports),
+ err => callback(err)
);
}
return promise;
@@ -676,7 +684,7 @@ serialport.js
diff --git a/packages/serialport-util/packages/node-serialport/lib/bindings/base.js b/packages/serialport-util/packages/node-serialport/lib/bindings/base.js
index 39fa81a749..60419e9233 100644
--- a/packages/serialport-util/packages/node-serialport/lib/bindings/base.js
+++ b/packages/serialport-util/packages/node-serialport/lib/bindings/base.js
@@ -16,7 +16,7 @@ const debug = require('debug')('serialport:bindings');
/**
* 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.
* @class BaseBinding
- * @param {object} options
+ * @param {object} options options for the biding
* @property {boolean} isOpen Required property. `true` if the port is open, `false` otherwise. Should be read-only.
* @throws {TypeError} When given invalid arguments, a `TypeError` is thrown.
* @since 5.0.0
@@ -39,8 +39,8 @@ class BaseBinding {
/**
* Opens a connection to the serial port referenced by the path.
- * @param {string} path
- * @param {module:serialport~openOptions} openOptions
+ * @param {string} path the path or com port to open
+ * @param {openOptions} options openOptions for the serialport
* @returns {Promise} Resolves after the port is opened and configured.
* @throws {TypeError} When given invalid arguments, a `TypeError` is thrown.
*/
@@ -78,7 +78,7 @@ class BaseBinding {
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.
- * @param {buffer} data Accepts a [`Buffer`](http://nodejs.org/api/buffer.html) object.
+ * @param {buffer} buffer Accepts a [`Buffer`](http://nodejs.org/api/buffer.html) object.
* @param {integer} offset The offset in the buffer to start writing at.
* @param {integer} length Specifies the maximum number of bytes to read.
* @returns {Promise} Resolves with the number of bytes read after a read operation.
@@ -113,7 +113,7 @@ The in progress reads must error when the port is closed with an error object th
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.
- * @param {buffer} data - Accepts a [`Buffer`](http://nodejs.org/api/buffer.html) object.
+ * @param {buffer} buffer - Accepts a [`Buffer`](http://nodejs.org/api/buffer.html) object.
* @returns {Promise} Resolves after the data is passed to the operating system for writing.
* @throws {TypeError} When given invalid arguments, a `TypeError` is thrown.
*/
@@ -155,11 +155,11 @@ The in progress writes must error when the port is closed with an error object t
/**
* Set control flags on an open port.
* @param {object=} options 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.
- * @param {Boolean} [options.brk=false]
- * @param {Boolean} [options.cts=false]
- * @param {Boolean} [options.dsr=false]
- * @param {Boolean} [options.dtr=true]
- * @param {Boolean} [options.rts=true]
+ * @param {Boolean} [options.brk=false] flag for brk
+ * @param {Boolean} [options.cts=false] flag for cts
+ * @param {Boolean} [options.dsr=false] flag for dsr
+ * @param {Boolean} [options.dtr=true] flag for dtr
+ * @param {Boolean} [options.rts=true] flag for rts
* @returns {Promise} Resolves once the port's flags are set.
* @throws {TypeError} When given invalid arguments, a `TypeError` is thrown.
*/
diff --git a/packages/serialport-util/packages/node-serialport/lib/bindings/poller.js b/packages/serialport-util/packages/node-serialport/lib/bindings/poller.js
index 5ea8bf9182..9bba0c2df2 100644
--- a/packages/serialport-util/packages/node-serialport/lib/bindings/poller.js
+++ b/packages/serialport-util/packages/node-serialport/lib/bindings/poller.js
@@ -4,10 +4,6 @@ const logger = debug('serialport:poller');
const EventEmitter = require('events');
const FDPoller = require('bindings')('serialport.node').Poller;
-/**
- * Enum of event values
- * @enum {int}
- */
const EVENTS = {
UV_READABLE: 1,
UV_WRITABLE: 2,
@@ -47,8 +43,8 @@ class Poller extends EventEmitter {
}
/**
* Wait for the next event to occur
- * @param {string} Event ('readable'|'writable'|'disconnect')
- * @param {function} callback
+ * @param {string} event ('readable'|'writable'|'disconnect')
+ * @returns {Poller} returns itself
*/
once(event) {
switch (event) {
@@ -66,8 +62,9 @@ class Poller extends EventEmitter {
}
/**
- * Ask the bindings to listen for an event
- * @param {EVENTS} eventFlag
+ * Ask the bindings to listen for an event, it is recommend to use `.once()` for easy use
+ * @param {EVENTS} eventFlag polls for an event or group of events based upon a flag.
+ * @returns {undefined}
*/
poll(eventFlag) {
eventFlag = eventFlag || 0;
@@ -87,6 +84,7 @@ class Poller extends EventEmitter {
/**
* Stop listening for events and cancel all outstanding listening with an error
+ * @returns {undefined}
*/
stop() {
logger('Stopping poller');
diff --git a/packages/serialport-util/packages/node-serialport/lib/parsers/byte-length.js b/packages/serialport-util/packages/node-serialport/lib/parsers/byte-length.js
index 4cd0ced218..cd7cb50176 100644
--- a/packages/serialport-util/packages/node-serialport/lib/parsers/byte-length.js
+++ b/packages/serialport-util/packages/node-serialport/lib/parsers/byte-length.js
@@ -5,7 +5,7 @@ const Transform = require('stream').Transform;
/**
* A transform stream that emits data as a buffer after a specific number of bytes are received.
* @extends Transform
- * @param {Object} options
+ * @param {Object} options parser options object
* @param {Number} options.length the number of bytes on each data event
* @example
To use the `ByteLength` parser:
diff --git a/packages/serialport-util/packages/node-serialport/lib/parsers/ready.js b/packages/serialport-util/packages/node-serialport/lib/parsers/ready.js
index b0a6f32b48..c953ba7b5e 100644
--- a/packages/serialport-util/packages/node-serialport/lib/parsers/ready.js
+++ b/packages/serialport-util/packages/node-serialport/lib/parsers/ready.js
@@ -18,8 +18,8 @@ parser.on('data', console.log); // all data after READY is received
class ReadyParser extends Transform {
/**
*
- * @param {object} options
- * @param {string|Buffer|array} options.delimiter
+ * @param {object} options options for the parser
+ * @param {string|Buffer|array} options.delimiter data to look for before emitted "ready"
*/
constructor(options) {
options = options || {};
diff --git a/packages/serialport-util/packages/node-serialport/lib/serialport.js b/packages/serialport-util/packages/node-serialport/lib/serialport.js
index 695e80462b..acffaa9eeb 100644
--- a/packages/serialport-util/packages/node-serialport/lib/serialport.js
+++ b/packages/serialport-util/packages/node-serialport/lib/serialport.js
@@ -69,7 +69,7 @@ function allocNewReadPool(poolSize) {
* @property {boolean} [xoff=false] flow control setting
* @property {boolean} [xany=false] flow control setting
* @property {object=} bindingOptions sets binding-specific options
- * @property {module:serialport~Binding=} 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.
+ * @property {Binding=} 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.
* @property {number} [bindingOptions.vmin=1] see [`man termios`](http://linux.die.net/man/3/termios) LinuxBinding and DarwinBinding
* @property {number} [bindingOptions.vtime=0] see [`man termios`](http://linux.die.net/man/3/termios) LinuxBinding and DarwinBinding
*/
@@ -78,26 +78,26 @@ function allocNewReadPool(poolSize) {
* 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`.
* @class SerialPort
* @param {string} path - The system path of the serial port you want to open. For example, `/dev/tty.XXX` on Mac/Linux, or `COM1` on Windows.
- * @param {module:serialport~openOptions=} options - Port configuration options
- * @param {module:serialport~errorCallback=} openCallback - 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.
+ * @param {openOptions=} options - Port configuration options
+ * @param {errorCallback=} openCallback - 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.
* @property {number} baudRate The port's baudRate. Use `.update` to change it. Read-only.
* @property {object} binding The binding object backing the port. Read-only.
* @property {boolean} isOpen `true` if the port is open, `false` otherwise. Read-only. (`since 5.0.0`)
* @property {string} path The system path or name of the serial port. Read-only.
* @throws {TypeError} When given invalid arguments, a `TypeError` will be thrown.
- * @emits module:serialport#open
- * @emits module:serialport#data
- * @emits module:serialport#close
- * @emits module:serialport#error
+ * @emits open
+ * @emits data
+ * @emits close
+ * @emits error
* @alias module:serialport
*/
-function SerialPort(path, options, callback) {
+function SerialPort(path, options, openCallback) {
if (!(this instanceof SerialPort)) {
- return new SerialPort(path, options, callback);
+ return new SerialPort(path, options, openCallback);
}
if (options instanceof Function) {
- callback = options;
+ openCallback = options;
options = {};
}
@@ -168,7 +168,7 @@ function SerialPort(path, options, callback) {
this._kMinPoolSpace = 128;
if (this.settings.autoOpen) {
- this.open(callback);
+ this.open(openCallback);
}
}
@@ -191,7 +191,7 @@ Object.defineProperties(SerialPort.prototype, {
/**
* The `error` event's callback is called with an error object whenever there is an error.
- * @event module:serialport#error
+ * @event error
*/
SerialPort.prototype._error = function(error, callback) {
@@ -208,21 +208,22 @@ SerialPort.prototype._asyncError = function(error, callback) {
/**
* 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](#opening-a-port) for more information.
- * @event module:serialport#open
+ * @event open
*/
/**
* Opens a connection to the given serial port.
- * @param {module:serialport~errorCallback=} callback - 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.
- * @emits module:serialport#open
+ * @param {errorCallback=} openCallback - 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.
+ * @emits open
+ * @returns {undefined}
*/
-SerialPort.prototype.open = function(callback) {
+SerialPort.prototype.open = function(openCallback) {
if (this.isOpen) {
- return this._asyncError(new Error('Port is already open'), callback);
+ return this._asyncError(new Error('Port is already open'), openCallback);
}
if (this.opening) {
- return this._asyncError(new Error('Port is opening'), callback);
+ return this._asyncError(new Error('Port is opening'), openCallback);
}
this.opening = true;
@@ -231,11 +232,11 @@ SerialPort.prototype.open = function(callback) {
debug('opened', `path: ${this.path}`);
this.opening = false;
this.emit('open');
- if (callback) { callback.call(this, null) }
+ if (openCallback) { openCallback.call(this, null) }
}, (err) => {
this.opening = false;
debug('Binding #open had an error', err);
- this._error(err, callback);
+ this._error(err, openCallback);
});
};
@@ -243,7 +244,8 @@ SerialPort.prototype.open = function(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.
* @param {object=} options Only supports `baudRate`.
* @param {number=} [options.baudRate] 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. Custom rates are supported best effort per platform. 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.
- * @param {module:serialport~errorCallback=} [callback] 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.
+ * @param {errorCallback=} [callback] 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.
+ * @returns {undefined}
*/
SerialPort.prototype.update = function(options, callback) {
if (typeof options !== 'object') {
@@ -281,7 +283,7 @@ From the [stream docs](https://nodejs.org/api/stream.html#stream_writable_write_
> If an error occurs, the callback may or may not be called with the error as its first argument. To reliably detect write errors, add a listener for the 'error' event.
In addition to the usual `stream.write` arguments (`String` and `Buffer`), `write()` can accept arrays of bytes (positive numbers under 256) which is passed to `Buffer.from([])` for conversion. This extra functionality is pretty sweet.
- * @method module:serialport#write
+ * @method SerialPort.prototype.write
* @param {(string|array|buffer)} data Accepts a [`Buffer` ](http://nodejs.org/api/buffer.html) object, or a type that is accepted by the `Buffer` constructor (e.g. an array of bytes or a string).
* @param {string=} encoding The encoding, if chunk is a string. Defaults to `'utf8'`. Also accepts `'ascii'`, `'base64'`, `'binary'`, and `'hex'` See [Buffers and Character Encodings](https://nodejs.org/api/buffer.html#buffer_buffers_and_character_encodings) for all available options.
* @param {function=} callback Called once the write operation finishes. Data may not yet be flushed to the underlying port. No arguments.
@@ -325,15 +327,15 @@ SerialPort.prototype._writev = function(data, callback) {
/**
* 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 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.
- * @method module:serialport#read
+ * @method SerialPort.prototype.read
* @param {number=} size Specify how many bytes of data to return, if available
* @returns {(string|Buffer|null)} The data from internal buffers
* @since 5.0.0
*/
/**
- * 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](#module_serialport--SerialPort.parsers) section for more information on parsers, and the [Node.js stream documentation](https://nodejs.org/api/stream.html#stream_event_data) for more information on the data event.
- * @event module:serialport#data
+ * Listening for 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](#module_serialport--SerialPort.parsers) section for more information on parsers, and the [Node.js stream documentation](https://nodejs.org/api/stream.html#stream_event_data) for more information on the data event.
+ * @event data
*/
SerialPort.prototype._read = function(bytesToRead) {
@@ -391,15 +393,17 @@ SerialPort.prototype._disconnected = function(err) {
/**
* The `close` event's callback is called with no arguments when the port is closed. In the case of a disconnect it will be called with a Disconnect Error object (`err.disconnected == true`). In the event of a close error (unlikely), an error event is triggered.
- * @event module:serialport#close
+ * @event close
*/
/**
* Closes an open connection.
*
* If there are in progress writes when the port is closed the writes will error.
- * @param {errorCallback} callback Called once a connection is closed.
- * @emits module:serialport#close
+ * @param {errorCallback} callback Called once a connection is closed.
+ * @param {Error} disconnectError used internally to propagate a disconnect error
+ * @emits close
+ * @returns {undefined}
*/
SerialPort.prototype.close = function(callback, disconnectError) {
disconnectError = disconnectError || null;
@@ -426,13 +430,14 @@ SerialPort.prototype.close = function(callback, disconnectError) {
/**
* Set control flags on an open port. Uses [`SetCommMask`](https://msdn.microsoft.com/en-us/library/windows/desktop/aa363257(v=vs.85).aspx) for Windows and [`ioctl`](http://linux.die.net/man/4/tty_ioctl) for OS X and Linux.
* @param {object=} options 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.
- * @param {Boolean} [options.brk=false]
- * @param {Boolean} [options.cts=false]
- * @param {Boolean} [options.dsr=false]
- * @param {Boolean} [options.dtr=true]
- * @param {Boolean} [options.rts=true]
- * @param {module:serialport~errorCallback=} callback Called once the port's flags have been set.
+ * @param {Boolean} [options.brk=false] sets the brk flag
+ * @param {Boolean} [options.cts=false] sets the cts flag
+ * @param {Boolean} [options.dsr=false] sets the dsr flag
+ * @param {Boolean} [options.dtr=true] sets the dtr flag
+ * @param {Boolean} [options.rts=true] sets the rts flag
+ * @param {errorCallback=} callback Called once the port's flags have been set.
* @since 5.0.0
+ * @returns {undefined}
*/
SerialPort.prototype.set = function(options, callback) {
if (typeof options !== 'object') {
@@ -458,7 +463,8 @@ SerialPort.prototype.set = function(options, callback) {
/**
* Returns the control flags (CTS, DSR, DCD) on the open port.
* Uses [`GetCommModemStatus`](https://msdn.microsoft.com/en-us/library/windows/desktop/aa363258(v=vs.85).aspx) for Windows and [`ioctl`](http://linux.die.net/man/4/tty_ioctl) for mac and linux.
- * @param {module:serialport~modemBitsCallback=} callback Called once the modem bits are retrieved.
+ * @param {modemBitsCallback=} callback Called once the modem bits are retrieved.
+ * @returns {undefined}
*/
SerialPort.prototype.get = function(callback) {
if (!this.isOpen) {
@@ -478,7 +484,8 @@ SerialPort.prototype.get = function(callback) {
/**
* Flush discards data received but not read, and written but not transmitted by the operating system. For more technical details, see [`tcflush(fd, TCIOFLUSH)`](http://linux.die.net/man/3/tcflush) for Mac/Linux and [`FlushFileBuffers`](http://msdn.microsoft.com/en-us/library/windows/desktop/aa364439) for Windows.
- * @param {module:serialport~errorCallback=} callback Called once the flush operation finishes.
+ * @param {errorCallback=} callback Called once the flush operation finishes.
+ * @returns {undefined}
*/
SerialPort.prototype.flush = function(callback) {
if (!this.isOpen) {
@@ -498,7 +505,8 @@ SerialPort.prototype.flush = function(callback) {
/**
* Waits until all output data is transmitted to the serial port. After any pending write has completed it calls [`tcdrain()`](http://linux.die.net/man/3/tcdrain) or [FlushFileBuffers()](https://msdn.microsoft.com/en-us/library/windows/desktop/aa364439(v=vs.85).aspx) to ensure it has been written to the device.
- * @param {module:serialport~errorCallback=} callback Called once the drain operation returns.
+ * @param {errorCallback=} callback Called once the drain operation returns.
+ * @returns {undefined}
* @example
Write the `data` and wait until it has finished transmitting to the target serial port before calling the callback. This will queue until the port is open and writes are finished.
@@ -528,16 +536,16 @@ SerialPort.prototype.drain = function(callback) {
/**
* 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.
- * @method module:serialport#pause
- * @see module:serialport#resume
+ * @method SerialPort.prototype.pause
+ * @see resume
* @since 5.0.0
* @returns `this`
*/
/**
* The `resume()` method causes an explicitly paused, `Readable` stream to resume emitting 'data' events, switching the stream into flowing mode.
- * @method module:serialport#resume
- * @see module:serialport#pause
+ * @method SerialPort.prototype.resume
+ * @see pause
* @since 5.0.0
* @returns `this`
*/
@@ -554,7 +562,7 @@ SerialPort.prototype.drain = function(callback) {
*
* We make an effort to identify the hardware attached and have consistent results between systems. Linux and OS X are mostly consistent. Windows relies on 3rd party device drivers for the information and is unable to guarantee the information. On windows If you have a USB connected device can we provide a serial number otherwise it will be `undefined`. The `pnpId` and `locationId` are not the same or present on all systems. The examples below were run with the same Arduino Uno.
* @type {function}
- * @param {listCallback=} callback
+ * @param {listCallback=} callback Called with a list of available serial ports.
* @returns {Promise} Resolves with the list of available serial ports.
* @example
```js
@@ -609,16 +617,16 @@ SerialPort.list()
.catch(err) {...});
```
*/
-SerialPort.list = function(cb) {
+SerialPort.list = function(callback) {
if (!SerialPort.Binding) {
throw new TypeError('No Binding set on `SerialPort.Binding`');
}
debug('.list');
const promise = SerialPort.Binding.list();
- if (typeof cb === 'function') {
+ if (typeof callback === 'function') {
promise.then(
- ports => cb(null, ports),
- err => cb(err)
+ ports => callback(null, ports),
+ err => callback(err)
);
}
return promise;