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
Port Information
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
Assigning a 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.