From 792459d81285cc10ff955625cc1a036866bee959 Mon Sep 17 00:00:00 2001 From: Francis Gulotta Date: Thu, 15 Feb 2018 16:38:17 -0500 Subject: [PATCH] docs(api): commit docs for github pages --- .gitignore | 1 - .npmignore | 2 +- README.md | 4 +- docs/BaseBinding.html | 2392 ++++++++++++++++++ docs/ByteLengthParser.html | 294 +++ docs/CCTalkParser.html | 196 ++ docs/DelimiterParser.html | 196 ++ docs/Poller.html | 550 ++++ docs/ReadLineParser.html | 196 ++ docs/ReadyParser.html | 301 +++ docs/RegexParser.html | 196 ++ docs/SerialPort.html | 2209 ++++++++++++++++ docs/bindings_base.js.html | 289 +++ docs/bindings_poller.js.html | 162 ++ docs/global.html | 1871 ++++++++++++++ docs/index.html | 472 ++++ docs/index.js.html | 74 + docs/parsers_byte-length.js.html | 118 + docs/parsers_cctalk.js.html | 103 + docs/parsers_delimiter.js.html | 111 + docs/parsers_index.js.html | 95 + docs/parsers_readline.js.html | 90 + docs/parsers_ready.js.html | 125 + docs/parsers_regex.js.html | 112 + docs/scripts/linenumber.js | 25 + docs/scripts/prettify/Apache-License-2.0.txt | 202 ++ docs/scripts/prettify/lang-css.js | 2 + docs/scripts/prettify/prettify.js | 28 + docs/serialport.js.html | 685 +++++ docs/styles/jsdoc.css | 645 +++++ docs/styles/prettify.css | 79 + 31 files changed, 11821 insertions(+), 4 deletions(-) create mode 100644 docs/BaseBinding.html create mode 100644 docs/ByteLengthParser.html create mode 100644 docs/CCTalkParser.html create mode 100644 docs/DelimiterParser.html create mode 100644 docs/Poller.html create mode 100644 docs/ReadLineParser.html create mode 100644 docs/ReadyParser.html create mode 100644 docs/RegexParser.html create mode 100644 docs/SerialPort.html create mode 100644 docs/bindings_base.js.html create mode 100644 docs/bindings_poller.js.html create mode 100644 docs/global.html create mode 100644 docs/index.html create mode 100644 docs/index.js.html create mode 100644 docs/parsers_byte-length.js.html create mode 100644 docs/parsers_cctalk.js.html create mode 100644 docs/parsers_delimiter.js.html create mode 100644 docs/parsers_index.js.html create mode 100644 docs/parsers_readline.js.html create mode 100644 docs/parsers_ready.js.html create mode 100644 docs/parsers_regex.js.html create mode 100644 docs/scripts/linenumber.js create mode 100644 docs/scripts/prettify/Apache-License-2.0.txt create mode 100644 docs/scripts/prettify/lang-css.js create mode 100644 docs/scripts/prettify/prettify.js create mode 100644 docs/serialport.js.html create mode 100644 docs/styles/jsdoc.css create mode 100644 docs/styles/prettify.css diff --git a/.gitignore b/.gitignore index 0ac53aa53..a5ed931f5 100644 --- a/.gitignore +++ b/.gitignore @@ -7,4 +7,3 @@ npm-debug.log package-lock.json Release/ prebuilds/ -docs diff --git a/.npmignore b/.npmignore index c84abb798..2cc5e0dd0 100644 --- a/.npmignore +++ b/.npmignore @@ -18,6 +18,7 @@ test-config.json UPGRADE_GUIDE.md changelog.md .DS_Store +docs # MIRRORED FROM .gitignore PLEASE MAINTAIN .mailmap @@ -27,4 +28,3 @@ node_modules npm-debug.log package-lock.json Release/ -docs diff --git a/README.md b/README.md index 6db098f97..128531888 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ 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 -- [**API Docs**](https://doclets.io/node-serialport/node-serialport/) +- [**API Docs**](https://node-serialport.github.io/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/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). @@ -29,7 +29,7 @@ We're not against firmware but we're better than it. ## API Documentation -Can be found at https://doclets.io/node-serialport/node-serialport/ +Can be found at https://node-serialport.github.io/node-serialport/ 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. diff --git a/docs/BaseBinding.html b/docs/BaseBinding.html new file mode 100644 index 000000000..992cb5dd1 --- /dev/null +++ b/docs/BaseBinding.html @@ -0,0 +1,2392 @@ + + + + + BaseBinding - Documentation + + + + + + + + + + + + + + + + +
+ +

BaseBinding

+ + + + + + + +
+ +
+ +

+ BaseBinding +

+ + +
+ +
+
+ + + + + +

new BaseBinding(options)

+ + + + + + +
+ + +
Source:
+
+ + + + + +
Since:
+
  • 5.0.0
+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + +
Properties:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
isOpen + + +boolean + + + +

Required property. true if the port is open, false otherwise. Should be read-only.

+ + + + + + +
+

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.

+
+ + + + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
options + + +object + + + +
+ + + + + + + + + + + + +
Throws:
+ + + +
+
+
+

When given invalid arguments, a TypeError is thrown.

+
+
+
+
+
+
+ Type +
+
+ +TypeError + + +
+
+
+
+
+ + + + + + + + +
+ + + + + + + + + + + + + + +

Methods

+ + + + + + +

(static) list() → {Promise}

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

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.

+
+ + + + + + + + + + + + + + + + + + + + + + + +
Returns:
+ + +
+

resolves to an array of port info objects.

+
+ + + +
+
+ Type +
+
+ +Promise + + +
+
+ + + + + + + + + +

close() → {Promise}

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

Closes an open connection

+
+ + + + + + + + + + + + + + + + + + + + + +
Throws:
+ + + +
+
+
+

When given invalid arguments, a TypeError is thrown.

+
+
+
+
+
+
+ Type +
+
+ +TypeError + + +
+
+
+
+
+ + + + + +
Returns:
+ + +
+

Resolves once the connection is closed.

+
+ + + +
+
+ Type +
+
+ +Promise + + +
+
+ + + + + + + + + +

drain() → {Promise}

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

Drain waits until all output data is transmitted to the serial port. An in progress write should be completed before this returns.

+
+ + + + + + + + + + + + + + + + + + + + + +
Throws:
+ + + +
+
+
+

When given invalid arguments, a TypeError is thrown.

+
+
+
+
+
+
+ Type +
+
+ +TypeError + + +
+
+
+
+
+ + + + + +
Returns:
+ + +
+

Resolves once the drain operation finishes.

+
+ + + +
+
+ Type +
+
+ +Promise + + +
+
+ + + + + + + + + +

flush() → {Promise}

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

Flush (discard) data received but not read, and written but not transmitted.

+
+ + + + + + + + + + + + + + + + + + + + + +
Throws:
+ + + +
+
+
+

When given invalid arguments, a TypeError is thrown.

+
+
+
+
+
+
+ Type +
+
+ +TypeError + + +
+
+
+
+
+ + + + + +
Returns:
+ + +
+

Resolves once the flush operation finishes.

+
+ + + +
+
+ Type +
+
+ +Promise + + +
+
+ + + + + + + + + +

get() → {Promise}

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

Get the control flags (CTS, DSR, DCD) on the open port.

+
+ + + + + + + + + + + + + + + + + + + + + +
Throws:
+ + + +
+
+
+

When given invalid arguments, a TypeError is thrown.

+
+
+
+
+
+
+ Type +
+
+ +TypeError + + +
+
+
+
+
+ + + + + +
Returns:
+ + +
+

Resolves with the retrieved flags.

+
+ + + +
+
+ Type +
+
+ +Promise + + +
+
+ + + + + + + + + +

getBaudRate() → {Promise}

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

Get the OS reported baud rate for the open port.
Used mostly for debugging custom baud rates.

+
+ + + + + + + + + + + + + + + + + + + + + +
Throws:
+ + + +
+
+
+

When given invalid arguments, a TypeError is thrown.

+
+
+
+
+
+
+ Type +
+
+ +TypeError + + +
+
+
+
+
+ + + + + +
Returns:
+ + +
+

Resolves with the current baud rate.

+
+ + + +
+
+ Type +
+
+ +Promise + + +
+
+ + + + + + + + + +

open(path, openOptions) → {Promise}

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

Opens a connection to the serial port referenced by the path.

+
+ + + + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
path + + +string + + + +
openOptions + + +module:serialport~openOptions + + + +
+ + + + + + + + + + + + +
Throws:
+ + + +
+
+
+

When given invalid arguments, a TypeError is thrown.

+
+
+
+
+
+
+ Type +
+
+ +TypeError + + +
+
+
+
+
+ + + + + +
Returns:
+ + +
+

Resolves after the port is opened and configured.

+
+ + + +
+
+ Type +
+
+ +Promise + + +
+
+ + + + + + + + + +

read(data, offset, length) → {Promise}

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

Request a number of bytes from the SerialPort. This function is similar to Node's fs.read except it will always return at least one byte.

+

The in progress reads must error when the port is closed with an error object that has the property canceled equal to true. Any other error will cause a disconnection.

+
+ + + + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
data + + +buffer + + + +

Accepts a Buffer object.

offset + + +integer + + + +

The offset in the buffer to start writing at.

length + + +integer + + + +

Specifies the maximum number of bytes to read.

+ + + + + + + + + + + + +
Throws:
+ + + +
+
+
+

When given invalid arguments, a TypeError is thrown.

+
+
+
+
+
+
+ Type +
+
+ +TypeError + + +
+
+
+
+
+ + + + + +
Returns:
+ + +
+

Resolves with the number of bytes read after a read operation.

+
+ + + +
+
+ Type +
+
+ +Promise + + +
+
+ + + + + + + + + +

set(optionsopt) → {Promise}

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

Set control flags on an open port.

+
+ + + + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
options + + +object + + + + + + <optional>
+ + + + + +

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.

+
Properties
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDefaultDescription
brk + + +Boolean + + + + + + <optional>
+ + + + + + 		+ + false + +
cts + + +Boolean + + + + + + <optional>
+ + + + + + 		+ + false + +
dsr + + +Boolean + + + + + + <optional>
+ + + + + + 		+ + false + +
dtr + + +Boolean + + + + + + <optional>
+ + + + + + 		+ + true + +
rts + + +Boolean + + + + + + <optional>
+ + + + + + 		+ + true + +
+ +
+ + + + + + + + + + + + +
Throws:
+ + + +
+
+
+

When given invalid arguments, a TypeError is thrown.

+
+
+
+
+
+
+ Type +
+
+ +TypeError + + +
+
+
+
+
+ + + + + +
Returns:
+ + +
+

Resolves once the port's flags are set.

+
+ + + +
+
+ Type +
+
+ +Promise + + +
+
+ + + + + + + + + +

update(optionsopt) → {Promise}

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

Changes connection settings on an open port. Only baudRate is supported.

+
+ + + + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
options + + +object + + + + + + <optional>
+ + + + + +

Only supports baudRate.

+
Properties
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
baudRate + + +number + + + + + + <optional>
+ + + + + +

If provided a baud rate that the bindings do not support, it should pass an error to the callback.

+ +
+ + + + + + + + + + + + +
Throws:
+ + + +
+
+
+

When given invalid arguments, a TypeError is thrown.

+
+
+
+
+
+
+ Type +
+
+ +TypeError + + +
+
+
+
+
+ + + + + +
Returns:
+ + +
+

Resolves once the port's baud rate changes.

+
+ + + +
+
+ Type +
+
+ +Promise + + +
+
+ + + + + + + + + +

write(data) → {Promise}

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

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.

+
+ + + + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
data + + +buffer + + + +

Accepts a Buffer object.

+ + + + + + + + + + + + +
Throws:
+ + + +
+
+
+

When given invalid arguments, a TypeError is thrown.

+
+
+
+
+
+
+ Type +
+
+ +TypeError + + +
+
+
+
+
+ + + + + +
Returns:
+ + +
+

Resolves after the data is passed to the operating system for writing.

+
+ + + +
+
+ Type +
+
+ +Promise + + +
+
+ + + + + + + + + + +
+ +
+ + + + +
+ +
+ + + + + + + \ No newline at end of file diff --git a/docs/ByteLengthParser.html b/docs/ByteLengthParser.html new file mode 100644 index 000000000..6b0751206 --- /dev/null +++ b/docs/ByteLengthParser.html @@ -0,0 +1,294 @@ + + + + + ByteLengthParser - Documentation + + + + + + + + + + + + + + + + +
+ +

ByteLengthParser

+ + + + + + + +
+ +
+ +

+ ByteLengthParser +

+ +

A transform stream that emits data as a buffer after a specific number of bytes are received.

+ + +
+ +
+
+ + + + +

Constructor

+ + +

new ByteLengthParser(options)

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + +
Example
+ + 
To use the `ByteLength` parser:
+```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); // will have 8 bytes per data event
+```
+ + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
options + + +Object + + + + +
Properties
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
length + + +Number + + + +

the number of bytes on each data event

+ +
+ + + + + + + + + + + + + + + + + +
+ + +

Extends

+ + + + +
    +
  • Transform
    • +
+ + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ +
+ + + + + + + \ No newline at end of file diff --git a/docs/CCTalkParser.html b/docs/CCTalkParser.html new file mode 100644 index 000000000..b3e15c94b --- /dev/null +++ b/docs/CCTalkParser.html @@ -0,0 +1,196 @@ + + + + + CCTalkParser - Documentation + + + + + + + + + + + + + + + + +
+ +

CCTalkParser

+ + + + + + + +
+ +
+ +

+ CCTalkParser +

+ +

Parses the CCTalk protocol

+ + +
+ +
+
+ + + + +

Constructor

+ + +

