ssterm - Simple Serial-Port Terminal

Visit the github repository for ssterm here: http://github.com/vsergeev/ssterm

Download the latest version of ssterm source here: ssterm-1.2.tar.gz

Download the latest Linux x86 binary of ssterm here: ssterm-linux-x86-1.2.gz

Visit the Arch Linux AUR Package here: http://aur.archlinux.org/packages.php?ID=46701

ChangeLog

• Version 1.2 - 02/04/2011
  • Added mutexes for safer handling of shared variables across threads.
• Version 1.1 - 11/22/2009
  • CRITICAL FIX: Serial port was not being opened in non-blocking mode, preventing ssterm from working in some situations. This has been fixed.
• Version 1.0 - 10/26/2009
  • Initial release.

ssterm, or simple serial-port terminal, is a console-based serial port terminal with curses and stdin/stdout user interfaces.

ssterm features several useful formatting options:

• hexadecimal representation
  • newline interpretation
  • newline character color coding
• choice of transmit newline character mappings (e.g. LF → CRLF)
• choice of receive newline characters mapping (e.g. CR → LF)
• buffer scroll in curses interface
• buffer dump in curses interface
• local character echo

The curses interface is the more interactive user interface. It allows scrolling through the receive buffer, dumping the receive buffer, as well as dynamically toggling the formatting options mentioned above. The stdin/stdout interface is more suitable for situations where data needs to be piped to/from ssterm (such as data logging).

In the curses interface, ssterm's transmit and receive handlers are threaded with pthreads. The stdin/stdout interface uses select() for receiving data from the serial port and stdin.

ssterm should work on most *nix platforms, as well as a MinGW or Cygwin environment. ssterm was written by Vanya A. Sergeev, and tested with the GNU C Compiler on Linux. Feel free to report any bugs!, ideas, or suggestions to vsergeev at gmail dot com.

ssterm is released under the GNU General Public License Version 2.

    You should have received a copy of the GNU General Public License
    along with this program; see the file "COPYING".  If not, visit
    http://www.gnu.org or write to the Free Software Foundation, Inc.,
    59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Running,

$ make

in the ssterm project directory should compile ssterm on most *nix systems, including a Cygwin or MinGW environment. The Makefile is configured to use GCC to compile ssterm. ssterm should have no problem being compiled with “gmake”.

$ make install

will install ssterm into /usr/bin/.

$ make uninstall

will remove ssterm from /usr/bin/.

ssterm requires pthread and ncurses header files and libraries for compilation.

By default, ssterm will open the specified serial port with 9600 baudrate, 8 data bits, no parity, 1 stop bit, and no flow control. These settings can be adjusted with the baudrate, databits, parity, stopbits, and flow-control options.

The curses interface is selected by default. The stdin/stdout interface can be enabled with the -s option. This interface mode allows for data to be piped to and from ssterm.

The newline characters that are transmitted and interpreted on reception can be specified with the tx-nl and rx-nl options. These options were created to accomodate working with the serial port on LF based systems. They can be disabled by selecting raw mode in both tx-nl and rx-nl options.

The following receive newline character settings are available:

• raw - no re-interpretation of received newline characters
• none - dismisses any received newline characters
• cr - maps received CR → LF, received LF are ignored
• lf - maps received LF → LF, received CR are ignored
• crlf - maps received CRLF → LF, otherwise out-of-sequence newline characters are ignored

Similarly, the transmit newline character settings consist of:

• raw - no re-interpretation of transmitted newline characters
• none - omits newline characters on transmit
• cr - maps LF → CR on transmit
• lf - maps LF → LF on transmit
• crlf - maps LF → CRLF on transmit

The LF setting is default for both tx-nl and rx-nl.

Additional settings include hexadecimal instead of ASCII representation of the data with the hex option, newline interpretation in hexadecimal mode with the hex-nl option, and local character echo with the echo option. These options are off by default.

Running ssterm with the serial port device path and no additional options will open the serial port at 9600 baudrate, 8 data bits, no parity, and 1 stop bit with the curses interface. The curses interface supports several options to make analysis of received data easier.

Ctrl-h enables hexadecimal representation mode: all data will be presented in hexadecimal form instead of ASCII. Ctrl-n enables newline recognition in hexadecimal mode, so data is not only presented in hexadecimal form, but also separated at the newline markers. Ctrl-o enables newline character color coding in hexadecimal mode, so that CR characters will be highlighted with magenta, and LF characters will be highlighted with cyan.

Up/Down Arrow keys, Page Up/Page Down, and Home/End facilitate scrolling through the buffer.

Ctrl-l clears the buffer. Ctrl-r refreshes the screen and reprints the current buffer.

Ctrl-d dumps the current buffer to a file in the local directory, with a filename ranging from ssterm-dump-00 to ssterm-dump-99.

Ctrl-q/Ctrl-s sends the XON/XOFF control character (respectively) if software flow-control is required.

Additional usage information from the program's command line options is provided below.

