Inherits from NSObject
Declared in ORSSerialPort.h

Overview

The ORSSerialPort class represents a serial port, and includes methods to configure, open and close a port, and send and receive data to and from a port.

There is a 1:1 correspondence between port devices on the system and instances of ORSSerialPort. That means that repeated requests for a port object for a given device or device path will return the same instance of ORSSerialPort.

Opening a Port and Setting It Up

You can get an ORSSerialPort instance either of two ways. The easiest is to use ORSSerialPortManager’s availablePorts array. The other way is to get a new ORSSerialPort instance using the serial port’s BSD device path:

ORSSerialPort *port = [ORSSerialPort serialPortWithPath:@"/dev/cu.KeySerial1"];

Note that you must give +serialPortWithPath: the full path to the device, as shown in the example above.

After you’ve got a port instance, you can open it with the -open method. When you’re done using the port, close it using the -close method.

Port settings such as baud rate, number of stop bits, parity, and flow control settings can be set using the various properties ORSSerialPort provides. Note that all of these properties are Key Value Observing (KVO) compliant. This KVO compliance also applies to read-only properties for reading the state of the CTS, DSR and DCD pins. Among other things, this means it’s easy to be notified when the state of one of these pins changes, without having to continually poll them, as well as making them easy to connect to a UI with Cocoa bindings.

Sending Data

Send data by passing an NSData object to the -sendData: method:

NSData *dataToSend = [self.sendTextField.stringValue dataUsingEncoding:NSUTF8StringEncoding];
[self.serialPort sendData:dataToSend];

Receiving Data

To receive data, you must implement the ORSSerialPortDelegate protocol’s -serialPort:didReceiveData: method, and set the ORSSerialPort instance’s delegate property. As noted in the documentation for ORSSerialPortDelegate, this method is always called on the main queue. An example implementation is included below:

- (void)serialPort:(ORSSerialPort *)serialPort didReceiveData:(NSData *)data
{
    NSString *string = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
    [self.receivedDataTextView.textStorage.mutableString appendString:string];
    [self.receivedDataTextView setNeedsDisplay:YES];
}

Tasks

Getting a Serial Port

Opening and Closing

Sending Data

  • – sendData:

    Sends data out through the serial port represented by the receiver.

  • – sendRequest:

    Sends the data in request, and begins watching for a valid response to the request, to be delivered to the delegate.

Delegate

Request/Response Properties

  •   pendingRequest

    The previously-sent request for which the port is awaiting a response, or nil if there is no pending request.

    property
  •   queuedRequests

    Requests in the queue waiting to be sent, or an empty array if there are no queued requests. Requests are sent from the queue in FIFO order. That is, the first request in the array returned by this property is the next request to be sent.

    property

Port Properties

  •   open

    A Boolean value that indicates whether the port is open. (read-only)

    property
  •   path

    An string representation of the device path for the serial port represented by the receiver. (read-only)

    property
  •   IOKitDevice

    The IOKit port object for the serial port device represented by the receiver. (read-only)

    property
  •   name

    The name of the serial port.

    property

Configuring the Serial Port

Other Port Pins

  •   RTS

    The state of the serial port’s RTS pin.

    property
  •   DTR

    The state of the serial port’s DTR pin.

    property
  •   CTS

    The state of the serial port’s CTS pin.

    property
  •   DSR

    The state of the serial port’s DSR pin. (read-only)

    property
  •   DCD

    The state of the serial port’s DCD pin. (read-only)

    property

Properties

CTS

@property (nonatomic, readonly) BOOL CTS
Discussion

The state of the serial port’s CTS pin.

  • YES means 1 or high state.
  • NO means 0 or low state.

This property is observable using Key Value Observing.

Declared In

ORSSerialPort.h

DCD

@property (nonatomic, readonly) BOOL DCD
Discussion

The state of the serial port’s DCD pin. (read-only)

  • YES means 1 or high state.
  • NO means 0 or low state.

This property is observable using Key Value Observing.

Declared In

ORSSerialPort.h

DSR

@property (nonatomic, readonly) BOOL DSR
Discussion

The state of the serial port’s DSR pin. (read-only)

  • YES means 1 or high state.
  • NO means 0 or low state.

This property is observable using Key Value Observing.

Declared In

ORSSerialPort.h

DTR

@property (nonatomic) BOOL DTR
Discussion

The state of the serial port’s DTR pin.

  • YES means 1 or high state.
  • NO means 0 or low state.

