This guide explains the SD card features and functions. There are no great variations in this library for our new product lines Waspmote v15 and Plug & Sense! v15, released on October 2016.
WaspSD.h ; WaspSD.cpp ;
Other utilities inside the sd_utilities subdirectory: bufstream.h, ostream.cpp, SdBaseFile.h, SdFile.cpp, SdSpi.h , ios.h, ostream.h, SdFatConfig.h, SdFile.h, SdStream.cpp , iostream.h, Sd2Card.cpp, SdFat.cpp, SdInfo.h, SdStream.h , istream.cpp, Sd2Card.h, SdFat.h, SdSpiArduino.cpp, SdVolume.cpp , istream.h, SdBaseFile.cpp, SdFatStructs.h, SdSpiAVR.cpp, SdVolume.h
To start using Waspmote SD library, an object from class ‘WaspSD’ must be created. This object, called ‘SD’, is created inside Waspmote SD library and it is public to all libraries. It is used through the guide to show how Waspmote SD library works.
When creating this constructor, no variables are initialized by default.
A flag to indicate if there have been any problem during execution of a function has been created. This flag shows the state of the SD card during initialization and operation. Possible values are:
• 0 : nothing failed, all processes have been executed properly. • 1 : no SD card in the slot. • 2 : initialization failed. • 4 : volume partition failed. • 8 : root failed. • 16 : truncated data. Data length is bigger than buffer length, so data will be truncated to fit the buffer. • 32 : error when opening a file. • 64 : error when creating a file. • 128 : error when creating a directory. • 256 : error when writing to a file.
When executing some functions, a string is returned explaining the state of SD card. Possible messages are:
• “no SD” : SD has not been found in the card slot • “Invalid filename”: An invalid name for a file or a directory. It must respect the “8.3 filename” format (also called “short filename” or “SFN”)
Due to memory restrictions, a buffer has been created to limit the length of the data managed by Waspmote API libraries when working with SD cards. Buffer size has been set to 256Bytes due to it is a sufficient value to manage strings and it occupies little memory.
This limit must be considered when developing applications, using the flag previously explained to know when data has been truncated. Obviously this does not mean you can handle 256B only, but you have to make writings and readings of this size.
When formatting the SD card before starting using Waspmote, there are some considerations to have in mind. The most important matter to know before formatting an SD card is setting the right size of the allocation tables to address the card properly. Depending on the SD card used FAT16 (2 GB) or FAT32 (8 GB or more) will be needed.
An 8.3 filename (also called a short filename or SFN) is a filename convention which is followed by the SD card library. 8.3 filenames have at most eight characters, optionally followed by a "." character and a filename extension of at most three characters.
Only upper-case letters A–Z are valid. When using lower-case letters a-z, these are converted to upper-case letter.
Besides, illegal characters for directories and filenames include the following: | < > ^ + = ? / [ ] ; , * \ " \ \
Example of valid and invalid filenames:
FILE.TXT → valid FILENAME → valid FILENAME.TXT → valid FOLDER → valid SUBFOLDER → invalid (more than 8 characters) FILENAME1.TXT → invalid (more than 8 characters before '.') FILENAME.AAAA → invalid (more than 3 characters after '.') file.txt → valid (but it will be interpreted as FILE.TXT)