chore: update docs and examples (#2429)

Just a lot of cleanup

Author: reconbot

UPGRADE_GUIDE.md

@@ -1,141 +1,3 @@
-Upgading from 9x to 10x
--------------
-
-- Typscript types are now available for all packages
-- Serialport no longer supports Node 10
-- SerialPort stream (from npm `serialport` and `@serialport/stream`) now take an options object with a required `path` and `baudRate`. They no longer default to a `baudRate` of 9600 as that's slow and usually not what's needed.
-- All packages now have named exports. They export their types and all relevant classes.
-- The package `serialport` no longer exports `serialport/test` but instead who classes `{ SerialPort, SerialPortMock }` where the mock is pre-configured with a mock binding.
-- Bindings have moved from `@serialport/bindings` to `@serialport/bindings-cpp` they are shipped with `prebuildify` and no longer require a post install download.
-- `@serialport/bindings-cpp` leverages N-API and shouldn't need to be upgraded for every node release or rebuild for electron
-- Bindings in general now have a new interface with the `@serialport/bindings-interface` type package that replaces `@serialport/bindings-abstract`
-- `SerialPortStream` from `@serialport/stream` no longer has a `list()` method as that was a direct call to the bindings.
-- `SerialPort` class from the `serialport` package no longer has a static `Bindings` property as it provides the OS specific bindings from `@serialport/bindings-cpp` if you need control of the bindings use `SerialPortStream`.
-- `SerialPortStream` methods (and by extension `SerialPort` methods) no longer throw when called with invalid input, their callbacks or the error event will convey input errors. This is because the binding layer now handles input validation as it's different on each platform.
-- `SerialPort` is now delivering a few more parsers
-- `@serialport/terminal` no longer has a default baudRate
-
-TODO
-- stop bits are incorrect
-
-
-Upgrading from 8.x to 9.x
--------------
-- Serialport no longer supports Node 8
-- We no longer provide 32 bit linux prebuild builds, you may still build these binaries yourself however.
-
-
-Upgrading from 7.x to 8.x
--------------
-- Serialport cli tools are now their own packages. See https://serialport.io/docs/guide-cli for more information on how to use them.
-- `SerialPort.list()` and `Bindings.list()` no longer take a callback and only return a promise.
-- `comName` has been renamed `path` in the `PortInfo` objects returned from `SerialPort.list()` or `Bindings.list()` you'll get a deprecation warning if you access `comName` until the next major version where it will be absent.
-- `@serialport/terminal` now takes a `--path` argument instead of a `--port` argument
-- Bindings now use async functions and no longer throw errors, they only reject errors. If you relied on this behavior you can now simplify your code to only looking for promise rejections.
-
-
-Upgrading from 6.x to 7.x
--------------
-We dropped support for Node.js 4, so you'll have to upgrade if you're running 4. We also split into many packages. See https://serialport.io/docs/api-overview for an overview of the new packages. Binaries have moved into `@serialport/bindings` so if you're distributing serialport in an electron app, you may have to make some changes.
-
-
-Upgrading from 5.x to 6.x
--------------
-TLDR: You probably don't have to change anything. You might need to enable `rtscts` in your open options.
-
-* **binaries:** We switched to `prebuild` a breaking change because it's substantially changes our install processes. It's also possible the install flags to ensure downloading or building from source has changed slightly. That's not our api per se, but it's enough for a breaking change.
-* **windows:** We previously hard coded to have RTS on for windows at all times it now default to off.
-
-
-Upgrading from 4.x to 5.x
--------------
-Node SerialPort 5.0.0 is a major rewrite that improves stability, compatibility and performance. While the api surface is similar there have been a number of changes to ensure consistent error handling and operation of a serial port.
-
-### Platforms
-- Drop NodeJS 0.10, 0.12, 5, and 7 support
-- Add node 8 support (we now only support LTS node versions)
-
-### The SerialPort Object
-- Node SerialPort is now a [duplex stream](https://nodejs.org/api/stream.html) and can be paused and resumed on all platforms.
-- `isOpen` is now a property
-- `SerialPort.list` now has more consistent output across all platforms. This means the data in the objects may be different than 4x. Notably the path on OSX now returns the `tty` instead of the `cu` path and the `0x` has been removed from values on linux and osx.
-- `port.path` is now read only
-- removed lowercase options all options are now only accepted camelCase
-- Changed parsers to be transform streams. There are replacements for the built in parsers but custom parsers will have to be modified.
-
-### Open options
-- `bufferSize` is now `highWaterMark` and defaults to 64k.
-- `parser` is removed in favor of using the new transform streams parsers
-
-### Opening and closing
-- Removed the `disconnect` event. The `close` event now fires with a disconnect error object in the event of a disconnection.
-- `port.isOpen` is now a property not a function
-
-### Reading and writing.
-- `port.on('data')` still works but `port.read()` and the `readable` event is now the preferred way to get data.
-- `port.read()` is now the best way to read data
-- `port.drain()` now waits for the current javascript write to complete before calling the system level drain.
-
-### Other
-- We now conform to NodeJS error message formats. Most messages have changed.
-- The event loop is no longer held open if there are no active reads or writes
-- `SerialPort.list` has slightly different output with more information, decoded strings and `0x` prefixes removed from some properties.
-- `SerialPort.list` now returns a promise if no call back is provided
-
-Upgrading from 3.x to 4.x
--------------
-4.x brings a lot of changes please see the [changelog](./changelog.md) for the full list of changes. We'll review the api and behavior changes here.
-
-The constructor has changed. We've removed an argument, changed how errors are thrown and it is returned when you `require('serialport');`
-
- - Requiring `serialport` now returns the SerialPort constructor function instead of a factory object. `SerialPort.SerialPort` is now deprecated.
- - `SerialPort` constructor now throws on argument errors immediately.
- - Removed `openImmediately` from the constructor's api, the functionality is now named `autoOpen` on the options object.
- - Removed extraneous flow control settings from the `flowControl` option, use the specific options to set these flags now.
- - Removed undocumented callbacks from the options object `disconnectedCallback` and `dataCallback`
-
- Write had a major change
-
-  - `.write(writeCallback)` now only calls it's callback once after the entire write operation, it used to be called for each write cycle and return the bytes written. This reduces the number of callbacks by hundreds of thousands over a megabyte at low bandwidth.
-
-Callbacks changed a little
-
- - All callbacks are called in the context of the port, `this` now equals the port.
- - Disconnections now always attempt to close the port, and you'll always get a `close` event after a `disconnect` event
-
-Renamed our binaries
-
- - Reanmed `serialportlist` to `serialport-list`
- - Renamed `serialportterm` to `serialport-term`
-
-We fixed a bunch of bugs too
-
- - [unix] `.drain` and `.set` now properly report errors
- - [windows] Fixed a bug where we weren't properly opening ports (provides better support virtual com ports too) thanks to @RogerHardiman
- - [windows] known issue `lock` false doesn't work (no change in behavior)
-
-And added a new features
-
- - [unix] Ports are now locked by default with the new `lock` options matches windows default behavior
- - [windows] `.update()` now supports windows for changing baud rates
-
-Upgrading from 2.x to 3.x
--------------
-3.0 brought a single major breaking change and a lot of minor improvements.
-
-We stopped removing event listeners, if you wrote code to work around that, we're sorry we made you do it.
-
-- `close` and `disconnect` events no longer call `removeAllListeners` and removes your event listeners. This was particularly bad for the `error` event. This is the only change and if you didn't have a special code to deal with this behavior you should probably upgrade from v2.1.2
-
-New Features
-
- - Added support for node 6.0
- - Update the cli tools. serialportterm can now list ports, serialportlist can now output in different formats
- - [unix] Better unix error messages
-
-Fixed bugs
-
- - [linux] bug fix in `.list()` where we weren't filtering out non block devices that are named like serial ports
- - [unix] Update now has less memory leaks, documentation and better error messages
- - [windows] Better error messages for opening ports
+# Upgrade Guide
 
+Moved to https://serialport.io/docs/guide-upgrade

packages/parser-byte-length/lib/index.ts

@@ -9,12 +9,6 @@ export interface ByteLengthOptions extends TransformOptions {
  * Emit data every number of bytes
  *
  * A transform stream that emits data as a buffer after a specific number of bytes are received. Runs in O(n) time.
- * @example
-const SerialPort = require('serialport')
-const ByteLength = require('@serialport/parser-byte-length')
-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
  */
 export class ByteLengthParser extends Transform {
   length: number

packages/parser-cctalk/lib/index.ts

@@ -5,12 +5,6 @@ import { Transform, TransformCallback } from 'stream'
  * @extends Transform
  *
  * A transform stream that emits CCTalk packets as they are received.
- * @example
-import { CCTalkParser } from '@serialport/parser-cctalk'
-const SerialPort = require('serialport')
-const port = new SerialPort('/dev/ttyUSB0')
-const parser = port.pipe(new CCtalk())
-parser.on('data', console.log)
  */
 export class CCTalkParser extends Transform {
   array: number[]

packages/parser-delimiter/lib/index.ts

@@ -12,12 +12,6 @@ export interface DelimiterOptions extends TransformOptions {
  * @extends Transform
  *
  * To use the `Delimiter` parser, provide a delimiter as a string, buffer, or array of bytes. Runs in O(n) time.
- * @example
-const SerialPort = require('serialport')
-const {DelimiterParser} = require('@serialport/parser-delimiter')
-const port = new SerialPort('/dev/tty-usbserial1')
-const parser = port.pipe(new DelimiterParser({ delimiter: '\n' }))
-parser.on('data', console.log)
  */
 export class DelimiterParser extends Transform {
   includeDelimiter: boolean

packages/parser-packet-length/lib/index.ts

@@ -14,29 +14,18 @@ export interface PacketLengthOptions extends TransformOptions {
 }
 
 /**
-* A transform stream that decodes packets with a delimiter and length of payload
-* specified within the data stream.
-* @extends Transform
-* @summary Decodes packets of the general form:
-*       [delimiter][len][payload0] ... [payload0 + len]
-*
-* The length field can be up to 4 bytes and can be at any offset within the packet
-*       [delimiter][header0][header1][len0][len1[payload0] ... [payload0 + len]
-*
-* The offset and number of bytes of the length field need to be provided in options
-* if not 1 byte immediately following the delimiter.
-* @example
-// Parse length encoded packets received on the serial port
-const SerialPort = require('serialport')
-const PacketLengthParser = require('@serialport/packet-length-parser')
-const port = new SerialPort('/dev/tty-usbserial1')
-const parser = port.pipe(new PacketLengthParser({
-  delimiter: 0xbc,
-  packetOverhead: 5,
-  lengthBytes: 2,
-  lengthOffset: 2,
-}))
-*/
+ * A transform stream that decodes packets with a delimiter and length of payload
+ * specified within the data stream.
+ * @extends Transform
+ * @summary Decodes packets of the general form:
+ *       [delimiter][len][payload0] ... [payload0 + len]
+ *
+ * The length field can be up to 4 bytes and can be at any offset within the packet
+ *       [delimiter][header0][header1][len0][len1[payload0] ... [payload0 + len]
+ *
+ * The offset and number of bytes of the length field need to be provided in options
+ * if not 1 byte immediately following the delimiter.
+ */
 export class PacketLengthParser extends Transform {
   buffer: Buffer
   start: boolean

packages/parser-readline/lib/index.ts

@@ -13,13 +13,7 @@ export interface ReadlineOptions extends TransformOptions {
 /**
  *  A transform stream that emits data after a newline delimiter is received.
  * @summary To use the `Readline` parser, provide a delimiter (defaults to `\n`). Data is emitted as string controllable by the `encoding` option (defaults to `utf8`).
- * @example
-const SerialPort = require('serialport')
-const {ReadlineParser} = require('@serialport/parser-readline')
-const port = new SerialPort('/dev/tty-usbserial1')
-const parser = port.pipe(new ReadlineParser({ delimiter: '\r\n' }))
-parser.on('data', console.log)
-*/
+ */
 export class ReadlineParser extends DelimiterParser {
   constructor(options?: ReadlineOptions) {
     const opts = {

packages/serialport/README.md

@@ -5,21 +5,24 @@ Access serial ports with JavaScript. Linux, OSX and Windows. Welcome your roboti
 > Go to https://serialport.io/ to learn more, find guides and api documentation.
 
 ## Quick Links
+
 - [**Guides**](https://serialport.io/docs/guide-about)
 - [**API Docs**](https://serialport.io/docs/api-serialport)
-- [The `serialport` package api docs](https://serialport.io/docs/api-serialport)
-
 
 ### Serialport
+
 - [`serialport`](https://serialport.io/docs/api-serialport) Chances are you're looking for the `serialport` package which provides a good set of defaults for most projects. However it is quite easy to mix and match the parts of serialport you need.
 
 ### Bindings
+
 The Bindings provide a low level interface to work with your serialport. It is possible to use them alone but it's usually easier to use them with an interface.
+
 - [`@serialport/bindings-cpp`](https://serialport.io/docs/api-bindings) bindings for Linux, Mac and Windows
-- [`@serialport/binding-abstract`](https://serialport.io/docs/api-bindings-abstract) as an abstract class to use if you're making your own bindings
+- [`@serialport/binding-interface`](https://serialport.io/docs/api-bindings-interface) a typescript interface to use if you're making your own bindings
 - [`@serialport/binding-mock`](https://serialport.io/docs/api-binding-mock) for a mock binding package for testing
 
 ### Interfaces
+
 Interfaces take a binding object and provide a different API on top of it. Currently we only ship a Node Stream Interface.
 
 - [`@serialport/stream`](https://serialport.io/docs/api-stream) our traditional Node.js Stream interface
@@ -41,33 +44,28 @@ Parsers are traditionally Transform streams, but Duplex streams and other non st
 ## Developing
 
 ### Developing node serialport projects
+
 1. Clone this repo `git clone git@github.com:serialport/node-serialport.git`
 1. Run `npm install` to setup local package dependencies (run this any time you depend on a package local to this repo)
 1. Run `npm test` to ensure everything is working properly
 1. Add dev dependencies to the root package.json and package dependencies to the package's one.
 
 ### Developing Docs
 
-You can develop the docs by running
-
-```bash
-npm run docs:dev
-```
-
-And build them by running
-```bash
-npm run docs
-```
+You can develop the docs with in the [website repo](https://github.com/serialport/website).
 
-Docs are automatically built with [netlify](https://www.netlify.com/pricing/) including previews on branches. The master branch is deployed to https://serialport.io
+Docs are automatically built with [vercel](https://vercel.com/) including previews on branches. The main branch is deployed to https://serialport.io
 
 ## License
+
 SerialPort packages are all [MIT licensed](LICENSE) and all it's dependencies are MIT licensed.
 
 ## Code of Conduct
+
 SerialPort follows the [Nodebots Code of Conduct](http://nodebots.io/conduct.html). While the code is MIT licensed participation in the community has some rules to make this a good place to work and learn.
 
 ### TLDR
+
 - Be respectful.
 - Abusive behavior is never tolerated.
 - Data published to NodeBots is hosted at the discretion of the service administrators, and may be removed.
@@ -84,7 +82,7 @@ SerialPort is currently employees a [governance](https://medium.com/the-node-js-
 
 If you have a PR that improves the project people in any or all of the above people will help you land it.
 
-**Maintainers**
+### Maintainers
 
 - [Francis Gulotta](https://twitter.com/reconbot) | [reconbot](https://github.com/reconbot)
 - [Nick Hehr](https://twitter.com/hipsterbrown) | [hipsterbrown](https://github.com/hipsterbrown)

packages/serialport/examples/mocking.js

@@ -1,7 +1,6 @@
 /* eslint-disable node/no-missing-require */
 
 // Load Serialport with mock bindings
-// const SerialPort = require('../test'); // from inside the serialport repo
 const { SerialPortMock: SerialPort } = require('serialport') // when installed as a package
 const { MockBinding } = SerialPort
 

packages/serialport/lib/serialport.ts

@@ -6,56 +6,6 @@ const DetectedBinding = autoDetect()
 export type SerialPortOpenOptions<T extends AutoDetectTypes> = Omit<StreamOptions<T>, 'binding'> & OpenOptionsFromBinding<T>
 
 export class SerialPort<T extends AutoDetectTypes = AutoDetectTypes> extends SerialPortStream<T> {
-  /**
-   * Retrieves a list of available serial ports with metadata. Only the `path` is guaranteed. If unavailable the other fields will be undefined. The `path` 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.
-   * Resolves with the list of available serial ports.
-   * @example
-  ```js
-  // OSX example port
-  {
-    path: '/dev/tty.usbmodem1421',
-    manufacturer: 'Arduino (www.arduino.cc)',
-    serialNumber: '752303138333518011C1',
-    pnpId: undefined,
-    locationId: '14500000',
-    productId: '0043',
-    vendorId: '2341'
-  }
-
-  // Linux example port
-  {
-    path: '/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
-  {
-    path: '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');
-
-  // promise approach
-  SerialPort.list()
-    .then(ports) {...});
-    .catch(err) {...});
-  ```
-  */
   static list = DetectedBinding.list
   static readonly binding = DetectedBinding
 

packages/serialport/test-manual/drain.js

@@ -1,6 +1,6 @@
 /* eslint-disable node/no-missing-require */
 
-const SerialPort = require('../')
+const { SerialPort } = require('../')
 const port = process.env.TEST_PORT
 // number of bytes to send
 const size = 512