Usage: ./ssterm <option(s)> <serial port>

 Interface Options:
  -s, --stdin			Use an stdin/stdout interface as opposed to 
				curses 

 Serial Port Options:
  -b, --baudrate <rate>		Specify the baudrate
  -d, --databits <number>	Specify the number of data bits [5,6,7,8]
  -p, --parity <type>	 	Specify the parity [none, odd, even]
  -t, --stopbits <number>	Specify number of stop bits [1,2]
  -f, --flow-control <type>	Specify the flow-control [none, rtscts, xonxoff]

 Formatting Options:
  --tx-nl <combination>		Specify the transmit newline combination
				 [raw, none, cr, lf, crlf]
  --rx-nl <combination>		Specify the receive newline combination
				 [raw, none, cr, lf, crlf]
  -e, --echo			Turn on local character echo
  -x, --hex			Turn on hexadecimal representation mode
  --hex-nl			Turn on newlines in hexadecimal mode

 Curses Formatting Options:
  -c, --rx-nl-color		Color-code all receive newline combinations

 Misc. Options:
  --buffer-size <bytes>		Specify the size of ssterm's receive buffer
  -h, --help			Display this usage/help
  -k, --commands		Display curses commands
  -v, --version			Display the program's version

Default options: curses, 9600, 8N1, flow control: none, transmit: LF,
receive: LF, echo: off, hex: off, receive color-code: off, buffer size: 4096

Curses Commands for ssterm:
 Page Up/Page Down	Scroll buffer up/down by 5 lines
 Home/End		Scroll to the top/bottom of the buffer
 Up/Down		Scroll buffer up/down by 1 line

 Ctrl-l			Clear buffer
 Ctrl-r			Reprint buffer
 Ctrl-d			Dump buffer to file

 Ctrl-h			Hexadecimal representation mode
 Ctrl-n			Interpret newlines in hexadecimal mode
 Ctrl-o			Color-code newline characters in hexadecimal
			mode

 Ctrl-q			Send XON
 Ctrl-s			Send XOFF

If you encounter any program bugs or problems, please notify the program author by email: Vanya A. Sergeev - vsergeev at gmail dot com.

This version of ssterm does not support file-based configuration. However, this feature is planned for the next release.

ssterm does not support printing raw receive newline characters in curses interface (curses interprets a CR character literally and deletes the current line on the screen). There may be a work-around for this in a future release (such as a color-coded blank character). The stdin/stdout interface, however, does support raw receive newline characters.

In addition, the curses interface of ssterm does not currently support custom color-coded characters (only newline characters), transmitting special control characters outside of XON and XOFF, or manual manipulation of the serial port's control lines. These features may be available in upcoming releases.

ssterm with stdin/stdout interface (useful for datalogging):

$ ssterm -s /dev/ttyUSB0 > nmea_data.txt

ssterm (curses) with hexadecimal representation mode, and newline character color-coding:

$ ssterm -xc /dev/ttyUSB0

ssterm (curses) with specified serial port settings (115200 baudrate, odd parity, 2 stop bits), 8 data bits are default/implied:

$ ssterm -b 115200 -p odd -t 2

ssterm (curses) with CRLF for transmitted newlines, but just LF for received newlines:

$ ssterm --tx-nl crlf --rx-nl lf /dev/ttyUSB0

ssterm (stdin/stdout) with hexadecimal representation mode:

$ ssterm -s -x /dev/ttyUSB0
24 47 50 47 47 41 2C 30 38 32 38 33 30 2E 38 32 31 2C 2C 2C 2C 2C 30 2C 30 30 2C
2C 2C 4D 2C 30 2E 30 2C 4D 2C 2C 30 30 30 30 2A 35 43 0D 0A 24 47 50 47 53 41 2C
41 2C 31 2C 2C 2C 2C 2C 2C 2C 2C 2C 2C 2C 2C 2C 2C 2C 2A 31 45 0D 0A 24 47 50 52
4D 43 2C 30 38 32 38 33 30 2E 38 32 31 2C 56 2C 2C 2C 2C 2C 2C 2C 32 36 31 30 30
39 2C 2C 2A 32 39 0D 0A 24 47 50 47 47 41 2C 30 38 32 38 33 31 2E 38 31 34 2C 2C
2C 2C 2C 30 2C 30 30 2C 2C 2C 4D 2C 30 2E 30 2C 4D 2C 2C 30 30 30 30 2A 35 42 0D
0A 24 47 50 47 53 41 2C 41 2C 31 2C 2C 2C 2C 2C 2C 2C 2C 2C 2C 2C 2C 2C 2C 2C 2A
31 45 0D 0A 24 47 50 52 4D 43 2C 30 38 32 38 33 31 2E 38 31 34 2C 56 2C 2C 2C 2C
2C 2C 2C 32 36 31 30 30 39 2C 2C 2A 32 45 0D 0A 24 47 50 47 47 41 2C 30 38