In this tutorial, I'll show you how to write data to an SD or SDHC card with the Propeller. This builds on my other tutorials which you can find here.
The multi-core Propeller chip has developed to the point where there are literally hundreds of ready-to-use objects (code) to communicate data collection devices of all types. The Propeller can easily accept data from everything from common PC keyboards to more complex items like that of a GPS module. Most of this code has excellent demonstration code usually displaying basic data on a screen or serial terminal. This works well for quickly creating programs which for immediate user interaction, but what if you need to collect the data when no one is around? Remember the old riddle, "If a tree falls in the forest does it make a sound"? Thankfully there is an easy way to collect data from the variety of Propeller devices and log that information to a Secure Digital (SD) card.
On the surface, reading and writing data to and from an SD card seems like a complex problem, but in reality there is another of those ready-to-use objects which handle all of the hard work in the background. This article provides the missing documentation which will have you recording data which will be completely compatible with a personal computer.
Connecting the hardware
If you're using a Propeller Platform USB, a microSD card slot is already connected on pin 0 through pin 3. Otherwise, you can use an SD card breakout board. There are several SD breakout boards which work fine, Parallax makes a nice one, so does Gadget Gangster. Don’t be overwhelmed by the number of connections that many of these SD adapter boards have, we’ll only need four I/O connections, along with power and ground.
When connecting the adapter to the Propeller, look for the following connections: DO, CLK (sometimes called SCLK), DI, and CS. These abbreviations are: Data Output, Synchronous Clock Input, Data Input, and Chip Select. Don’t worry about trying to commit these to memory. Most programmers simply refer to them in shorthand. Remember to connect the 3.3v and ground connections as well. You can actually use any four Propeller I/O pins you like for this, but generally I will connect them in the order below. This is also how the Propeller Platform USB is connected:
DO=Propeller I/O 0
CLK=Propeller I/O 1
DI=Propeller I/O 2
CS=Propeller I/O 3
Obtaining the software:
Remember when I mentioned that the Propeller has hundreds of ready-to-use "objects"? Parallax maintains a repository of code call the OBEX, or Object Exchange where both Parallax engineers and users alike share their code under an MIT license which makes the software usable for any project, both hobby level and commercial products. The software we’ll use with our Propeller connected SD card. Download the "FAT16 routines with secure digital layer" written by Tomas Rokicki. Extract the zip file to a folder. Don’t worry about the number of files. We’ll only actually use a couple of the spin files for our purposes. If you save the work we’ll be doing to this folder, the Propeller Tool will automatically sort things out.
Getting started:
Now that you have all the requirements in place, half of the battle is already won. Let’s start with a simple demo. We will write some data to a text file, and monitor the results using the Parallax Serial Terminal (PST). The Parallax Serial Terminal program is located in the same folder the Propeller Tool was installed. The only information we’ll need for PST is the COM port the Propeller plugged into. This information can be obtained by simply launching the Propeller Tool and pressing F7 which the Propeller is connected and switched on. Simply set PST to use the same port from its pull down and minimize it to the bottom of the screen.
Let’s take a quick look at the first program (mount.spin), which is a simple test program which will attempt to find and mount the SD card. It will report the results back to PST, and is an excellent starting point to determine that both your hardware connections are correct and that your card is working with the Propeller. I’ve left plenty of code comments so that you can follow along.
Adjust the DO, CLK, DI, and CS lines to match the hardware connections to the Propeller. Insert your SD card, and power on your Propeller. You’ll want to have the PST program running at the bottom of the screen so that you can jump to it quickly. Press F10 to send this code to the Propeller. Once it has finished, click on PST from the bottom of your screen and press the enable button. I’ve added a four second delay to give you plenty of time to navigate. If you see the words, "SD was card found and mounted fine." Congratulations! Your hardware is working fine and we can move unto the more interesting aspects of writing information to the card itself.
Actually writing data to the card:
Let us take things a step further this time by writing some information to the card. The FSRW software we are using supports FAT16 which is compatible with your personal computer. We will write a simple text file which can be opened with NOTEPAD or your word processor. This time we’ll insert a few lines of code into your existing program to accomplish this task. The source code for this program is write.spin.
Notice that we only added the following three lines of code:
sdfat.popen(string("test.txt"),"w")
sdfat.pputs(string("Sending information to an SD card is easy!", 13,10 ))
sdfat.pclose
The .popen method sets up a new file called "test.txt" for writing.
The .pputs method writes a line of information to the file.
The .pclose method finishes and closes the file properly.
Run this program, monitoring the results again with PST. This time, take the card out and insert it into the SD adapter slot on your personal computer. You should have a new file, called TEST.TXT which can be opened with NOTEPAD.
We could have inserted as many .pputs lines as needed to write multiple lines to our file. Writing data is easy isn’t it? If your program is recording simple text information, outputting each line to a notepad compatible file is pretty easy going, but what if you want to chart your information? We can make a few adjustments to our program which will make it compatible with a spreadsheet by simply using commas to separate our data.
Consider the following example (writecsv.spin):
sdfat.popen(string("test.csv"),"w")
sdfat.pputs(string("1,2,3,4,5", 13,10 ))
sdfat.pclose
Again, I’ve only made a couple adjustments to our code. The first thing I’ve done is change the name of the file written to a .csv extension. The file is still text, but this will allow spreadsheet programs like Microsoft Excel to quickly understand what I’m doing. The second change is that I separated my actual information using commas, which a spreadsheet will import as "Comma Delimited Data" and will magically place each item is its own field.
Run the program again. This time open the test.csv file you have created with your spreadsheet program. Spreadsheet programs like Excel and Google Documents recognize the .csv extension and will handle it properly. It doesn’t take much imagination to see how the Propeller can collect information from various devices, logging this information to the SD card for analysis or even charting.
Putting it all together:
Until now, we have been simply creating our data inside our program. This time let’s collect some data from Parallax Serial Terminal to write to the card. I’ve added a few more lines which prompt for input, then write that information to a file called, input.txt.
Our information could have come from a GPS device, or a sensor. I only used the PST interface only because it is already there.
Logging data from any device is easy! In a coming tutorial we’ll look at the flip side of reading information from SD and using it to influence our program.
Get out there and do some data logging!