new CCTalkParser()

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + +
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);
+```
+ + + + + + + + + + + + + + + + + + + +
+ + +

Extends

+ + + + +
    +
  • Transform
    • +
+ + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ +
+ + + + + + + \ No newline at end of file diff --git a/docs/DelimiterParser.html b/docs/DelimiterParser.html new file mode 100644 index 000000000..153a16146 --- /dev/null +++ b/docs/DelimiterParser.html @@ -0,0 +1,196 @@ + + + + + DelimiterParser - Documentation + + + + + + + + + + + + + + + + +
+ +

DelimiterParser

+ + + + + + + +
+ +
+ +

+ DelimiterParser +

+ +

A transform stream that emits data each time a byte sequence is received.

+ + +
+ +
+
+ + + + +

Constructor

+ + +

new DelimiterParser()

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + +
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);
+```
+ + + + + + + + + + + + + + + + + + + +
+ + +

Extends

+ + + + +
    +
  • Transform
    • +
+ + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ +
+ + + + + + + \ No newline at end of file diff --git a/docs/Poller.html b/docs/Poller.html new file mode 100644 index 000000000..c2de0c594 --- /dev/null +++ b/docs/Poller.html @@ -0,0 +1,550 @@ + + + + + Poller - Documentation + + + + + + + + + + + + + + + + +
+ +

Poller

+ + + + + + + +
+ +
+ +

+ Poller +

+ +

Polls unix systems for readable or writable states of a file or serialport

+ + +
+ +
+
+ + + + +

Constructor

+ + +

new Poller()

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + +

Methods

+ + + + + + +

once(Event, callback)

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

Wait for the next event to occur

+
+ + + + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
Event + + +string + + + +

('readable'|'writable'|'disconnect')

callback + + +function + + + +
+ + + + + + + + + + + + + + + + + + + + + +

poll(eventFlag)

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

Ask the bindings to listen for an event

+
+ + + + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
eventFlag + + +EVENTS + + + +
+ + + + + + + + + + + + + + + + + + + + + +

stop()

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

Stop listening for events and cancel all outstanding listening with an error

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ +
+ + + + + + + \ No newline at end of file diff --git a/docs/ReadLineParser.html b/docs/ReadLineParser.html new file mode 100644 index 000000000..4e878a42f --- /dev/null +++ b/docs/ReadLineParser.html @@ -0,0 +1,196 @@ + + + + + ReadLineParser - Documentation + + + + + + + + + + + + + + + + +
+ +

ReadLineParser

+ + + + + + + +
+ +
+ +

+ ReadLineParser +

+ +

A transform stream that emits data after a newline delimiter is received.

+ + +
+ +
+
+ + + + +

Constructor

+ + +

new ReadLineParser()

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + +
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);
+```
+ + + + + + + + + + + + + + + + + + + +
+ + +

Extends

+ + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ +
+ + + + + + + \ No newline at end of file diff --git a/docs/ReadyParser.html b/docs/ReadyParser.html new file mode 100644 index 000000000..ce14eb461 --- /dev/null +++ b/docs/ReadyParser.html @@ -0,0 +1,301 @@ + + + + + ReadyParser - Documentation + + + + + + + + + + + + + + + + +
+ +

ReadyParser

+ + + + + + + +
+ +
+ +

+ ReadyParser +

+ +

A transform stream that waits for a sequence of "ready" bytes before emitting a ready event and emitting data events

+ + +
+ +
+
+ + + + +

Constructor

+ + +

new ReadyParser(options)

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + +
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({ delimiter: 'READY' }));
+parser.on('ready', () => console.log('the ready byte sequence has been received'))
+parser.on('data', console.log); // all data after READY is received
+```
+ + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
options + + +object + + + + +
Properties
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
delimiter + + +string +| + +Buffer +| + +array + + + +
+ +
+ + + + + + + + + + + + + + + + + +
+ + +

Extends

+ + + + +
    +
  • Transform
    • +
+ + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ +
+ + + + + + + \ No newline at end of file diff --git a/docs/RegexParser.html b/docs/RegexParser.html new file mode 100644 index 000000000..f4b19744a --- /dev/null +++ b/docs/RegexParser.html @@ -0,0 +1,196 @@ + + + + + RegexParser - Documentation + + + + + + + + + + + + + + + + +
+ +

RegexParser

+ + + + + + + +
+ +
+ +

+ RegexParser +

+ +

A transform stream that uses a regular expression to split the incoming text upon.

+ + +
+ +
+
+ + + + +

Constructor

+ + +

new RegexParser()

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + +
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);
+```
+ + + + + + + + + + + + + + + + + + + +
+ + +

Extends

+ + + + +
    +
  • Transform
    • +
+ + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ +
+ + + + + + + \ No newline at end of file diff --git a/docs/SerialPort.html b/docs/SerialPort.html new file mode 100644 index 000000000..b35739ab7 --- /dev/null +++ b/docs/SerialPort.html @@ -0,0 +1,2209 @@ + + + + + SerialPort - Documentation + + + + + + + + + + + + + + + + +
+ +

SerialPort

+ + + + + + + +
+ +
+ +

+ SerialPort +

+ + +
+ +
+
+ + + + + +

new SerialPort(path, optionsopt, openCallbackopt)

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + +
Properties:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
baudRate + + +number + + + +

The port's baudRate. Use .update to change it. Read-only.

binding + + +object + + + +

The binding object backing the port. Read-only.

isOpen + + +boolean + + + +

true if the port is open, false otherwise. Read-only. (since 5.0.0)

path + + +string + + + +

The system path or name of the serial port. Read-only.

+ + + + + + +
+

Create a new serial port object for the path. In the case of invalid arguments or invalid options, when constructing a new SerialPort it will throw an error. The port will open automatically by default, which is the equivalent of calling port.open(openCallback) in the next tick. You can disable this by setting the option autoOpen to false.

+
+ + + + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
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 + + +module:serialport~openOptions + + + + + + <optional>
+ + + + + +

Port configuration options

openCallback + + +module:serialport~errorCallback + + + + + + <optional>
+ + + + + +

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.

+ + + + + + +
Fires:
+ + + + + + + + +
Throws:
+ + + +
+
+
+

When given invalid arguments, a TypeError will be thrown.

+
+
+
+
+
+
+ Type +
+
+ +TypeError + + +
+
+
+
+
+ + + + + + + + +
+ + + + + + + + + + + + +

Members

+ + + +

(static) Binding :BaseBinding

+ + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + +
Type:
+ + + + + + + + + +

(static) parsers :Parsers

+ + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + +
Type:
+ + + + + + + + + + + +

Methods

+ + + + + + +

(static) list(callbackopt) → {Promise}

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

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.

+
+ + + + + + + + + +
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) {...});
+```
+ + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
callback + + +listCallback + + + + + + <optional>
+ + + + + +
+ + + + + + + + + + + + + + +
Returns:
+ + +
+

Resolves with the list of available serial ports.

+
+ + + +
+
+ Type +
+
+ +Promise + + +
+
+ + + + + + + + + +

close(callback)

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

Closes an open connection.

+

If there are in progress writes when the port is closed the writes will error.

+
+ + + + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
callback + + +errorCallback + + + +

Called once a connection is closed.

+ + + + + + +
Fires:
+ + + + + + + + + + + + + + + + + +

drain(callbackopt)

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

Waits until all output data is transmitted to the serial port. After any pending write has completed it calls tcdrain() or FlushFileBuffers().aspx) to ensure it has been written to the device.

+
+ + + + + + + + + +
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);
+}
+```
+ + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
callback + + +module:serialport~errorCallback + + + + + + <optional>
+ + + + + +

Called once the drain operation returns.

+ + + + + + + + + + + + + + + + + + + + + +

flush(callbackopt)

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

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

+
+ + + + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
callback + + +module:serialport~errorCallback + + + + + + <optional>
+ + + + + +

Called once the flush operation finishes.

+ + + + + + + + + + + + + + + + + + + + + +

get(callbackopt)

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

Returns the control flags (CTS, DSR, DCD) on the open port.
Uses GetCommModemStatus.aspx) for Windows and ioctl for mac and linux.

+
+ + + + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
callback + + +module:serialport~modemBitsCallback + + + + + + <optional>
+ + + + + +

Called once the modem bits are retrieved.

+ + + + + + + + + + + + + + + + + + + + + +

open(callbackopt)

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

Opens a connection to the given serial port.

+
+ + + + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
callback + + +module:serialport~errorCallback + + + + + + <optional>
+ + + + + +

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.

+ + + + + + +
Fires:
+ + + + + + + + + + + + + + + + + +

set(optionsopt, callbackopt)

+ + + + + + +
+ + +
Source:
+
+ + + + + +
Since:
+
  • 5.0.0
+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

Set control flags on an open port. Uses SetCommMask.aspx) for Windows and ioctl for OS X and Linux.

+
+ + + + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
options + + +object + + + + + + <optional>
+ + + + + +

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.

+
Properties
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDefaultDescription
brk + + +Boolean + + + + + + <optional>
+ + + + + + 		+ + false + +
cts + + +Boolean + + + + + + <optional>
+ + + + + + 		+ + false + +
dsr + + +Boolean + + + + + + <optional>
+ + + + + + 		+ + false + +
dtr + + +Boolean + + + + + + <optional>
+ + + + + + 		+ + true + +
rts + + +Boolean + + + + + + <optional>
+ + + + + + 		+ + true + +
+ +
callback + + +module:serialport~errorCallback + + + + + + <optional>
+ + + + + +

Called once the port's flags have been set.

+ + + + + + + + + + + + + + + + + + + + + +

update(optionsopt, callbackopt)

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

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.

+
+ + + + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
options + + +object + + + + + + <optional>
+ + + + + +

Only supports baudRate.

+
Properties
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
baudRate + + +number + + + + + + <optional>
+ + + + + +

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 + + +module:serialport~errorCallback + + + + + + <optional>
+ + + + + +

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.

+ + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ +
+ + + + + + + \ No newline at end of file diff --git a/docs/bindings_base.js.html b/docs/bindings_base.js.html new file mode 100644 index 000000000..f59aa45b7 --- /dev/null +++ b/docs/bindings_base.js.html @@ -0,0 +1,289 @@ + + + + + bindings/base.js - Documentation + + + + + + + + + + + + + + + + +
+ +

bindings/base.js

+ + + + + + + +
+
+ 
'use strict';
+const debug = require('debug')('serialport:bindings');
+
+/**
+ * @name module:serialport.Binding
+ * @type {module:serialport~BaseBinding}
+ * @since 5.0.0
+ * @description 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;
+  ```
+ */
+
+/**
+ * You never have to use `Binding` objects directly. SerialPort uses them to access the underlying hardware. This documentation is geared towards people who are making bindings for different platforms. This class can be inherited from to get type checking for each method.
+ * @class BaseBinding
+ * @param {object} options
+ * @property {boolean} isOpen Required property. `true` if the port is open, `false` otherwise. Should be read-only.
+ * @throws {TypeError} When given invalid arguments, a `TypeError` is thrown.
+ * @since 5.0.0
+ */
+class BaseBinding {
+  /**
+   * 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.
+   * @returns {Promise} resolves to an array of port [info objects](#module_serialport--SerialPort.list).
+   */
+  static list() {
+    debug('list');
+    return Promise.resolve();
+  }
+
+  constructor(opt) {
+    if (typeof opt !== 'object') {
+      throw new TypeError('"options" is not an object');
+    }
+  }
+
+  /**
+   * Opens a connection to the serial port referenced by the path.
+   * @param {string} path
+   * @param {module:serialport~openOptions} openOptions
+   * @returns {Promise} Resolves after the port is opened and configured.
+   * @throws {TypeError} When given invalid arguments, a `TypeError` is thrown.
+   */
+  open(path, options) {
+    if (!path) {
+      throw new TypeError('"path" is not a valid port');
+    }
+
+    if (typeof options !== 'object') {
+      throw new TypeError('"options" is not an object');
+    }
+    debug('open');
+
+    if (this.isOpen) {
+      return Promise.reject(new Error('Already open'));
+    }
+    return Promise.resolve();
+  }
+
+  /**
+   * Closes an open connection
+   * @returns {Promise} Resolves once the connection is closed.
+   * @throws {TypeError} When given invalid arguments, a `TypeError` is thrown.
+   */
+  close() {
+    debug('close');
+    if (!this.isOpen) {
+      return Promise.reject(new Error('Port is not open'));
+    }
+    return Promise.resolve();
+  }
+
+  /**
+   * 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.
+
+   * @param {buffer} data Accepts a [`Buffer`](http://nodejs.org/api/buffer.html) object.
+   * @param {integer} offset The offset in the buffer to start writing at.
+   * @param {integer} length Specifies the maximum number of bytes to read.
+   * @returns {Promise} Resolves with the number of bytes read after a read operation.
+   * @throws {TypeError} When given invalid arguments, a `TypeError` is thrown.
+   */
+  read(buffer, offset, length) {
+    if (!Buffer.isBuffer(buffer)) {
+      throw new TypeError('"buffer" is not a Buffer');
+    }
+
+    if (typeof offset !== 'number') {
+      throw new TypeError('"offset" is not an integer');
+    }
+
+    if (typeof length !== 'number') {
+      throw new TypeError('"length" is not an integer');
+    }
+
+    debug('read');
+    if (buffer.length < offset + length) {
+      return Promise.reject(new Error('buffer is too small'));
+    }
+
+    if (!this.isOpen) {
+      return Promise.reject(new Error('Port is not open'));
+    }
+    return Promise.resolve();
+  }
+
+  /**
+   * 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.
+
+   * @param {buffer} data - Accepts a [`Buffer`](http://nodejs.org/api/buffer.html) object.
+   * @returns {Promise} Resolves after the data is passed to the operating system for writing.
+   * @throws {TypeError} When given invalid arguments, a `TypeError` is thrown.
+   */
+  write(buffer) {
+    if (!Buffer.isBuffer(buffer)) {
+      throw new TypeError('"buffer" is not a Buffer');
+    }
+
+    debug('write', buffer.length, 'bytes');
+    if (!this.isOpen) {
+      return Promise.reject(new Error('Port is not open'));
+    }
+    return Promise.resolve();
+  }
+
+  /**
+   * Changes connection settings on an open port. Only `baudRate` is supported.
+   * @param {object=} options Only supports `baudRate`.
+   * @param {number=} [options.baudRate] If provided a baud rate that the bindings do not support, it should pass an error to the callback.
+   * @returns {Promise} Resolves once the port's baud rate changes.
+   * @throws {TypeError} When given invalid arguments, a `TypeError` is thrown.
+   */
+  update(options) {
+    if (typeof options !== 'object') {
+      throw TypeError('"options" is not an object');
+    }
+
+    if (typeof options.baudRate !== 'number') {
+      throw new TypeError('"options.baudRate" is not a number');
+    }
+
+    debug('update');
+    if (!this.isOpen) {
+      return Promise.reject(new Error('Port is not open'));
+    }
+    return Promise.resolve();
+  }
+
+  /**
+   * Set control flags on an open port.
+   * @param {object=} options All options are operating system default when the port is opened. Every flag is set on each call to the provided or default values. All options are always provided.
+   * @param {Boolean} [options.brk=false]
+   * @param {Boolean} [options.cts=false]
+   * @param {Boolean} [options.dsr=false]
+   * @param {Boolean} [options.dtr=true]
+   * @param {Boolean} [options.rts=true]
+   * @returns {Promise} Resolves once the port's flags are set.
+   * @throws {TypeError} When given invalid arguments, a `TypeError` is thrown.
+   */
+  set(options) {
+    if (typeof options !== 'object') {
+      throw new TypeError('"options" is not an object');
+    }
+    debug('set');
+    if (!this.isOpen) {
+      return Promise.reject(new Error('Port is not open'));
+    }
+    return Promise.resolve();
+  }
+
+  /**
+   * Get the control flags (CTS, DSR, DCD) on the open port.
+   * @returns {Promise} Resolves with the retrieved flags.
+   * @throws {TypeError} When given invalid arguments, a `TypeError` is thrown.
+   */
+  get() {
+    debug('get');
+    if (!this.isOpen) {
+      return Promise.reject(new Error('Port is not open'));
+    }
+    return Promise.resolve();
+  }
+
+  /**
+     * Get the OS reported baud rate for the open port.
+     * Used mostly for debugging custom baud rates.
+     * @returns {Promise} Resolves with the current baud rate.
+     * @throws {TypeError} When given invalid arguments, a `TypeError` is thrown.
+     */
+  getBaudRate() {
+    debug('getBuadRate');
+    if (!this.isOpen) {
+      return Promise.reject(new Error('Port is not open'));
+    }
+    return Promise.resolve();
+  }
+
+  /**
+   * Flush (discard) data received but not read, and written but not transmitted.
+   * @returns {Promise} Resolves once the flush operation finishes.
+   * @throws {TypeError} When given invalid arguments, a `TypeError` is thrown.
+   */
+  flush() {
+    debug('flush');
+    if (!this.isOpen) {
+      return Promise.reject(new Error('Port is not open'));
+    }
+    return Promise.resolve();
+  }
+
+  /**
+   * Drain waits until all output data is transmitted to the serial port. An in progress write should be completed before this returns.
+   * @returns {Promise} Resolves once the drain operation finishes.
+   * @throws {TypeError} When given invalid arguments, a `TypeError` is thrown.
+   */
+  drain() {
+    debug('drain');
+    if (!this.isOpen) {
+      return Promise.reject(new Error('Port is not open'));
+    }
+    return Promise.resolve();
+  }
+}
+
+module.exports = BaseBinding;
+
+
+
+ + + + +
+ +
+ + + + + + + diff --git a/docs/bindings_poller.js.html b/docs/bindings_poller.js.html new file mode 100644 index 000000000..e5880016b --- /dev/null +++ b/docs/bindings_poller.js.html @@ -0,0 +1,162 @@ + + + + + bindings/poller.js - Documentation + + + + + + + + + + + + + + + + +
+ +

