Serial Tools

Kok Chen, W7AY [w7ay (at) arrl (dot) net]
Last updated: July 13, 2013

Introduction

Serial Tools is a set of serial port tools for Mac OS X. It includes a Terminal Emulator, a Protocol Analyzer, an NMEA parser and a serial port monitor to watch for connections and removals of serial ports.

Please note that Serial Tools is not a supported product, but simply a project that I wrote for myself to use. If you have similar needs, Serial Tools is completely free. The Xcode project for Serial Tools and the sources are also free.

Serial Tools is built as a Universal Binary application and works natively with both the PowerPC and the Intel based Macintosh running Tiger (Mac OS X 10.4) or newer. You can download both the Serial Tools application and Xcode project from the Download page. The sources in Serial Tools are GPL free, and you have the freedom to make any changes that you want without needing to publish your changes.

The terminal emulator (Terminal.m) in Serial Tools is an Objective-C extension of NSTextView class. It can be used as sample code for any Cocoa application that needs to communicate with a Mac OS X serial port through a text view. For example, the protocol analyzer in Serial Tools is just a sub-class of Terminal.m that supports a second serial port connection.


Sessions

A Serial Tool session consists of a set of port-specific preferences (baud rate, parity, etc) that can be saved and re-opened at a later time.

After launching Serial Tools, you can select a New Session or open an existing session file. You can also launch Serial Tools by double clicking on a previously saved Session file. Multiple sessions can be concurrently opened, each one connected to a different serial port.



Each session can be Saved (or Saved As a file with a different name). The saved file is a Cocoa dictionary (similar to a plist file) with the properties of the session. The saved file has an sertool extension. Double clicking on a sertool file will launch Serial Tools if the application is not already running. Serial Tools uses the sertool file to open a new session that has the parameters of the saved session.

When you select New Session, a new untitled Serial Tools session window will appear.



Once you save the session under a name, the title bar of the session window will inherit the same name. Likewise, if you open a session using a previously saved session file, the title bar of the session window will have the name of the session file. Recent session files can be found in the Open Recent menu item of the File menu.

Currently, the Serial Tools application contains three tools, a Terminal Emulator (shown above), a Protocol Analyzer (next figure below) and a Connections Monitor.


Terminal Emulator

When the session window is tabbed to the Terminal tab, you will see the window that is previously shown above.The Serial Port popup menu lets you select the serial port to use. In the above, a KeySpan USB serial PDA adapter has been selected.

Please note that the serial adapter from some manufacturers can show up more than once under different names in the Serial Port menu. If the device driver registers the device under more than one name, both will appear in the Serial Port menu. You can select either one.

You can choose the baud rate, the number of data bits, whether to use even or odd or no parity and the number of stop bits in the async protocol. Your selection also shows up as a common designation, as in "9600 / 8-N-1" above.

Click on the Connect button to open a connection to the serial port. The button caption will change to Disconnect. If you click on Disconnect, you will close the connection to the serial port and allow other apps to gain full control of the serial port again.

Once connected, the CTS and DSR indicators will show the status of those two RS-232 control lines. You can also assert either RTS or DTR by clicking on their checkboxes. When a serial port is disconnected, the RTS and DTR checkboxes and the CTS and DSR indicators become inactive.

The textview below the menus and buttons is a half duplex (what you type is immediately echoed to the text view) "terminal emulator." Anything you type will go out through the serial port, if it is connected. Anything that the serial port receives will also appear on this text view.

When the cr/lf checkbox is selected, each newline (return or enter keyboard key) will cause an ASCII carriage return character and a linefeed character to be sent.

When the Raw checkbox is selected, ASCII control characters (less than 0x20 or greater or equal to 0x7f) will be printed as two hex digits in between angle brackets. This option can help diagnose the difference between 8-bit-no-parity and 7-bit-with-parity settings.


Protocol Analyzer

The Protocol Analyzer (port sniffer) allows you to monitor the traffic between an existing DTE-DCE connection. This can, for example, be an existing connection between a computer and a TNC. Another example is a connection between a microKeyer and a transceiver's CAT port.

The Protocol Analyzer in Serial Tools works in conjunction with two serial ports. One serial port is connected to the DTE (with an appropriate null modem, if required) and the other serial port is connected to the DCE.

Any character that is received by the serial port that is connected to the DTE is printed to the text view and also relayed to the serial port that is connected to the DCE. Likewise, any character that is received from the DCE port is relayed by Serial Tools to the DTE port and also echoed to the text view.

The following figure shows the Protocol Analyzer that is connected to intercept data which are flowing between a different computer and an Elecraft K3. The red text (serial port A) shows the characters that are sent from the second computer, and the blue text (serial port B) are the responses from the K3 transceiver.




NMEA (GPS) Monitor

The NMEA tab view displays information from the GGA, GSA, GSV and RMC packets of an NMEA data stream from a serial-port connected GPS device. The NMEA panel is developed with an SiRF III receiver, but should work with other GPS devices.



Select the serial port and baud rate and click on the Connect button.

Date information is extracted from RMC packets. Time information, latitude and longitude data are extracted from both RMC and GGA packets. The GGA packet also provides Altitude information.

The GSA packet provides information on the fix (no fix, 2D fix or 3D fix) and dilution of precision (PDOP). The horizontal dilution of precision (HDOP) and vertical dilution of precision (VDOP) are shown in parenthesis after the PDOP value.

The GGA packet provides information on how many satellites are being tracked.

GSV packets provide information on how many satellites are in view. Up to 9 of the satellites in the GSV packets are listed in Serial Tools in the order of descending signal to noise ratio. Together with the satellites' elevation and azimuth, these are shown in boxes at the bottom part of the window.


Connections Monitor

The Monitor tab view shows the connections to serial ports on your computer.



As shown above, it lists all devices on your computer that are registered to be serial devices. In addition, the monitor "listens" for any notification when a device is added or removed. The window below shows the display when the Keyspan is disconnected from its USB hub:



Notice that the Monitor shows two device removals. This is because the Keyspan driver has registered the Keysan PDA adapter as both KeySerial1 and as USA19bP1.1.

When the Keysan PDA adapter is plugged back into the USB hub, this is what is shown in the Monitor:



With a new device set up, where you are not sure what a serial port's name is, you can use the Connection Monitor to watch for port activity as you physically add or remove the device.

If there is no activity in the Connection Monitor when you add or remove the device, you are most likely missing the device driver.


Saving a Session

When you use the Save menu item in the File menu on an Untitled session (or if you use the Save As... menu item on any session), you will be shown a dialog to provide a name for a session file and where to save it to. This should create an XML file (pretty much like what a plist file contains, and can be likewise opened using the Mac OS Property List Editor that is on the Developer disk) with a sertool file extension. The Finder icon will look like this:



If you click on a previously created session file, Serial Tools will create a new session with the parameters determined by the file. If Serial Tools is not running, double clicking on a Session file will also launch Serial Tools for you.