SFTARDCAL


An application to communicate with serial port devices


In the beginning

In the beginning, I had no way of easily doing what should be easy to do with a device that uses a serial port for communication: command and control. This was, of course, FRUSTRATING, but I've solved this problem enough times already, that it was time to SOLVE IT FOR GOOD!

And so, several years ago, I wrote the 'sftardcal' application, which is intended to run on Windows as well as on POSIX systems (like Linux, FreeBSD, OSX, yotta yotta). And I intended to make it open source from the beginning. But I have to admit, the Win32 code is somewhat 'behind' (though it DOES work last time I tried it). Some of the features are POSIX-only as a result, but the Win32 code should 'get you going' or at least point you in a good direction.

I'd done serial communications via Win32 before, and let me tell you, it's not for the faint at heart. If you don't know what you're doing, the performance is likely to be miserable, and you'll either burn up 100% cpu all of the time, or you'll 'stutter' and either miss data or not get it in a timely manner. It's really not very pretty. I'll leave it at that, and say that it's "solved" in sftardcal.

So it's all ok, I've got it all WORKING (years ago, even) in 'sftardcal'. And, you can build it and run it yourself, and you should be able to communicate to a serial-port device from your console to an application running on your serial device via the serial port on your computer. Yeah, it's such a BASIC function that should be supported MORE, right? Well, it USED to be, but there you go.

There are many built-in features as well as basic serial communication frmo the console, but the boiled down summary is that you can set the baud rate, bits, and so on, set it up to automatically do that 'reset thing' for Arduino devices, or not [depending on the driver, some Linux drivers do it anyway], do xmodem transfers (as long as the device you do the xmodem transfers on understands how to do that), and (best of all) compile in your OWN utilities to do calibration and so forth. Isn't that cool? Well, I thought so when I wrote it. There's ALSO a sample calibration function that's set up to calibrate a device that doesn't really exist, in case you want to see how it's done, something that this utility was NAMED for - 'sft' 'ard'[uino] 'cal'[ibration]. There, now you know.


You can download the source files here: sftardcal on Github


This utility is being offered for FREE with no warranty, guarantee, or even any promise that it will work as claimed and NOT destroy any of your hardware. Use it at your own risk.

(Legal disclaimer, yeah.)


License

More legaleze, the LICENSE is either a BSD-like license, or GPLv2 (or later). See the top of 'sftardcal.c' for the details, which aren't very complicated, really. Pick one of those two licenses if you want to re-distribute this code in either source or binary format, or a derived work (as per the license).



The Documentation

This documentation is SPARSE at best. I only document the features that are working at the moment, and some of these won't work in Win32. In any case, the following documentation exists

 
Command Line sftardcal [options] {serial device}
where '[options]' represents zero or more of the options described below
 and   '{serial device}' is the serial device to use

Note that when no serial device is specified, the default device is used. The default device's name can be seen via the '-h' option, if desired, or by reading the code if you're so inclined
 
Option Description
 
-h Prints the 'help' message via the 'usage()' function. Gives a short description of the possible command line options and also tells you what the default serial device is.
 
-r puts you in 'raw' terminal mode. Use with '-N' to avoid the automatic reset for Arduinos. Use with '-e' to enable local echo of the things that you type. Terminates with CTRL+C.
 
-m sets the terminator to [CR] in 'raw' mode and 'question' mode (default is CRLF)
 
-n sets the terminator to [LF] in 'raw' mode and 'question' mode (default is CRLF)
 
-B assigns the 'baud rate' configuration string
Example: sftardcal -B 9600,n,8,1 /dev/ttyU0
 
-N disables the serial port auto-reset (for Arduino)
 
-F enables hardware flow control (implies -N)
 
-W assigns the reset 'wait' period in seconds (default 5)
 
-d dumps [serial port] debug information
 
-e enables local echo
 
-R forces a factory reset during calibration (must be implemented by YOUR code)
 
-v increases verbosity of debug info sent to stderr
(can be specified multiple times to increase verbosity)
 
-XSfilename
-XRfilename
performs an xmodem transfer
the 'S' or 'R' must immediately precede the file name (no space).
The command 'XSfilename' or 'XRfilename' (followed by \r) is sent to the remote device, followed by the file transfer itself.
This option may not be used with '-q', '-r', or '-R'
Example:  sftardcal -XSmyfile.ext /dev/ttyU0

NOTE: your program on the device must accept the command 'XSfilename' or 'XRfilename' to send/receive files.
 
-c specifies an alternate console for stdin,stdout
This can be useful for using 'sftardcal' to provide a tunnel from a VM running this software.
specifying a port as ':port' assumes localhost:port
Examples:
          sftardcal -c /var/run/tunnel1 /dev/ttyU0
          sftardcal -c some.machine.domain:8001 /dev/ttyU0
 
-l This is a special case version of '-c' that allows you to LISTEN for a TCP connection on a specific TCP port, optionally specifying the 'bind' address (default is all available IPs).
Example:  sftardcal -l my.machine.domain:8001 /dev/ttyU0
 
-q This function specifies a 'question' to send. The response returned on stdout.
Using '-q' implies '-N' to disable serial port auto-reset.
This option may not be used with '-r', '-R', or '-X'
Example:  sftardcal -q "Identify Yourself" -w 3000 /dev/ttyU0
 
-w specifies a wait time (for use with '-q'), in milliseconds. Default is 5000 milliseconds.
 




©2015-2017 by Bob Frazier and Stewart~Frazier Tools, Inc. - all rights reserved
last updated: 02/04/2017

Community projects are generally good, but socialism, in all of its forms, is always evil.