SerialManager

Kok Chen, W7AY
[ w7ay (at) arrl.net ]
April 29, 2009


Overview


SerialManager is a Cocoa class that simplifies the use of serial ports. SerialManager finds modems and/or RS-232 ports, provides simple methods to open ports at specified baud rate, data bits, parity bits and stop bits, and it has methods to set the state of output control flags (e.g., RTS and DTR).

SerialManager also provides delegate methods that are called when ports are added or removed from the computer, and when control flags (DSR and CTS) changes.



Download


The SerialManager sources can be downloaded from here.


Requirements


SerialManager needs to be linked against the IOKit framework (/System/Library/Frameworks/IOKit.framework).



Tasks


Enumerating ports

- findModems
- findRS232Ports
- findPorts
- port:added: (delegate method)


Port Information

- streamAtIndex:
- pathAtIndex:


Opening and closing ports

- openInput:baudrate:bits:parity:stopbits:
- openInput:baudrate:bits:parity:stopbits:flags:
- openOutput:baudrate:bits:parity:stopbits:
- openOutput:baudrate:bits:parity:stopbits:flags:
- closeInput
- closeOutput
- inputFileDescriptor
- outputFileDescriptor


Control Flags

- getTermios
- setRTS:
- setDTR:
- controlFlagsChanged: (delegate method)


Assigning a Delegate

- setDelegate:
- delegate




Instance Methods


closeInput

Closes the currently opened input port.

- (void)closeInput



closeOutput

Closes the currently opened output port.

- (void)closeOutput



delegate

Returns the delgate that was previously set in the receiver.

- (id)delegate

Return Value

A delegate used by the receiver, or nil if there is no delegate.



findModems

Find all serial ports that are registered as modems. Use findPorts to find both modems and RS232 ports.

- (int)findModems

Return Value

An integer count of the number of modems found.



findPorts

Find serial ports that are registered either as modems or RS232 ports.

- (int)findPorts

Return Value

An integer count of the number of ports found.



findRS232Ports

Find serial ports that are registered as RS232 ports. Use findPorts to find both modems and RS232 ports.

- (int)findRS232Ports

Return Value

An integer count of the number of RS232 ports found.



getTermios

Get the Unix termios word of the input port.

- (int)getTermios

Return Value

The termios bits of the currently opened input serial port.



inputFileDescriptor

File descriptor of input port. The returned descriptor can be used in the Unix read() and select() calls to get bytes from the port.

- (FileDescriptor)inputFileDescriptor

Return Value

The Unix file descriptor (integer) of the currently open input port, or -1 if the input port is not open.



openInput:baudrate:bits:parity:stopbits:

Open port as input. The file is opened with the ( O_RDONLY | O_NOCTTY | O_NDELAY ) fcntl.h flag bits.

- (FileDescriptor)openInput:(NSString*)path baudrate:(int)baudRate bits:(int)dataBits parity:(int)parityBit stopbits:(int)stopBits

Parameters

path
an NSString containing a path name that is obtained from the -pathAtIndex method.

baudRate
an integer for the baud rate to open the port at..

dataBits
the number of data bits.

parityBit
an integer zero for no parity, integer 1 for odd parity and integer 2 for even parity.

stopBits
an integer 1 or less specifies 1 stop bit, an integer greater than 1 specifies 2 stop bits..

Return Value

Returns the Unix file descriptor (an integer) of an opened port, or -1 if the open operation has failed.



openInput:baudrate:bits:parity:stopbits:flags

Open port as input, with fcntl.h flags.

- (FileDescriptor)openInput:(NSString*)path baudrate:(int)baudRate bits:(int)dataBits parity:(int)parityBit stopbits:(int)stopBits flags:(int)openFlags

Parameters

path
an NSString containing a path name that is obtained from the -pathAtIndex method.

baudRate
an integer for the baud rate to open the port at..

dataBits
the number of data bits.

parityBit
an integer zero for no parity, integer 1 for odd parity and integer 2 for even parity.

stopBits
an integer 1 or less specifies 1 stop bit, an integer greater than 1 specifies 2 stop bits.

openFlags
flag bits as defined in fcntl.h.

Return Value

Returns the Unix file descriptor (an integer) of an opened port, or -1 if the open operation has failed.



outputFileDescriptor

File descriptor of output port. The returned descriptor is used in the Unix write() and select() calls to write bytes to the port.

- (FileDescriptor)outputFileDescriptor

Return Value

The Unix file descriptor (integer) of the currently opened output port, or -1 if the output port is not open.



pathAtIndex:

SerialManager stores a list of stream names and Unix path names after a call to -findPorts, -findModems or -findRS232Ports. After that, a call to -pathAtIndex will return a NSString that contains a path of a port. This path name can be subsequently sent to one of the "-open" methods.

- (NSString*)pathAtIndex:(int)index


index
an integer index of the port. This number should be between 0 and n-1, where n is the number that is returned by -findPorts, -findModems or -findRS232Ports., If the integer is outside of range of available ports, a nil pointer is returned.

Return Value

An NSString containg the Unix path name, or a nil pointer if the index is out of range.



setDelegate:

Closes the currently opened output port.

- (void)setDelegate:(id)object

Parameters

object
the new delegate object. If the delegate handles -controlFlagsChanged:, setDelegate also turns on a background thread to monitor flag changes. This thread terminates when nil is sent to setDelegate.



setDTR:

Set/clear the Data Terminal Ready control bit.

- (void)setDTR:(Boolean)state

Parameters

state
state is true to assert DTR, state is false to clear DTR.



setRTS:

Set/clear the Request To Send control bit.

- (void)setRTS:(Boolean)state

Parameters

state
state is true to assert RTS, state is false to clear RTS.



streamAtIndex:

SerialManager stores a list of stream names and Unix path names after a call to -findPorts, -findModems or -findRS232Ports. After that, a call to -streamAtIndex will return a NSString that contains the stream name of a port. This stream name can be used to identify the port in a menu.

- (NSString*)streamAtIndex:(int)index


index
an integer index of the port. This number should be between 0 and n-1, where n is the number that is returned by -findPorts, -findModems or -findRS232Ports., If the integer is outside of range of available ports, a nil pointer is returned.

Return Value

An NSString containg the stream name, or a nil pointer if the index is out of range.



Delegate Methods


controlFlagsChanged:

Sent when control bits has changed.

- (void)controlFlagsChanged:(int)termbits

termbits
The current termios word.



port:added:

Sent when the operating system detects if serial ports have been added or removed. When the delegate receives this message, it should call findPorts, findModems or findRS232Ports to update its list of ports.

- (void)port:(NSString*)streamName added:(Boolean)addState

streamName
the stream name of a port that has been added or removed.

addState
addState is true if the port is added. addState is false if the port is removed.