Classes | External Control

SerialPort : Object

serial port interface

This class provides basic support for serial port communication. Ports are opened with *new and closed with -close.

Each SerialPort object uses an 8KB internal buffer and reads data as soon as it is available. If the data is not read out of the buffer and the buffer fills up, incoming bytes will be dropped. Use -rxErrors to get a count of the number of bytes dropped.

Since it is constantly polling the port for available data, a SerialPort object knows almost immediately when the port has been lost. When this happens, it will call the -doneAction callback and mark itself as closed.

Class Methods, baudrate: 9600, databits: 8, stopbit: true, parity, crtscts: false, xonxoff: false, exclusive: false)

Creates and opens the port. Throws if creation fails; this may be because the port does not exist, the port could not be opened, or the settings were invalid.



A String representing the port to be opened. (An Integer index into *devices is allowed, but this is deprecated.)


Integer baud rate, typically in the range [4800..230400].


Bits per character. Typically 8, but can be any integer.


A Boolean indicating whether to use two stop bits (true) or one stop bit (false).


Whether the port uses even, odd, or no parity. Pass 'even', 'odd', or nil (for none).


A Boolean indicating whether to use hardware flow control (RTS/CTS signals).


A Boolean indicating whether to use software flow control (XON/XOFF signals).


A Boolean indicating whether to open the device exclusively. This option is not implemented on Windows.


crtscts and xonxoff cannot both be true; *new will throw an error if both are set.


Retrieve an array of available devices represented as Strings. On macOS and Linux, this list is obtained using a number of regular expression rules on files in the /dev/ directory. On Windows, this is obtained using a registry key. The matching rules are designed to be identical to that of the Arduino IDE.

For backward compatibility, if SerialPort.devicePattern is not nil, SerialPort.devicePattern.pathMatch is returned instead of the default behavior.


Prints the list of available devices, one per line. Shorthand for


SerialPort.devicePattern = value

If set to a non-nil value, SerialPort.devicePattern instead returns SerialPort.devicePattern.patchMatch. That is, the value of this class variable is used as a file glob.

This is a legacy feature and no longer recommended. File globbing alone is not powerful enough to capture a general set of possible serial port paths, and this level of customization was not necessary for SerialPort.devices. If you need to refine the results returned by SerialPort.devices, it is better to do your own matching or filtering.


Calls -close on all ports.


Deprecated; use *closeAll instead.

Inherited class methods

Instance Methods


Whether this object represents a valid serial port connection.


Read a byte from the device. Non-blocking read.


Read a byte from the device. Blocking read.


RX (receive) errors since last query. An RX error occurs when the internal buffer is completely full. This count is reset to 0 every time this method is called.

.put(byte, timeout: 0.005)

Write a byte to the device. Always blocks.



An Integer or Char. Only values in the range from 0 to 2**databits - 1 may be written. If a value out of that range is passed to put, only the lowest bits will be used.


Unused, deprecated.


A Boolean indicating whether the write was successful.

.putAll(bytes, timeout: 0.005)

Write multiple bytes to the device.



Collection may be Int8Array or String.


Unused, deprecated.


.doneAction = value

A Function which will be evaluated if the port gets closed (maybe unexpectedly so, due to hardware failure or accidental disconnection). This allows you to for example to make a backup solution and activate it (like using fake input data for your algorithm, or trying to reopen the device). By default it will post a message reading "SerialPort X was closed".


Closes the port.

Inherited instance methods


Arduino write example

First load the sketch Examples/Communication/Dimmer. See

NOTE: Always make sure the serial monitor is closed in the Arduino application before opening the port in SuperCollider.

Arduino read example

First load the sketch Examples/Communication/Graph. See

NOTE: Always make sure the serial monitor is closed in the Arduino application before opening the port in SuperCollider.