This property is observable using Key Value Observing.

Declared In

ORSSerialPort.h

IOKitDevice

@property (readonly) io_object_t IOKitDevice
Discussion

The IOKit port object for the serial port device represented by the receiver. (read-only)

Declared In

ORSSerialPort.h

RTS

@property (nonatomic) BOOL RTS
Discussion

The state of the serial port’s RTS pin.

  • YES means 1 or high state.
  • NO means 0 or low state.

This property is observable using Key Value Observing.

Declared In

ORSSerialPort.h

allowsNonStandardBaudRates

@property (nonatomic) BOOL allowsNonStandardBaudRates
Discussion

Whether or not the port allows setting non-standard baud rates. Set this property to YES to allow setting non-standard baud rates for the port. The default is NO.

Note: Support for non-standard baud rates depends on the serial hardware and driver being used. Even for hardware/drivers that support non-standard baud rates, it may be that not all baud rates are supported. ORSSerialPort may not report an error when setting a non-standard baud rate, nor will the baudRate getter return the actual baud rate when non-standard baud rates are used. This option should only be used when necessary, and should be used with caution.

Declared In

ORSSerialPort.h

baudRate

@property (nonatomic, copy) NSNumber *baudRate
Discussion

The baud rate for the port.

Unless supportsNonStandardBaudRates is YES, this value should be one of the values defined in termios.h:

- 0
- 50
- 75
- 110
- 134
- 150
- 200
- 300
- 600
- 1200
- 1800
- 2400
- 4800
- 9600
- 19200
- 38400
- 7200
- 14400
- 28800
- 57600
- 76800
- 115200
- 230400

Declared In

ORSSerialPort.h

delegate

@property (nonatomic, weak, nullable) id<ORSSerialPortDelegate> delegate
Discussion

The delegate for the serial port object. Must implement the ORSSerialPortDelegate protocol.

Declared In

ORSSerialPort.h

name

@property (copy, readonly) NSString *name
Discussion

The name of the serial port.

Can be presented to the user, e.g. in a serial port selection pop up menu.

Declared In

ORSSerialPort.h

numberOfStopBits

@property (nonatomic) NSUInteger numberOfStopBits
Discussion

The number of stop bits. Values other than 1 or 2 are invalid.

Declared In

ORSSerialPort.h

open

@property (readonly, getter=isOpen) BOOL open
Discussion

A Boolean value that indicates whether the port is open. (read-only)

Declared In

ORSSerialPort.h

parity

@property (nonatomic) ORSSerialPortParity parity
Discussion

The parity setting for the port. Possible values are:

  • ORSSerialPortParityNone
  • ORSSerialPortParityOdd
  • ORSSerialPortParityEven

Declared In

ORSSerialPort.h

path

@property (copy, readonly) NSString *path
Discussion

An string representation of the device path for the serial port represented by the receiver. (read-only)

Declared In

ORSSerialPort.h

pendingRequest

@property (strong, readonly, nullable) ORSSerialRequest *pendingRequest
Discussion

The previously-sent request for which the port is awaiting a response, or nil if there is no pending request.

This property can be observed using Key Value Observing.

Declared In

ORSSerialPort.h

queuedRequests

@property (strong, readonly) NSArray *queuedRequests
Discussion

Requests in the queue waiting to be sent, or an empty array if there are no queued requests. Requests are sent from the queue in FIFO order. That is, the first request in the array returned by this property is the next request to be sent.

This property can be observed using Key Value Observing.

Note: This array does not contain the pending request, a sent request for which the port is awaiting a response.

Declared In

ORSSerialPort.h

shouldEchoReceivedData

@property (nonatomic) BOOL shouldEchoReceivedData

Declared In

ORSSerialPort.h

usesDCDOutputFlowControl

@property (nonatomic) BOOL usesDCDOutputFlowControl
Discussion

A Boolean value indicating whether the serial port uses DCD Flow Control.

Declared In

ORSSerialPort.h

usesDTRDSRFlowControl

@property (nonatomic) BOOL usesDTRDSRFlowControl
Discussion

A Boolean value indicating whether the serial port uses DTR/DSR Flow Control.

Declared In

ORSSerialPort.h

usesRTSCTSFlowControl

@property (nonatomic) BOOL usesRTSCTSFlowControl
Discussion

A Boolean value indicating whether the serial port uses RTS/CTS Flow Control.

Declared In

ORSSerialPort.h

Class Methods

serialPortWithDevice:

