Serial

The Serial class provides a straightforward interface for communicating with devices connected via a serial port (e.g., RS-232, USB-to-Serial adapters). It simplifies the process of listing available ports, configuring connection parameters, and handling data streams.

An instance of this class must be created for each serial port you wish to interact with.

---

list

This is a static function that scans the system and returns a list of all detected serial ports. This is useful for finding the correct port path before creating an instance.

Parameters

None.

Output

An array of objects, where each object contains detailed information about a serial port. For example:

[
  {
    "path": "COM3",
    "manufacturer": "Arduino LLC",
    "serialNumber": "12345",
    "pnpId": "USB\\VID_2341&PID_0043\\12345",
    "locationId": "Port_#0003.Hub_#0001",
    "productId": "0043",
    "vendorId": "2341"
  }
]

---

create

Creates an instance for a specific serial port and configures its connection parameters. The port is not opened until the open() function is called.

Parameters

• options: An object containing the serial port configuration.

  • path: The system path of the serial port (e.g., /dev/ttyUSB0 on Linux, COM3 on Windows). This is required.

  • baudRate: The communication speed in bits per second. Defaults to 9600.

  • dataBits: Number of data bits. Can be 5, 6, 7, or 8. Defaults to 8.

  • stopBits: Number of stop bits. Can be 1, 1.5, or 2. Defaults to 1.

  • parity: The parity checking method. Can be none, even, mark, odd, or space. Defaults to none.

Example

# options
path: COM3
baudRate: 9600
dataBits: 8
parity: none
stopBits: 1

---

open

Opens the connection to the serial port specified in the create call.

Parameters

None.

Output

Returns true on a successful connection.

---

close

Closes an open serial port connection.

Parameters

None.

Output

Returns true on a successful disconnection.

---

isOpen

Checks if the port connection is currently open.

Parameters

None.

Output

Returns true if the port is open, otherwise false.

---

write

Writes a string of data to the open serial port. This function can automatically append special termination characters.

NOTE: To send a carriage return, use the placeholder <CR>. For a line feed, use <LF>. For both, use <CRLF>.

Parameters

• data: The string of data to be sent.

• suffix: An optional string to always append to the data. This is useful for command terminators.

Example: Sending a command with a terminator

This sends the command GET_DATA followed by a carriage return and line feed.

# data
GET_DATA
# suffix
<CRLF>

Output

Returns true once the data has been successfully written and transmitted.

---

read

Reads a specific number of bytes directly from the port's internal receive buffer.

Note: For most applications, especially those involving asynchronous or stream-based communication, it is highly recommended to use the onData function instead of read.

Parameters

• size: The number of bytes to attempt to read.

Output

A string containing the data read from the buffer, or null if the requested number of bytes is not available in the buffer.

---

changeBaudRate

Changes the baud rate for an already open port connection.

Parameters

• baudRate: The new baud rate (e.g., 19200, 115200).

Example

# baudRate
115200

Output

Returns true if the baud rate was changed successfully.

---

onData

This is the primary method for receiving data from a serial device. It attaches a listener that automatically parses the incoming data stream and triggers a callback function when a complete message is received. You can choose one of three parsing strategies.

Parameters

• name: A unique name for this data handler.

• handler: The callback function that will be executed with the received data.

• parserOptions: An object specifying the parsing strategy. You should only use one of the options below.

  • delimiter: Triggers the handler after a specific sequence of characters is received. Common values are <LF> (line feed, \n) or <CRLF> (\r\n). Defaults to <LF>.

  • timeout: Triggers the handler when there is a pause in the incoming data stream for a specified duration.

  • byteLength: Triggers the handler after a fixed number of bytes has been received.

Example: Delimiter Parsing

This is ideal for devices that end each message with a newline character.

# name
line_handler
# handler
<callback>
# parserOptions
delimiter: <LF>

Example: Timeout Parsing

This is useful for devices that send data in bursts without a clear delimiter.

# name
burst_handler
# handler
<callback>
# parserOptions
timeout: 50

Example: Fixed Length Parsing

This is for devices that send data in fixed-size packets.

# name
packet_handler
# handler
<callback>
# parserOptions
byteLength: 16

Output

Returns true if the data handler was attached successfully.

---

onError

Attaches a listener that will be called if an error occurs with the serial port connection.

Parameters

• name: A unique name for this error handler.

• handler: The callback function to execute when an error is detected.

Example

# name
my_error_handler
# handler
<callback>

Output

Returns true if the error handler was attached successfully.