Main

Référence : Langage Arduino : [ Mini | Standard | Etendue | Maxi ] Librairies : [ Vue d'ensemble | Synthèse ] Infos : [ Comparaison | Changements ]

Librairie SdFatLib pour carte SD du module Ethernet (hors-référence)


Description

La librairie SdFatLib est une librairie qui permet l'utilisation d'une carte mémoire SD avec le module Ethernet Arduino qui comporte un emplacement pour carte microSD.

Cette librairie est essentielle pour permettre du stockage de données en grande quantité avec une carte Arduino ( les cartes 2GB sont supportées).

Liens de référence :

Pour plus de détails sur le protocole SPI, voir :

Pour plus de détails sur les cartes mémoires SD, voir :

Les fonctions de la librairie SdFatLib

Constructeurs

  • Sd2Card card; : crée un objet Sd2Card (carte SD)
  • SdVolume volume; : crée un objet SdVolume (volume FAT..)
  • SdFile root; : crée un objet SdFile pour le répertoire root
  • SdFile file; : crée un objet SdFile = un fichier

Types prédéfinis (cf SdInfo.h)

  • cid_t : structure comportant information sur la carte SD (cf SdInfo.h)
  • csd_t : structure donnant accès à registre interne de la carte SD (cf SdInfo.h)
  • part_t : structure donnant accès à la table de partition de la carte SD (cf FatStruct.h)

Les fonctions de l'objet Sd2Card

Initialisation

Et aussi :

  • uint8_t erase(uint32_t firstBlock, uint32_t lastBlock);
  • uint8_t eraseSingleBlockEnable(void);
  • uint8_t setSckRate(uint8_t sckRateID);

Informations sur la carte

  • cardSize (void): renvoie le nombre de blocs de 512 octets.
  • type (void) : Renvoie une valeur correspondant au type de carte utilisée
  • readCID(cid_t* cid) : lit le répertoire CID de la carte qui contient des informations sur le constructeur, le nom de la carte, numéro de série, etc...

Et aussi :

  • uint8_t readCSD(csd_t* csd) - Read a cards CSD register. The CSD contains Card-Specific Data that provides information regarding access to the card's contents.

Gestion erreurs

  • uint8_t errorCode(void)
  • uint8_t errorData(void)

Lecture

  • uint8_t partialBlockRead(void)
  • uint8_t readBlock(uint32_t block, uint8_t* dst);
  • uint8_t readData(uint32_t block,uint16_t offset, uint16_t count, uint8_t* dst);
  • void readEnd(void);

Ecriture

  • uint8_t writeBlock(uint32_t blockNumber, const uint8_t* src);
  • uint8_t writeData(const uint8_t* src);
  • uint8_t writeStart(uint32_t blockNumber, uint32_t eraseCount);
  • uint8_t writeStop(void);

Les fonctions de l'objet SdVolume

Initialisation

  • init() : initialise le volume.

Et aussi :

  • static uint8_t* cacheClear(void) : Clear the cache and returns a pointer to the cache. Used by the WaveRP recorder to do raw write to the SD card. Not for normal apps.

Informations sur le volume

  • uint8_t blocksPerCluster(void) : return The volume's cluster size in blocks.
  • uint32_t blocksPerFat(void) : return The number of blocks in one FAT.
  • uint32_t clusterCount(void) : return The total number of clusters in the volume.
  • uint8_t clusterSizeShift(void) : return The shift count required to multiply by blocksPerCluster.
  • uint32_t dataStartBlock(void) : return The logical block number for the start of file data.
  • uint8_t fatCount(void) : return The number of FAT structures on the volume.
  • uint32_t fatStartBlock(void) : return The logical block number for the start of the first FAT.
  • uint8_t fatType(void) return The FAT type of the volume. Values are 12, 16 or 32.
  • uint32_t rootDirEntryCount(void) : return The number of entries in the root directory for FAT16 volumes.
  • uint32_t rootDirStart(void) : return The logical block number for the start of the root directory on FAT16 volumes or the first cluster number on FAT32 volumes.
  • static Sd2Card* sdCard(void) : return a pointer to the Sd2Card object for this volume

Les fonctions de l'objet SdFile

Fonctions de création/ouverture/fermeture de fichier

  • open(SdFile* dirFile, uint16_t index, uint8_t oflag) : Ouvre / crée un fichier en fixant les conditions d'accès (lecture, écriture ou les 2).
  • close() : ferme le fichier ou le répertoire
  • isOpen() : Renvoie la valeur VRAI si un fichier ou un répertoire est ouvert

Et aussi :

  • uint8_t openRoot(SdVolume* vol);

Fonctions d'écriture de fichier

  • print() et println() : L'objet SdFile supporte également les fonctions arduino print() et println() ce qui rend l'écriture dans un fichier aussi simple que l'écriture dans le Terminal série !

Et aussi :

  • static void printDirName(const dir_t& dir, uint8_t width);
  • static void printFatDate(uint16_t fatDate);
  • static void printFatTime(uint16_t fatTime);
  • static void printTwoDigits(uint8_t v);
  • void write(uint8_t b);
  • int16_t write(const void* buf, uint16_t nbyte);
  • void write(const char* str);
  • void write_P(PGM_P str);
  • void writeln_P(PGM_P str);

Fonctions de lecture de fichier

  • Read() : Lit l'octet suivant d'un fichier. Renvoie la valeur lue sous forme d'un int.

Et aussi :

  • void setUnbufferedRead(void) : Use unbuffered reads to access this file. Used with Wave Shield ISR. Used with Sd2Card::partialBlockRead() in WaveRP. Not recommended for normal applications.
  • void clearUnbufferedRead(void)
  • uint8_t unbufferedRead(void) \return Unbuffered read flag.

Fonctions d'effacement

  • truncate(longueur) : réduit la taille du fichier à la longueur indiquée. Valeur 0 efface le fichier.

Et aussi :

  • static uint8_t remove(SdFile* dirFile, const char* fileName);
  • uint8_t remove(void); Efface un fichier ou un répertoire

Fonctions d'information sur le fichier

  • fileSize() : renvoie le nombre d'octets d'un fichier ou d'un répertoire

Et aussi :

  • uint32_t dirBlock(void) : return Address of the block that contains this file's directory.
  • uint8_t dirEntry(dir_t* dir);
  • uint8_t dirIndex(void) return Index of this file's directory in the block dirBlock.
  • uint8_t isDir(void) : return True if this is a SdFile for a directory else false.
  • uint8_t isFile(void) : return True if this is a SdFile for a file else false.
  • uint8_t isSubDir(void) return True if this is a SdFile for a subdirectory else false.
  • uint8_t isRoot(void) return True if this is a SdFile for the root directory.
  • void ls(uint8_t flags = 0, uint8_t indent = 0);
  • uint8_t type(void) : Type of this SdFile. You should use isFile() or isDir() instead of type() if possible. \return The file or directory type.
  • SdVolume* volume(void) : \return SdVolume that contains this file.
  • uint32_t curCluster(void) : return The current cluster number for a file or directory.
  • uint32_t firstCluster(void) : return The first cluster number for a file or directory.

Fonctions de positionnement dans le fichier

  • rewind() : Fixe la position courante dans le fichier à 0.

Et aussi :

  • uint8_t seekEnd(void) Set the files current position to end of file. Useful to position a file for append. See seekSet().
  • uint8_t seekSet(uint32_t pos);
  • uint32_t curPosition(void) : return The current position for a file or directory.
  • uint8_t seekCur(uint32_t pos)Set the files position to current position + \a pos. See seekSet().

Fonctions de gestion des répertoires

  • static void dirName(const dir_t& dir, char* name);
  • int8_t readDir(dir_t* dir);
  • uint8_t rmDir(void);
  • uint8_t rmRfStar(void);
  • uint8_t makeDir(SdFile* dir, const char* dirName);

Fonctions de date

  • static void dateTimeCallbackCancel(void) :Cancel the date/time callback function.
  • static void dateTimeCallback(void (*dateTime)(uint16_t* date, uint16_t* time)) : Set the date/time callback function (voir info dans la librairie sdFat.h)
  • uint8_t timestamp(uint8_t flag, uint16_t year, uint8_t month, uint8_t day,uint8_t hour, uint8_t minute, uint8_t second);

Variables utiles

  • file.writeError : indique si une erreur est survenue lors de l'écriture de données dans un fichier

Autres fonctions

  • uint8_t contiguousRange(uint32_t* bgnBlock, uint32_t* endBlock);
  • uint8_t createContiguous(SdFile* dirFile,const char* fileName, uint32_t size);
  • uint8_t sync(void);

Installation

Principe d'utilisation

Pour inclure la librairie SdFatLib dans un programme, on ajoutera au début du programme les lignes suivantes :

#include <SdFat.h>

#include <SdFatUtil.h> 

A noter la librairie SdFatUtil.h qui n'est pas indispensable et qui comprend quelques défintions/ fonctions utiles pour calculer l'espace de RAM restante et enregistrer des chaînes en mémoire Flash.

Cette librairie doit être installée au préalable dans le répertoire Arduino 00XX/ Libraries/

Ensuite, le plus simple est d'utiliser le menu du logiciel Arduino Programme > Importer Librairie > Nom_librairie

Voir également l'instruction #include

Exemple


// --- Programme Arduino ---
// Trame de code générée par le générateur de code Arduino
// du site www.mon-club-elec.fr

// Auteur du Programme : X. HINAULT - Tous droits réservés
// Programme écrit le : 6/11/2010.

// ------- Licence du code de ce programme -----
//  This program is free software: you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation, either version 3 of the License,
//  or any later version.
//  This program is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//  You should have received a copy of the GNU General Public License
//  along with this program.  If not, see <http://www.gnu.org/licenses/>.

// ////////////////////  PRESENTATION DU PROGRAMME ////////////////////

// -------- Que fait ce programme ? ---------
 /*  Ecrit la valeur courante de milliS dans un fichier
  sur la carte SD et affiche le fichier dans le Terminal Série
 */


// --- Fonctionnalités utilisées ---

// Utilise la connexion série vers le PC
// Utilise une carte mémoire micro-SD avec le module Ethernet Arduino

// -------- Circuit à réaliser ---------

// La connexion série vers le PC utilise les broches 0 et 1 (via le câble USB)

// Le module Ethernet est à enficher broche à broche sur la carte Arduino
// Connecter broche SCLK du module Ethernet sur la broche 13
// Connecter broche MISO du module Ethernet sur la broche 12
// Connecter broche MOSI du module Ethernet sur la broche 11
// Connecter broche Select Ethernet du module Ethernet sur la broche 10
// Connecter broche Select SD Card du module Ethernet sur la broche 4
// Le module Ethernet est compatible avec la carte Mega via le connecteur ICSP


// /////////////////////////////// 1. Entête déclarative ///////////////////////
// A ce niveau sont déclarées les librairies incluses, les constantes, les variables, les objets utiles...

// --- Déclaration des constantes ---

// --- Inclusion des librairies ---

#include <SdFat.h> // inclusion de la librairie pour carte mémoire SD en connexion SPI

// --- Déclaration des constantes utiles ---

// --- Déclaration des constantes des broches E/S numériques ---

const int brocheSDCardSelect=4; // broche utilisée pour sélectionner la SD card

// --- Déclaration des constantes des broches analogiques ---


// --- Déclaration des variables globales ---


int testSD; // Variable utilisée pour tester valeur renvoyée par fonctions SD Card


// --- Déclaration des objets utiles pour les fonctionnalités utilisées ---

Sd2Card card; // création d'un objet Sd2Card
SdVolume volume; // création d'un objet SdVolume
SdFile root; // création d'un objet SdFile pour le répertoire racine
SdFile file; // création d'un objet SdFile pour le fichier utilisé


// ////////////////////////// 2. FONCTION SETUP = Code d'initialisation //////////////////////////
// La fonction setup() est exécutée en premier et 1 seule fois, au démarrage du programme

void setup()   { // debut de la fonction setup()

// --- ici instructions à exécuter 1 seule fois au démarrage du programme ---

// ------- Initialisation fonctionnalités utilisées -------  

Serial.begin(115200); // initialise connexion série à 115200 bauds
// IMPORTANT : régler le terminal côté PC avec la même valeur de transmission

//---- initialise l'utilisation de la carte mémoire SD en mode SPI  
pinMode(10, OUTPUT); // met la broche 10 (SS) en sortie (nécessaire avec module ethernet)
digitalWrite(10, HIGH); // mais désactive le  circuit intégré W5100 du module ethernet!

testSD= card.init(SPI_HALF_SPEED,brocheSDCardSelect); // initialise la carte SD à la vitesse et avec la broche CS voulues
if (testSD==1) Serial.println ("Initialisation SD card OK"); else ("Erreur initialisation SD Card");

testSD=volume.init(&card); // initialise le volume FAT de la carte SD
if (testSD==1) Serial.println ("Initialisation Volume FAT OK"); else ("Erreur initialisation Volume FAT");

testSD=root.openRoot(&volume); // ouverture du répertoire root
if (testSD==1) Serial.println ("Ouverture repertoire root OK"); else ("Echec ouverture repertoire root");

// ------- Broches en sorties numériques -------  

// ------- Broches en entrées numériques -------  

// ------- Activation si besoin du rappel au + (pullup) des broches en entrées numériques -------  

// ------- Initialisation des variables utilisées -------  

} // fin de la fonction setup()
// ********************************************************************************

////////////////////////////////// 3. FONCTION LOOP = Boucle sans fin = coeur du programme //////////////////
// la fonction loop() s'exécute sans fin en boucle aussi longtemps que l'Arduino est sous tension

void loop(){ // debut de la fonction loop()


// --- ici instructions à exécuter par le programme principal ---

//
//---- ouverture du répertoire root
if (!root.isOpen()) { // si root pas ouvert
  testSD=root.openRoot(&volume); // si root pas ouvert, on l'ouvre

  if (testSD==1) Serial.println ("Ouverture repertoire root OK"); else ("Echec ouverture repertoire root");

}

else Serial.println("Root deja ouvert"); // si root déjà ouvert

//----- ouverture de fichier ----

// nom du fichier court (8 caractères maxi . 3 caractères maxi) (dit format DOS 8.3)
char nomFichier[] = "FICHIER.TXT";

file.writeError = false; // réinitialise la variable writeError

// ouverture / création fichier en écriture + position fin du fichier
testSD=file.open(&root, nomFichier, O_CREAT| O_APPEND | O_WRITE);
    // O_CREAT - crée le fichier si il n'existe pas
    // O_APPEND - se postionne à la fin du fichier avant chaque écriture
    // O_WRITE - ouverture en mode écriture de donnée

if (testSD==1) Serial.print ("Ouverture fichier "), Serial.print(nomFichier),Serial.println(" OK");
else Serial.println ("Echec ouverture fichier");

//----- effacement du fichier
// Réduit la longueur du fichier à la valeur indiquée.
testSD=file.truncate(0); // Longueur = 0 pour effacement complet du fichier
if (testSD==1) Serial.print ("Effacement fichier"), Serial.print(nomFichier),Serial.println(" OK");
else Serial.println ("Echec effacement fichier");

//----- Ecriture dans le fichier -----

file.print("Ecriture de la valeur millis() dans le fichier = ");
delay(10);
file.println(millis());

//----- vérification erreur ecriture
// lit la variable writeError - attention writeError n'est pas une fonction
if (file.writeError==1) Serial.println ("Une erreur est survenue lors de l'ecriture"); else Serial.println("Ecriture reussie");

//----- fermeture de fichier -----
testSD=file.close(); // fermeture fichier
if (testSD==1) Serial.println("Fermeture fichier reussie !");


//*************** lecture fichier sur SD Card ***************

//---- ouverture du fichier en lecture ---
//char nomFichier[] = "FICHIER.TXT"; // nom du fichier court (8 caractères maxi . 3 caractères maxi) (dit format DOS 8.3)

testSD=file.open(&root, nomFichier, O_READ); // ouverture du fichier en lecture
if (testSD==1) Serial.print ("Ouverture fichier "), Serial.print(nomFichier),Serial.println(" en lecture OK");
else Serial.println ("Echec ouverture fichier");

//------ lecture des données du fichier -----

Serial.println();
Serial.println("****** Debut du fichier ******");

int c; // variable de reception données lues

// lit tous les octets disponibles et les affiche sur le port série
while ((c = file.read()) > 0) Serial.print(char(c));  

Serial.println("****** fin du fichier ******");
Serial.println();

//----- fermeture de fichier -----
testSD=file.close(); // fermeture fichier
if (testSD==1) Serial.println("Fermeture fichier reussie !");


//delay(3000);

while(1); // stop loop

} // fin de la fonction loop() - le programme recommence au début de la fonction loop sans fin
// ********************************************************************************


// ////////////////////////// FONCTIONS DE GESTION DES INTERRUPTIONS ////////////////////


// ////////////////////////// AUTRES FONCTIONS DU PROGRAMME ////////////////////


// ////////////////////////// Fin du programme ////////////////////

 

Autres exemples d'utilisation :

Sur le site Arduino anglais :

Aucun

Sur le site www-mon-club-elec.fr :

Aucun


Page d'accueil de la référence Arduino en français

Corrections, suggestions et nouvelle documentation peuvent être postées sur le Forum Arduino ou à l'adresse suivante : support_at_mon-club-elec_point_fr

Le texte original de la référence Arduino est sous licence Creative Commons Attribution-ShareAlike 3.0 . Les exemples de code dans la référence sont dans le domaine public.

La présente traduction française commentée a été réalisée par Xavier HINAULT (2010-2012) (www.mon-club-elec.fr) et est sous licence Creative Commons Attribution-ShareAlike 3.0.

Cette page est création originale de X. HINAULT