visus
/
teensy-sdfat


			
				
					
						
						
							
							<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.8"/>
<title>SdFat: Arduino SdFat Library</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">SdFat
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.8 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li class="current"><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="annotated.html"><span>Classes</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
    </ul>
  </div>
</div><!-- top -->
<div class="header">
  <div class="headertitle">
<div class="title">Arduino SdFat Library </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><center>Copyright &copy; 2012, 2013, 2014 by William Greiman </center><h1><a class="anchor" id="Intro"></a>
Introduction</h1>
<p>The Arduino SdFat Library is a minimal implementation of FAT16 and FAT32 file systems on SD flash memory cards. Standard SD and high capacity SDHC cards are supported.</p>
<p>Experimental support for FAT12 can be enabled by setting FAT12_SUPPORT nonzero in <a class="el" href="_sd_fat_config_8h.html" title="configuration definitions ">SdFatConfig.h</a>.</p>
<p>The SdFat library only supports short 8.3 names.</p>
<p>The main classes in SdFat are <a class="el" href="class_sd_fat.html" title="Integration class for the SdFat library. ">SdFat</a>, <a class="el" href="class_sd_base_file.html" title="Base class for SdFile with Print and C++ streams. ">SdBaseFile</a>, <a class="el" href="class_sd_file.html" title="SdBaseFile with Arduino Stream. ">SdFile</a>, <a class="el" href="class_file.html" title="Arduino SD.h style File API. ">File</a>, <a class="el" href="class_stdio_stream.html" title="StdioStream implements a minimal stdio stream. ">StdioStream</a>, <a class="el" href="classfstream.html">fstream</a>, <a class="el" href="classifstream.html">ifstream</a>, and <a class="el" href="classofstream.html">ofstream</a>.</p>
<p>The <a class="el" href="class_sd_fat.html" title="Integration class for the SdFat library. ">SdFat</a> class maintains a FAT volume, a current working directory, and simplifies initialization of other classes.</p>
<p>The <a class="el" href="class_sd_base_file.html" title="Base class for SdFile with Print and C++ streams. ">SdBaseFile</a> class provides basic file access functions such as open(), binary read(), binary write(), close(), remove(), and sync(). <a class="el" href="class_sd_base_file.html" title="Base class for SdFile with Print and C++ streams. ">SdBaseFile</a> is the smallest file class.</p>
<p>The <a class="el" href="class_sd_file.html" title="SdBaseFile with Arduino Stream. ">SdFile</a> class has all the <a class="el" href="class_sd_base_file.html" title="Base class for SdFile with Print and C++ streams. ">SdBaseFile</a> class functions plus the Arduino Print class functions.</p>
<p>The <a class="el" href="class_file.html" title="Arduino SD.h style File API. ">File</a> class has all the <a class="el" href="class_sd_base_file.html" title="Base class for SdFile with Print and C++ streams. ">SdBaseFile</a> functions plus the functions in the Arduino SD.h <a class="el" href="class_file.html" title="Arduino SD.h style File API. ">File</a> class. This provides compatibility with the Arduino SD.h library.</p>
<p>The <a class="el" href="class_stdio_stream.html" title="StdioStream implements a minimal stdio stream. ">StdioStream</a> class implements functions similar to Linux/Unix standard buffered input/output.</p>
<p>The <a class="el" href="classfstream.html">fstream</a> class implements C++ iostreams for both reading and writing text files.</p>
<p>The <a class="el" href="classifstream.html">ifstream</a> class implements C++ iostreams for reading text files.</p>
<p>The <a class="el" href="classofstream.html">ofstream</a> class implements C++ iostreams for writing text files.</p>
<p>The classes <a class="el" href="classibufstream.html">ibufstream</a> and <a class="el" href="classobufstream.html">obufstream</a> format and parse character strings in memory buffers.</p>
<p>the classes <a class="el" href="class_arduino_in_stream.html" title="Input stream for Arduino Stream objects. ">ArduinoInStream</a> and <a class="el" href="class_arduino_out_stream.html" title="Output stream for Arduino Print objects. ">ArduinoOutStream</a> provide iostream functions for Serial, LiquidCrystal, and other devices.</p>
<p>A number of example are provided in the SdFat/examples folder. These were developed to test SdFat and illustrate its use.</p>
<h1><a class="anchor" id="Install"></a>
Installation</h1>
<p>You must manually install <a class="el" href="class_sd_fat.html" title="Integration class for the SdFat library. ">SdFat</a> by copying the <a class="el" href="class_sd_fat.html" title="Integration class for the SdFat library. ">SdFat</a> folder from the download package to the Arduino libraries folder in you sketch book.</p>
<p>See the Manual installation section of this guide.</p>
<p><a href="http://arduino.cc/en/Guide/Libraries">http://arduino.cc/en/Guide/Libraries</a></p>
<h1><a class="anchor" id="SDconfig"></a>
SdFat Configuration</h1>
<p>Several configuration options may be changed by editing the <a class="el" href="_sd_fat_config_8h.html" title="configuration definitions ">SdFatConfig.h</a> file in the <a class="el" href="class_sd_fat.html" title="Integration class for the SdFat library. ">SdFat</a> folder.</p>
<p>Set SD_FILE_USES_STREAM nonzero to use Stream instead of Print for <a class="el" href="class_sd_file.html" title="SdBaseFile with Arduino Stream. ">SdFile</a>. Using Stream will use more flash.</p>
<p>To enable SD card CRC checking set USE_SD_CRC nonzero.</p>
<p>To use multiple SD cards set USE_MULTIPLE_CARDS nonzero.</p>
<p>Set FAT12_SUPPORT nonzero to enable use of FAT12 volumes. FAT12 has not been well tested and requires additional flash.</p>
<p>Set USE_ARDUINO_SPI_LIBRARY nonzero to force use of Arduino Standard SPI library. This will override native and software SPI for all boards.</p>
<p>Use of software SPI can be enabled for selected boards by setting the symbols AVR_SOFT_SPI, DUE_SOFT_SPI, LEONARDO_SOFT_SPI, MEGA_SOFT_SPI, and TEENSY3_SOFT_SPI.</p>
<p>Set ENABLE_SPI_TRANSACTION nonzero to enable the SPI transaction feature of the standard Arduino SPI library. You must include SPI.h in your sketches when ENABLE_SPI_TRANSACTION is nonzero.</p>
<p>Set ENABLE_SPI_YIELD nonzero to enable release of the SPI bus during SD card busy waits.</p>
<h1><a class="anchor" id="SDcard"></a>
SD\SDHC Cards</h1>
<p>Arduinos access SD cards using the cards SPI protocol. PCs, Macs, and most consumer devices use the 4-bit parallel SD protocol. A card that functions well on A PC or Mac may not work well on the Arduino.</p>
<p>Most cards have good SPI read performance but cards vary widely in SPI write performance. Write performance is limited by how efficiently the card manages internal erase/remapping operations. The Arduino cannot optimize writes to reduce erase operations because of its limit RAM.</p>
<p>SanDisk cards generally have good write performance. They seem to have more internal RAM buffering than other cards and therefore can limit the number of flash erase operations that the Arduino forces due to its limited RAM.</p>
<h1><a class="anchor" id="Hardware"></a>
Hardware Configuration</h1>
<p>SdFat was developed using an <a href="http://www.adafruit.com/">Adafruit Industries</a> Data Logging Shield.</p>
<p>The hardware interface to the SD card should not use a resistor based level shifter. SdFat sets the SPI bus frequency to 8 MHz which results in signal rise times that are too slow for the edge detectors in many newer SD card controllers when resistor voltage dividers are used.</p>
<p>The 5 to 3.3 V level shifter for 5 V Arduinos should be IC based like the 74HC4050N based circuit shown in the file SdLevel.png. The Adafruit Wave Shield uses a 74AHC125N. Gravitech sells SD and MicroSD Card Adapters based on the 74LCX245.</p>
<p>If you are using a resistor based level shifter and are having problems try setting the SPI bus frequency to 4 MHz. This can be done by using card.init(SPI_HALF_SPEED) to initialize the SD card.</p>
<h1><a class="anchor" id="comment"></a>
Bugs and Comments</h1>
<p>If you wish to report bugs or have comments, send email to <a href="#" onclick="location.href='mai'+'lto:'+'fat'+'16'+'lib'+'@s'+'bcg'+'lo'+'bal'+'.n'+'et'; return false;">fat16<span style="display: none;">.nosp@m.</span>lib@<span style="display: none;">.nosp@m.</span>sbcgl<span style="display: none;">.nosp@m.</span>obal<span style="display: none;">.nosp@m.</span>.net</a>.</p>
<h1><a class="anchor" id="SdFatClass"></a>
SdFat Usage</h1>
<p>SdFat uses a slightly restricted form of short names. Short names are limited to 8 characters followed by an optional period (.) and extension of up to 3 characters. The characters may be any combination of letters and digits. The following special characters are also allowed:</p>
<p>$ % ' - _ @ ~ ` ! ( ) { } ^ # &amp;</p>
<p>Short names are always converted to upper case and their original case value is lost.</p>
<p>An application which writes to a file using print(), println() or <a class="el" href="class_sd_file.html#a67267a4b63d03a16e099195935613006">write() </a> must call <a class="el" href="class_sd_base_file.html#a292247972772be832f2c6ea166f4049a">sync() </a> at the appropriate time to force data and directory information to be written to the SD Card. Data and directory information are also written to the SD card when <a class="el" href="class_sd_base_file.html#a17f7e949aa0f80d89782d8e31f5edc15">close() </a> is called.</p>
<p>Applications must use care calling <a class="el" href="class_sd_base_file.html#a292247972772be832f2c6ea166f4049a">sync() </a> since 2048 bytes of I/O is required to update file and directory information. This includes writing the current data block, reading the block that contains the directory entry for update, writing the directory block back and reading back the current data block.</p>
<p>It is possible to open a file with two or more instances of a file object. A file may be corrupted if data is written to the file by more than one instance of a file object.</p>
<h1><a class="anchor" id="HowTo"></a>
How to format SD Cards as FAT Volumes</h1>
<p>The best way to restore an SD card's format on a PC or Mac is to use SDFormatter which can be downloaded from:</p>
<p><a href="http://www.sdcard.org/downloads">http://www.sdcard.org/downloads</a></p>
<p>A formatter sketch, SdFormatter.ino, is included in the SdFat/examples/SdFormatter directory. This sketch attempts to emulate SD Association's SDFormatter.</p>
<p>SDFormatter aligns flash erase boundaries with file system structures which reduces write latency and file system overhead.</p>
<p>The PC/Mac SDFormatter does not have an option for FAT type so it may format very small cards as FAT12. Use the <a class="el" href="class_sd_fat.html" title="Integration class for the SdFat library. ">SdFat</a> formatter to force FAT16 formatting of small cards.</p>
<p>Do not format the SD card with an OS utility, OS utilities do not format SD cards in conformance with the SD standard.</p>
<p>You should use a freshly formatted SD card for best performance. FAT file systems become slower if many files have been created and deleted. This is because the directory entry for a deleted file is marked as deleted, but is not deleted. When a new file is created, these entries must be scanned before creating the file. Also files can become fragmented which causes reads and writes to be slower.</p>
<h1><a class="anchor" id="ExampleFilder"></a>
Examples</h1>
<p>A number of examples are provided in the SdFat/examples folder. See the html documentation for a list.</p>
<p>To access these examples from the Arduino development environment go to: File -&gt; Examples -&gt; SdFat -&gt; &lt;Sketch Name&gt;</p>
<p>Compile, upload to your Arduino and click on Serial Monitor to run the example.</p>
<p>Here is a list:</p>
<p>AnalogBinLogger - Fast AVR ADC logger - see the AnalogBinLoggerExtras folder.</p>
<p>bench - A read/write benchmark.</p>
<p>cin_cout - Demo of <a class="el" href="class_arduino_in_stream.html" title="Input stream for Arduino Stream objects. ">ArduinoInStream</a> and <a class="el" href="class_arduino_out_stream.html" title="Output stream for Arduino Print objects. ">ArduinoOutStream</a>.</p>
<p>dataLogger - A simple modifiable data logger.</p>
<p>directoryFunctions - Demo of chdir(), ls(), mkdir(), and rmdir().</p>
<p>fgets - Demo of the fgets read line/string function.</p>
<p>formating - Print a table with various formatting options.</p>
<p>getline - Example of getline from section 27.7.1.3 of the C++ standard.</p>
<p>LowLatencyLogger - A modifiable data logger for higher data rates.</p>
<p>OpenNext - Open all files in the root dir and print their filename.</p>
<p>PrintBenchmark - A simple benchmark for printing to a text file.</p>
<p>QuickStart - A sketch to quickly test your SD card and SD shield/module.</p>
<p>RawWrite - A test of raw write functions for contiguous files.</p>
<p>readCSV - Read a comma-separated value file using iostream extractors.</p>
<p>ReadWriteSdFat - <a class="el" href="class_sd_fat.html" title="Integration class for the SdFat library. ">SdFat</a> version of Arduino SD ReadWrite example.</p>
<p>rename - A demo of SdFat::rename(old, new) and SdFile::rename(dirFile, newPath).</p>
<p>SdFormatter - This sketch will format an SD or SDHC card.</p>
<p>SdInfo - Initialize an SD card and analyze its structure for trouble shooting.</p>
<p>StdioBench - Demo and test of stdio style stream.</p>
<p>StreamParseInt - Simple demo of parseInt() Stream member function.</p>
<p>StressTest - Create and write files until the SD is full.</p>
<p>Timestamp - Sets file create, modify, and access timestamps.</p>
<p>TwoCards - Example using two SD cards. </p>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Sat Oct 25 2014 07:56:23 for SdFat by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.8
</small></address>
</body>
</html>