Home

Welcome Arduino Enthusiasts!

I built this sketch in order to be able to interact with an SDCard on an Arduino shield over the Serial interface presented by the Arduino USB port. Using this sketch, one can download/upload/delete/etc. files on an SDCard installed in a suitable Arduino shield without having to take the card out of the shield. The key is in using the old ZModem protocol that was once used on BBS's prior to the Internet age. Thanks to "Pete (El Supremo)" who got this started years ago with a sketch that dumped all files on an Arduino SDCard using ZModem send. And, of course, thanks to the late Chuck Forsberg who might have been happy to know that his work on ZModem still has a useful application for modern microcontrollers.

I hope to improve this document over time based on feedback and interest. For the time being, I wanted to publish this first edition and gauge the response and need. The best way to get started in understanding how to use this sketch might be to watch this video I created that walks through the basic functionality and use:

Arduino SDCard file manager sketch with ZModem

I have tested this sketch with an Arduino Mega 2560 R3 interfacing with Windows 10 using Hyperterminal, Syncterm and TeraTerm. All of them seem to work, though their crash recovery (partial file transfer restart) behaviours vary. Syncterm kicks out a couple of non-fatal errors at the beginning of sending a file to the Arduino, but appears to always recover and complete the transfer successfully.

As of version 2.1, this sketch should operate on boards with 30K of available flash and 2K of RAM, so Uno, Nano, etc. I did a large scale code clean-up, reduced variable sizes where they were unnecessarily large, put in some tricky sharing of global variables previously unshared between sz and rz, and made some very creative use of the send/receive buffer in order to make this happen. I don't actually have such a board to test it on, so it is still unknown if it will truly work. Check out zmodem_config.h for a few ways to cut out functionality you might not need and slim the sketch down even further.

The sketch relies on taking over the Arduino Serial interface (and demands a lot of memory) so I decided to release it as a sketch rather than a library. The idea is that you upload this sketch to your Arduino when you need to transfer files, do what you like with the files on the Arduino's SDCard, then re-upload whatever sketch normally runs on your Arduino.

Before getting started, take a look at zmodem_config.h. If you are using a SparkFun MP3 Shield as your SDCard interface, you need to uncomment the SFMP3_SHIELD macro in that file or the SDCard will misbehave. Also, if you are using a faster Arduino board than the Mega 2560 R3 (16mhz) or you are only planning to transfer files from your Arduino to your computer, you might want to try cranking up the baud rate. Even after some pretty significant optimizations to the original code, I was only able to send files to the Mega 2560 R3 at up to 57600 baud error free.

Available commands are displayed when the terminal application connects to the Arduino:

HELP - Print this list of commands
DIR - List files in current working directory - alternate LS
PWD - Print current working directory
CD - Change current working directory
DEL file - Delete file - alternate RM
MD dir - Create dir - alternate MKDIR
RD dir - Delete dir - alternate RMDIR
SZ file - Send file from Arduino to terminal (* = all files)
RZ - Receive a file from terminal to Arduino (Hyperterminal sends this
`` `` `` ``automatically when you select Transfer->Send File...)

Most of those are borrowed from DOS/shell functionality and hopefully do not need further explanation.

"SZ file" sends file from the Arduino to the terminal, * for file means all files in the current working directory. There should be no need to start the download in the terminal application manually, all applications that I tested recognized the ZModem start sequence from the Arduino and started the download automatically.

RZ should not need to be typed manually as all the terminal applications that I tested sent "RZ\r" after selecting a file to send from the file transfer menu option and prior to beginning the ZModem transfer.

I added "crash recovery" to both SZ and RZ; that is to say, a file transfer can be continued if it is interrupted part way through. I am not yet sure how useful that will be given that the interface is on a closed cable and not an old style modem with a carrier that can drop, but if you accidentally pull your USB cable in the middle of a large transfer maybe it will be a welcome feature. One use case I can think of for this feature is if you have a log file on your Arduino SDCard that constantly grows over time and you just want to refresh the tail end to your computer - just SZ the log file and the transfer will continue at the point where you last downloaded the log.

The code could use some more cleanup to completely dump the defunct code from long bygone platforms. Regardless, I'd rather publish this early in hopes that it is useful rather than waiting until the code is pristine which may never be the case.

I hope you find the sketch useful for your Arduino application!