SdFatmainpage.h

00001 /* Arduino SdFat Library
00002  * Copyright (C) 2009 by William Greiman
00003  *  
00004  * This file is part of the Arduino SdFat Library
00005  *  
00006  * This Library is free software: you can redistribute it and/or modify 
00007  * it under the terms of the GNU General Public License as published by 
00008  * the Free Software Foundation, either version 3 of the License, or
00009  * (at your option) any later version.
00010  * 
00011  * This Library is distributed in the hope that it will be useful,
00012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00014  * GNU General Public License for more details.
00015  *
00016  * You should have received a copy of the GNU General Public License
00017  * along with the Arduino SdFat Library.  If not, see
00018  * <http://www.gnu.org/licenses/>.
00019  */
00020 
00021 /**
00022 \mainpage Arduino SdFat Library
00023 <CENTER>Copyright &copy; 2009 by William Greiman
00024 </CENTER>
00025 
00026 \section Intro Introduction
00027 The Arduino SdFat Library is a minimal implementation of FAT16 and FAT32
00028 file systems on SD flash memory cards.  Standard SD and high capacity
00029 SDHC cards are supported.
00030 
00031 The SdFat only supports short 8.3 names.
00032 
00033 The main classes in SdFat are Sd2Card, SdVolume, and SdFile.
00034 
00035 The Sd2Card class supports access to standard SD cards and SDHC cards.  Most
00036 applications will only need to call the Sd2Card::init() member function.
00037 
00038 The SdVolume class supports FAT16 and FAT32 partitions.  Most applications
00039 will only need to call the SdVolume::init() member function.
00040 
00041 The SdFile class provides file access functions such as open(), read(),
00042 remove(), write(), close() and sync(). This class supports access to the root
00043 directory and subdirectories.
00044 
00045 A number of example are provided in the SdFat/examples folder.  These were
00046 developed to test SdFat and illustrate its use.
00047 
00048 SdFat was developed for high speed data recording.  SdFat was used to implement
00049 an audio record/play class, WaveRP, for the Adafruit Wave Shield.  This
00050 application uses special Sd2Card calls to write to contiguous files in raw mode.
00051 These functions reduce write latency so that audio can be recorded with the
00052 small amount of RAM in the Arduino.
00053 
00054 \section SDcard SD\SDHC Cards
00055 
00056 Arduinos access SD cards using the cards SPI protocol.  PCs, Macs, and
00057 most consumer devices use the 4-bit parallel SD protocol.  A card that
00058 functions well on A PC or Mac may not work well on the Arduino.
00059 
00060 Most cards have good SPI read performance but cards vary widely in SPI
00061 write performance.  Write performance is limited by how efficiently the
00062 card manages internal erase/remapping operations.  The Arduino cannot
00063 optimize writes to reduce erase operations because of its limit RAM.
00064 
00065 SanDisk cards generally have good write performance.  They seem to have
00066 more internal RAM buffering than other cards and therefore can limit
00067 the number of flash erase operations that the Arduino forces due to its
00068 limited RAM.
00069 
00070 \section Hardware Hardware Configuration
00071 
00072 SdFat was developed using an
00073 <A HREF = "http://www.adafruit.com/"> Adafruit Industries</A> 
00074 <A HREF = "http://www.ladyada.net/make/waveshield/"> Wave Shield</A>.
00075 
00076 The hardware interface to the SD card should not use a resistor based level
00077 shifter.  SdFat sets the SPI bus frequency to 8 MHz which results in signal
00078 rise times that are too slow for the edge detectors in many newer SD card
00079 controllers when resistor voltage dividers are used.
00080 
00081 The 5 to 3.3 V level shifter for 5 V Arduinos should be IC based like the
00082 74HC4050N based circuit shown in the file SdLevel.png.  The Adafruit Wave Shield
00083 uses a 74AHC125N.  Gravitech sells SD and MicroSD Card Adapters based on the
00084 74LCX245.
00085 
00086 If you are using a resistor based level shifter and are having problems try
00087 setting the SPI bus frequency to 4 MHz.  This can be done by using 
00088 card.init(SPI_HALF_SPEED) to initialize the SD card.
00089 
00090 \section comment Bugs and Comments
00091 
00092 If you wish to report bugs or have comments, send email to fat16lib@sbcglobal.net.
00093 
00094 \section SdFatClass SdFat Usage
00095 
00096 SdFat uses a slightly restricted form of short names.
00097 Only printable ASCII characters are supported. No characters with code point
00098 values greater than 127 are allowed.  Space is not allowed even though space
00099 was allowed in the API of early versions of DOS.
00100 
00101 Short names are limited to 8 characters followed by an optional period (.)
00102 and extension of up to 3 characters.  The characters may be any combination
00103 of letters and digits.  The following special characters are also allowed:
00104 
00105 $ % ' - _ @ ~ ` ! ( ) { } ^ # &
00106 
00107 Short names are always converted to upper case and their original case
00108 value is lost.
00109 
00110 \note
00111   The Arduino Print class uses character
00112 at a time writes so it was necessary to use a \link SdFile::sync() sync() \endlink
00113 function to control when data is written to the SD card.
00114 
00115 \par
00116 An application which writes to a file using \link Print::print() print()\endlink,
00117 \link Print::println() println() \endlink
00118 or \link SdFile::write write() \endlink must call \link SdFile::sync() sync() \endlink
00119 at the appropriate time to force data and directory information to be written
00120 to the SD Card.  Data and directory information are also written to the SD card
00121 when \link SdFile::close() close() \endlink is called.
00122 
00123 \par
00124 Applications must use care calling \link SdFile::sync() sync() \endlink
00125 since 2048 bytes of I/O is required to update file and
00126 directory information.  This includes writing the current data block, reading
00127 the block that contains the directory entry for update, writing the directory
00128 block back and reading back the current data block.
00129 
00130 It is possible to open a file with two or more instances of SdFile.  A file may
00131 be corrupted if data is written to the file by more than one instance of SdFile.
00132 
00133 \section HowTo How to format SD Cards as FAT Volumes
00134 
00135 You should use a freshly formatted SD card for best performance.  FAT
00136 file systems become slower if many files have been created and deleted.
00137 This is because the directory entry for a deleted file is marked as deleted,
00138 but is not deleted.  When a new file is created, these entries must be scanned
00139 before creating the file, a flaw in the FAT design.  Also files can become
00140 fragmented which causes reads and writes to be slower.
00141 
00142 Microsoft operating systems support removable media formatted with a
00143 Master Boot Record, MBR, or formatted as a super floppy with a FAT Boot Sector
00144 in block zero.
00145 
00146 Microsoft operating systems expect MBR formatted removable media
00147 to have only one partition. The first partition should be used.
00148 
00149 Microsoft operating systems do not support partitioning SD flash cards.
00150 If you erase an SD card with a program like KillDisk, Most versions of
00151 Windows will format the card as a super floppy.
00152 
00153 The best way to restore an SD card's format is to use SDFormatter
00154 which can be downloaded from:
00155 
00156 http://www.sdcard.org/consumers/formatter/
00157 
00158 SDFormatter aligns flash erase boundaries with file
00159 system structures which reduces write latency and file system overhead.
00160 
00161 SDFormatter does not have an option for FAT type so it may format
00162 small cards as FAT12.
00163 
00164 After the MBR is restored by SDFormatter you may need to reformat small
00165 cards that have been formatted FAT12 to force the volume type to be FAT16.
00166 
00167 If you reformat the SD card with an OS utility, choose a cluster size that
00168 will result in:
00169 
00170 4084 < CountOfClusters && CountOfClusters < 65525
00171 
00172 The volume will then be FAT16.
00173 
00174 If you are formatting an SD card on OS X or Linux, be sure to use the first
00175 partition. Format this partition with a cluster count in above range.
00176 
00177 \section  References References
00178 
00179 Adafruit Industries:
00180 
00181 http://www.adafruit.com/
00182 
00183 http://www.ladyada.net/make/waveshield/
00184 
00185 The Arduino site:
00186 
00187 http://www.arduino.cc/
00188 
00189 For more information about FAT file systems see:
00190 
00191 http://www.microsoft.com/whdc/system/platform/firmware/fatgen.mspx
00192 
00193 For information about using SD cards as SPI devices see:
00194 
00195 http://www.sdcard.org/developers/tech/sdcard/pls/Simplified_Physical_Layer_Spec.pdf
00196 
00197 The ATmega328 datasheet:
00198 
00199 http://www.atmel.com/dyn/resources/prod_documents/doc8161.pdf
00200  
00201 
00202  */