+ (nullable ORSSerialPort *)serialPortWithDevice:(io_object_t)device
Discussion

Returns an ORSSerialPort instance for the serial port represented by device.

Generally, serialPortWithPath: is the method to use to get port instances programatically. This method may be useful if you’re doing your own device discovery with IOKit functions, or otherwise have an IOKit port object you want to “turn into” an ORSSerialPort. Most people will not use this method directly.

Parameters

device

An IOKit port object representing the serial port device.

Return Value

An initalized ORSSerialPort instance, or nil if there was an error.

Declared In

ORSSerialPort.h

serialPortWithPath:

+ (nullable ORSSerialPort *)serialPortWithPath:(NSString *)devicePath
Discussion

Returns an ORSSerialPort instance representing the serial port at devicePath.

devicePath must be the full, callout (cu.) or tty (tty.) path to an available serial port device on the system.

Parameters

devicePath

The full path (e.g. /dev/cu.usbserial) to the device.

Return Value

An initalized ORSSerialPort instance, or nil if there was an error.

Declared In

ORSSerialPort.h

Instance Methods

cleanup

- (void)cleanup

cleanupAfterSystemRemoval

- (void)cleanupAfterSystemRemoval
Discussion

Closes the port and cleans up.

This method should never be called directly. Call close to close a port instead.

Declared In

ORSSerialPort.h

close

- (BOOL)close
Discussion

Closes the port represented by the receiver.

If the port is closed successfully, the ORSSerialPortDelegate method -serialPortWasClosed: will be called before this method returns.

Return Value

YES if closing the port was closed successfully, NO if closing the port failed.

Declared In

ORSSerialPort.h

initWithDevice:

- (nullable instancetype)initWithDevice:(io_object_t)device
Discussion

Returns an ORSSerialPort instance for the serial port represented by device.

Generally, initWithPath: is the method to use to get port instances programatically. This method may be useful if you’re doing your own device discovery with IOKit functions, or otherwise have an IOKit port object you want to “turn into” an ORSSerialPort. Most people will not use this method directly.

Parameters

device

An IOKit port object representing the serial port device.

Return Value

An initalized ORSSerialPort instance, or nil if there was an error.

Declared In

ORSSerialPort.h

initWithPath:

- (nullable instancetype)initWithPath:(NSString *)devicePath
Discussion

Returns an ORSSerialPort instance representing the serial port at devicePath.

devicePath must be the full, callout (cu.) or tty (tty.) path to an available serial port device on the system.

Parameters

devicePath

The full path (e.g. /dev/cu.usbserial) to the device.

Return Value

An initalized ORSSerialPort instance, or nil if there was an error.

Declared In

ORSSerialPort.h

open

- (void)open
Discussion

Opens the port represented by the receiver.

If this method succeeds, the ORSSerialPortDelegate method -serialPortWasOpened: will be called.

If opening the port fails, the ORSSerialPortDelegate method -serialPort:didEncounterError: will be called.

Declared In

ORSSerialPort.h

sendData:

- (BOOL)sendData:(NSData *)data
Discussion

Sends data out through the serial port represented by the receiver.

This method attempts to send all data synchronously. That is, the method will not return until all passed in data has been sent, or an error has occurred.

If an error occurs, the ORSSerialPortDelegate method -serialPort:didEncounterError: will be called. The exception to this is if sending data fails because the port is closed. In that case, this method returns NO, but -serialPort:didEncounterError: is not called. You can ensure that the port is open by calling isOpen before calling this method.

Note: This method can take a long time to return when a very large amount of data is passed in, due to the relatively slow nature of serial communication. It is better to send data in discrete short packets if possible.

Parameters

data

An NSData object containing the data to be sent.

Return Value

YES if sending data succeeded, NO if an error occurred.

Declared In

ORSSerialPort.h

sendRequest:

- (BOOL)sendRequest:(ORSSerialRequest *)request
Discussion

Sends the data in request, and begins watching for a valid response to the request, to be delivered to the delegate.

If the receiver already has one or more pending requests, the request is queued to be sent after all previous requests have received valid responses or have timed out and this method will return YES. If there are no pending requests, the request is sent immediately and NO is returned if an error occurs.

Note: This method calls through to sendData:, and the same caveat about it taking a long time to send very large requests applies.

Parameters

request

An ORSSerialRequest instance including the data to be sent.

Return Value

YES if sending the request’s data succeeded, NO if an error occurred.

Declared In

ORSSerialPort.h