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.

Features

• High-level API access via 2 API functions, XSend() and XReceive()
• Designed to be OS portable for POSIX-compatible, Arduino, and Win32 (Win32 incomplete)
• Written so that it compiles SMALL (for microcontrollers, particularly)
• Doxygen-generated documentation (and I include the doxy files so you can make your own)
  The xmodem_doc sub-directory contains documentation that is 'POSIX' oriented.
  The xmodem_arduino_doc sub-directory contains documentation that is 'ARDUINO' oriented. Yes, there ARE some differences, which is why I made 2 sets of documentation.
• LICENSE via BSD-like or LGPLv2.1 (your choice)

HISTORY

KNOWN ISSUES

• Windows code is incomplete. This will probably be finished in the next release. You are welcome to 'fill in the blanks' and send me what you did, and I'll test it a little more on my end before publishing. Thanks in advance.
• Comparison against programs like 'rz' and 'sz', as well as verification of the actual specs, and proper testing of error recovery under a wide variety of failure conditions, still needs to be done
• Arduino IDEs earlier than 1.0 won't like the 'Arduino.h' file (it doesn't exist). You can fix this by finding the appropriate header files and including THEM instead, or upgrade your IDE to 1.0 or later.

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.

FAQ

• Can I use the Arduino IDE to initiate XMODEM transfer?
  The short answer is, no. You should write an application for the client that can first command your Arduino-based device to go into 'xmodem transfer mode' so that it will call the appropriate function. Then your application would use the same library (compiled for your operating system) and call the appropriate function to actually transfer the file. Alternately you could use a terminal program that is capable of performing XMODEM transfers and type the appropriate command for the Arduino-compatible device.
• Is there a sample client application?
  Yes. If you compile xmodem.c on a POSIX compatible system, and define 'STAND_ALONE', it will build a sample client application that does file transfers. Your Arduino-based device will need to respond to the 'XSEND' and 'XRECEIVE' commands that the client program uses in order to initiate file transfer by calling the appropriate xmodem library function.
• Will the library work in windows?
  I have written a windows application that uses the xmodem library, but the amount of additional coding required to make the serial device work properly is beyond the scope of this FAQ. Suffice it to say it requires 'overlapped I/O' and possible multi-thread coding, synchronization objects, buffering, and so forth. Serial I/O is much more easily accomplished using a POSIX-compatible system. As such, Cygwin and SFU [aka Interix] may be good alternative solutions for windows (SFU is only for windows versions prior to windows 8, requires 'pro' for windows 7)

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.