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.14"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<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="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.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 id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">SdFat
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.14 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Arduino SdFat Library </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Copyright (c) 2011-2019 Bill Greiman This file is part of the SdFat library for SD memory cards.</p>
<p>MIT License</p>
<p>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</p>
<p>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</p>
<p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. <br />
</p>
<h1><a class="anchor" id="Warn"></a>
Warnings for SdFat V2 Alpha/Beta</h1>
<p>This is a development version of SdFat V2 and any feature may change. There are bound to be serious bugs, and stability/compatibility problems. <br />
 Initially this is closer to an alpha test so expect stability problems.</p>
<p>You can help by posting issues for bugs you find. I am doing a great deal of testing but actual applications make the best test cases.</p>
<p>Please try to isolate the bug and post code that demonstrates the bug.</p>
<p>The purpose of this release is to get feedback on features and address compatibility problems.</p>
<p>You should edit <a class="el" href="_sd_fat_config_8h.html" title="configuration definitions ">SdFatConfig.h</a> to select features. <a class="el" href="_sd_fat_config_8h.html" title="configuration definitions ">SdFatConfig.h</a> is suitable for UNO and other small AVR boards.</p>
<h1><a class="anchor" id="Intro"></a>
Introduction</h1>
<p>The Arduino SdFat library supports FAT16, FAT32, and exFAT file systems on Standard SD, SDHC, and SDXC cards.</p>
<p>In SdFat version 1, SdFat and File are the main classes.</p>
<p>In SdFat version 2, SdFat and File are defined by typedefs in terms of the following classes.</p>
<p>The file system classes in the SdFat library are <a class="el" href="class_sd_fat32.html" title="SD file system class for FAT volumes. ">SdFat32</a>, <a class="el" href="class_sd_ex_fat.html" title="SD file system class for exFAT volumes. ">SdExFat</a>, and <a class="el" href="class_sd_fs.html" title="SD file system class for FAT16, FAT32, and exFAT volumes. ">SdFs</a>. <a class="el" href="class_sd_fat32.html" title="SD file system class for FAT volumes. ">SdFat32</a> supports FAT16 and FAT32. <a class="el" href="class_sd_ex_fat.html" title="SD file system class for exFAT volumes. ">SdExFat</a> supports exFAT, <a class="el" href="class_sd_fs.html" title="SD file system class for FAT16, FAT32, and exFAT volumes. ">SdFs</a> supports FAT16, FAT32, and exFAT.</p>
<p>The corresponding file classes are <a class="el" href="class_file32.html" title="FAT16/FAT32 file with Arduino Stream. ">File32</a>, <a class="el" href="class_ex_file.html" title="exFAT file with Arduino Stream. ">ExFile</a>, and <a class="el" href="class_fs_file.html" title="FsBaseFile file with Arduino Stream. ">FsFile</a>.</p>
<p>The types for SdFat and File are defined in <a class="el" href="_sd_fat_config_8h.html" title="configuration definitions ">SdFatConfig.h</a>. This version uses FAT16/FAT32 for small AVR boards and FAT16/FAT32/exFAT for all other boards.</p>
<div class="fragment"><div class="line"><span class="comment">// File types for SdFat, File, SdFile, SdBaseFile, fstream,</span></div><div class="line"><span class="comment">// ifstream, and ofstream.</span></div><div class="line"><span class="comment">//</span></div><div class="line"><span class="comment">// Set SDFAT_FILE_TYPE to:</span></div><div class="line"><span class="comment">// 1 for FAT16/FAT32, 2 for exFAT, 3 for FAT16/FAT32 and exFAT.</span></div><div class="line"><span class="comment">//</span></div><div class="line"><span class="preprocessor">#if defined(__AVR__) &amp;&amp; FLASHEND &lt; 0X8000</span></div><div class="line"><span class="comment">// FAT16/FAT32 for 32K AVR boards.</span></div><div class="line"><span class="preprocessor">#define SDFAT_FILE_TYPE 1</span></div><div class="line"><span class="preprocessor">#else  // defined(__AVR__) &amp;&amp; FLASHEND &lt; 0X8000</span></div><div class="line"><span class="comment">// FAT16/FAT32 and exFAT for all other boards.</span></div><div class="line"><span class="preprocessor">#define SDFAT_FILE_TYPE 3</span></div><div class="line"><span class="preprocessor">#endif  // defined(__AVR__) &amp;&amp; FLASHEND &lt; 0X8000</span></div></div><!-- fragment --><p>It is possible to use option three, support or FAT16/FAT32 and exFat on an Uno or other AVR board with 32KB flash and 2KB SRAM but memory will be very limited.</p>
<p>Uno memory use for a simple data logger is:</p>
<blockquote class="doxtable">
<p>option 1, FAT16/FAT32, 11902 bytes of flash and 855 bytes of SRAM.</p>
<p>option 2, exFAT, 14942 bytes of flash and 895 bytes of SRAM.</p>
<p>option 3, FAT16/FAT32 and exFAT, 21834 bytes of flash and 908 bytes of SRAM. </p>
</blockquote>
<p>Please read documentation under the above classes tab for more information.</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="exFAT"></a>
exFAT Features</h1>
<p>exFAT has many features not available in FAT16/FAT32.</p>
<p>Files larger than 4GiB, 64-bit file size and file position.</p>
<p>Free space allocation performance improved by using a free space bitmap.</p>
<p>Removal of the physical "." and ".." directory entries that appear in FAT16/FAT32 subdirectories.</p>
<p>Better support for large flash pages with boundary alignment offsets for the FAT table and data region.</p>
<p>exFAT files have two separate 64-bit length fields. The DataLength field indicate how much space is allocate to the file. The ValidDataLength field indicates how much actual data has been written to the file.</p>
<p>An exFAT file can be contiguous with pre-allocate clusters and bypass the use of the FAT table. In this case the contiguous flag is set in the directory entry. This allows an entire file to be written as one large multi-block write.</p>
<h1><a class="anchor" id="SDPath"></a>
Paths and Working Directories</h1>
<p>Relative paths in SdFat are resolved in a manner similar to Windows.</p>
<p>Each instance of <a class="el" href="class_sd_fat32.html" title="SD file system class for FAT volumes. ">SdFat32</a>, <a class="el" href="class_sd_ex_fat.html" title="SD file system class for exFAT volumes. ">SdExFat</a>, and <a class="el" href="class_sd_fs.html" title="SD file system class for FAT16, FAT32, and exFAT volumes. ">SdFs</a> has a current directory. <br />
This directory is called the volume working directory, vwd. <br />
Initially this directory is the root directory for the volume.</p>
<p>The volume working directory is changed by calling the chdir(path).</p>
<p>The call sd.chdir("/2014") will change the volume working directory for sd to "/2014", assuming "/2014" exists.</p>
<p>Relative paths for member functions are resolved by starting at the volume working directory.</p>
<p>For example, the call sd.mkdir("April") will create the directory "/2014/April" assuming the volume working directory is "/2014".</p>
<p>There is current working directory, cwd, that is used to resolve paths for file.open() calls.</p>
<p>For a single SD card, the current working directory is always the volume working directory for that card.</p>
<p>For multiple SD cards the current working directory is set to the volume working directory of a card by calling the chvol() member function. The chvol() call is like the Windows &lt;drive letter&gt;: command.</p>
<p>The call sd2.chvol() will set the current working directory to the volume working directory for sd2.</p>
<p>If the volume working directory for sd2 is "/music" the call</p>
<p>file.open("BigBand.wav", O_READ);</p>
<p>will open "/music/BigBand.wav" on sd2.</p>
<h1><a class="anchor" id="Install"></a>
Installation</h1>
<p>You must manually install SdFat by renaming the download folder SdFat and copy the SdFat folder to the Arduino libraries folder in your sketchbook folder.</p>
<p>It will be necessary to unzip and rename the folder if you download a zip file from GitHub.</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 SdFat/src folder.</p>
<p>Here are a few of the key options.</p>
<p>If the symbol ENABLE_DEDICATED_SPI is nonzero, multi-block SD I/O may be used for better performance. The SPI bus may not be shared with other devices in this mode.</p>
<p>The symbol SPI_DRIVER_SELECT is used to select the SPI driver.</p>
<blockquote class="doxtable">
<p>If the symbol SPI_DRIVER_SELECT is:</p>
<p>0 - An optimized custom SPI driver is used if it exists else the standard library driver is used.</p>
<p>1 - The standard library driver is always used.</p>
<p>2 - The software SPI driver is always used. </p>
</blockquote>
<p>To enable SD card CRC checking in SPI mode set USE_SD_CRC nonzero.</p>
<p>See <a class="el" href="_sd_fat_config_8h.html" title="configuration definitions ">SdFatConfig.h</a> for other options.</p>
<h1><a class="anchor" id="Hardware"></a>
Hardware Configuration</h1>
<p>The hardware interface to the SD card should not use a resistor based level shifter. Resistor based level shifters results in signal rise times that are too slow for many newer SD cards.</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 program, SdFormatter.ino, is included in the SdFat/examples/SdFormatter directory. This program 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 SdFormatter example 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="ExampleFiles"></a>
Examples</h1>
<p>A number of examples are provided in the SdFat/examples folder.</p>
<p>To access these examples from the Arduino development environment go to: File -&gt; Examples -&gt; SdFat -&gt; &lt;program 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>AvrAdcLogger - Fast AVR ADC logger using Timer/ADC interrupts.</p>
<p>BackwardCompatibility - Demonstrate SD.h compatibility with SdFat.h.</p>
<p>bench - A read/write benchmark.</p>
<p><a class="el" href="class_buffered_print.html" title="Fast buffered print template. ">BufferedPrint</a> - Demo a buffered print class for AVR loggers.</p>
<p>debug folder - Some of my debug programs - will be remove in the future.</p>
<p>DirectoryFunctions - Use of chdir(), ls(), mkdir(), and rmdir().</p>
<p>examplesV1 folder - Examples from SdFat V1 for compatibility tests.</p>
<p>ExFatFormatter - Produces optimal exFAT format for smaller SD cards.</p>
<p>ExFatLogger - A data-logger optimized for exFAT features.</p>
<p>ExFatUnicodeTest - Test program for Unicode file names.</p>
<p>OpenNext - Open all files in the root dir and print their filename.</p>
<p>ReadCsvFile - Function to read a CSV text file one field at a time.</p>
<p>RtcTimestampTest - Demonstration of timestamps with RTClib.</p>
<p>SdErrorCodes - Produce a list of error codes.</p>
<p>SdFormatter - This program will format an SD, SDHC, or SDXC card.</p>
<p>SdInfo - Initialize an SD card and analyze its structure for trouble shooting.</p>
<p>SoftwareSpi - Demo of limited Software SPI support in SdFat V2.</p>
<p>STM32Test - Example use of two SPI ports on an STM32 board.</p>
<p>TeensyRtcTimestamp - File timestamps for Teensy3.</p>
<p>TeensySdioDemo - Demo of SDIO and SPI modes for the Teensy 3.5/3.6 built-in SD. </p>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Thu May 9 2019 06:51:29 for SdFat by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.14
</small></address>
</body>
</html>