Introduction

There are many SD card models. Any of them has defective blocks, which are ignored when using th Waspmote’s SD library. However, when using OTA, those SD blocks cannot be avoided, so that the execution could crash. Libelium implements a special process to ensure the SD cards we provide will work fine with OTA. The only SD cards that Libelium can assure that work correctly with Waspmote are the SD cards we distribute officially.

Make sure Waspmote is switched off before inserting or removing the SD card. Otherwise, the SD card could be damaged.

Waspmote must not be switched off or reseted while there are ongoing read or write operations in the SD card. Otherwise, the SD card could be damaged and data could be lost. If you suspect that there may be some ongoing SD operations, wait a while until they are completed.

you can use one programmable LED to signal when the SD card is being processed.

Introduction

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.

Anyway, if you are using previous versions of our products, please use the corresponding guides, available on our Development website.

You can get more information about the generation change on the document “New generation of Libelium product lines”.

Waspmote libraries

Waspmote SD files

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

Constructor

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.

Flag

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.

Error messages

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”)

Buffer

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.

Formatting SD card

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.

Short filename format

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)