bindings/poller.js

+ + + + + + + +
+
+ 
'use strict';
+const debug = require('debug');
+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,
+  UV_DISCONNECT: 4
+};
+
+function handleEvent(error, eventFlag) {
+  if (error) {
+    logger('error', error);
+    this.emit('readable', error);
+    this.emit('writable', error);
+    this.emit('disconnect', error);
+    return;
+  }
+  if (eventFlag & EVENTS.UV_READABLE) {
+    logger('received "readable"');
+    this.emit('readable', null);
+  }
+  if (eventFlag & EVENTS.UV_WRITABLE) {
+    logger('received "writable"');
+    this.emit('writable', null);
+  }
+  if (eventFlag & EVENTS.UV_DISCONNECT) {
+    logger('received "disconnect"');
+    this.emit('disconnect', null);
+  }
+}
+
+/**
+ * Polls unix systems for readable or writable states of a file or serialport
+ */
+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':
+        this.poll(EVENTS.UV_READABLE);
+        break;
+      case 'writable':
+        this.poll(EVENTS.UV_WRITABLE);
+        break;
+      case 'disconnect':
+        this.poll(EVENTS.UV_DISCONNECT);
+        break;
+    }
+    return EventEmitter.prototype.once.apply(this, arguments);
+  }
+
+  /**
+   * Ask the bindings to listen for an event
+   * @param {EVENTS} eventFlag
+   */
+  poll(eventFlag) {
+    eventFlag = eventFlag || 0;
+
+    if (eventFlag & EVENTS.UV_READABLE) {
+      logger('Polling for "readable"');
+    }
+    if (eventFlag & EVENTS.UV_WRITABLE) {
+      logger('Polling for "writable"');
+    }
+    if (eventFlag & EVENTS.UV_DISCONNECT) {
+      logger('Polling for "disconnect"');
+    }
+
+    this.poller.poll(eventFlag);
+  }
+
+  /**
+   * Stop listening for events and cancel all outstanding listening with an error
+   */
+  stop() {
+    logger('Stopping poller');
+    this.poller.stop();
+    const err = new Error('Canceled');
+    err.canceled = true;
+    this.emit('readable', err);
+    this.emit('writable', err);
+    this.emit('disconnect', err);
+  }
+};
+
+Poller.EVENTS = EVENTS;
+
+module.exports = Poller;
+
+
+
+ + + + +
+ +
+ + + + + + + diff --git a/docs/global.html b/docs/global.html new file mode 100644 index 000000000..dd977957f --- /dev/null +++ b/docs/global.html @@ -0,0 +1,1871 @@ + + + + + Global - Documentation + + + + + + + + + + + + + + + + +
+ +

Global

+ + + + + + + +
+ +
+ +

+ +

+ + +
+ +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + +
+ + + + + + + + + + + + +

Members

+ + + +

(constant) EVENTS :int

+ + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + +
Properties:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
UV_READABLE + + +int + + + +
UV_WRITABLE + + +int + + + +
UV_DISCONNECT + + +int + + + +
+ + + + + + +
+

Enum of event values

+
+ + + +
Type:
+
    +
  • + +int + + +
    • +
+ + + + + + + + + + + + +

Type Definitions

+ + + + + + +

errorCallback(errornullable)

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

A callback called with an error or null.

+
+ + + + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
error + + +error + + + + + + + + <nullable>
+ + + +
+ + + + + + + + + + + + + + + + + + + + + +

listCallback(errornullable, ports)

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

This callback type is called requestCallback.

+
+ + + + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
error + + +error + + + + + + + + <nullable>
+ + + +
ports + + +array + + + + + + + + + +

an array of objects with port info

+ + + + + + + + + + + + + + + + + + + + + +

modemBitsCallback(errornullable, statusnullable)

+ + + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

A callback called with an error or an object with the modem line values (cts, dsr, dcd).

+
+ + + + + + + + + + + +
Parameters:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDescription
error + + +error + + + + + + + + <nullable>
+ + + +
status + + +object + + + + + + + + <nullable>
+ + + + 		+
Properties
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDefaultDescription
cts + + +boolean + + + + + + <optional>
+ + + + + + 		+ + false + +
dsr + + +boolean + + + + + + <optional>
+ + + + + + 		+ + false + +
dcd + + +boolean + + + + + + <optional>
+ + + + + + 		+ + false + +
+ +
+ + + + + + + + + + + + + + + + + + +

openOptions

+ + + + + +
+ + +
Source:
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + +
Properties:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeAttributesDefaultDescription
autoOpen + + +boolean + + + + + + <optional>
+ + + + 		+ + true + +

Automatically opens the port on nextTick.

baudRate + + +number + + + + + + <optional>
+ + + + 		+ + 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 + + + + + + <optional>
+ + + + 		+ + 8 + +

Must be one of these: 8, 7, 6, or 5.

highWaterMark + + +number + + + + + + <optional>
+ + + + 		+ + 65536 + +

The size of the read and write buffers defaults to 64k.

lock + + +boolean + + + + + + <optional>
+ + + + 		+ + true + +

Prevent other processes from opening the port. Windows does not currently support false.

stopBits + + +number + + + + + + <optional>
+ + + + 		+ + 1 + +

Must be one of these: 1 or 2.

parity + + +string + + + + + + <optional>
+ + + + 		+ + none + +

Must be one of these: 'none', 'even', 'mark', 'odd', 'space'.

rtscts + + +boolean + + + + + + <optional>
+ + + + 		+ + false + +

flow control setting

xon + + +boolean + + + + + + <optional>
+ + + + 		+ + false + +

flow control setting

xoff + + +boolean + + + + + + <optional>
+ + + + 		+ + false + +

flow control setting

xany + + +boolean + + + + + + <optional>
+ + + + 		+ + false + +

flow control setting

bindingOptions + + +object + + + + + + <optional>
+ + + + 		+ +

sets binding-specific options

Binding + + +module:serialport~Binding + + + + + + <optional>
+ + + + 		+ +

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 + + + + + + <optional>
+ + + + 		+ + 1 + +

see man termios LinuxBinding and DarwinBinding

bindingOptions.vtime + + +number + + + + + + <optional>
+ + + + 		+ + 0 + +

see man termios LinuxBinding and DarwinBinding

+ + + + + + + + +
Type:
+
    +
  • + +Object + + +
    • +
+ + + + + + + + +

Parsers

+ + + + + +
+ + +
Source:
+
+ + + + + +
Since:
+
  • 5.0.0
+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + +
Properties:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
ByteLength + + +Transform + + + +
CCtalk + + +Transform + + + +
Delimiter + + +Transform + + + +
Readline + + +Transform + + + +
Ready + + +Transform + + + +
Regex + + +Transform + + + +
+ + + + + + +
+

The default Parsers are Transform streams that parse data in different ways to transform incoming data.

+

To use the parsers, you must create them and then pipe the Serialport to the parser. Be careful to only write to the SerialPort object and not the parser.

+
+ + + +
Type:
+
    +
  • + +Object + + +
    • +
