git.piffa.net Git - arduino/blob - books/pdummies/Libraries/SD/utility/SdFatmainpage.h

   1 /* Arduino SdFat Library
   2  * Copyright (C) 2009 by William Greiman
   3  *
   4  * This file is part of the Arduino SdFat Library
   5  *
   6  * This Library is free software: you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation, either version 3 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This Library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with the Arduino SdFat Library.  If not, see
  18  * <http://www.gnu.org/licenses/>.
  19  */
  20
  21 /**
  22 \mainpage Arduino SdFat Library
  23 <CENTER>Copyright &copy; 2009 by William Greiman
  24 </CENTER>
  25
  26 \section Intro Introduction
  27 The Arduino SdFat Library is a minimal implementation of FAT16 and FAT32
  28 file systems on SD flash memory cards.  Standard SD and high capacity
  29 SDHC cards are supported.
  30
  31 The SdFat only supports short 8.3 names.
  32
  33 The main classes in SdFat are Sd2Card, SdVolume, and SdFile.
  34
  35 The Sd2Card class supports access to standard SD cards and SDHC cards.  Most
  36 applications will only need to call the Sd2Card::init() member function.
  37
  38 The SdVolume class supports FAT16 and FAT32 partitions.  Most applications
  39 will only need to call the SdVolume::init() member function.
  40
  41 The SdFile class provides file access functions such as open(), read(),
  42 remove(), write(), close() and sync(). This class supports access to the root
  43 directory and subdirectories.
  44
  45 A number of example are provided in the SdFat/examples folder.  These were
  46 developed to test SdFat and illustrate its use.
  47
  48 SdFat was developed for high speed data recording.  SdFat was used to implement
  49 an audio record/play class, WaveRP, for the Adafruit Wave Shield.  This
  50 application uses special Sd2Card calls to write to contiguous files in raw mode.
  51 These functions reduce write latency so that audio can be recorded with the
  52 small amount of RAM in the Arduino.
  53
  54 \section SDcard SD\SDHC Cards
  55
  56 Arduinos access SD cards using the cards SPI protocol.  PCs, Macs, and
  57 most consumer devices use the 4-bit parallel SD protocol.  A card that
  58 functions well on A PC or Mac may not work well on the Arduino.
  59
  60 Most cards have good SPI read performance but cards vary widely in SPI
  61 write performance.  Write performance is limited by how efficiently the
  62 card manages internal erase/remapping operations.  The Arduino cannot
  63 optimize writes to reduce erase operations because of its limit RAM.
  64
  65 SanDisk cards generally have good write performance.  They seem to have
  66 more internal RAM buffering than other cards and therefore can limit
  67 the number of flash erase operations that the Arduino forces due to its
  68 limited RAM.
  69
  70 \section Hardware Hardware Configuration
  71
  72 SdFat was developed using an
  73 <A HREF = "http://www.adafruit.com/"> Adafruit Industries</A>
  74 <A HREF = "http://www.ladyada.net/make/waveshield/"> Wave Shield</A>.
  75
  76 The hardware interface to the SD card should not use a resistor based level
  77 shifter.  SdFat sets the SPI bus frequency to 8 MHz which results in signal
  78 rise times that are too slow for the edge detectors in many newer SD card
  79 controllers when resistor voltage dividers are used.
  80
  81 The 5 to 3.3 V level shifter for 5 V Arduinos should be IC based like the
  82 74HC4050N based circuit shown in the file SdLevel.png.  The Adafruit Wave Shield
  83 uses a 74AHC125N.  Gravitech sells SD and MicroSD Card Adapters based on the
  84 74LCX245.
  85
  86 If you are using a resistor based level shifter and are having problems try
  87 setting the SPI bus frequency to 4 MHz.  This can be done by using
  88 card.init(SPI_HALF_SPEED) to initialize the SD card.
  89
  90 \section comment Bugs and Comments
  91
  92 If you wish to report bugs or have comments, send email to fat16lib@sbcglobal.net.
  93
  94 \section SdFatClass SdFat Usage
  95
  96 SdFat uses a slightly restricted form of short names.
  97 Only printable ASCII characters are supported. No characters with code point
  98 values greater than 127 are allowed.  Space is not allowed even though space
  99 was allowed in the API of early versions of DOS.
 100
 101 Short names are limited to 8 characters followed by an optional period (.)
 102 and extension of up to 3 characters.  The characters may be any combination
 103 of letters and digits.  The following special characters are also allowed:
 104
 105 $ % ' - _ @ ~ ` ! ( ) { } ^ # &
 106
 107 Short names are always converted to upper case and their original case
 108 value is lost.
 109
 110 \note
 111   The Arduino Print class uses character
 112 at a time writes so it was necessary to use a \link SdFile::sync() sync() \endlink
 113 function to control when data is written to the SD card.
 114
 115 \par
 116 An application which writes to a file using \link Print::print() print()\endlink,
 117 \link Print::println() println() \endlink
 118 or \link SdFile::write write() \endlink must call \link SdFile::sync() sync() \endlink
 119 at the appropriate time to force data and directory information to be written
 120 to the SD Card.  Data and directory information are also written to the SD card
 121 when \link SdFile::close() close() \endlink is called.
 122
 123 \par
 124 Applications must use care calling \link SdFile::sync() sync() \endlink
 125 since 2048 bytes of I/O is required to update file and
 126 directory information.  This includes writing the current data block, reading
 127 the block that contains the directory entry for update, writing the directory
 128 block back and reading back the current data block.
 129
 130 It is possible to open a file with two or more instances of SdFile.  A file may
 131 be corrupted if data is written to the file by more than one instance of SdFile.
 132
 133 \section HowTo How to format SD Cards as FAT Volumes
 134
 135 You should use a freshly formatted SD card for best performance.  FAT
 136 file systems become slower if many files have been created and deleted.
 137 This is because the directory entry for a deleted file is marked as deleted,
 138 but is not deleted.  When a new file is created, these entries must be scanned
 139 before creating the file, a flaw in the FAT design.  Also files can become
 140 fragmented which causes reads and writes to be slower.
 141
 142 Microsoft operating systems support removable media formatted with a
 143 Master Boot Record, MBR, or formatted as a super floppy with a FAT Boot Sector
 144 in block zero.
 145
 146 Microsoft operating systems expect MBR formatted removable media
 147 to have only one partition. The first partition should be used.
 148
 149 Microsoft operating systems do not support partitioning SD flash cards.
 150 If you erase an SD card with a program like KillDisk, Most versions of
 151 Windows will format the card as a super floppy.
 152
 153 The best way to restore an SD card's format is to use SDFormatter
 154 which can be downloaded from:
 155
 156 http://www.sdcard.org/consumers/formatter/
 157
 158 SDFormatter aligns flash erase boundaries with file
 159 system structures which reduces write latency and file system overhead.
 160
 161 SDFormatter does not have an option for FAT type so it may format
 162 small cards as FAT12.
 163
 164 After the MBR is restored by SDFormatter you may need to reformat small
 165 cards that have been formatted FAT12 to force the volume type to be FAT16.
 166
 167 If you reformat the SD card with an OS utility, choose a cluster size that
 168 will result in:
 169
 170 4084 < CountOfClusters && CountOfClusters < 65525
 171
 172 The volume will then be FAT16.
 173
 174 If you are formatting an SD card on OS X or Linux, be sure to use the first
 175 partition. Format this partition with a cluster count in above range.
 176
 177 \section  References References
 178
 179 Adafruit Industries:
 180
 181 http://www.adafruit.com/
 182
 183 http://www.ladyada.net/make/waveshield/
 184
 185 The Arduino site:
 186
 187 http://www.arduino.cc/
 188
 189 For more information about FAT file systems see:
 190
 191 http://www.microsoft.com/whdc/system/platform/firmware/fatgen.mspx
 192
 193 For information about using SD cards as SPI devices see:
 194
 195 http://www.sdcard.org/developers/tech/sdcard/pls/Simplified_Physical_Layer_Spec.pdf
 196
 197 The ATmega328 datasheet:
 198
 199 http://www.atmel.com/dyn/resources/prod_documents/doc8161.pdf
 200
 201
 202  */