new SerialPort(path, optionsopt, openCallbackopt)
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:
Name | Type | Attributes | Description |
---|---|---|---|
path |
string | The system path of the serial port you want to open. For example, |
|
options |
openOptions |
<optional> |
Port configuration options |
openCallback |
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 |
Properties:
Name | Type | Description |
---|---|---|
baudRate |
number | The port's baudRate. Use |
binding |
object | The binding object backing the port. Read-only. |
isOpen |
boolean |
|
path |
string | The system path or name of the serial port. Read-only. |
- Source:
Fires:
Throws:
-
When given invalid arguments, a
TypeError
will be thrown. - Type
- TypeError
Members
(static) Binding :AbstractBinding
Type:
- Source:
(static) parsers :Parsers
Type:
- Source:
Methods
(static) list(callbackopt) → {Promise}
Retrieves a list of available serial ports with metadata. Only the comName
is guaranteed. If unavailable the other fields will be undefined. The comName
is either the path or an identifier (eg COM1
) used to open the SerialPort.
We make an effort to identify the hardware attached and have consistent results between systems. Linux and OS X are mostly consistent. Windows relies on 3rd party device drivers for the information and is unable to guarantee the information. On windows If you have a USB connected device can we provide a serial number otherwise it will be undefined
. The pnpId
and locationId
are not the same or present on all systems. The examples below were run with the same Arduino Uno.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
callback |
listCallback |
<optional> |
Called with a list of available serial ports. |
- Source:
Returns:
Resolves with the list of available serial ports.
- Type
- Promise
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) {...});
```
close(callback, disconnectError) → {undefined}
Closes an open connection.
If there are in progress writes when the port is closed the writes will error.
Parameters:
Name | Type | Description |
---|---|---|
callback |
errorCallback | Called once a connection is closed. |
disconnectError |
Error | used internally to propagate a disconnect error |
- Source:
Fires:
Returns:
- Type
- undefined
drain(callbackopt) → {undefined}
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
callback |
errorCallback |
<optional> |
Called once the drain operation returns. |
- Source:
Returns:
- Type
- undefined
Example
Write the `data` and wait until it has finished transmitting to the target serial port before calling the callback. This will queue until the port is open and writes are finished.
```js
function writeAndDrain (data, callback) {
port.write(data);
port.drain(callback);
}
```
flush(callbackopt) → {undefined}
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:
Name | Type | Attributes | Description |
---|---|---|---|
callback |
errorCallback |
<optional> |
Called once the flush operation finishes. |
- Source:
Returns:
- Type
- undefined
get(callbackopt) → {undefined}
Returns the control flags (CTS, DSR, DCD) on the open port.
Uses GetCommModemStatus
.aspx) for Windows and ioctl
for mac and linux.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
callback |
modemBitsCallback |
<optional> |
Called once the modem bits are retrieved. |
- Source:
Returns:
- Type
- undefined
open(openCallbackopt) → {undefined}
Opens a connection to the given serial port.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
openCallback |
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 |
- Source:
Fires:
Returns:
- Type
- undefined
pause()
The pause()
method causes a stream in flowing mode to stop emitting 'data' events, switching out of flowing mode. Any data that becomes available remains in the internal buffer.
- Since:
- 5.0.0
- Source:
- See:
-
- resume
Returns:
this
read(sizeopt) → {string|Buffer|null}
Request a number of bytes from the SerialPort. The read()
method pulls some data out of the internal buffer and returns it. If no data is available to be read, null is returned. By default, the data is returned as a Buffer
object unless an encoding has been specified using the .setEncoding()
method.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
size |
number |
<optional> |
Specify how many bytes of data to return, if available |
- Since:
- 5.0.0
- Source:
Returns:
The data from internal buffers
- Type
- string | Buffer | null
resume()
The resume()
method causes an explicitly paused, Readable
stream to resume emitting 'data' events, switching the stream into flowing mode.
- Since:
- 5.0.0
- Source:
- See:
-
- pause
Returns:
this
set(optionsopt, callbackopt) → {undefined}
Set control flags on an open port. Uses SetCommMask
.aspx) for Windows and ioctl
for OS X and Linux.
Parameters:
Name | Type | Attributes | Description | ||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
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
|
||||||||||||||||||||||||||||||
callback |
errorCallback |
<optional> |
Called once the port's flags have been set. |
- Since:
- 5.0.0
- Source:
Returns:
- Type
- undefined
update(optionsopt, callbackopt) → {undefined}
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:
Name | Type | Attributes | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
options |
object |
<optional> |
Only supports Properties
|
||||||||
callback |
errorCallback |
<optional> |
Called once the port's baud rate changes. If |
- Source:
Returns:
- Type
- undefined
write(data, encodingopt, callbackopt) → {boolean}
Writes data to the given serial port. Buffers written data if the port is not open.
The write operation is non-blocking. When it returns, data might still not have been written to the serial port. See drain()
.
Some devices, like the Arduino, reset when you open a connection to them. In such cases, immediately writing to the device will cause lost data as they wont be ready to receive the data. This is often worked around by having the Arduino send a "ready" byte that your Node program waits for before writing. You can also often get away with waiting around 400ms.
If a port is disconnected during a write, the write will error in addition to the close
event.
From the stream docs 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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
data |
string | array | buffer | Accepts a |
|
encoding |
string |
<optional> |
The encoding, if chunk is a string. Defaults to |
callback |
function |
<optional> |
Called once the write operation finishes. Data may not yet be flushed to the underlying port. No arguments. |
- Since:
- 5.0.0
- Source:
Returns:
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
.
- Type
- boolean