+ + + + + +
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());
+```
+ + + + + + + +
+ +
+ + + + +
+ +
+ + + + + + + \ No newline at end of file diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 000000000..8f1f421dc --- /dev/null +++ b/docs/index.html @@ -0,0 +1,472 @@ + + + + + Home - Documentation + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + + + + + + +
+

Node Serialport

npm
Gitter chat
Known Vulnerabilities
codecov
Build Status
Build status
Greenkeeper badge

+

Intro to Node-Serialport

Imagine a world in which you can write JavaScript to control blenders, lights, security systems, or even robots. That's right—robots! Thanks to Node Serialport, that world is here.

+

Node-Serialport provides a stream interface for the low-level serial port code necessary to controll Arduino chipsets, X10 interfaces, Zigbee radios, highway signs, lcd screens, cash drawers, motor controllers, sensor packages, fork lifts, modems, drones, CNC machines, plotters, vending machines, ccTalk coin accecptors, SMS Gateways, RFID scanners and much more. If if you have a hardware device with an UART we can speak to it. The physical world is your oyster with this goodie.

+

For a full breakdown of why we made Node-Serialport, please read NodeBots - The Rise of JS Robotics. It explains why one would want to program robots in JS in the first place.

+

We're not against firmware but we're better than it.

+

Quick Answers to Important Questions

+
+

API Documentation

Can be found at https://doclets.io/node-serialport/node-serialport/

+

See our changelog for what's new, and our upgrade guide for a walk-through on differences between major versions.

+

Older versions are no longer supported but their docs can be found by looking through release tags.

+

You can generate the docs by running

+
npm run docs

And browsing to ./docs/index.html.

+
+

Helpful Resources for Getting Started with Node-Serialport

In addition to reading the article mentioned above, these others might help you:

+ +
+

Table of Contents

+
+

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 / ArchNode v4.xNode v6.xNode v8.xNode v9.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.

+

⁴ Node 9 is not supported but we're providing builds for it.

+

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 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 is a (very) small distro, but it uses the musl standard library instead of glibc (used by most other Linux distros) so it requires compilation. It's commonly used with Docker. A user has confirmed that Node-Serialport works with alpine-node.

+
# If you don't have node/npm already, add that first
+sudo apk add --no-cache nodejs
+
+# Add the necessary build and runtime dependencies
+sudo apk add --no-cache make gcc g++ python linux-headers udev
+
+# Then we can install serialport, forcing it to compile
+npm install serialport --build-from-source
+
+# If you're installing as root, you'll also need to use the --unsafe-perm flag

Electron

Electron is a framework for creating cross-platform desktop applications. It comes with its own version of the Node.js runtime.

+

If you require serialport as a dependency for an Electron project, you must compile it for the version of Electron your project's using.

+

When you first install serialport it will compile against the version of Node.js on your machine, not against the Node.js runtime bundled with Electron.

+

To recompile serialport (or any native Node.js module) for Electron, you can use electron-rebuild; more info at Electron's README.

+
    +
  1. npm install --save-dev electron-rebuild
    2. +
  2. Add electron-rebuild to your project's package.json's install hook
    3. +
  3. Run npm install
    4. +
+

For an example project, check out electron-serialport.

+

NW.js

NW.js is an app runtime based on Chromium and node.js.

+

Like Electron, NW.js also requires compilation against its own specific headers.

+

To instruct prebuild to build against the correct headers, place a file named .prebuildrc on your package root with the following content:

+
build_from_source=true
+runtime=node-webkit
+target=<target_version>

Where <target_version> is the NW.js version you are building against (for example, 0.26.6).

+

OBS: NW.js support requires prebuild >= 7.3.0.

+

Illegal Instruction

The pre-compiled binaries assume a fully capable chip. Intel's Galileo 2, for example, lacks a few instruction sets from the ia32 architecture. A few other platforms have similar issues. If you get Illegal Instruction when trying to run Node-Serialport, you'll need to ask npm to rebuild the Serialport binary.

+
# Will ask npm to build serialport during install time
+npm install serialport --build-from-source
+
+# If you have a package that depends on serialport, you can ask npm to rebuild it specifically...
+npm rebuild serialport --build-from-source

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. These projects use Node Serialport under the hood.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RevisionCPUArm Version
A, A+, B, B+32-bit ARM1176JZF-SARMv6
Compute Module32-bit ARM1176JZF-SARMv6
Zero32-bit ARM1176JZF-SARMv6
B232-bit ARM Cortex-A7ARMv7
B332-bit ARM Cortex-A53ARMv8
+

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.

+
sudo npm install serialport --unsafe-perm --build-from-source

Failure to use the flag results in an error like this:

+
root@rpi3:~# npm install -g serialport
+/usr/bin/serialport-list -> /usr/lib/node_modules/serialport/bin/serialport-list.js
+/usr/bin/serialport-term -> /usr/lib/node_modules/serialport/bin/serialport-terminal.js
+
+
+> serialport@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. Older versions of Ubuntu install Node.js with the wrong version and binary name. If your Node binary is nodejs instead of node, or if your Node version is v0.10.29, then you should follow these instructions.

+

You'll need the package build-essential to compile serialport. If there's a binary for your platform, you won't need it. Keep rocking!

+
# Using Ubuntu and Node 6
+curl -sL https://deb.nodesource.com/setup_7.x | sudo -E bash -
+sudo apt-get install -y nodejs
+
+# Using Debian and Node 6 as root
+curl -sL https://deb.nodesource.com/setup_7.x | bash -
+apt-get install -y nodejs

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 instructions. Once you've got things working, you can install Node-Serialport from source with:

+
npm install serialport --build-from-source

Node-gyp's documentation doesn't mention it, but it sometimes helps to create a C++ project in Visual Studio so that it will install any necessary components not already installed during the past two hours of setup. This will solve some instances of Failed to locate: "CL.exe".

+

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

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.
    2. +
  2. Options - optional and described below.
    3. +
+

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.
    • +
+
var SerialPort = require('serialport');
+var port = new SerialPort('/dev/tty-usbserial1');
+
+port.write('main screen turn on', function(err) {
+  if (err) {
+    return console.log('Error on write: ', err.message);
+  }
+  console.log('message written');
+});
+
+// Open errors will be emitted as an error event
+port.on('error', function(err) {
+  console.log('Error: ', err.message);
+})

Detecting open errors can be moved to the constructor's callback.

+
var SerialPort = require('serialport');
+var port = new SerialPort('/dev/tty-usbserial1', function (err) {
+  if (err) {
+    return console.log('Error: ', err.message);
+  }
+});
+
+port.write('main screen turn on', function(err) {
+  if (err) {
+    return console.log('Error on write: ', err.message);
+  }
+  console.log('message written');
+});

When disabling the autoOpen option you'll need to open the port on your own.

+
var SerialPort = require('serialport');
+var port = new SerialPort('/dev/tty-usbserial1', { autoOpen: false });
+
+port.open(function (err) {
+  if (err) {
+    return console.log('Error opening port: ', err.message);
+  }
+
+  // Because there's no callback to write, write errors will be emitted on the port:
+  port.write('main screen turn on');
+});
+
+// The open event is always emitted
+port.on('open', function() {
+  // open logic
+});

Get updates of new data from the serial port as follows:

+
// Switches the port into "flowing mode"
+port.on('data', function (data) {
+  console.log('Data:', data);
+});
+
+// Read data that is available but keep the stream from entering "flowing mode"
+port.on('readable', function () {
+  console.log('Data:', port.read());
+});

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

+
port.write('Hi Mom!');
+port.write(Buffer.from('Hi Mom!'));

Enjoy and do cool things with this code.

+

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.

+
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 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 docs for info.

+
DEBUG=serialport:main node myapp.js
+DEBUG=serialport:* node myapp.js
+DEBUG=* node myapp.js

You can enable core dumps on osx with;

+
ulimit -c unlimited for core dumps

You can "console.log" from c++ with;

+
fprintf(stdout, "Hellow World num=%d str=%s\n", 4, "hi");

You can make use of the serialport-repl command with;

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

+

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.

+
$ serialport-list -h
+
+  Usage: serialport-list [options]
+
+  List available serial ports
+
+  Options:
+
+    -h, --help           output usage information
+    -V, --version        output the version number
+    -f, --format <type>  Format the output as text, json, or jsonline. default: text
+
+
+$ serialport-list
+/dev/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.

+
$ serialport-term -h
+
+  Usage: serialport-term -p <port> [options]
+
+  A basic terminal interface for communicating over a serial port. Pressing ctrl+c exits.
+
+  Options:
+
+    -h, --help                     output usage information
+    -V, --version                  output the version number
+    -l --list                      List available ports then exit
+    -p, --port, --portname <port>  Path or name of serial port
+    -b, --baud <baudrate>          Baud rate default: 9600
+    --databits <databits>          Data bits default: 8
+    --parity <parity>              Parity default: none
+    --stopbits <bits>              Stop bits default: 1
+    --echo --localecho             Print characters as you type them
+
+$ serialport-term -l
+/dev/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;

+
$ 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 and all it's dependencies are MIT or BSD licensed.

+
+ + + + + + +
+ +
+ + + + + + + \ No newline at end of file diff --git a/docs/index.js.html b/docs/index.js.html new file mode 100644 index 000000000..04bef39c0 --- /dev/null +++ b/docs/index.js.html @@ -0,0 +1,74 @@ + + + + + index.js - Documentation + + + + + + + + + + + + + + + + +
+ +

index.js

+ + + + + + + +
+
+ 
'use strict';
+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/docs/parsers_byte-length.js.html b/docs/parsers_byte-length.js.html new file mode 100644 index 000000000..8b99c7d0b --- /dev/null +++ b/docs/parsers_byte-length.js.html @@ -0,0 +1,118 @@ + + + + + parsers/byte-length.js - Documentation + + + + + + + + + + + + + + + + +
+ +

parsers/byte-length.js

+ + + + + + + +
+
+ 
'use strict';
+const Buffer = require('safe-buffer').Buffer;
+const Transform = require('stream').Transform;
+
+/**
+ * A transform stream that emits data as a buffer after a specific number of bytes are received.
+ * @extends Transform
+ * @param {Object} options
+ * @param {Number} options.length the number of bytes on each data event
+ * @example
+To use the `ByteLength` parser:
+```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); // will have 8 bytes per data event
+```
+ */
+class ByteLengthParser extends Transform {
+  constructor(options) {
+    super(options);
+    options = options || {};
+
+    if (typeof options.length !== 'number') {
+      throw new TypeError('"length" is not a number');
+    }
+
+    if (options.length < 1) {
+      throw new TypeError('"length" is not greater than 0');
+    }
+
+    this.length = options.length;
+    this.position = 0;
+    this.buffer = Buffer.alloc(this.length);
+  }
+
+  _transform(chunk, encoding, cb) {
+    let cursor = 0;
+    while (cursor < chunk.length) {
+      this.buffer[this.position] = chunk[cursor];
+      cursor++;
+      this.position++;
+      if (this.position === this.length) {
+        this.push(this.buffer);
+        this.buffer = Buffer.alloc(this.length);
+        this.position = 0;
+      }
+    }
+    cb();
+  }
+
+  _flush(cb) {
+    this.push(this.buffer.slice(0, this.position));
+    this.buffer = Buffer.alloc(this.length);
+    cb();
+  }
+};
+
+module.exports = ByteLengthParser;
+
+
+
+ + + + +
+ +
+ + + + + + + diff --git a/docs/parsers_cctalk.js.html b/docs/parsers_cctalk.js.html new file mode 100644 index 000000000..4f725f9e6 --- /dev/null +++ b/docs/parsers_cctalk.js.html @@ -0,0 +1,103 @@ + + + + + parsers/cctalk.js - Documentation + + + + + + + + + + + + + + + + +
+ +

parsers/cctalk.js

+ + + + + + + +
+
+ 
'use strict';
+const Transform = require('stream').Transform;
+const Buffer = require('safe-buffer').Buffer;
+/**
+ * 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 = [];
+    this.cursor = 0;
+  }
+  _transform(buffer, _, cb) {
+    this.cursor += buffer.length;
+    // TODO: Better Faster es7 no supported by node 4
+    // ES7 allows directly push [...buffer]
+    // this.array = this.array.concat(Array.from(buffer)); //Slower ?!?
+    Array.from(buffer)
+      .map((byte) => this.array.push(byte));
+    while (this.cursor > 1 && this.cursor >= this.array[1] + 5) {
+      // full frame accumulated
+      // copy command from the array
+      const FullMsgLength = this.array[1] + 5;
+
+      const frame = Buffer.from(this.array.slice(0, FullMsgLength));
+      // Preserve Extra Data
+      this.array = this.array.slice(frame.length, this.array.length);
+      this.cursor -= FullMsgLength;
+      this.push(frame);
+    }
+    cb();
+  }
+};
+
+module.exports = CCTalkParser;
+
+
+
+ + + + +
+ +
+ + + + + + + diff --git a/docs/parsers_delimiter.js.html b/docs/parsers_delimiter.js.html new file mode 100644 index 000000000..b5d1c3482 --- /dev/null +++ b/docs/parsers_delimiter.js.html @@ -0,0 +1,111 @@ + + + + + parsers/delimiter.js - Documentation + + + + + + + + + + + + + + + + +
+ +

parsers/delimiter.js

+ + + + + + + +
+
+ 
'use strict';
+const Buffer = require('safe-buffer').Buffer;
+const Transform = require('stream').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);
+
+    if (options.delimiter === undefined) {
+      throw new TypeError('"delimiter" is not a bufferable object');
+    }
+
+    if (options.delimiter.length === 0) {
+      throw new TypeError('"delimiter" has a 0 or undefined length');
+    }
+
+    this.includeDelimiter = options.includeDelimiter !== undefined ? options.includeDelimiter : false;
+    this.delimiter = Buffer.from(options.delimiter);
+    this.buffer = Buffer.alloc(0);
+  }
+
+  _transform(chunk, encoding, cb) {
+    let data = Buffer.concat([this.buffer, chunk]);
+    let position;
+    while ((position = data.indexOf(this.delimiter)) !== -1) {
+      this.push(data.slice(0, position + (this.includeDelimiter ? this.delimiter.length : 0)));
+      data = data.slice(position + this.delimiter.length);
+    }
+    this.buffer = data;
+    cb();
+  }
+
+  _flush(cb) {
+    this.push(this.buffer);
+    this.buffer = Buffer.alloc(0);
+    cb();
+  }
+};
+
+module.exports = DelimiterParser;
+
+
+
+ + + + +
+ +
+ + + + + + + diff --git a/docs/parsers_index.js.html b/docs/parsers_index.js.html new file mode 100644 index 000000000..6e89298cb --- /dev/null +++ b/docs/parsers_index.js.html @@ -0,0 +1,95 @@ + + + + + parsers/index.js - Documentation + + + + + + + + + + + + + + + + +
+ +

parsers/index.js

+ + + + + + + +
+
+ 
'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.
+ * @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
+```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());
+```
+ */
+
+module.exports = {
+  ByteLength: require('./byte-length'),
+  CCTalk: require('./cctalk'),
+  Delimiter: require('./delimiter'),
+  Readline: require('./readline'),
+  Ready: require('./ready'),
+  Regex: require('./regex')
+};
+
+
+
+ + + + +
+ +
+ + + + + + + diff --git a/docs/parsers_readline.js.html b/docs/parsers_readline.js.html new file mode 100644 index 000000000..fd0b39339 --- /dev/null +++ b/docs/parsers_readline.js.html @@ -0,0 +1,90 @@ + + + + + parsers/readline.js - Documentation + + + + + + + + + + + + + + + + +
+ +

parsers/readline.js

+ + + + + + + +
+
+ 
'use strict';
+const Buffer = require('safe-buffer').Buffer;
+const DelimiterParser = require('./delimiter');
+/**
+ *  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'),
+      encoding: 'utf8'
+    }, options);
+
+    if (typeof opts.delimiter === 'string') {
+      opts.delimiter = Buffer.from(opts.delimiter, opts.encoding);
+    }
+
+    super(opts);
+  }
+};
+
+module.exports = ReadLineParser;
+
+
+
+ + + + +
+ +
+ + + + + + + diff --git a/docs/parsers_ready.js.html b/docs/parsers_ready.js.html new file mode 100644 index 000000000..5f0eadc92 --- /dev/null +++ b/docs/parsers_ready.js.html @@ -0,0 +1,125 @@ + + + + + parsers/ready.js - Documentation + + + + + + + + + + + + + + + + +
+ +

parsers/ready.js

+ + + + + + + +
+
+ 
'use strict';
+const Buffer = require('safe-buffer').Buffer;
+const Transform = require('stream').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({ delimiter: '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 {
+  /**
+   *
+   * @param {object} options
+   * @param {string|Buffer|array} options.delimiter
+   */
+  constructor(options) {
+    options = options || {};
+    if (options.delimiter === undefined) {
+      throw new TypeError('"delimiter" is not a bufferable object');
+    }
+
+    if (options.delimiter.length === 0) {
+      throw new TypeError('"delimiter" has a 0 or undefined length');
+    }
+
+    super(options);
+    this.delimiter = Buffer.from(options.delimiter);
+    this.readOffset = 0;
+    this.ready = false;
+  }
+
+  _transform(chunk, encoding, cb) {
+    if (this.ready) {
+      this.push(chunk);
+      return cb();
+    }
+    const delimiter = this.delimiter;
+    let chunkOffset = 0;
+    while (this.readOffset < delimiter.length && chunkOffset < chunk.length) {
+      if (delimiter[this.readOffset] === chunk[chunkOffset]) {
+        this.readOffset++;
+      } else {
+        this.readOffset = 0;
+      }
+      chunkOffset++;
+    }
+    if (this.readOffset === delimiter.length) {
+      this.ready = true;
+      this.emit('ready');
+      const chunkRest = chunk.slice(chunkOffset);
+      if (chunkRest.length > 0) {
+        this.push(chunkRest);
+      }
+    }
+    cb();
+  }
+};
+
+module.exports = ReadyParser;
+
+
+
+ + + + +
+ +
+ + + + + + + diff --git a/docs/parsers_regex.js.html b/docs/parsers_regex.js.html new file mode 100644 index 000000000..41a8b2435 --- /dev/null +++ b/docs/parsers_regex.js.html @@ -0,0 +1,112 @@ + + + + + parsers/regex.js - Documentation + + + + + + + + + + + + + + + + +
+ +

parsers/regex.js

+ + + + + + + +
+
+ 
'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);
+```
+
+ */
+class RegexParser extends Transform {
+  constructor(options) {
+    const opts = Object.assign({
+      encoding: 'utf8'
+    }, options);
+
+    if (opts.regex === undefined) {
+      throw new TypeError('"options.regex" must be a regular expression pattern or object');
+    }
+
+    if (!(opts.regex instanceof RegExp)) {
+      opts.regex = new RegExp(opts.regex);
+    }
+    super(opts);
+
+    this.regex = opts.regex;
+    this.buffer = '';
+  }
+
+  _transform(chunk, encoding, cb) {
+    const data = this.buffer + chunk;
+    const parts = data.split(this.regex);
+    this.buffer = parts.pop();
+
+    parts.forEach((part) => {
+      this.push(part);
+    });
+    cb();
+  }
+
+  _flush(cb) {
+    this.push(this.buffer);
+    this.buffer = '';
+    cb();
+  }
+};
+
+module.exports = RegexParser;
+
+
+
+ + + + +
+ +
+ + + + + + + diff --git a/docs/scripts/linenumber.js b/docs/scripts/linenumber.js new file mode 100644 index 000000000..9cb891484 --- /dev/null +++ b/docs/scripts/linenumber.js @@ -0,0 +1,25 @@ +/*global document */ +(function() { + var source = document.getElementsByClassName('prettyprint source linenums'); + var i = 0; + var lineNumber = 0; + var lineId; + var lines; + var totalLines; + var anchorHash; + + if (source && source[0]) { + anchorHash = document.location.hash.substring(1); + lines = source[0].getElementsByTagName('li'); + totalLines = lines.length; + + for (; i < totalLines; i++) { + lineNumber++; + lineId = 'line' + lineNumber; + lines[i].id = lineId; + if (lineId === anchorHash) { + lines[i].className += ' selected'; + } + } + } +})(); diff --git a/docs/scripts/prettify/Apache-License-2.0.txt b/docs/scripts/prettify/Apache-License-2.0.txt new file mode 100644 index 000000000..75b52484e --- /dev/null +++ b/docs/scripts/prettify/Apache-License-2.0.txt @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/docs/scripts/prettify/lang-css.js b/docs/scripts/prettify/lang-css.js new file mode 100644 index 000000000..bb6dbea43 --- /dev/null +++ b/docs/scripts/prettify/lang-css.js @@ -0,0 +1,2 @@ +PR.registerLangHandler(PR.createSimpleLexer([["pln",/^[\t\n\f\r ]+/,null," \t\r\n "]],[["str",/^"(?:[^\n\f\r"\\]|\\(?:\r\n?|\n|\f)|\\[\S\s])*"/,null],["str",/^'(?:[^\n\f\r'\\]|\\(?:\r\n?|\n|\f)|\\[\S\s])*'/,null],["lang-css-str",/^url\(([^"')]*)\)/i],["kwd",/^(?:url|rgb|!important|@import|@page|@media|@charset|inherit)(?=[^\w-]|$)/i,null],["lang-css-kw",/^(-?(?:[_a-z]|\\[\da-f]+ ?)(?:[\w-]|\\\\[\da-f]+ ?)*)\s*:/i],["com",/^\/\*[^*]*\*+(?:[^*/][^*]*\*+)*\//],["com", +/^(?:<\!--|--\>)/],["lit",/^(?:\d+|\d*\.\d+)(?:%|[a-z]+)?/i],["lit",/^#[\da-f]{3,6}/i],["pln",/^-?(?:[_a-z]|\\[\da-f]+ ?)(?:[\w-]|\\\\[\da-f]+ ?)*/i],["pun",/^[^\s\w"']+/]]),["css"]);PR.registerLangHandler(PR.createSimpleLexer([],[["kwd",/^-?(?:[_a-z]|\\[\da-f]+ ?)(?:[\w-]|\\\\[\da-f]+ ?)*/i]]),["css-kw"]);PR.registerLangHandler(PR.createSimpleLexer([],[["str",/^[^"')]+/]]),["css-str"]); diff --git a/docs/scripts/prettify/prettify.js b/docs/scripts/prettify/prettify.js new file mode 100644 index 000000000..ec2a488bd --- /dev/null +++ b/docs/scripts/prettify/prettify.js @@ -0,0 +1,28 @@ +var q=null;window.PR_SHOULD_USE_CONTINUATION=!0; +(function(){function L(a){function m(a){var f=a.charCodeAt(0);if(f!==92)return f;var b=a.charAt(1);return(f=r[b])?f:"0"<=b&&b<="7"?parseInt(a.substring(1),8):b==="u"||b==="x"?parseInt(a.substring(2),16):a.charCodeAt(1)}function e(a){if(a<32)return(a<16?"\\x0":"\\x")+a.toString(16);a=String.fromCharCode(a);if(a==="\\"||a==="-"||a==="["||a==="]")a="\\"+a;return a}function h(a){for(var f=a.substring(1,a.length-1).match(/\\u[\dA-Fa-f]{4}|\\x[\dA-Fa-f]{2}|\\[0-3][0-7]{0,2}|\\[0-7]{1,2}|\\[\S\s]|[^\\]/g),a= +[],b=[],o=f[0]==="^",c=o?1:0,i=f.length;c122||(d<65||j>90||b.push([Math.max(65,j)|32,Math.min(d,90)|32]),d<97||j>122||b.push([Math.max(97,j)&-33,Math.min(d,122)&-33]))}}b.sort(function(a,f){return a[0]-f[0]||f[1]-a[1]});f=[];j=[NaN,NaN];for(c=0;ci[0]&&(i[1]+1>i[0]&&b.push("-"),b.push(e(i[1])));b.push("]");return b.join("")}function y(a){for(var f=a.source.match(/\[(?:[^\\\]]|\\[\S\s])*]|\\u[\dA-Fa-f]{4}|\\x[\dA-Fa-f]{2}|\\\d+|\\[^\dux]|\(\?[!:=]|[()^]|[^()[\\^]+/g),b=f.length,d=[],c=0,i=0;c=2&&a==="["?f[c]=h(j):a!=="\\"&&(f[c]=j.replace(/[A-Za-z]/g,function(a){a=a.charCodeAt(0);return"["+String.fromCharCode(a&-33,a|32)+"]"}));return f.join("")}for(var t=0,s=!1,l=!1,p=0,d=a.length;p=5&&"lang-"===b.substring(0,5))&&!(o&&typeof o[1]==="string"))c=!1,b="src";c||(r[f]=b)}i=d;d+=f.length;if(c){c=o[1];var j=f.indexOf(c),k=j+c.length;o[2]&&(k=f.length-o[2].length,j=k-c.length);b=b.substring(5);B(l+i,f.substring(0,j),e,p);B(l+i+j,c,C(b,c),p);B(l+i+k,f.substring(k),e,p)}else p.push(l+i,b)}a.e=p}var h={},y;(function(){for(var e=a.concat(m), +l=[],p={},d=0,g=e.length;d=0;)h[n.charAt(k)]=r;r=r[1];n=""+r;p.hasOwnProperty(n)||(l.push(r),p[n]=q)}l.push(/[\S\s]/);y=L(l)})();var t=m.length;return e}function u(a){var m=[],e=[];a.tripleQuotedStrings?m.push(["str",/^(?:'''(?:[^'\\]|\\[\S\s]|''?(?=[^']))*(?:'''|$)|"""(?:[^"\\]|\\[\S\s]|""?(?=[^"]))*(?:"""|$)|'(?:[^'\\]|\\[\S\s])*(?:'|$)|"(?:[^"\\]|\\[\S\s])*(?:"|$))/,q,"'\""]):a.multiLineStrings?m.push(["str",/^(?:'(?:[^'\\]|\\[\S\s])*(?:'|$)|"(?:[^"\\]|\\[\S\s])*(?:"|$)|`(?:[^\\`]|\\[\S\s])*(?:`|$))/, +q,"'\"`"]):m.push(["str",/^(?:'(?:[^\n\r'\\]|\\.)*(?:'|$)|"(?:[^\n\r"\\]|\\.)*(?:"|$))/,q,"\"'"]);a.verbatimStrings&&e.push(["str",/^@"(?:[^"]|"")*(?:"|$)/,q]);var h=a.hashComments;h&&(a.cStyleComments?(h>1?m.push(["com",/^#(?:##(?:[^#]|#(?!##))*(?:###|$)|.*)/,q,"#"]):m.push(["com",/^#(?:(?:define|elif|else|endif|error|ifdef|include|ifndef|line|pragma|undef|warning)\b|[^\n\r]*)/,q,"#"]),e.push(["str",/^<(?:(?:(?:\.\.\/)*|\/?)(?:[\w-]+(?:\/[\w-]+)+)?[\w-]+\.h|[a-z]\w*)>/,q])):m.push(["com",/^#[^\n\r]*/, +q,"#"]));a.cStyleComments&&(e.push(["com",/^\/\/[^\n\r]*/,q]),e.push(["com",/^\/\*[\S\s]*?(?:\*\/|$)/,q]));a.regexLiterals&&e.push(["lang-regex",/^(?:^^\.?|[!+-]|!=|!==|#|%|%=|&|&&|&&=|&=|\(|\*|\*=|\+=|,|-=|->|\/|\/=|:|::|;|<|<<|<<=|<=|=|==|===|>|>=|>>|>>=|>>>|>>>=|[?@[^]|\^=|\^\^|\^\^=|{|\||\|=|\|\||\|\|=|~|break|case|continue|delete|do|else|finally|instanceof|return|throw|try|typeof)\s*(\/(?=[^*/])(?:[^/[\\]|\\[\S\s]|\[(?:[^\\\]]|\\[\S\s])*(?:]|$))+\/)/]);(h=a.types)&&e.push(["typ",h]);a=(""+a.keywords).replace(/^ | $/g, +"");a.length&&e.push(["kwd",RegExp("^(?:"+a.replace(/[\s,]+/g,"|")+")\\b"),q]);m.push(["pln",/^\s+/,q," \r\n\t\xa0"]);e.push(["lit",/^@[$_a-z][\w$@]*/i,q],["typ",/^(?:[@_]?[A-Z]+[a-z][\w$@]*|\w+_t\b)/,q],["pln",/^[$_a-z][\w$@]*/i,q],["lit",/^(?:0x[\da-f]+|(?:\d(?:_\d+)*\d*(?:\.\d*)?|\.\d\+)(?:e[+-]?\d+)?)[a-z]*/i,q,"0123456789"],["pln",/^\\[\S\s]?/,q],["pun",/^.[^\s\w"-$'./@\\`]*/,q]);return x(m,e)}function D(a,m){function e(a){switch(a.nodeType){case 1:if(k.test(a.className))break;if("BR"===a.nodeName)h(a), +a.parentNode&&a.parentNode.removeChild(a);else for(a=a.firstChild;a;a=a.nextSibling)e(a);break;case 3:case 4:if(p){var b=a.nodeValue,d=b.match(t);if(d){var c=b.substring(0,d.index);a.nodeValue=c;(b=b.substring(d.index+d[0].length))&&a.parentNode.insertBefore(s.createTextNode(b),a.nextSibling);h(a);c||a.parentNode.removeChild(a)}}}}function h(a){function b(a,d){var e=d?a.cloneNode(!1):a,f=a.parentNode;if(f){var f=b(f,1),g=a.nextSibling;f.appendChild(e);for(var h=g;h;h=g)g=h.nextSibling,f.appendChild(h)}return e} +for(;!a.nextSibling;)if(a=a.parentNode,!a)return;for(var a=b(a.nextSibling,0),e;(e=a.parentNode)&&e.nodeType===1;)a=e;d.push(a)}var k=/(?:^|\s)nocode(?:\s|$)/,t=/\r\n?|\n/,s=a.ownerDocument,l;a.currentStyle?l=a.currentStyle.whiteSpace:window.getComputedStyle&&(l=s.defaultView.getComputedStyle(a,q).getPropertyValue("white-space"));var p=l&&"pre"===l.substring(0,3);for(l=s.createElement("LI");a.firstChild;)l.appendChild(a.firstChild);for(var d=[l],g=0;g=0;){var h=m[e];A.hasOwnProperty(h)?window.console&&console.warn("cannot override language handler %s",h):A[h]=a}}function C(a,m){if(!a||!A.hasOwnProperty(a))a=/^\s*=o&&(h+=2);e>=c&&(a+=2)}}catch(w){"console"in window&&console.log(w&&w.stack?w.stack:w)}}var v=["break,continue,do,else,for,if,return,while"],w=[[v,"auto,case,char,const,default,double,enum,extern,float,goto,int,long,register,short,signed,sizeof,static,struct,switch,typedef,union,unsigned,void,volatile"], +"catch,class,delete,false,import,new,operator,private,protected,public,this,throw,true,try,typeof"],F=[w,"alignof,align_union,asm,axiom,bool,concept,concept_map,const_cast,constexpr,decltype,dynamic_cast,explicit,export,friend,inline,late_check,mutable,namespace,nullptr,reinterpret_cast,static_assert,static_cast,template,typeid,typename,using,virtual,where"],G=[w,"abstract,boolean,byte,extends,final,finally,implements,import,instanceof,null,native,package,strictfp,super,synchronized,throws,transient"], +H=[G,"as,base,by,checked,decimal,delegate,descending,dynamic,event,fixed,foreach,from,group,implicit,in,interface,internal,into,is,lock,object,out,override,orderby,params,partial,readonly,ref,sbyte,sealed,stackalloc,string,select,uint,ulong,unchecked,unsafe,ushort,var"],w=[w,"debugger,eval,export,function,get,null,set,undefined,var,with,Infinity,NaN"],I=[v,"and,as,assert,class,def,del,elif,except,exec,finally,from,global,import,in,is,lambda,nonlocal,not,or,pass,print,raise,try,with,yield,False,True,None"], +J=[v,"alias,and,begin,case,class,def,defined,elsif,end,ensure,false,in,module,next,nil,not,or,redo,rescue,retry,self,super,then,true,undef,unless,until,when,yield,BEGIN,END"],v=[v,"case,done,elif,esac,eval,fi,function,in,local,set,then,until"],K=/^(DIR|FILE|vector|(de|priority_)?queue|list|stack|(const_)?iterator|(multi)?(set|map)|bitset|u?(int|float)\d*)/,N=/\S/,O=u({keywords:[F,H,w,"caller,delete,die,do,dump,elsif,eval,exit,foreach,for,goto,if,import,last,local,my,next,no,our,print,package,redo,require,sub,undef,unless,until,use,wantarray,while,BEGIN,END"+ +I,J,v],hashComments:!0,cStyleComments:!0,multiLineStrings:!0,regexLiterals:!0}),A={};k(O,["default-code"]);k(x([],[["pln",/^[^]*(?:>|$)/],["com",/^<\!--[\S\s]*?(?:--\>|$)/],["lang-",/^<\?([\S\s]+?)(?:\?>|$)/],["lang-",/^<%([\S\s]+?)(?:%>|$)/],["pun",/^(?:<[%?]|[%?]>)/],["lang-",/^]*>([\S\s]+?)<\/xmp\b[^>]*>/i],["lang-js",/^]*>([\S\s]*?)(<\/script\b[^>]*>)/i],["lang-css",/^]*>([\S\s]*?)(<\/style\b[^>]*>)/i],["lang-in.tag",/^(<\/?[a-z][^<>]*>)/i]]), +["default-markup","htm","html","mxml","xhtml","xml","xsl"]);k(x([["pln",/^\s+/,q," \t\r\n"],["atv",/^(?:"[^"]*"?|'[^']*'?)/,q,"\"'"]],[["tag",/^^<\/?[a-z](?:[\w-.:]*\w)?|\/?>$/i],["atn",/^(?!style[\s=]|on)[a-z](?:[\w:-]*\w)?/i],["lang-uq.val",/^=\s*([^\s"'>]*(?:[^\s"'/>]|\/(?=\s)))/],["pun",/^[/<->]+/],["lang-js",/^on\w+\s*=\s*"([^"]+)"/i],["lang-js",/^on\w+\s*=\s*'([^']+)'/i],["lang-js",/^on\w+\s*=\s*([^\s"'>]+)/i],["lang-css",/^style\s*=\s*"([^"]+)"/i],["lang-css",/^style\s*=\s*'([^']+)'/i],["lang-css", +/^style\s*=\s*([^\s"'>]+)/i]]),["in.tag"]);k(x([],[["atv",/^[\S\s]+/]]),["uq.val"]);k(u({keywords:F,hashComments:!0,cStyleComments:!0,types:K}),["c","cc","cpp","cxx","cyc","m"]);k(u({keywords:"null,true,false"}),["json"]);k(u({keywords:H,hashComments:!0,cStyleComments:!0,verbatimStrings:!0,types:K}),["cs"]);k(u({keywords:G,cStyleComments:!0}),["java"]);k(u({keywords:v,hashComments:!0,multiLineStrings:!0}),["bsh","csh","sh"]);k(u({keywords:I,hashComments:!0,multiLineStrings:!0,tripleQuotedStrings:!0}), +["cv","py"]);k(u({keywords:"caller,delete,die,do,dump,elsif,eval,exit,foreach,for,goto,if,import,last,local,my,next,no,our,print,package,redo,require,sub,undef,unless,until,use,wantarray,while,BEGIN,END",hashComments:!0,multiLineStrings:!0,regexLiterals:!0}),["perl","pl","pm"]);k(u({keywords:J,hashComments:!0,multiLineStrings:!0,regexLiterals:!0}),["rb"]);k(u({keywords:w,cStyleComments:!0,regexLiterals:!0}),["js"]);k(u({keywords:"all,and,by,catch,class,else,extends,false,finally,for,if,in,is,isnt,loop,new,no,not,null,of,off,on,or,return,super,then,true,try,unless,until,when,while,yes", +hashComments:3,cStyleComments:!0,multilineStrings:!0,tripleQuotedStrings:!0,regexLiterals:!0}),["coffee"]);k(x([],[["str",/^[\S\s]+/]]),["regex"]);window.prettyPrintOne=function(a,m,e){var h=document.createElement("PRE");h.innerHTML=a;e&&D(h,e);E({g:m,i:e,h:h});return h.innerHTML};window.prettyPrint=function(a){function m(){for(var e=window.PR_SHOULD_USE_CONTINUATION?l.now()+250:Infinity;p=0){var k=k.match(g),f,b;if(b= +!k){b=n;for(var o=void 0,c=b.firstChild;c;c=c.nextSibling)var i=c.nodeType,o=i===1?o?b:c:i===3?N.test(c.nodeValue)?b:o:o;b=(f=o===b?void 0:o)&&"CODE"===f.tagName}b&&(k=f.className.match(g));k&&(k=k[1]);b=!1;for(o=n.parentNode;o;o=o.parentNode)if((o.tagName==="pre"||o.tagName==="code"||o.tagName==="xmp")&&o.className&&o.className.indexOf("prettyprint")>=0){b=!0;break}b||((b=(b=n.className.match(/\blinenums\b(?::(\d+))?/))?b[1]&&b[1].length?+b[1]:!0:!1)&&D(n,b),d={g:k,h:n,i:b},E(d))}}p + + + + serialport.js - Documentation + + + + + + + + + + + + + + + + +
+ +

serialport.js

+ + + + + + + +
+
+ 
'use strict';
+const Buffer = require('safe-buffer').Buffer;
+const stream = require('stream');
+const util = require('util');
+const debug = require('debug')('serialport:main');
+
+//  VALIDATION
+const DATABITS = Object.freeze([5, 6, 7, 8]);
+const STOPBITS = Object.freeze([1, 1.5, 2]);
+const PARITY = Object.freeze(['none', 'even', 'mark', 'odd', 'space']);
+const FLOWCONTROLS = Object.freeze(['xon', 'xoff', 'xany', 'rtscts']);
+
+const defaultSettings = Object.freeze({
+  autoOpen: true,
+  baudRate: 9600,
+  dataBits: 8,
+  hupcl: true,
+  lock: true,
+  parity: 'none',
+  rtscts: false,
+  stopBits: 1,
+  xany: false,
+  xoff: false,
+  xon: false,
+  highWaterMark: 64 * 1024
+});
+
+const defaultSetFlags = Object.freeze({
+  brk: false,
+  cts: false,
+  dtr: true,
+  dts: false,
+  rts: true
+});
+
+function allocNewReadPool(poolSize) {
+  const pool = Buffer.allocUnsafe(poolSize);
+  pool.used = 0;
+  return pool;
+}
+
+/**
+ * A callback called with an error or null.
+ * @typedef {function} errorCallback
+ * @param {?error} error
+ */
+
+/**
+ * A callback called with an error or an object with the modem line values (cts, dsr, dcd).
+ * @typedef {function} modemBitsCallback
+ * @param {?error} error
+ * @param {?object} status
+ * @param {boolean} [status.cts=false]
+ * @param {boolean} [status.dsr=false]
+ * @param {boolean} [status.dcd=false]
+ */
+
+/**
+ * @typedef {Object} openOptions
+ * @property {boolean} [autoOpen=true] Automatically opens the port on `nextTick`.
+ * @property {number=} [baudRate=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.
+ * @property {number} [dataBits=8] Must be one of these: 8, 7, 6, or 5.
+ * @property {number} [highWaterMark=65536] The size of the read and write buffers defaults to 64k.
+ * @property {boolean} [lock=true] Prevent other processes from opening the port. Windows does not currently support `false`.
+ * @property {number} [stopBits=1] Must be one of these: 1 or 2.
+ * @property {string} [parity=none] Must be one of these: 'none', 'even', 'mark', 'odd', 'space'.
+ * @property {boolean} [rtscts=false] flow control setting
+ * @property {boolean} [xon=false] flow control setting
+ * @property {boolean} [xoff=false] flow control setting
+ * @property {boolean} [xany=false] flow control setting
+ * @property {object=} bindingOptions sets binding-specific options
+ * @property {module:serialport~Binding=} Binding The hardware access binding. `Bindings` are how Node-Serialport talks to the underlying system. By default we auto detect Windows (`WindowsBinding`), Linux (`LinuxBinding`) and OS X (`DarwinBinding`) and load the appropriate module for your system.
+ * @property {number} [bindingOptions.vmin=1] see [`man termios`](http://linux.die.net/man/3/termios) LinuxBinding and DarwinBinding
+ * @property {number} [bindingOptions.vtime=0] see [`man termios`](http://linux.die.net/man/3/termios) LinuxBinding and DarwinBinding
+ */
+
+/**
+ * Create a new serial port object for the `path`. In the case of invalid arguments or invalid options, when constructing a new SerialPort it will throw an error. The port will open automatically by default, which is the equivalent of calling `port.open(openCallback)` in the next tick. You can disable this by setting the option `autoOpen` to `false`.
+ * @class SerialPort
+ * @param {string} path - The system path of the serial port you want to open. For example, `/dev/tty.XXX` on Mac/Linux, or `COM1` on Windows.
+ * @param {module:serialport~openOptions=} options - Port configuration options
+ * @param {module:serialport~errorCallback=} openCallback - Called after a connection is opened. If this is not provided and an error occurs, it will be emitted on the port's `error` event. The callback will NOT be called if `autoOpen` is set to `false` in the `openOptions` as the open will not be performed.
+ * @property {number} baudRate The port's baudRate. Use `.update` to change it. Read-only.
+ * @property {object} binding The binding object backing the port. Read-only.
+ * @property {boolean} isOpen `true` if the port is open, `false` otherwise. Read-only. (`since 5.0.0`)
+ * @property {string} path The system path or name of the serial port. Read-only.
+ * @throws {TypeError} When given invalid arguments, a `TypeError` will be thrown.
+ * @emits module:serialport#open
+ * @emits module:serialport#data
+ * @emits module:serialport#close
+ * @emits module:serialport#error
+ * @alias module:serialport
+ */
+function SerialPort(path, options, callback) {
+  if (!(this instanceof SerialPort)) {
+    return new SerialPort(path, options, callback);
+  }
+
+  if (options instanceof Function) {
+    callback = options;
+    options = {};
+  }
+
+  const settings = Object.assign({}, defaultSettings, options);
+
+  stream.Duplex.call(this, {
+    highWaterMark: settings.highWaterMark
+  });
+
+  const Binding = settings.binding || SerialPort.Binding;
+
+  if (!Binding) {
+    throw new TypeError('"Bindings" is invalid pass it as `options.binding` or set it on `SerialPort.Binding`');
+  }
+
+  if (!path) {
+    throw new TypeError(`"path" is not defined: ${path}`);
+  }
+
+  if (settings.baudrate) {
+    throw new TypeError(`"baudrate" is an unknown option, did you mean "baudRate"?`);
+  }
+
+  if (typeof settings.baudRate !== 'number') {
+    throw new TypeError(`"baudRate" must be a number: ${settings.baudRate}`);
+  }
+
+  if (DATABITS.indexOf(settings.dataBits) === -1) {
+    throw new TypeError(`"databits" is invalid: ${settings.dataBits}`);
+  }
+
+  if (STOPBITS.indexOf(settings.stopBits) === -1) {
+    throw new TypeError(`"stopbits" is invalid: ${settings.stopbits}`);
+  }
+
+  if (PARITY.indexOf(settings.parity) === -1) {
+    throw new TypeError(`"parity" is invalid: ${settings.parity}`);
+  }
+
+  FLOWCONTROLS.forEach((control) => {
+    if (typeof settings[control] !== 'boolean') {
+      throw new TypeError(`"${control}" is not boolean: ${settings[control]}`);
+    }
+  });
+
+  const binding = new Binding({
+    bindingOptions: settings.bindingOptions
+  });
+
+  Object.defineProperties(this, {
+    binding: {
+      enumerable: true,
+      value: binding
+    },
+    path: {
+      enumerable: true,
+      value: path
+    },
+    settings: {
+      enumerable: true,
+      value: settings
+    }
+  });
+
+  this.opening = false;
+  this.closing = false;
+  this._pool = allocNewReadPool(this.settings.highWaterMark);
+  this._kMinPoolSpace = 128;
+
+  if (this.settings.autoOpen) {
+    this.open(callback);
+  }
+}
+
+util.inherits(SerialPort, stream.Duplex);
+
+Object.defineProperties(SerialPort.prototype, {
+  isOpen: {
+    enumerable: true,
+    get() {
+      return this.binding.isOpen && !this.closing;
+    }
+  },
+  baudRate: {
+    enumerable: true,
+    get() {
+      return this.settings.baudRate;
+    }
+  }
+});
+
+/**
+ * The `error` event's callback is called with an error object whenever there is an error.
+ * @event module:serialport#error
+ */
+
+SerialPort.prototype._error = function(error, callback) {
+  if (callback) {
+    callback.call(this, error);
+  } else {
+    this.emit('error', error);
+  }
+};
+
+SerialPort.prototype._asyncError = function(error, callback) {
+  process.nextTick(() => this._error(error, callback));
+};
+
+/**
+ * The `open` event's callback is called with no arguments when the port is opened and ready for writing. This happens if you have the constructor open immediately (which opens in the next tick) or if you open the port manually with `open()`. See [Useage/Opening a Port](#opening-a-port) for more information.
+ * @event module:serialport#open
+ */
+
+/**
+ * Opens a connection to the given serial port.
+ * @param {module:serialport~errorCallback=} callback - Called after a connection is opened. If this is not provided and an error occurs, it will be emitted on the port's `error` event.
+ * @emits module:serialport#open
+ */
+SerialPort.prototype.open = function(callback) {
+  if (this.isOpen) {
+    return this._asyncError(new Error('Port is already open'), callback);
+  }
+
+  if (this.opening) {
+    return this._asyncError(new Error('Port is opening'), callback);
+  }
+
+  this.opening = true;
+  debug('opening', `path: ${this.path}`);
+  this.binding.open(this.path, this.settings).then(() => {
+    debug('opened', `path: ${this.path}`);
+    this.opening = false;
+    this.emit('open');
+    if (callback) { callback.call(this, null) }
+  }, (err) => {
+    this.opening = false;
+    debug('Binding #open had an error', err);
+    this._error(err, callback);
+  });
+};
+
+/**
+ * Changes the baud rate for an open port. Throws if you provide a bad argument. Emits an error or calls the callback if the baud rate isn't supported.
+ * @param {object=} options Only supports `baudRate`.
+ * @param {number=} [options.baudRate] The baud rate of the port to be opened. This should match one of the commonly available baud rates, such as 110, 300, 1200, 2400, 4800, 9600, 14400, 19200, 38400, 57600, or 115200. Custom rates are supported best effort per platform. The device connected to the serial port is not guaranteed to support the requested baud rate, even if the port itself supports that baud rate.
+ * @param {module:serialport~errorCallback=} [callback] Called once the port's baud rate changes. If `.update` is called without a callback, and there is an error, an error event is emitted.
+ */
+SerialPort.prototype.update = function(options, callback) {
+  if (typeof options !== 'object') {
+    throw TypeError('"options" is not an object');
+  }
+
+  if (!this.isOpen) {
+    debug('update attempted, but port is not open');
+    return this._asyncError(new Error('Port is not open'), callback);
+  }
+
+  const settings = Object.assign({}, defaultSettings, options);
+  this.settings.baudRate = settings.baudRate;
+
+  debug('update', `baudRate: ${settings.baudRate}`);
+  this.binding.update(this.settings).then(() => {
+    debug('binding.update', 'finished');
+    if (callback) { callback.call(this, null) }
+  }, (err) => {
+    debug('binding.update', 'error', err);
+    return this._error(err, callback);
+  });
+};
+
+/**
+ * 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.
+ * @method module:serialport#write
+ * @param  {(string|array|buffer)} data Accepts a [`Buffer` ](http://nodejs.org/api/buffer.html) object, or a type that is accepted by the `Buffer` constructor (e.g. an array of bytes or a string).
+ * @param  {string=} encoding The encoding, if chunk is a string. Defaults to `'utf8'`. Also accepts `'ascii'`, `'base64'`, `'binary'`, and `'hex'` See [Buffers and Character Encodings](https://nodejs.org/api/buffer.html#buffer_buffers_and_character_encodings) for all available options.
+ * @param  {function=} callback Called once the write operation finishes. Data may not yet be flushed to the underlying port. No arguments.
+ * @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
+ */
+const superWrite = SerialPort.prototype.write;
+SerialPort.prototype.write = function(data, encoding, callback) {
+  if (Array.isArray(data)) {
+    data = Buffer.from(data);
+  }
+  return superWrite.call(this, data, encoding, callback);
+};
+
+SerialPort.prototype._write = function(data, encoding, callback) {
+  if (!this.isOpen) {
+    return this.once('open', function afterOpenWrite() {
+      this._write(data, encoding, callback);
+    });
+  }
+  debug('_write', `${data.length} bytes of data`);
+  this.binding.write(data).then(
+    () => {
+      debug('binding.write', 'write finished');
+      callback(null);
+    },
+    (err) => {
+      debug('binding.write', 'error', err);
+      if (!err.canceled) {
+        this._disconnected(err);
+      }
+      callback(err);
+    });
+};
+
+SerialPort.prototype._writev = function(data, callback) {
+  debug('_writev', `${data.length} chunks of data`);
+  const dataV = data.map(write => write.chunk);
+  this._write(Buffer.concat(dataV), null, callback);
+};
+
+/**
+ * Request a number of bytes from the SerialPort. The `read()` method pulls some data out of the internal buffer and returns it. If no data is available to be read, null is returned. By default, the data is returned as a `Buffer` object unless an encoding has been specified using the `.setEncoding()` method.
+ * @method module:serialport#read
+ * @param {number=} size Specify how many bytes of data to return, if available
+ * @returns {(string|Buffer|null)} The data from internal buffers
+ * @since 5.0.0
+ */
+
+/**
+ * The `data` event puts the port in flowing mode. Data is emitted as soon as it's received. Data is a `Buffer` object with a varying amount of data in it. The `readLine` parser converts the data into string lines. See the [parsers](#module_serialport--SerialPort.parsers) section for more information on parsers, and the [Node.js stream documentation](https://nodejs.org/api/stream.html#stream_event_data) for more information on the data event.
+ * @event module:serialport#data
+ */
+
+SerialPort.prototype._read = function(bytesToRead) {
+  if (!this.isOpen) {
+    debug('_read', 'queueing _read for after open');
+    this.once('open', () => {
+      this._read(bytesToRead);
+    });
+    return;
+  }
+
+  if (!this._pool || this._pool.length - this._pool.used < this._kMinPoolSpace) {
+    debug('_read', 'discarding the read buffer pool');
+    this._pool = allocNewReadPool(this.settings.highWaterMark);
+  }
+
+  // Grab another reference to the pool in the case that while we're
+  // in the thread pool another read() finishes up the pool, and
+  // allocates a new one.
+  const pool = this._pool;
+  // Read the smaller of rest of the pool or however many bytes we want
+  const toRead = Math.min(pool.length - pool.used, bytesToRead);
+  const start = pool.used;
+
+  // the actual read.
+  debug('_read', `reading`);
+  this.binding.read(pool, start, toRead).then((bytesRead) => {
+    debug('binding.read', `finished`);
+    // zero bytes means read means we've hit EOF? Maybe this should be an error
+    if (bytesRead === 0) {
+      debug('binding.read', 'Zero bytes read closing readable stream');
+      this.push(null);
+      return;
+    }
+    pool.used += bytesRead;
+    this.push(pool.slice(start, start + bytesRead));
+  }, (err) => {
+    debug('binding.read', `error`, err);
+    if (!err.canceled) {
+      this._disconnected(err);
+    }
+    this._read(bytesToRead); // prime to read more once we're reconnected
+  });
+};
+
+SerialPort.prototype._disconnected = function(err) {
+  if (!this.isOpen) {
+    debug('disconnected aborted because already closed', err);
+    return;
+  }
+  debug('disconnected', err);
+  err.disconnected = true;
+  this.close(null, err);
+};
+
+/**
+ * The `close` event's callback is called with no arguments when the port is closed. In the case of a disconnect it will be called with a Disconnect Error object (`err.disconnected == true`). In the event of a close error (unlikely), an error event is triggered.
+ * @event module:serialport#close
+ */
+
+/**
+ * Closes an open connection.
+ *
+ * If there are in progress writes when the port is closed the writes will error.
+ * @param  {errorCallback} callback Called once a connection is closed.
+ * @emits module:serialport#close
+ */
+SerialPort.prototype.close = function(callback, disconnectError) {
+  disconnectError = disconnectError || null;
+
+  if (!this.isOpen) {
+    debug('close attempted, but port is not open');
+    return this._asyncError(new Error('Port is not open'), callback);
+  }
+
+  this.closing = true;
+  debug('#close');
+  this.binding.close().then(() => {
+    this.closing = false;
+    debug('binding.close', 'finished');
+    this.emit('close', disconnectError);
+    if (callback) { callback.call(this, disconnectError) }
+  }, (err) => {
+    this.closing = false;
+    debug('binding.close', 'had an error', err);
+    return this._error(err, 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.
+ * @param {object=} options All options are operating system default when the port is opened. Every flag is set on each call to the provided or default values. If options isn't provided default options is used.
+ * @param {Boolean} [options.brk=false]
+ * @param {Boolean} [options.cts=false]
+ * @param {Boolean} [options.dsr=false]
+ * @param {Boolean} [options.dtr=true]
+ * @param {Boolean} [options.rts=true]
+ * @param {module:serialport~errorCallback=} callback Called once the port's flags have been set.
+ * @since 5.0.0
+ */
+SerialPort.prototype.set = function(options, callback) {
+  if (typeof options !== 'object') {
+    throw TypeError('"options" is not an object');
+  }
+
+  if (!this.isOpen) {
+    debug('set attempted, but port is not open');
+    return this._asyncError(new Error('Port is not open'), callback);
+  }
+
+  const settings = Object.assign({}, defaultSetFlags, options);
+  debug('#set', settings);
+  this.binding.set(settings).then(() => {
+    debug('binding.set', 'finished');
+    if (callback) { callback.call(this, null) }
+  }, (err) => {
+    debug('binding.set', 'had an error', err);
+    return this._error(err, callback);
+  });
+};
+
+/**
+ * Returns the control flags (CTS, DSR, DCD) on the open port.
+ * Uses [`GetCommModemStatus`](https://msdn.microsoft.com/en-us/library/windows/desktop/aa363258(v=vs.85).aspx) for Windows and [`ioctl`](http://linux.die.net/man/4/tty_ioctl) for mac and linux.
+ * @param {module:serialport~modemBitsCallback=} callback Called once the modem bits are retrieved.
+ */
+SerialPort.prototype.get = function(callback) {
+  if (!this.isOpen) {
+    debug('get attempted, but port is not open');
+    return this._asyncError(new Error('Port is not open'), callback);
+  }
+
+  debug('#get');
+  this.binding.get().then((status) => {
+    debug('binding.get', 'finished');
+    if (callback) { callback.call(this, null, status) }
+  }, (err) => {
+    debug('binding.get', 'had an error', err);
+    return this._error(err, callback);
+  });
+};
+
+/**
+ * Flush discards data received but not read, and written but not transmitted by the operating system. For more technical details, see [`tcflush(fd, TCIOFLUSH)`](http://linux.die.net/man/3/tcflush) for Mac/Linux and [`FlushFileBuffers`](http://msdn.microsoft.com/en-us/library/windows/desktop/aa364439) for Windows.
+ * @param  {module:serialport~errorCallback=} callback Called once the flush operation finishes.
+ */
+SerialPort.prototype.flush = function(callback) {
+  if (!this.isOpen) {
+    debug('flush attempted, but port is not open');
+    return this._asyncError(new Error('Port is not open'), callback);
+  }
+
+  debug('#flush');
+  this.binding.flush().then(() => {
+    debug('binding.flush', 'finished');
+    if (callback) { callback.call(this, null) }
+  }, (err) => {
+    debug('binding.flush', 'had an error', err);
+    return this._error(err, callback);
+  });
+};
+
+/**
+ * Waits until all output data is transmitted to the serial port. After any pending write has completed it calls [`tcdrain()`](http://linux.die.net/man/3/tcdrain) or [FlushFileBuffers()](https://msdn.microsoft.com/en-us/library/windows/desktop/aa364439(v=vs.85).aspx) to ensure it has been written to the device.
+ * @param {module:serialport~errorCallback=} callback Called once the drain operation returns.
+ * @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.prototype.drain = function(callback) {
+  debug('drain');
+  if (!this.isOpen) {
+    debug('drain queuing on port open');
+    return this.once('open', () => {
+      this.drain(callback);
+    });
+  }
+  this.binding.drain().then(() => {
+    debug('binding.drain', 'finished');
+    if (callback) { callback.call(this, null) }
+  }, (err) => {
+    debug('binding.drain', 'had an error', err);
+    return this._error(err, callback);
+  });
+};
+
+/**
+ * The `pause()` method causes a stream in flowing mode to stop emitting 'data' events, switching out of flowing mode. Any data that becomes available remains in the internal buffer.
+ * @method module:serialport#pause
+ * @see module:serialport#resume
+ * @since 5.0.0
+ * @returns `this`
+ */
+
+/**
+ * The `resume()` method causes an explicitly paused, `Readable` stream to resume emitting 'data' events, switching the stream into flowing mode.
+ * @method module:serialport#resume
+ * @see module:serialport#pause
+ * @since 5.0.0
+ * @returns `this`
+ */
+
+/**
+ * This callback type is called `requestCallback`.
+ * @callback listCallback
+ * @param {?error} error
+ * @param {array} ports an array of objects with port info
+ */
+
+/**
+ * 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.
+ * @type {function}
+ * @param {listCallback=} callback
+ * @returns {Promise} Resolves with the list of available serial ports.
+ * @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.list = function(cb) {
+  if (!SerialPort.Binding) {
+    throw new TypeError('No Binding set on `SerialPort.Binding`');
+  }
+  debug('.list');
+  const promise = SerialPort.Binding.list();
+  if (typeof cb === 'function') {
+    promise.then(
+      ports => cb(null, ports),
+      err => cb(err)
+    );
+  }
+  return promise;
+};
+
+module.exports = SerialPort;
+
+
+
+ + + + +
+ +
+ +
+ Documentation generated by JSDoc 3.5.5 on Thu Feb 15 2018 16:36:25 GMT-0500 (EST) using the docdash theme. +
+ + + + + diff --git a/docs/styles/jsdoc.css b/docs/styles/jsdoc.css new file mode 100644 index 000000000..c13c7d4ad --- /dev/null +++ b/docs/styles/jsdoc.css @@ -0,0 +1,645 @@ +@import url(https://fonts.googleapis.com/css?family=Montserrat:400,700); + +* { + box-sizing: border-box +} + +html, body { + height: 100%; + width: 100%; +} + +body { + color: #4d4e53; + background-color: white; + margin: 0 auto; + padding: 0 20px; + font-family: 'Helvetica Neue', Helvetica, sans-serif; + font-size: 16px; + line-height: 160%; +} + +a, +a:active { + color: #606; + text-decoration: none; +} + +a:hover { + text-decoration: none; +} + +article a { + border-bottom: 1px solid #ddd; +} + +article a:hover, article a:active { + border-bottom-color: #222; +} + +p, ul, ol, blockquote { + margin-bottom: 1em; +} + +h1, h2, h3, h4, h5, h6 { + font-family: 'Montserrat', sans-serif; +} + +h1, h2, h3, h4, h5, h6 { + color: #000; + font-weight: 400; + margin: 0; +} + +h1 { + font-weight: 300; + font-size: 48px; + margin: 1em 0 .5em; +} + +h1.page-title { + font-size: 48px; + margin: 1em 30px; +} + +h2 { + font-size: 24px; + margin: 1.5em 0 .3em; +} + +h3 { + font-size: 24px; + margin: 1.2em 0 .3em; +} + +h4 { + font-size: 18px; + margin: 1em 0 .2em; + color: #4d4e53; +} + +h4.name { + color: #fff; + background: #6d426d; + box-shadow: 0 .25em .5em #d3d3d3; + border-top: 1px solid #d3d3d3; + border-bottom: 1px solid #d3d3d3; + margin: 1.5em 0 0.5em; + padding: .75em 0 .75em 10px; +} + +h4.name a { + color: #fc83ff; +} + +h4.name a:hover { + border-bottom-color: #fc83ff; +} + +h5, .container-overview .subsection-title { + font-size: 120%; + letter-spacing: -0.01em; + margin: 8px 0 3px 0; +} + +h6 { + font-size: 100%; + letter-spacing: -0.01em; + margin: 6px 0 3px 0; + font-style: italic; +} + +tt, code, kbd, samp { + font-family: Consolas, Monaco, 'Andale Mono', monospace; + background: #f4f4f4; + padding: 1px 5px; +} + +.class-description { + font-size: 130%; + line-height: 140%; + margin-bottom: 1em; + margin-top: 1em; +} + +.class-description:empty { + margin: 0 +} + +#main { + float: right; + min-width: 360px; + width: calc(100% - 240px); +} + +header { + display: block +} + +section { + display: block; + background-color: #fff; + padding: 0 0 0 30px; +} + +.variation { + display: none +} + +.signature-attributes { + font-size: 60%; + color: #eee; + font-style: italic; + font-weight: lighter; +} + +nav { + float: left; + display: block; + width: 250px; + background: #fff; + overflow: auto; + position: fixed; + height: 100%; +} + +nav h3 { + margin-top: 12px; + font-size: 13px; + text-transform: uppercase; + letter-spacing: 1px; + font-weight: 700; + line-height: 24px; + margin: 15px 0 10px; + padding: 0; + color: #000; +} + +nav ul { + font-family: 'Lucida Grande', 'Lucida Sans Unicode', arial, sans-serif; + font-size: 100%; + line-height: 17px; + padding: 0; + margin: 0; + list-style-type: none; +} + +nav ul a, +nav ul a:active { + font-family: 'Montserrat', sans-serif; + line-height: 18px; + padding: 0; + display: block; + font-size: 12px; +} + +nav a:hover, +nav a:active { + color: #606; +} + +nav > ul { + padding: 0 10px; +} + +nav > ul > li > a { + color: #606; +} + +nav ul ul { + margin-bottom: 10px +} + +nav ul ul + ul { + margin-top: -10px; +} + +nav ul ul a { + color: hsl(207, 1%, 60%); + border-left: 1px solid hsl(207, 10%, 86%); +} + +nav ul ul a, +nav ul ul a:active { + padding-left: 20px +} + +nav h2 { + font-size: 12px; + margin: 0; + padding: 0; +} + +nav > h2 > a { + display: block; + margin: 10px 0 -10px; + color: #606 !important; +} + +footer { + color: hsl(0, 0%, 28%); + margin-left: 250px; + display: block; + padding: 15px; + font-style: italic; + font-size: 90%; +} + +.ancestors { + color: #999 +} + +.ancestors a { + color: #999 !important; +} + +.clear { + clear: both +} + +.important { + font-weight: bold; + color: #950B02; +} + +.yes-def { + text-indent: -1000px +} + +.type-signature { + color: #CA79CA +} + +.type-signature:last-child { + color: #eee; +} + +.name, .signature { + font-family: Consolas, Monaco, 'Andale Mono', monospace +} + +.signature { + color: #fc83ff; +} + +.details { + margin-top: 6px; + border-left: 2px solid #DDD; + line-height: 20px; + font-size: 14px; +} + +.details dt { + width: 120px; + float: left; + padding-left: 10px; +} + +.details dd { + margin-left: 70px; + margin-top: 6px; + margin-bottom: 6px; +} + +.details ul { + margin: 0 +} + +.details ul { + list-style-type: none +} + +.details pre.prettyprint { + margin: 0 +} + +.details .object-value { + padding-top: 0 +} + +.description { + margin-bottom: 1em; + margin-top: 1em; +} + +.code-caption { + font-style: italic; + font-size: 107%; + margin: 0; +} + +.prettyprint { + font-size: 14px; + overflow: auto; +} + +.prettyprint.source { + width: inherit; + line-height: 18px; + display: block; + background-color: #0d152a; + color: #aeaeae; +} + +.prettyprint code { + line-height: 18px; + display: block; + background-color: #0d152a; + color: #4D4E53; +} + +.prettyprint > code { + padding: 15px; +} + +.prettyprint .linenums code { + padding: 0 15px +} + +.prettyprint .linenums li:first-of-type code { + padding-top: 15px +} + +.prettyprint code span.line { + display: inline-block +} + +.prettyprint.linenums { + padding-left: 70px; + -webkit-user-select: none; + -moz-user-select: none; + -ms-user-select: none; + user-select: none; +} + +.prettyprint.linenums ol { + padding-left: 0 +} + +.prettyprint.linenums li { + border-left: 3px #34446B solid; +} + +.prettyprint.linenums li.selected, .prettyprint.linenums li.selected * { + background-color: #34446B; +} + +.prettyprint.linenums li * { + -webkit-user-select: text; + -moz-user-select: text; + -ms-user-select: text; + user-select: text; +} + +.params, .props { + border-spacing: 0; + border: 1px solid #ddd; + border-collapse: collapse; + border-radius: 3px; + box-shadow: 0 1px 3px rgba(0,0,0,0.1); + width: 100%; + font-size: 14px; + margin: 1em 0; +} + +.params .type { + white-space: nowrap; +} + +.params code { + white-space: pre; +} + +.params td, .params .name, .props .name, .name code { + color: #4D4E53; + font-family: Consolas, Monaco, 'Andale Mono', monospace; + font-size: 100%; +} + +.params td, .params th, .props td, .props th { + margin: 0px; + text-align: left; + vertical-align: top; + padding: 10px; + display: table-cell; +} + +.params td { + border-top: 1px solid #eee +} + +.params thead tr, .props thead tr { + background-color: #fff; + font-weight: bold; +} + +.params .params thead tr, .props .props thead tr { + background-color: #fff; + font-weight: bold; +} + +.params td.description > p:first-child, .props td.description > p:first-child { + margin-top: 0; + padding-top: 0; +} + +.params td.description > p:last-child, .props td.description > p:last-child { + margin-bottom: 0; + padding-bottom: 0; +} + +span.param-type, .params td .param-type, .param-type dd { + color: #606; + font-family: Consolas, Monaco, 'Andale Mono', monospace +} + +.param-type dt, .param-type dd { + display: inline-block +} + +.param-type { + margin: 14px 0; +} + +.disabled { + color: #454545 +} + +/* navicon button */ +.navicon-button { + display: none; + position: relative; + padding: 2.0625rem 1.5rem; + transition: 0.25s; + cursor: pointer; + -webkit-user-select: none; + -moz-user-select: none; + -ms-user-select: none; + user-select: none; + opacity: .8; +} +.navicon-button .navicon:before, .navicon-button .navicon:after { + transition: 0.25s; +} +.navicon-button:hover { + transition: 0.5s; + opacity: 1; +} +.navicon-button:hover .navicon:before, .navicon-button:hover .navicon:after { + transition: 0.25s; +} +.navicon-button:hover .navicon:before { + top: .825rem; +} +.navicon-button:hover .navicon:after { + top: -.825rem; +} + +/* navicon */ +.navicon { + position: relative; + width: 2.5em; + height: .3125rem; + background: #000; + transition: 0.3s; + border-radius: 2.5rem; +} +.navicon:before, .navicon:after { + display: block; + content: ""; + height: .3125rem; + width: 2.5rem; + background: #000; + position: absolute; + z-index: -1; + transition: 0.3s 0.25s; + border-radius: 1rem; +} +.navicon:before { + top: .625rem; +} +.navicon:after { + top: -.625rem; +} + +/* open */ +.nav-trigger:checked + label:not(.steps) .navicon:before, +.nav-trigger:checked + label:not(.steps) .navicon:after { + top: 0 !important; +} + +.nav-trigger:checked + label .navicon:before, +.nav-trigger:checked + label .navicon:after { + transition: 0.5s; +} + +/* Minus */ +.nav-trigger:checked + label { + -webkit-transform: scale(0.75); + transform: scale(0.75); +} + +/* × and + */ +.nav-trigger:checked + label.plus .navicon, +.nav-trigger:checked + label.x .navicon { + background: transparent; +} + +.nav-trigger:checked + label.plus .navicon:before, +.nav-trigger:checked + label.x .navicon:before { + -webkit-transform: rotate(-45deg); + transform: rotate(-45deg); + background: #FFF; +} + +.nav-trigger:checked + label.plus .navicon:after, +.nav-trigger:checked + label.x .navicon:after { + -webkit-transform: rotate(45deg); + transform: rotate(45deg); + background: #FFF; +} + +.nav-trigger:checked + label.plus { + -webkit-transform: scale(0.75) rotate(45deg); + transform: scale(0.75) rotate(45deg); +} + +.nav-trigger:checked ~ nav { + left: 0 !important; +} + +.nav-trigger:checked ~ .overlay { + display: block; +} + +.nav-trigger { + position: fixed; + top: 0; + clip: rect(0, 0, 0, 0); +} + +.overlay { + display: none; + position: fixed; + top: 0; + bottom: 0; + left: 0; + right: 0; + width: 100%; + height: 100%; + background: hsla(0, 0%, 0%, 0.5); + z-index: 1; +} + +@media only screen and (min-width: 320px) and (max-width: 680px) { + body { + overflow-x: hidden; + } + + nav { + background: #FFF; + width: 250px; + height: 100%; + position: fixed; + top: 0; + right: 0; + bottom: 0; + left: -250px; + z-index: 3; + padding: 0 10px; + transition: left 0.2s; + } + + .navicon-button { + display: inline-block; + position: fixed; + top: 1.5em; + right: 0; + z-index: 2; + } + + #main { + width: 100%; + min-width: 360px; + } + + #main h1.page-title { + margin: 1em 0; + } + + #main section { + padding: 0; + } + + footer { + margin-left: 0; + } +} + +/** Add a '#' to static members */ +[data-type="member"] a::before { + content: '#'; + display: inline-block; + margin-left: -14px; + margin-right: 5px; +} diff --git a/docs/styles/prettify.css b/docs/styles/prettify.css new file mode 100644 index 000000000..629bde515 --- /dev/null +++ b/docs/styles/prettify.css @@ -0,0 +1,79 @@ +.pln { + color: #ddd; +} + +/* string content */ +.str { + color: #61ce3c; +} + +/* a keyword */ +.kwd { + color: #fbde2d; +} + +/* a comment */ +.com { + color: #aeaeae; +} + +/* a type name */ +.typ { + color: #8da6ce; +} + +/* a literal value */ +.lit { + color: #fbde2d; +} + +/* punctuation */ +.pun { + color: #ddd; +} + +/* lisp open bracket */ +.opn { + color: #000000; +} + +/* lisp close bracket */ +.clo { + color: #000000; +} + +/* a markup tag name */ +.tag { + color: #8da6ce; +} + +/* a markup attribute name */ +.atn { + color: #fbde2d; +} + +/* a markup attribute value */ +.atv { + color: #ddd; +} + +/* a declaration */ +.dec { + color: #EF5050; +} + +/* a variable name */ +.var { + color: #c82829; +} + +/* a function name */ +.fun { + color: #4271ae; +} + +/* Specify class=linenums on a pre to get line numbering */ +ol.linenums { + margin-top: 0; + margin-bottom: 0; +}