S.F.T. XMODEM Library

The XMODEM protocol has been around for a VERY long time, and there are a LOT of resources out there that will perform XMODEM transfers. Unfortunately it seems, at least to me, that a lot of these are either poorly written, not very portable, difficult to use, encumbered by licenses that I don't necessarily like, or a combination of the above.

As a result, I have written an XMODEM library that is relatively easy to use, reasonably well documented, and dual-licensed under a BSD-like or LGPLv2.1 license, your choice. In short, you can do what you want with it, as long as you don't hold S.F.T. Inc. (or me) responsible for any damages that might occur as a result of the use or abuse of this software (the usual gutless disclaimer).

You can obtain a copy of the code HERE:

    xmodem-1.0.tgz     SHA256:  006a0d4c69eb18ce666209325893cbb686c48b70bacfa7baa7ef7b7c49323c45

You're welcome.

There is a patch available for a specific problem that was reported in which the 'doubled' retry count was failing to time out properly during a failed 'send' operation. If you are experiencing a similar problem, you might want to apply the patch, using a command similar to:

    patch <xmodem.c.patch

from within the directory containing 'xmodem.c'.

If you do not have access to the 'patch' utility you can manually edit line 1199 to use 'TOTAL_ERROR_COUNT' instead of 'TOTAL_ERROR_COUNT * 2'.

Additional Information

I ported this code to the C language (compatible with C++) from a VB 'terminal' program I had written back in 1995, and then tested it using FreeBSD 8.2 and an Arduino clone, programmed via the Arduino 1.0 IDE (available HERE).

Although it has been tested, it has not been THOROUGHLY tested, particularly with respect to handling every possible type of error condition (see 'patch' above). Fortunately I left a lot of the debug code in-place, and the ability to run it as a stand-alone. You will note that the stand-alone code sends 'XSfilename' or 'XRfilename' to 'the other end' to send or receive a file, then calls the high level API functions to perform the actual transfer. I used an Arduino clone board with the SD library and a micro-SD card to move files back and forth. The Arduino code was configured to input a line of text, and then interpret it. 'XR' and 'XS' drove the xmodem transfer. I also had an 'XX' function on the Arduino-compatible device that let me transfer all of the characters to make sure that none were being 'translated' by the console 'tty' device. Since you have the source, you can see how I did it.



2012-09-17Initial (pre)release 1.0
2012-09-19 Minor edit/cleanup, corrected 'ENQ' response to 'EOT', now 'ACK' (now official release 1.0)
Tested satisfactorily using XMODEM transfer from Windows XP's Hyperterminal
Also resolved a linux-related build issue (FreeBSD has extra things that aren't defined for Linux)


Use as an Arduino library

To use the S.F.T. XMODEM Library as an Arduino library, you will need to create a directory called 'libraries' within your sketchbook directory (if you have not already done so). Then, create a directory called 'xmodem' (you cannot have '-' in the directory name or the Arduino IDE will complain) and copy the files xmodem.c (as xmodem.cpp) and xmodem.h (as xmodem.h) into this directory. THEN, when you re-load the Arduino IDE, the libraries SHOULD be available for you to use by adding the line

    #include <xmodem.h>

into your Arduino 'ino' or 'pde' script, and call the appropriate functions.


In any case, enjoy! You might find that it does exactly what you need. Or not. But it's open source. And it's free. And THAT is a good thing.

©2012,2013 by Stewart~Frazier Tools, Inc. - all rights reserved
Last Update: 3/20/2013

Back to S.F.T. Inc. main page