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