SerialPort:
Filter:
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

SerialPort.new(port, 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.

Arguments:

port

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

baudrate

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

databits

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

stopbit

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

parity

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

crtscts

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

xonxoff

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

exclusive

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

Discussion:

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

SerialPort.devices

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.

SerialPort.listDevices

Prints the list of available devices, one per line. Shorthand for SerialPort.devices.do(_.postln).

SerialPort.devicePattern

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.

SerialPort.closeAll

Calls -close on all ports.

SerialPort.cleanupAll

Deprecated; use *closeAll instead.

Inherited class methods

Instance Methods

.isOpen

Whether this object represents a valid serial port connection.

.next

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

.read

Read a byte from the device. Blocking read.

.rxErrors

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.

Arguments:

byte

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.

timeout

Unused, deprecated.

Returns:

A Boolean indicating whether the write was successful.

.putAll(bytes, timeout: 0.005)

Write multiple bytes to the device.

Arguments:

bytes

Collection may be Int8Array or String.

timeout

Unused, deprecated.

.doneAction

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

.close

Closes the port.

Inherited instance methods

Examples

Arduino write example

First load the sketch Examples/Communication/Dimmer. See http://www.arduino.cc/en/Tutorial/Dimmer.

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 http://www.arduino.cc/en/Tutorial/Graph.

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