diff --git a/.doclets.yml b/.doclets.yml new file mode 100644 index 000000000..3b2eaf6bf --- /dev/null +++ b/.doclets.yml @@ -0,0 +1,7 @@ +dir: lib +packageJson: package.json +articles: + - Overview: README.md +branches: + - master + - jsdoc diff --git a/.docs/README.hbs b/.docs/README.hbs deleted file mode 100644 index 6312309d9..000000000 --- a/.docs/README.hbs +++ /dev/null @@ -1,485 +0,0 @@ -# Node Serialport - -{{> edit-warning }} - -[![npm](https://img.shields.io/npm/dm/serialport.svg?maxAge=2592000)](http://npmjs.com/package/serialport) -[![Gitter chat](https://badges.gitter.im/EmergingTechnologyAdvisors/node-serialport.svg)](https://gitter.im/EmergingTechnologyAdvisors/node-serialport) -[![Known Vulnerabilities](https://snyk.io/test/github/EmergingTechnologyAdvisors/node-serialport/badge.svg)](https://snyk.io/test/github/EmergingTechnologyAdvisors/node-serialport) -[![codecov](https://codecov.io/gh/EmergingTechnologyAdvisors/node-serialport/branch/master/graph/badge.svg)](https://codecov.io/gh/EmergingTechnologyAdvisors/node-serialport) -[![Build Status](https://travis-ci.org/EmergingTechnologyAdvisors/node-serialport.svg?branch=master)](https://travis-ci.org/EmergingTechnologyAdvisors/node-serialport) -[![Build status](https://ci.appveyor.com/api/projects/status/u6xe3iao2crd7akn/branch/master?svg=true)](https://ci.appveyor.com/project/j5js/node-serialport/branch/master) -[![Greenkeeper badge](https://badges.greenkeeper.io/EmergingTechnologyAdvisors/node-serialport.svg)](https://greenkeeper.io/) - -## 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](http://www.arduino.cc/) chipsets, X10 interfaces, [Zigbee](http://www.zigbee.org/) 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](https://en.wikipedia.org/wiki/Universal_asynchronous_receiver/transmitter) 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](http://www.voodootikigod.com/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 -- **For support**, open a [GitHub issue](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/new). -- **For discussions, design ideas, and clarifications**, please join our [Gitter chat room](https://gitter.im/EmergingTechnologyAdvisors/node-serialport). -- **To test Node-Serialport**, we recommend two related projects—[Browser Serialport](https://github.com/garrows/browser-serialport) ("just like Node Serialport, but for browser apps") and [Serialport Test Piliot](https://github.com/j5js/serialport-test-pilot). -- **To contribute**, please review our [contribution guide](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md). You might want to check out our [roadmap](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/746). We also have issues tagged ["good first PR"](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+pr%22), if you'd like to start somewhere specific. We'll do our best to support you until we merge your PR. - -*** - -## For which version of Node-Serialport would you like documentation? - -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](CHANGELOG.md) for what's new, and our [upgrade guide](UPGRADE_GUIDE.md) for a walk-through on differences between major versions. - -- [`serialport@6.0.4` docs](https://github.com/EmergingTechnologyAdvisors/node-serialport/blob/v6.0.4/README.md) the latest `6.x` release. -- [`serialport@4.0.7` docs](https://github.com/EmergingTechnologyAdvisors/node-serialport/blob/4.0.7/README.md) the latest `4.x` release. - -Older versions are no longer supported but their docs can be found by looking through release tags. - -*** -## Helpful Resources for Getting Started with Node-Serialport - -In addition to reading the [article mentioned above](http://www.voodootikigod.com/nodebots-the-rise-of-js-robotics), these others might help you: -* [Johnny-Five](http://johnny-five.io/#hello-world): The Johnny-Five Robotics and IoT platform's six-line "Hello World" (awesome). -* [Arduino Node Security Sensor Hacking](http://nexxylove.tumblr.com/post/20159263403/arduino-node-security-sensor-hacking): A great all-around "how do I use this" article. - -*** -## Table of Contents - -* [Platform Support](#platform-support) -* [Installation](#installation-instructions) -* [Installation Special Cases](#installation-special-cases) - * [Alpine Linux](#alpine-linux) - * [Electron](#electron) - * [Illegal Instruction](#illegal-instruction) - * [Mac OS X](#mac-os-x) - * [Raspberry Pi Linux](#raspberry-pi-linux) - * [sudo / root](#sudo--root) - * [Ubuntu/Debian Linux](#ubuntudebian-linux) - * [Windows](#windows) -* [Usage](#usage) - * [Opening a Port](#opening-a-port) - * [Testing](#testing) - * [Debugging](#debugging) - * [Error Handling](#error-handling) -{{#class name="SerialPort"}} -{{>member-index-grouped baseLevel=0 ~}} -{{/class}} -* [Command Line Tools](#command-line-tools) - * [Serial Port List](#serial-port-list) - * [Serial Port Terminal](#serial-port-terminal) - * [Serial Port Repl](#serial-port-repl) -* [License](#license) - -*** - -### Platform Support -`serialport` 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. - -## Installation Instructions - -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 -``` - -### Installation Special Cases - -We use [prebuild](https://github.com/mafintosh/prebuild) 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 during the install. Compiling with nodejs is done via `node-gyp` which 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 Linux - -[Alpine](http://www.alpinelinux.org/) is a (very) small distro, but it uses the [musl](https://www.musl-libc.org/) standard library instead of [glibc](https://www.gnu.org/software/libc/) (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](https://github.com/mhart/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 - -[Electron](https://electron.atom.io/) 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](https://github.com/electron/electron-rebuild/blob/master/README.md). - -1. `npm install --save-dev electron-rebuild` -2. Add `electron-rebuild` to your project's package.json's install hook -3. Run `npm install` - -For an example project, check out [`electron-serialport`](https://github.com/johnny-five-io/electron-serialport). - -#### Illegal Instruction - -The pre-compiled binaries assume a fully capable chip. Intel's [Galileo 2](https://software.intel.com/en-us/iot/hardware/galileo), 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. - -```bash -# 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 -``` - -#### Mac OS X - -Ensure that you have at a minimum the xCode Command Line Tools installed appropriate for your system configuration. If you recently upgraded the OS, it probably removed your installation of Command Line Tools, please verify before submitting a ticket. To compile `node-serialport` with Node.js 4.x+, you will need to use g++ v4.8 or higher. - -#### Raspberry Pi Linux - -Follow the instructions for [setting up a Raspberry pi for use with Johnny-Five and Raspi IO](https://github.com/nebrius/raspi-io/wiki/Getting-a-Raspberry-Pi-ready-for-NodeBots). 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 | - -#### sudo / root -If you're going to use `sudo` or root to install Node-Serialport, `npm` will require you to use the unsafe parameters flag. - -```bash -sudo npm install serialport --unsafe-perm --build-from-source -``` - -Failure to use the flag results in an error like this: - -```bash -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@6.0.0-beta1 install /Users/wizard/src/node-serialport -> prebuild-install || node-gyp rebuild - -prebuild-install info begin Prebuild-install version 2.2.1 -prebuild-install info install installing standalone, skipping download. - -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 - -``` - -#### Ubuntu/Debian Linux - -The best way to install any version of Node.js is to use the [NodeSource Node.js binary distributions](https://github.com/nodesource/distributions#installation-instructions). 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`](https://github.com/fivdi/onoff/wiki/Node.js-v0.10.29-and-native-addons-on-the-Raspberry-Pi), 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 -``` - -#### Windows -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](https://github.com/nodejs/node-gyp#installation) instructions. Once you've got things working, you can install Node-Serialport from source with: - -```powershell -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](https://www.visualstudio.com/) 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"`. - -An old issue that you may still run into. When working with multiple Serial Ports you can set the `UV_THREADPOOL_SIZE` environment variable to be set to 1 + the number of ports you wish to open at a time. (Defaults to `4` which supports 3 open ports). - -## Usage - -### Opening a Port - -```js -var SerialPort = require('serialport'); -var port = new SerialPort('/dev/tty-usbserial1', { - baudRate: 57600 -}); -``` - -When opening a serial port, specify (in this order) - -1. Path to Serial Port - required. -1. Options - optional and described below. - -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. - -- The `open` event is always emitted when the port is opened. -- The constructor's openCallback is passed to `.open()`, if you haven't disabled the `autoOpen` option. If you have disabled it, the callback is ignored. -- The `.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. - -```js -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. -```js -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. - -```js -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: - -```js -// 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: - -```js -port.write('Hi Mom!'); -port.write(Buffer.from('Hi Mom!')); -``` - -Enjoy and do cool things with this code. - -### Testing - -Testing is an important feature of any library. To aid in our own tests we've developed a `MockBinding` a fake hardware binding that doesn't actually need any hardware to run. This class passes all of the same tests as our hardware based bindings and provides a few additional test related interfaces. To use the mock binding check out the example [here](/examples/mocking.js). - -```js -const SerialPort = require('serialport/test'); -const MockBinding = SerialPort.Binding; - -// Create a port and enable the echo and recording. -MockBinding.createPort('/dev/ROBOT', { echo: true, record: true }) -const port = new SerialPort('/dev/ROBOT') -``` - -### Debugging - -We use the [debug](https://www.npmjs.com/package/debug) package and log under the `serialport` namespace: - - - `serialport:main` for all high-level/main logging - - `serialport:binding` for all low-level logging - -You can enable logging through environment variables. Check the [debug](https://www.npmjs.com/package/debug) docs for info. - -```bash -DEBUG=serialport:main node myapp.js -DEBUG=serialport:* node myapp.js -DEBUG=* node myapp.js -``` - -You can enable core dumps on osx with; -```bash -ulimit -c unlimited for core dumps -``` - -You can "console.log" from c++ with; -```c++ -fprintf(stdout, "Hellow World num=%d str=%s\n", 4, "hi"); -``` - -You can make use of the `serialport-repl` command with; -```bash -serialport-repl # to auto detect an arduino -serialport-repl /path/name # to connect to a specific port -``` - -It will load a serialport object with debugging turned on. - -### Error Handling - -All functions in Node-Serialport follow 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 an [`error event`](#module_serialport--SerialPort+event_error) 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. - -{{#module name="serialport"}} -{{>members~}} -{{/module}} - -## Command Line Tools -If you install `serialport` globally (e.g., `npm install -g serialport`), you'll receive two command line tools. - -### Serial Port List -`serialport-list` will list all available serial ports in different formats. - -```bash -$ 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 Format the output as text, json, or jsonline. default: text - - -$ serialport-list -/dev/tty.Bluetooth-Incoming-Port -/dev/tty.usbmodem1421 Arduino (www.arduino.cc) - -$ serialport-list -f json -[{"comName":"/dev/tty.Bluetooth-Incoming-Port"},{"comName":"/dev/tty.usbmodem1421","manufacturer":"Arduino (www.arduino.cc)","serialNumber":"752303138333518011C1","locationId":"14200000","vendorId":"2341","productId":"0043"}] - -$ serialport-list -f jsonline -{"comName":"/dev/tty.Bluetooth-Incoming-Port"} -{"comName":"/dev/tty.usbmodem1421","manufacturer":"Arduino (www.arduino.cc)","serialNumber":"752303138333518011C1","locationId":"14200000","vendorId":"2341","productId":"0043"} -``` - -### Serial Port Terminal -`serialport-term` provides a basic terminal interface for communicating over a serial port. `ctrl+c` will exit. - -```bash -$ serialport-term -h - - Usage: serialport-term -p [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 Path or name of serial port - -b, --baud Baud rate default: 9600 - --databits Data bits default: 8 - --parity Parity default: none - --stopbits Stop bits default: 1 - --echo --localecho Print characters as you type them - -$ serialport-term -l -/dev/tty.Bluetooth-Incoming-Port -/dev/tty.usbmodem1421 Arduino (www.arduino.cc) -``` - -### Serial Port Repl -`serialport-repl` provides a nodejs repl for working with serialport. This is valuable when debugging. - -You can make use of the `serialport-repl` command with; -```bash -$ serialport-repl # to auto detect an arduino -$ serialport-repl /dev/tty.usbmodem1421 # to connect to a specific port -``` - -It will load a serialport object with debugging turned on. -``` - serialport:binding:auto-detect loading DarwinBinding +0ms -port = SerialPort("/dev/tty.usbmodem1421", { autoOpen: false }) -globals { SerialPort, portName, port } -> SerialPort.list() - serialport:main .list +6s -[ { comName: '/dev/tty.usbmodem1421', - manufacturer: 'Arduino (www.arduino.cc)', - serialNumber: '752303138333518011C1', - pnpId: undefined, - locationId: '14200000', - vendorId: '2341', - productId: '0043' } ] -> port.write('Calling all Autobots!') -true -> port.read() - serialport:main _read queueing _read for after open +1m -null -> port.open() - serialport:main opening path: /dev/tty.usbmodem1421 +30s - serialport:bindings open +1ms -``` - -## License -SerialPort is [MIT licensed](LICENSE) and all it's dependencies are MIT or BSD licensed. diff --git a/.docs/edit-warning.hbs b/.docs/edit-warning.hbs deleted file mode 100644 index d861dbc53..000000000 --- a/.docs/edit-warning.hbs +++ /dev/null @@ -1,10 +0,0 @@ - diff --git a/.docs/sig-link.hbs b/.docs/sig-link.hbs deleted file mode 100644 index 9d810d9f5..000000000 --- a/.docs/sig-link.hbs +++ /dev/null @@ -1,14 +0,0 @@ -{{#if virtual}}*{{/if}}{{#with (parentObject)}}{{#if virtual}}*{{/if~}}{{/with~}} -{{#if name}}{{#sig~}} -{{{@depOpen}~}} -[{{{@codeOpen}~}} -{{#if @prefix}}{{@prefix}} {{/if~}} -{{@accessSymbol}}{{#if (isEvent)}}Event: "{{{name}}}"{{else}}{{{name}}}{{/if~}} -{{~#if @methodSign}}{{#if (isEvent)}} {{@methodSign}}{{else}}{{@methodSign}}{{/if}}{{/if~}} -{{{@codeClose}}}](#{{{anchorName}}}) -{{~#if @returnSymbol}} {{@returnSymbol}}{{/if~}} -{{#if @returnTypes}} {{>linked-type-list types=@returnTypes delimiter=" | " }}{{/if~}} -{{#if @suffix}} {{@suffix}}{{/if~}} -{{{@depClose}~}} -{{~/sig}}{{/if~}} -{{#if virtual}}*{{/if}}{{#with (parentObject)}}{{#if virtual}}*{{/if~}}{{/with~}} diff --git a/.docs/sig-name.hbs b/.docs/sig-name.hbs deleted file mode 100644 index ad672f42f..000000000 --- a/.docs/sig-name.hbs +++ /dev/null @@ -1,15 +0,0 @@ -{{#if virtual}}*{{/if}}{{#with (parentObject)}}{{#if virtual}}*{{/if~}}{{/with~}} -{{#if name}}{{#sig~}} -{{{@depOpen}~}} -{{{@codeOpen}~}} -{{#if @prefix}}{{@prefix}} {{/if~}} -{{@parent~}} -{{@accessSymbol}}{{#if (isEvent)}}Event: "{{{name}}}"{{else}}{{{name}}}{{/if~}} -{{#if @methodSign}}{{#if (isEvent)}} {{@methodSign}}{{else}}{{@methodSign}}{{/if}}{{/if~}} -{{{@codeClose}~}} -{{#if @returnSymbol}} {{@returnSymbol}}{{/if~}} -{{#if @returnTypes}} {{>linked-type-list types=@returnTypes delimiter=" | " }}{{/if~}} -{{#if @suffix}} {{@suffix}}{{/if~}} -{{{@depClose}~}} -{{~/sig}}{{/if~}} -{{#if virtual}}*{{/if}}{{#with (parentObject)}}{{#if virtual}}*{{/if~}}{{/with~}} diff --git a/.gitignore b/.gitignore index a5ed931f5..0ac53aa53 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,4 @@ npm-debug.log package-lock.json Release/ prebuilds/ +docs diff --git a/.jsdoc.json b/.jsdoc.json new file mode 100644 index 000000000..5c0254cc8 --- /dev/null +++ b/.jsdoc.json @@ -0,0 +1,34 @@ +{ + "tags": { + "allowUnknownTags": true, + "dictionaries": ["jsdoc"] + }, + "source": { + "include": ["lib", "README.md"], + "includePattern": ".+\\.(js|jsx)?$" + }, + "plugins": [ + "plugins/markdown" + ], + "markdown": { + "parser": "gfm", + "hardwrap": true, + "excludeTags": [] + }, + "templates": { + "cleverLinks": true, + "monospaceLinks": true + }, + "opts": { + "template": "node_modules/docdash", + "encoding": "utf8", + "private": true, + "destination": "./docs/", + "recurse": true, + "_tutorials": "./examples" + }, + "docdash": { + "static": true, + "sort": true + } +} diff --git a/.npmignore b/.npmignore index f59f53e44..c84abb798 100644 --- a/.npmignore +++ b/.npmignore @@ -27,3 +27,4 @@ node_modules npm-debug.log package-lock.json Release/ +docs diff --git a/.travis.yml b/.travis.yml index 908a93298..17e277ebd 100644 --- a/.travis.yml +++ b/.travis.yml @@ -91,7 +91,6 @@ script: npm run lint fi; -- npm run docs:diff - node ./ - npm test diff --git a/CHANGELOG.md b/CHANGELOG.md index bfa03c19a..ff0295b1f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,53 +1,53 @@ -## [6.0.4](https://github.com/EmergingTechnologyAdvisors/node-serialport/compare/v6.0.3...v6.0.4) (2017-10-26) +## [6.0.4](https://github.com/node-serialport/node-serialport/compare/v6.0.3...v6.0.4) (2017-10-26) ### Bug Fixes -* **packages:** just-extend isn't necessary anymore ([#1376](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/1376)) ([8f650c3](https://github.com/EmergingTechnologyAdvisors/node-serialport/commit/8f650c3)) -* **windows:** bad parameter for ReadThread (windows) ([#1377](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/1377)) ([6f3afbe](https://github.com/EmergingTechnologyAdvisors/node-serialport/commit/6f3afbe)) +* **packages:** just-extend isn't necessary anymore ([#1376](https://github.com/node-serialport/node-serialport/issues/1376)) ([8f650c3](https://github.com/node-serialport/node-serialport/commit/8f650c3)) +* **windows:** bad parameter for ReadThread (windows) ([#1377](https://github.com/node-serialport/node-serialport/issues/1377)) ([6f3afbe](https://github.com/node-serialport/node-serialport/commit/6f3afbe)) -## [6.0.3](https://github.com/EmergingTechnologyAdvisors/node-serialport/compare/v6.0.0...v6.0.3) (2017-10-22) +## [6.0.3](https://github.com/node-serialport/node-serialport/compare/v6.0.0...v6.0.3) (2017-10-22) ### Bug Fixes -* **windows:** Fix async handle leak ([#1367](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/1367)) ([c1d9d88](https://github.com/EmergingTechnologyAdvisors/node-serialport/commit/c1d9d88)), closes [#1363](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/1363) -* **windows:** Fix read & write bugs for windows ([#1364](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/1364)) ([0e4b1f9](https://github.com/EmergingTechnologyAdvisors/node-serialport/commit/0e4b1f9)) +* **windows:** Fix async handle leak ([#1367](https://github.com/node-serialport/node-serialport/issues/1367)) ([c1d9d88](https://github.com/node-serialport/node-serialport/commit/c1d9d88)), closes [#1363](https://github.com/node-serialport/node-serialport/issues/1363) +* **windows:** Fix read & write bugs for windows ([#1364](https://github.com/node-serialport/node-serialport/issues/1364)) ([0e4b1f9](https://github.com/node-serialport/node-serialport/commit/0e4b1f9)) -# [6.0.0](https://github.com/EmergingTechnologyAdvisors/node-serialport/compare/5.0.0...v6.0.0) (2017-10-09) +# [6.0.0](https://github.com/node-serialport/node-serialport/compare/5.0.0...v6.0.0) (2017-10-09) ### Features -* **open:** Throw on incorrect baudrate option ([#1347](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/1347)) ([a3b8d35](https://github.com/EmergingTechnologyAdvisors/node-serialport/commit/a3b8d35)) -* **parsers:** Add cctalk parsers ([#1342](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/1342)) ([bcb492f](https://github.com/EmergingTechnologyAdvisors/node-serialport/commit/bcb492f)) -* **test:** tone down codecov comments ([#1289](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/1289)) ([749ffac](https://github.com/EmergingTechnologyAdvisors/node-serialport/commit/749ffac)) -* **windows:** Add ERROR_INVALID_PARAMETER to supported bindings errors ([#1354](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/1354)) ([4ff9c67](https://github.com/EmergingTechnologyAdvisors/node-serialport/commit/4ff9c67)) +* **open:** Throw on incorrect baudrate option ([#1347](https://github.com/node-serialport/node-serialport/issues/1347)) ([a3b8d35](https://github.com/node-serialport/node-serialport/commit/a3b8d35)) +* **parsers:** Add cctalk parsers ([#1342](https://github.com/node-serialport/node-serialport/issues/1342)) ([bcb492f](https://github.com/node-serialport/node-serialport/commit/bcb492f)) +* **test:** tone down codecov comments ([#1289](https://github.com/node-serialport/node-serialport/issues/1289)) ([749ffac](https://github.com/node-serialport/node-serialport/commit/749ffac)) +* **windows:** Add ERROR_INVALID_PARAMETER to supported bindings errors ([#1354](https://github.com/node-serialport/node-serialport/issues/1354)) ([4ff9c67](https://github.com/node-serialport/node-serialport/commit/4ff9c67)) ### Bug Fixes -* **docs:** Add a note about windows support ([76b7191](https://github.com/EmergingTechnologyAdvisors/node-serialport/commit/76b7191)), closes [#1299](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/1299) -* **docs:** add missing parsers to properties list ([3faadac](https://github.com/EmergingTechnologyAdvisors/node-serialport/commit/3faadac)) -* **docs:** correct default highWaterMark to 65536 bytes ([e83ec4e](https://github.com/EmergingTechnologyAdvisors/node-serialport/commit/e83ec4e)) -* **docs:** Fixed typo in upgrade guide ([#1321](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/1321)) ([bf251a9](https://github.com/EmergingTechnologyAdvisors/node-serialport/commit/bf251a9)) -* **linux:** The productID should be a number not a description string ([#1279](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/1279)) ([bf46f68](https://github.com/EmergingTechnologyAdvisors/node-serialport/commit/bf46f68)) -* **package:** update debug to version 3.0.0 ([#1292](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/1292)) ([4987750](https://github.com/EmergingTechnologyAdvisors/node-serialport/commit/4987750)) -* **tests:** fixup for [#1279](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/1279) ([#1285](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/1285)) ([56074f6](https://github.com/EmergingTechnologyAdvisors/node-serialport/commit/56074f6)) -* **windows:** Add option to disable RTS ([#1277](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/1277)) ([5b8d163](https://github.com/EmergingTechnologyAdvisors/node-serialport/commit/5b8d163)) -* **windows:** Asynchronous callbacks for reading and writing ([#1328](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/1328)) ([69de595](https://github.com/EmergingTechnologyAdvisors/node-serialport/commit/69de595)), closes [#1221](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/1221) -* **windows:** Parse more types of pnpIds ([#1288](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/1288)) ([0b554d7](https://github.com/EmergingTechnologyAdvisors/node-serialport/commit/0b554d7)), closes [#1220](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/1220) +* **docs:** Add a note about windows support ([76b7191](https://github.com/node-serialport/node-serialport/commit/76b7191)), closes [#1299](https://github.com/node-serialport/node-serialport/issues/1299) +* **docs:** add missing parsers to properties list ([3faadac](https://github.com/node-serialport/node-serialport/commit/3faadac)) +* **docs:** correct default highWaterMark to 65536 bytes ([e83ec4e](https://github.com/node-serialport/node-serialport/commit/e83ec4e)) +* **docs:** Fixed typo in upgrade guide ([#1321](https://github.com/node-serialport/node-serialport/issues/1321)) ([bf251a9](https://github.com/node-serialport/node-serialport/commit/bf251a9)) +* **linux:** The productID should be a number not a description string ([#1279](https://github.com/node-serialport/node-serialport/issues/1279)) ([bf46f68](https://github.com/node-serialport/node-serialport/commit/bf46f68)) +* **package:** update debug to version 3.0.0 ([#1292](https://github.com/node-serialport/node-serialport/issues/1292)) ([4987750](https://github.com/node-serialport/node-serialport/commit/4987750)) +* **tests:** fixup for [#1279](https://github.com/node-serialport/node-serialport/issues/1279) ([#1285](https://github.com/node-serialport/node-serialport/issues/1285)) ([56074f6](https://github.com/node-serialport/node-serialport/commit/56074f6)) +* **windows:** Add option to disable RTS ([#1277](https://github.com/node-serialport/node-serialport/issues/1277)) ([5b8d163](https://github.com/node-serialport/node-serialport/commit/5b8d163)) +* **windows:** Asynchronous callbacks for reading and writing ([#1328](https://github.com/node-serialport/node-serialport/issues/1328)) ([69de595](https://github.com/node-serialport/node-serialport/commit/69de595)), closes [#1221](https://github.com/node-serialport/node-serialport/issues/1221) +* **windows:** Parse more types of pnpIds ([#1288](https://github.com/node-serialport/node-serialport/issues/1288)) ([0b554d7](https://github.com/node-serialport/node-serialport/commit/0b554d7)), closes [#1220](https://github.com/node-serialport/node-serialport/issues/1220) ### Chores -* **binaries:** Lets switch to prebuild! ([#1282](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/1282)) ([8c36e99](https://github.com/EmergingTechnologyAdvisors/node-serialport/commit/8c36e99)) +* **binaries:** Lets switch to prebuild! ([#1282](https://github.com/node-serialport/node-serialport/issues/1282)) ([8c36e99](https://github.com/node-serialport/node-serialport/commit/8c36e99)) ### BREAKING CHANGES @@ -57,7 +57,7 @@ Version 5.0.0 🎉 ------------- -Nearly [a year in the making](https://github.com/EmergingTechnologyAdvisors/node-serialport/compare/4.0.7...5.0.0-beta9) Node SerialPort 5.0.0 is a major rewrite that improves stability, compatibility and performance. The api surface is similar to version 4 there have been a number of changes to ensure consistent error handling and operation of a serial port. Notably we are now a [`Stream`](https://nodejs.org/api/stream.html)! We can also introduce a bindings layer. A small low level api to provide access to underlying hardware. External bindings written in other languages or targeting other platforms can now be used. +Nearly [a year in the making](https://github.com/node-serialport/node-serialport/compare/4.0.7...5.0.0-beta9) Node SerialPort 5.0.0 is a major rewrite that improves stability, compatibility and performance. The api surface is similar to version 4 there have been a number of changes to ensure consistent error handling and operation of a serial port. Notably we are now a [`Stream`](https://nodejs.org/api/stream.html)! We can also introduce a bindings layer. A small low level api to provide access to underlying hardware. External bindings written in other languages or targeting other platforms can now be used. Some major cpu performance gains on unix platforms can be found and we're less buggy and better performing on Windows too. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 243ab469d..01498c8b2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,7 +15,7 @@ There are a lot of ways to get involved and help out: ## Reporting An Issue -SerialPort does it's [issue tracking](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues) through github. To report an issue first search the repo to make sure that it has not been reported before. If no one has reported the bug before, create a new issue and be sure to include the following information: +SerialPort does it's [issue tracking](https://github.com/node-serialport/node-serialport/issues) through github. To report an issue first search the repo to make sure that it has not been reported before. If no one has reported the bug before, create a new issue and be sure to include the following information: Operating System and Hardware: NodeJS Version: @@ -36,7 +36,7 @@ If the issue has been reported before but you have new information to help troub ## Requesting Features -To request a new feature be added take a look at the [current roadmap](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/746) and create a [github issue](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues) and include: +To request a new feature be added take a look at the [current roadmap](https://github.com/node-serialport/node-serialport/issues/746) and create a [github issue](https://github.com/node-serialport/node-serialport/issues) and include: **What feature you'd like to see:** **Why this is important to you:** (this is here because it's interesting knowing what cool things people are working on and also could help community members make suggestions for work-arounds until the feature is built) @@ -56,12 +56,12 @@ It's very important that your pull requests include all of the above in order fo ## Writing Tests -Tests are written using [mocha](https://mochajs.org/), [chai](http://chaijs.com/) and [sinon](http://sinonjs.org/). If you are having issues making a test pass, ask for help in the SerialPort [gitter](https://gitter.im/EmergingTechnologyAdvisors/node-serialport) room or on your PR. Tests can be the hardest part to write when contributing code, so don't be discouraged. +Tests are written using [mocha](https://mochajs.org/), [chai](http://chaijs.com/) and [sinon](http://sinonjs.org/). If you are having issues making a test pass, ask for help in the SerialPort [gitter](https://gitter.im/node-serialport/node-serialport) room or on your PR. Tests can be the hardest part to write when contributing code, so don't be discouraged. ## Writing Documentation -We are always looking to improve our docs. If you find that any are lacking information or have wrong information, fix and submit a PR. If you're looking for areas to start writing docs for, see the [docs](https://github.com/EmergingTechnologyAdvisors/node-serialport/labels/docs) label in issues. +We are always looking to improve our docs. If you find that any are lacking information or have wrong information, fix and submit a PR. If you're looking for areas to start writing docs for, see the [docs](https://github.com/node-serialport/node-serialport/labels/docs) label in issues. We use [jsdoc](http://usejsdoc.org/) and [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown) to generate our docs. Make your changes to `.docs/README.hbs` or the documentation blocks in the JavaScript files and run `npm run docs` to update `README.md`. diff --git a/PUBLISHING.md b/PUBLISHING.md index bcf9ffd2d..8d3c090b5 100644 --- a/PUBLISHING.md +++ b/PUBLISHING.md @@ -8,11 +8,10 @@ This can be checked in the .travis.yml file and appveyor.yml file. Within these 1. Bump up npm version in `package.json` 2. Run `npm run changelog` and modify `CHANGELOG.md` if needed -3. Update the `.docs/README.hbs` to reference this current version and to previous major version docs then regenerate docs `npm run docs`. -4. Commit everything then generate new tags based on package.json version number with `git tag v6.0.0 -a` and include the change log in the tag's annotation. (beta `git tag v6.0.0-beta3 -a`) -5. Push tags to Github with `git push --tags` -6. Wait for the CI to publish all the binaries. Remove the content of the Github release message so the tag's text shows. -7. `rm -rf package-lock.json node_modules build && npm install` -8. When the entire matrix succeeds and all binaries exist run `npm publish` or `npm publish --tag beta`. -9. Kick off the build matrix for either the master or beta branch on [serialport-test-pilot](https://travis-ci.org/j5js/serialport-test-pilot). It will install serialport from npm on a wide range of systems. -10. Let everyone know 🎉 +3. Commit everything then generate new tags based on package.json version number with `git tag v6.0.0 -a` and include the change log in the tag's annotation. (beta `git tag v6.0.0-beta3 -a`) +4. Push tags to Github with `git push --tags` +5. Wait for the CI to publish all the binaries. Remove the content of the Github release message so the tag's text shows. +6. `rm -rf package-lock.json node_modules build && npm install` +7. When the entire matrix succeeds and all binaries exist run `npm publish` or `npm publish --tag beta`. +8. Kick off the build matrix for either the master or beta branch on [serialport-test-pilot](https://travis-ci.org/j5js/serialport-test-pilot). It will install serialport from npm on a wide range of systems. +9. Let everyone know 🎉 diff --git a/README.md b/README.md index dff94acb0..72747e6dc 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,12 @@ # Node Serialport - - [![npm](https://img.shields.io/npm/dm/serialport.svg?maxAge=2592000)](http://npmjs.com/package/serialport) -[![Gitter chat](https://badges.gitter.im/EmergingTechnologyAdvisors/node-serialport.svg)](https://gitter.im/EmergingTechnologyAdvisors/node-serialport) -[![Known Vulnerabilities](https://snyk.io/test/github/EmergingTechnologyAdvisors/node-serialport/badge.svg)](https://snyk.io/test/github/EmergingTechnologyAdvisors/node-serialport) -[![codecov](https://codecov.io/gh/EmergingTechnologyAdvisors/node-serialport/branch/master/graph/badge.svg)](https://codecov.io/gh/EmergingTechnologyAdvisors/node-serialport) -[![Build Status](https://travis-ci.org/EmergingTechnologyAdvisors/node-serialport.svg?branch=master)](https://travis-ci.org/EmergingTechnologyAdvisors/node-serialport) +[![Gitter chat](https://badges.gitter.im/node-serialport/node-serialport.svg)](https://gitter.im/node-serialport/node-serialport) +[![Known Vulnerabilities](https://snyk.io/test/github/node-serialport/node-serialport/badge.svg)](https://snyk.io/test/github/node-serialport/node-serialport) +[![codecov](https://codecov.io/gh/node-serialport/node-serialport/branch/master/graph/badge.svg)](https://codecov.io/gh/node-serialport/node-serialport) +[![Build Status](https://travis-ci.org/node-serialport/node-serialport.svg?branch=master)](https://travis-ci.org/node-serialport/node-serialport) [![Build status](https://ci.appveyor.com/api/projects/status/u6xe3iao2crd7akn/branch/master?svg=true)](https://ci.appveyor.com/project/j5js/node-serialport/branch/master) -[![Greenkeeper badge](https://badges.greenkeeper.io/EmergingTechnologyAdvisors/node-serialport.svg)](https://greenkeeper.io/) +[![Greenkeeper badge](https://badges.greenkeeper.io/node-serialport/node-serialport.svg)](https://greenkeeper.io/) ## Intro to Node-Serialport @@ -30,22 +19,30 @@ For a full breakdown of why we made Node-Serialport, please read [NodeBots - The We're not against firmware but we're better than it. ## Quick Answers to Important Questions -- **For support**, open a [GitHub issue](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/new). -- **For discussions, design ideas, and clarifications**, please join our [Gitter chat room](https://gitter.im/EmergingTechnologyAdvisors/node-serialport). +- [**API Docs**](https://doclets.io/node-serialport/node-serialport/) +- **For support**, open a [GitHub issue](https://github.com/node-serialport/node-serialport/issues/new). +- **For discussions, design ideas, and clarifications**, please join our [Gitter chat room](https://gitter.im/node-serialport/node-serialport). - **To test Node-Serialport**, we recommend two related projects—[Browser Serialport](https://github.com/garrows/browser-serialport) ("just like Node Serialport, but for browser apps") and [Serialport Test Piliot](https://github.com/j5js/serialport-test-pilot). -- **To contribute**, please review our [contribution guide](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md). You might want to check out our [roadmap](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues/746). We also have issues tagged ["good first PR"](https://github.com/EmergingTechnologyAdvisors/node-serialport/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+pr%22), if you'd like to start somewhere specific. We'll do our best to support you until we merge your PR. +- **To contribute**, please review our [contribution guide](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md). You might want to check out our [roadmap](https://github.com/node-serialport/node-serialport/issues/746). We also have issues tagged ["good first PR"](https://github.com/node-serialport/node-serialport/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+pr%22), if you'd like to start somewhere specific. We'll do our best to support you until we merge your PR. *** -## For which version of Node-Serialport would you like documentation? +## API Documentation -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](CHANGELOG.md) for what's new, and our [upgrade guide](UPGRADE_GUIDE.md) for a walk-through on differences between major versions. +Can be found at https://doclets.io/node-serialport/node-serialport/ -- [`serialport@6.0.4` docs](https://github.com/EmergingTechnologyAdvisors/node-serialport/blob/v6.0.4/README.md) the latest `6.x` release. -- [`serialport@4.0.7` docs](https://github.com/EmergingTechnologyAdvisors/node-serialport/blob/4.0.7/README.md) the latest `4.x` release. +See our [changelog](CHANGELOG.md) for what's new, and our [upgrade guide](UPGRADE_GUIDE.md) 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 + +```bash +npm run docs +``` + +And browsing to `./docs/index.html`. + *** ## Helpful Resources for Getting Started with Node-Serialport @@ -72,50 +69,9 @@ In addition to reading the [article mentioned above](http://www.voodootikigod.co * [Testing](#testing) * [Debugging](#debugging) * [Error Handling](#error-handling) -* [SerialPort](#exp_module_serialport--SerialPort) ⏏ - * [`new SerialPort(path, [options], [openCallback])`](#new_module_serialport--SerialPort_new) - * _instance_ - * [`.open([callback])`](#module_serialport--SerialPort+open) - * [`.update([options], [callback])`](#module_serialport--SerialPort+update) - * [`.write(data, [encoding], [callback])`](#module_serialport--SerialPort+write) ⇒ boolean - * [`.read([size])`](#module_serialport--SerialPort+read) ⇒ string | Buffer | null - * [`.close(callback)`](#module_serialport--SerialPort+close) - * [`.set([options], [callback])`](#module_serialport--SerialPort+set) - * [`.get([callback])`](#module_serialport--SerialPort+get) - * [`.flush([callback])`](#module_serialport--SerialPort+flush) - * [`.drain([callback])`](#module_serialport--SerialPort+drain) - * [`.pause()`](#module_serialport--SerialPort+pause) ⇒ - * [`.resume()`](#module_serialport--SerialPort+resume) ⇒ - * [`Event: "error"`](#module_serialport--SerialPort+event_error) - * [`Event: "open"`](#module_serialport--SerialPort+event_open) - * [`Event: "data"`](#module_serialport--SerialPort+event_data) - * [`Event: "close"`](#module_serialport--SerialPort+event_close) - * _static_ - * [`.Binding`](#module_serialport--SerialPort.Binding) : [BaseBinding](#module_serialport--SerialPort..BaseBinding) - * [`.parsers`](#module_serialport--SerialPort.parsers) : object - * [`.list([callback])`](#module_serialport--SerialPort.list) ⇒ Promise - * _inner_ - * [~BaseBinding](#module_serialport--SerialPort..BaseBinding) - * [`new BaseBinding(options)`](#new_module_serialport--SerialPort..BaseBinding_new) - * _instance_ - * [`.open(path, openOptions)`](#module_serialport--SerialPort..BaseBinding+open) ⇒ Promise - * [`.close()`](#module_serialport--SerialPort..BaseBinding+close) ⇒ Promise - * [`.read(data, offset, length)`](#module_serialport--SerialPort..BaseBinding+read) ⇒ Promise - * [`.write(data)`](#module_serialport--SerialPort..BaseBinding+write) ⇒ Promise - * [`.update([options])`](#module_serialport--SerialPort..BaseBinding+update) ⇒ Promise - * [`.set([options])`](#module_serialport--SerialPort..BaseBinding+set) ⇒ Promise - * [`.get()`](#module_serialport--SerialPort..BaseBinding+get) ⇒ Promise - * [`.flush()`](#module_serialport--SerialPort..BaseBinding+flush) ⇒ Promise - * [`.drain()`](#module_serialport--SerialPort..BaseBinding+drain) ⇒ Promise - * _static_ - * [`.list()`](#module_serialport--SerialPort..BaseBinding.list) ⇒ Promise - * [`~errorCallback`](#module_serialport--SerialPort..errorCallback) : function - * [`~modemBitsCallback`](#module_serialport--SerialPort..modemBitsCallback) : function - * [`~openOptions`](#module_serialport--SerialPort..openOptions) : Object - * [`~listCallback`](#module_serialport--SerialPort..listCallback) : function -* [Command Line Tools](#command-line-tools) +d* [Command Line Tools](#command-line-tools) * [Serial Port List](#serial-port-list) - * [Serial Port Terminal](#serial-port-terminal) + * [Srial Port Terminal](#serial-port-terminal) * [Serial Port Repl](#serial-port-repl) * [License](#license) @@ -432,738 +388,6 @@ All functions in Node-Serialport follow two conventions: You should never have to wrap a Node-Serialport object in a try/catch statement if you call the functions with the correct arguments. - - -### SerialPort ⏏ -**Kind**: Exported class -**Emits**: [open](#module_serialport--SerialPort+event_open), [data](#module_serialport--SerialPort+event_data), [close](#module_serialport--SerialPort+event_close), [error](#module_serialport--SerialPort+event_error) -**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](#module_serialport--SerialPort..openOptions) | Port configuration options | -| [openCallback] | [errorCallback](#module_serialport--SerialPort..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](#exp_module_serialport--SerialPort) -**Emits**: [open](#module_serialport--SerialPort+event_open) - -| Param | Type | Description | -| --- | --- | --- | -| [callback] | [errorCallback](#module_serialport--SerialPort..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](#exp_module_serialport--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. 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. | -| [callback] | [errorCallback](#module_serialport--SerialPort..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])` ⇒ boolean -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 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 `close` event. - -From the [stream docs](https://nodejs.org/api/stream.html#stream_writable_write_chunk_encoding_callback) write errors don't always provide the error in the callback, sometimes they use the error event. -> 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. - -**Kind**: instance method of [SerialPort](#exp_module_serialport--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` ](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). | -| [encoding] | string | 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. | -| [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 | null -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. - -**Kind**: instance method of [SerialPort](#exp_module_serialport--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](#exp_module_serialport--SerialPort) -**Emits**: [close](#module_serialport--SerialPort+event_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`](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. - -**Kind**: instance method of [SerialPort](#exp_module_serialport--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](#module_serialport--SerialPort..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`](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. - -**Kind**: instance method of [SerialPort](#exp_module_serialport--SerialPort) - -| Param | Type | Description | -| --- | --- | --- | -| [callback] | [modemBitsCallback](#module_serialport--SerialPort..modemBitsCallback) | Called once the modem bits are retrieved. | - - -* * * - - - -#### `serialPort.flush([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. - -**Kind**: instance method of [SerialPort](#exp_module_serialport--SerialPort) - -| Param | Type | Description | -| --- | --- | --- | -| [callback] | [errorCallback](#module_serialport--SerialPort..errorCallback) | Called once the flush operation finishes. | - - -* * * - - - -#### `serialPort.drain([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. - -**Kind**: instance method of [SerialPort](#exp_module_serialport--SerialPort) - -| Param | Type | Description | -| --- | --- | --- | -| [callback] | [errorCallback](#module_serialport--SerialPort..errorCallback) | Called once the drain operation returns. | - -**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. - -```js -function writeAndDrain (data, callback) { - port.write(data); - port.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](#exp_module_serialport--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](#exp_module_serialport--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](#exp_module_serialport--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](#opening-a-port) for more information. - -**Kind**: event emitted by [SerialPort](#exp_module_serialport--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](#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. - -**Kind**: event emitted by [SerialPort](#exp_module_serialport--SerialPort) - -* * * - - - -#### `Event: "close"` -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. - -**Kind**: event emitted by [SerialPort](#exp_module_serialport--SerialPort) - -* * * - - - -#### `SerialPort.Binding` : [BaseBinding](#module_serialport--SerialPort..BaseBinding) -The `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](https://npmjs.org/). - Prevent auto loading the default bindings by requiring SerialPort with: - ```js - var SerialPort = require('serialport/lib/serialport'); - SerialPort.Binding = MyBindingClass; - ``` - -**Kind**: static property of [SerialPort](#exp_module_serialport--SerialPort) -**Since**: 5.0.0 - -* * * - - - -#### `SerialPort.parsers` : object -The default `Parsers` are [Transform streams](https://nodejs.org/api/stream.html#stream_class_stream_transform) 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](#exp_module_serialport--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. | -| Ready | Class | is a transform stream that waits for a sequence of "ready" bytes before emitting a ready event and emitting data events | -| Regex | Class | is a transform stream that uses a regular expression to split the incoming text upon. | - -**Example** -```js -const SerialPort = require('serialport'); -const Readline = SerialPort.parsers.Readline; -const port = new SerialPort('/dev/tty-usbserial1'); -const 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 -// const parser = port.pipe(new Readline()); -``` - -To use the `ByteLength` parser, provide the length of the number of bytes: -```js -const SerialPort = require('serialport'); -const ByteLength = SerialPort.parsers.ByteLength -const port = new SerialPort('/dev/tty-usbserial1'); -const 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: -```js -const SerialPort = require('serialport'); -const Delimiter = SerialPort.parsers.Delimiter; -const port = new SerialPort('/dev/tty-usbserial1'); -const 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'). Data is emitted as string controllable by the `encoding` option (defaults to `utf8`). -```js -const SerialPort = require('serialport'); -const Readline = SerialPort.parsers.Readline; -const port = new SerialPort('/dev/tty-usbserial1'); -const parser = port.pipe(new Readline({ delimiter: '\r\n' })); -parser.on('data', console.log); -``` - -To use the `Ready` parser provide a byte start sequence. After the bytes have been received a ready event is fired and data events are passed through. -```js -const SerialPort = require('serialport'); -const Ready = SerialPort.parsers.Ready; -const port = new SerialPort('/dev/tty-usbserial1'); -const parser = port.pipe(new Ready({ data: 'READY' })); -parser.on('ready', () => console.log('the ready byte sequence has been received')) -parser.on('data', console.log); // all data after READY is received -``` - -To use the `Regex` parser provide a regular expression to split the incoming text upon. Data is emitted as string controllable by the `encoding` option (defaults to `utf8`). -```js -const SerialPort = require('serialport'); -const Regex = SerialPort.parsers.Regex; -const port = new SerialPort('/dev/tty-usbserial1'); -const parser = port.pipe(new Regex({ regex: /[\r\n]+/ })); -parser.on('data', console.log); -``` - -To use the `CCTalk` parser you need to provide nothing. CCTalk Messages get emitted as buffer. -```js -const SerialPort = require('serialport'); -const CCTalk = SerialPort.parsers.CCTalk; -const port = new SerialPort('/dev/ttyUSB0'); -const parser = port.pipe(new CCtalk()); -parser.on('data', console.log); -``` - -* * * - - - -#### `SerialPort.list([callback])` ⇒ Promise -Retrieves 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. - -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. - -**Kind**: static method of [SerialPort](#exp_module_serialport--SerialPort) -**Returns**: Promise - Resolves with the list of available serial ports. - -| Param | Type | -| --- | --- | -| [callback] | listCallback | - -**Example** -```js -// OSX example port -{ - comName: '/dev/tty.usbmodem1421', - manufacturer: 'Arduino (www.arduino.cc)', - serialNumber: '752303138333518011C1', - pnpId: undefined, - locationId: '14500000', - productId: '0043', - vendorId: '2341' -} - -// Linux example port -{ - comName: '/dev/ttyACM0', - manufacturer: 'Arduino (www.arduino.cc)', - serialNumber: '752303138333518011C1', - pnpId: 'usb-Arduino__www.arduino.cc__0043_752303138333518011C1-if00', - locationId: undefined, - productId: '0043', - vendorId: '2341' -} - -// Windows example port -{ - comName: 'COM3', - manufacturer: 'Arduino LLC (www.arduino.cc)', - serialNumber: '752303138333518011C1', - pnpId: 'USB\\VID_2341&PID_0043\\752303138333518011C1', - locationId: 'Port_#0003.Hub_#0001', - productId: '0043', - vendorId: '2341' -} -``` - -```js -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) {...}); -``` - -* * * - - - -#### SerialPort~BaseBinding -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](#exp_module_serialport--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](#module_serialport--SerialPort..BaseBinding) - * [`new BaseBinding(options)`](#new_module_serialport--SerialPort..BaseBinding_new) - * _instance_ - * [`.open(path, openOptions)`](#module_serialport--SerialPort..BaseBinding+open) ⇒ Promise - * [`.close()`](#module_serialport--SerialPort..BaseBinding+close) ⇒ Promise - * [`.read(data, offset, length)`](#module_serialport--SerialPort..BaseBinding+read) ⇒ Promise - * [`.write(data)`](#module_serialport--SerialPort..BaseBinding+write) ⇒ Promise - * [`.update([options])`](#module_serialport--SerialPort..BaseBinding+update) ⇒ Promise - * [`.set([options])`](#module_serialport--SerialPort..BaseBinding+set) ⇒ Promise - * [`.get()`](#module_serialport--SerialPort..BaseBinding+get) ⇒ Promise - * [`.flush()`](#module_serialport--SerialPort..BaseBinding+flush) ⇒ Promise - * [`.drain()`](#module_serialport--SerialPort..BaseBinding+drain) ⇒ Promise - * _static_ - * [`.list()`](#module_serialport--SerialPort..BaseBinding.list) ⇒ Promise - - -* * * - - - -##### `new BaseBinding(options)` -**Throws**: - -- TypeError When given invalid arguments, a `TypeError` is thrown. - - -| Param | Type | -| --- | --- | -| options | object | - - -* * * - - - -##### `baseBinding.open(path, openOptions)` ⇒ Promise -Opens a connection to the serial port referenced by the path. - -**Kind**: instance method of [BaseBinding](#module_serialport--SerialPort..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](#module_serialport--SerialPort..openOptions) | - - -* * * - - - -##### `baseBinding.close()` ⇒ Promise -Closes an open connection - -**Kind**: instance method of [BaseBinding](#module_serialport--SerialPort..BaseBinding) -**Returns**: Promise - Resolves once the connection is closed. -**Throws**: - -- TypeError When given invalid arguments, a `TypeError` is thrown. - - -* * * - - - -##### `baseBinding.read(data, offset, length)` ⇒ Promise -Request a number of bytes from the SerialPort. This function is similar to Node's [`fs.read`](http://nodejs.org/api/fs.html#fs_fs_read_fd_buffer_offset_length_position_callback) 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](#module_serialport--SerialPort..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`](http://nodejs.org/api/buffer.html) 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)` ⇒ Promise -Write 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](#module_serialport--SerialPort..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`](http://nodejs.org/api/buffer.html) object. | - - -* * * - - - -##### `baseBinding.update([options])` ⇒ Promise -Changes connection settings on an open port. Only `baudRate` is supported. - -**Kind**: instance method of [BaseBinding](#module_serialport--SerialPort..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])` ⇒ Promise -Set control flags on an open port. - -**Kind**: instance method of [BaseBinding](#module_serialport--SerialPort..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()` ⇒ Promise -Get the control flags (CTS, DSR, DCD) on the open port. - -**Kind**: instance method of [BaseBinding](#module_serialport--SerialPort..BaseBinding) -**Returns**: Promise - Resolves with the retrieved flags. -**Throws**: - -- TypeError When given invalid arguments, a `TypeError` is thrown. - - -* * * - - - -##### `baseBinding.flush()` ⇒ Promise -Flush (discard) data received but not read, and written but not transmitted. - -**Kind**: instance method of [BaseBinding](#module_serialport--SerialPort..BaseBinding) -**Returns**: Promise - Resolves once the flush operation finishes. -**Throws**: - -- TypeError When given invalid arguments, a `TypeError` is thrown. - - -* * * - - - -##### `baseBinding.drain()` ⇒ Promise -Drain waits until all output data is transmitted to the serial port. An in progress write should be completed before this returns. - -**Kind**: instance method of [BaseBinding](#module_serialport--SerialPort..BaseBinding) -**Returns**: Promise - Resolves once the drain operation finishes. -**Throws**: - -- TypeError When given invalid arguments, a `TypeError` is thrown. - - -* * * - - - -##### `BaseBinding.list()` ⇒ Promise -Retrieves 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](#module_serialport--SerialPort..BaseBinding) -**Returns**: Promise - resolves to an array of port [info objects](#module_serialport--SerialPort.list). - -* * * - - - -#### `SerialPort~errorCallback` : function -A callback called with an error or null. - -**Kind**: inner typedef of [SerialPort](#exp_module_serialport--SerialPort) - -| Param | Type | -| --- | --- | -| error | error | - - -* * * - - - -#### `SerialPort~modemBitsCallback` : function -A callback called with an error or an object with the modem line values (cts, dsr, dcd). - -**Kind**: inner typedef of [SerialPort](#exp_module_serialport--SerialPort) - -| Param | Type | Default | -| --- | --- | --- | -| error | error | | -| status | object | | -| [status.cts] | boolean | false | -| [status.dsr] | boolean | false | -| [status.dcd] | boolean | false | - - -* * * - - - -#### `SerialPort~openOptions` : Object -**Kind**: inner typedef of [SerialPort](#exp_module_serialport--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. 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. | -| dataBits | number | 8 | Must be one of these: 8, 7, 6, or 5. | -| highWaterMark | number | 65536 | The size of the read and write buffers defaults to 64k. | -| 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`](http://linux.die.net/man/3/termios) LinuxBinding and DarwinBinding | -| bindingOptions.vtime | number | 0 | see [`man termios`](http://linux.die.net/man/3/termios) LinuxBinding and DarwinBinding | - - -* * * - - - -#### `SerialPort~listCallback` : function -This callback type is called `requestCallback`. - -**Kind**: inner typedef of [SerialPort](#exp_module_serialport--SerialPort) - -| Param | Type | Description | -| --- | --- | --- | -| error | error | | -| ports | array | an array of objects with port info | - - -* * * - - ## Command Line Tools If you install `serialport` globally (e.g., `npm install -g serialport`), you'll receive two command line tools. diff --git a/lib/bindings/base.js b/lib/bindings/base.js index 62545eb10..864c47849 100644 --- a/lib/bindings/base.js +++ b/lib/bindings/base.js @@ -1,8 +1,5 @@ 'use strict'; const debug = require('debug')('serialport:bindings'); -/** - * @module serialport - */ /** * @name module:serialport.Binding @@ -18,7 +15,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 + * @class BaseBinding * @param {object} options * @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. diff --git a/lib/bindings/poller.js b/lib/bindings/poller.js index 91a17528c..5ea8bf918 100644 --- a/lib/bindings/poller.js +++ b/lib/bindings/poller.js @@ -4,6 +4,10 @@ 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, @@ -35,13 +39,17 @@ function handleEvent(error, eventFlag) { /** * Polls unix systems for readable or writable states of a file or serialport */ -module.exports = class Poller extends EventEmitter { +class Poller extends EventEmitter { constructor(fd) { logger('Creating poller'); super(); this.poller = new FDPoller(fd, handleEvent.bind(this)); } - + /** + * Wait for the next event to occur + * @param {string} Event ('readable'|'writable'|'disconnect') + * @param {function} callback + */ once(event) { switch (event) { case 'readable': @@ -57,6 +65,10 @@ module.exports = class Poller extends EventEmitter { return EventEmitter.prototype.once.apply(this, arguments); } + /** + * Ask the bindings to listen for an event + * @param {EVENTS} eventFlag + */ poll(eventFlag) { eventFlag = eventFlag || 0; @@ -73,13 +85,12 @@ module.exports = class Poller extends EventEmitter { this.poller.poll(eventFlag); } + /** + * Stop listening for events and cancel all outstanding listening with an error + */ stop() { logger('Stopping poller'); this.poller.stop(); - this.emitCanceled(); - } - - emitCanceled() { const err = new Error('Canceled'); err.canceled = true; this.emit('readable', err); @@ -87,3 +98,7 @@ module.exports = class Poller extends EventEmitter { this.emit('disconnect', err); } }; + +Poller.EVENTS = EVENTS; + +module.exports = Poller; diff --git a/lib/index.js b/lib/index.js index c5fc6dc55..5fdd43e6d 100644 --- a/lib/index.js +++ b/lib/index.js @@ -1,15 +1,16 @@ 'use strict'; - -/** - * @module serialport - * @copyright Chris Williams - */ - const SerialPort = require('./serialport'); const Binding = require('./bindings/auto-detect'); const parsers = require('./parsers'); +/** + * @type {BaseBinding} + */ SerialPort.Binding = Binding; + +/** + * @type {Parsers} + */ SerialPort.parsers = parsers; module.exports = SerialPort; diff --git a/lib/parsers/byte-length.js b/lib/parsers/byte-length.js index d11e9491d..63d4b6091 100644 --- a/lib/parsers/byte-length.js +++ b/lib/parsers/byte-length.js @@ -2,7 +2,20 @@ const Buffer = require('safe-buffer').Buffer; const Transform = require('stream').Transform; -module.exports = class ByteLengthParser extends Transform { +/** + * A transform stream that emits data as a buffer after a specific number of bytes are received. + * @extends Transform + * @example +To use the `ByteLength` parser, provide the length of the number of bytes: +```js +const SerialPort = require('serialport'); +const ByteLength = SerialPort.parsers.ByteLength +const port = new SerialPort('/dev/tty-usbserial1'); +const parser = port.pipe(new ByteLength({length: 8})); +parser.on('data', console.log); +``` + */ +class ByteLengthParser extends Transform { constructor(options) { super(options); options = options || {}; @@ -36,3 +49,5 @@ module.exports = class ByteLengthParser extends Transform { cb(); } }; + +module.exports = ByteLengthParser; diff --git a/lib/parsers/cctalk.js b/lib/parsers/cctalk.js index 19104522b..e895f8687 100644 --- a/lib/parsers/cctalk.js +++ b/lib/parsers/cctalk.js @@ -1,8 +1,20 @@ 'use strict'; const Transform = require('stream').Transform; const Buffer = require('safe-buffer').Buffer; - -module.exports = class CCTalkParser extends Transform { +/** + * Parses the CCTalk protocol + * @extends Transform + * @example +CCTalk Messages are emitted as buffers. +```js +const SerialPort = require('serialport'); +const CCTalk = SerialPort.parsers.CCTalk; +const port = new SerialPort('/dev/ttyUSB0'); +const parser = port.pipe(new CCtalk()); +parser.on('data', console.log); +``` + */ +class CCTalkParser extends Transform { constructor() { super(); this.array = []; @@ -29,3 +41,5 @@ module.exports = class CCTalkParser extends Transform { cb(); } }; + +module.exports = CCTalkParser; diff --git a/lib/parsers/delimiter.js b/lib/parsers/delimiter.js index 729d31fcc..de91c7995 100644 --- a/lib/parsers/delimiter.js +++ b/lib/parsers/delimiter.js @@ -1,8 +1,20 @@ 'use strict'; const Buffer = require('safe-buffer').Buffer; const Transform = require('stream').Transform; - -module.exports = class DelimiterParser extends Transform { +/** + * A transform stream that emits data each time a byte sequence is received. + * @extends Transform + * @example +To use the `Delimiter` parser, provide a delimiter as a string, buffer, or array of bytes: +```js +const SerialPort = require('serialport'); +const Delimiter = SerialPort.parsers.Delimiter; +const port = new SerialPort('/dev/tty-usbserial1'); +const parser = port.pipe(new Delimiter({ delimiter: Buffer.from('EOL') })); +parser.on('data', console.log); +``` + */ +class DelimiterParser extends Transform { constructor(options) { options = options || {}; super(options); @@ -36,3 +48,5 @@ module.exports = class DelimiterParser extends Transform { cb(); } }; + +module.exports = DelimiterParser; diff --git a/lib/parsers/index.js b/lib/parsers/index.js index 275ba44ba..6e18d42b2 100644 --- a/lib/parsers/index.js +++ b/lib/parsers/index.js @@ -1,16 +1,15 @@ 'use strict'; - /** * The default `Parsers` are [Transform streams](https://nodejs.org/api/stream.html#stream_class_stream_transform) 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. - * @name module:serialport.parsers - * @type {object} - * @property {Class} [ByteLength] is a transform stream that emits data as a buffer after a specific number of bytes are received. - * @property {Class} [Delimiter] is a transform stream that emits data each time a byte sequence is received. - * @property {Class} [Readline] is a transform stream that emits data after a newline delimiter is received. - * @property {Class} [Ready] is a transform stream that waits for a sequence of "ready" bytes before emitting a ready event and emitting data events - * @property {Class} [Regex] is a transform stream that uses a regular expression to split the incoming text upon. + * @typedef {Object} Parsers + * @property {Transform} ByteLength + * @property {Transform} CCtalk + * @property {Transform} Delimiter + * @property {Transform} Readline + * @property {Transform} Ready + * @property {Transform} Regex * @since 5.0.0 * @example @@ -25,61 +24,6 @@ port.write('ROBOT PLEASE RESPOND\n'); // Creating the parser and piping can be shortened to // const parser = port.pipe(new Readline()); -``` - -To use the `ByteLength` parser, provide the length of the number of bytes: -```js -const SerialPort = require('serialport'); -const ByteLength = SerialPort.parsers.ByteLength -const port = new SerialPort('/dev/tty-usbserial1'); -const 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: -```js -const SerialPort = require('serialport'); -const Delimiter = SerialPort.parsers.Delimiter; -const port = new SerialPort('/dev/tty-usbserial1'); -const 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'). Data is emitted as string controllable by the `encoding` option (defaults to `utf8`). -```js -const SerialPort = require('serialport'); -const Readline = SerialPort.parsers.Readline; -const port = new SerialPort('/dev/tty-usbserial1'); -const parser = port.pipe(new Readline({ delimiter: '\r\n' })); -parser.on('data', console.log); -``` - -To use the `Ready` parser provide a byte start sequence. After the bytes have been received a ready event is fired and data events are passed through. -```js -const SerialPort = require('serialport'); -const Ready = SerialPort.parsers.Ready; -const port = new SerialPort('/dev/tty-usbserial1'); -const parser = port.pipe(new Ready({ data: 'READY' })); -parser.on('ready', () => console.log('the ready byte sequence has been received')) -parser.on('data', console.log); // all data after READY is received -``` - -To use the `Regex` parser provide a regular expression to split the incoming text upon. Data is emitted as string controllable by the `encoding` option (defaults to `utf8`). -```js -const SerialPort = require('serialport'); -const Regex = SerialPort.parsers.Regex; -const port = new SerialPort('/dev/tty-usbserial1'); -const parser = port.pipe(new Regex({ regex: /[\r\n]+/ })); -parser.on('data', console.log); -``` - -To use the `CCTalk` parser you need to provide nothing. CCTalk Messages get emitted as buffer. -```js -const SerialPort = require('serialport'); -const CCTalk = SerialPort.parsers.CCTalk; -const port = new SerialPort('/dev/ttyUSB0'); -const parser = port.pipe(new CCtalk()); -parser.on('data', console.log); ``` */ diff --git a/lib/parsers/readline.js b/lib/parsers/readline.js index 12f52f23d..348437199 100644 --- a/lib/parsers/readline.js +++ b/lib/parsers/readline.js @@ -1,8 +1,20 @@ 'use strict'; const Buffer = require('safe-buffer').Buffer; const DelimiterParser = require('./delimiter'); - -module.exports = class ReadLineParser extends DelimiterParser { +/** + * A transform stream that emits data after a newline delimiter is received. + * @extends DelimiterParser + * @example +To use the `Readline` parser, provide a delimiter (defaults to '\n'). Data is emitted as string controllable by the `encoding` option (defaults to `utf8`). +```js +const SerialPort = require('serialport'); +const Readline = SerialPort.parsers.Readline; +const port = new SerialPort('/dev/tty-usbserial1'); +const parser = port.pipe(new Readline({ delimiter: '\r\n' })); +parser.on('data', console.log); +``` +*/ +class ReadLineParser extends DelimiterParser { constructor(options) { const opts = Object.assign({ delimiter: Buffer.from('\n', 'utf8'), @@ -16,3 +28,5 @@ module.exports = class ReadLineParser extends DelimiterParser { super(opts); } }; + +module.exports = ReadLineParser; diff --git a/lib/parsers/ready.js b/lib/parsers/ready.js index 3cec15a38..64a78442e 100644 --- a/lib/parsers/ready.js +++ b/lib/parsers/ready.js @@ -1,8 +1,21 @@ 'use strict'; const Buffer = require('safe-buffer').Buffer; const Transform = require('stream').Transform; - -module.exports = class ReadyParser extends Transform { +/** + * A transform stream that waits for a sequence of "ready" bytes before emitting a ready event and emitting data events + * @extends Transform + * @example +To use the `Ready` parser provide a byte start sequence. After the bytes have been received a ready event is fired and data events are passed through. +```js +const SerialPort = require('serialport'); +const Ready = SerialPort.parsers.Ready; +const port = new SerialPort('/dev/tty-usbserial1'); +const parser = port.pipe(new Ready({ data: 'READY' })); +parser.on('ready', () => console.log('the ready byte sequence has been received')) +parser.on('data', console.log); // all data after READY is received +``` + */ +class ReadyParser extends Transform { constructor(options) { options = options || {}; if (options.delimiter === undefined) { @@ -45,3 +58,5 @@ module.exports = class ReadyParser extends Transform { cb(); } }; + +module.exports = ReadyParser; diff --git a/lib/parsers/regex.js b/lib/parsers/regex.js index 8097c6f2f..fa4031b64 100644 --- a/lib/parsers/regex.js +++ b/lib/parsers/regex.js @@ -1,7 +1,20 @@ 'use strict'; const Transform = require('stream').Transform; +/** + * A transform stream that uses a regular expression to split the incoming text upon. + * @extends Transform + * @example +To use the `Regex` parser provide a regular expression to split the incoming text upon. Data is emitted as string controllable by the `encoding` option (defaults to `utf8`). +```js +const SerialPort = require('serialport'); +const Regex = SerialPort.parsers.Regex; +const port = new SerialPort('/dev/tty-usbserial1'); +const parser = port.pipe(new Regex({ regex: /[\r\n]+/ })); +parser.on('data', console.log); +``` -module.exports = class RegexParser extends Transform { + */ +class RegexParser extends Transform { constructor(options) { const opts = Object.assign({ encoding: 'utf8' @@ -37,3 +50,5 @@ module.exports = class RegexParser extends Transform { cb(); } }; + +module.exports = RegexParser; diff --git a/lib/serialport.js b/lib/serialport.js index c090d9525..695e80462 100644 --- a/lib/serialport.js +++ b/lib/serialport.js @@ -1,10 +1,4 @@ 'use strict'; - -/** - * @module serialport - * @copyright Chris Williams - */ - const Buffer = require('safe-buffer').Buffer; const stream = require('stream'); const util = require('util'); @@ -82,7 +76,7 @@ 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 + * @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. diff --git a/package.json b/package.json index a94f35335..427e3a43f 100644 --- a/package.json +++ b/package.json @@ -2,15 +2,10 @@ "name": "serialport", "version": "6.0.4", "description": "Node.js package to access serial ports. Linux, OSX and Windows. Welcome your robotic JavaScript overlords. Better yet, program them!", - "author": { - "name": "Chris Williams", - "email": "voodootikigod@gmail.com", - "url": "http://www.voodootikigod.com" - }, "main": "lib", "repository": { "type": "git", - "url": "git://github.com/EmergingTechnologyAdvisors/node-serialport.git" + "url": "git://github.com/node-serialport/node-serialport.git" }, "keywords": [ "ccTalk", @@ -33,13 +28,19 @@ "UART" ], "maintainers": [ + { + "name": "Francis Gulotta", + "email": "wizard@roborooter.com", + "url": "https://www.roborooter.com" + }, { "name": "Jacob Rosenthal", "email": "jakerosenthal@gmail.com" }, { "name": "Chris Williams", - "email": "voodootikigod@gmail.com" + "email": "voodootikigod@gmail.com", + "url": "http://www.voodootikigod.com" }, { "name": "Joe Ferner", @@ -52,10 +53,6 @@ { "name": "Rob Giseburt", "email": "giseburt@gmail.com" - }, - { - "name": "Francis Gulotta", - "email": "wizard@roborooter.com" } ], "dependencies": { @@ -72,6 +69,7 @@ "chai": "^4.0.2", "chai-subset": "^1.5.0", "conventional-changelog-cli": "^1.3.2", + "docdash": "^0.4.0", "eslint": "^4.7.2", "eslint-config-standard": "^10.2.1", "eslint-plugin-import": "^2.7.0", @@ -79,7 +77,7 @@ "eslint-plugin-promise": "^3.5.0", "eslint-plugin-standard": "^3.0.1", "istanbul": "^0.4.4", - "jsdoc-to-markdown": "^3.0.0", + "jsdoc": "^3.5.5", "mocha": "^4.0.0", "prebuild": "^6.2.1", "proxyquire": "^1.7.10", @@ -97,8 +95,7 @@ "scripts": { "arduino-test": "TEST_PORT=$(./bin/find-arduino.js) npm test", "changelog": "conventional-changelog -i CHANGELOG.md -p angular -s", - "docs": "jsdoc2md --no-cache -t .docs/README.hbs --partial .docs/sig-name.hbs --partial .docs/sig-link.hbs --partial .docs/edit-warning.hbs -r table --separators --name-format -f lib/* lib/bindings/* lib/parsers/* > README.md", - "docs:diff": "jsdoc2md --no-cache -t .docs/README.hbs --partial .docs/sig-name.hbs --partial .docs/sig-link.hbs --partial .docs/edit-warning.hbs -r table --separators --name-format -f lib/* lib/bindings/* lib/parsers/* | diff README.md - || (echo 'Docs out of date, run `npm run docs` and commit the new README.md' && false)", + "docs": "jsdoc -c ./.jsdoc.json ", "lint": "eslint lib test bin examples", "rebuild-all": "npm rebuild && node-gyp rebuild", "repl": "node bin/repl.js",