SENSOREN/AKTOREN

ESP32 S3 - Konfiguration von SD-Karte lesen

Die Verwaltung von Konfigurationen ist eine häufige Herausforderung bei Embedded-Projekten. Einstellungen in einer Datei auf einer Micro-SD-Karte zu speichern, ist eine praktische, hardwareunabhängige Lösung. Dieses Tutorial zeigt Ihnen, wie Sie mit dem ESP32 S3 Schlüssel-Wert-Paare aus einer Datei config.txt auf einer Micro-SD-Karte lesen und diese Werte zur Laufzeit in typisierte Variablen laden.

Was Sie bauen werden:

Eine Datei config.txt auf der Micro-SD-Karte mit Schlüssel-Wert-Paaren in einem einfachen Format.
Code, der die Konfigurationsdatei liest und einen Wert in einer int-Variablen speichert.
Code, der die Konfigurationsdatei liest und einen Wert in einer float-Variablen speichert.
Code, der die Konfigurationsdatei liest und einen Wert in einer String-Variablen speichert.

ESP32 S3 Micro-SD-Karte Konfigurationsdatei

Erforderliche Hardware

1	×	ESP32 S3 WROOM N16R8
1	×	(Alternativ) ESP32 S3 SuperMini Dev Module
1	×	(Alternativ) ESP32 S3 Uno-form Board
1	×	(Alternativ) ESP32 S3 Camera Board
1	×	USB-Kabel Typ-A zu Typ-C (für USB-A PC)
1	×	USB-Kabel Typ-C zu Typ-C (für USB-C PC)
1	×	Micro-SD-Karte
1	×	Micro-SD-Karten-Modul
1	×	Verbindungskabel
1	×	(Optional) MicroSD-zu-SD-Speicherkarten-Adapter
1	×	(Empfohlen) Screw Terminal Expansion Board for ESP32 S3
1	×	(Empfohlen) Breakout Expansion Board for ESP32 S3
1	×	(Empfohlen) Power Splitter for ESP32 S3

Oder Sie können die folgenden Kits kaufen:

1	×	DIYables ESP32 S3 Starter-Kit (ESP32 S3 enthalten)
1	×	DIYables Sensor-Kit (18 Sensoren/Displays)

Offenlegung: Einige der in diesem Abschnitt bereitgestellten Links sind Amazon-Affiliate-Links. Wir können eine Provision für Käufe erhalten, die über diese Links getätigt werden, ohne zusätzliche Kosten für Sie. Wir schätzen Ihre Unterstützung.

Überblick über Micro SD Card Module

Das Micro-SD-Kartenmodul gibt dem ESP32 S3 über die SPI-Schnittstelle Zugriff auf einen austauschbaren Flash-Speicher. So können Sie Dateien wie in einem herkömmlichen Dateisystem lesen und schreiben. Es benötigt nur vier Datenleitungen (MOSI, MISO, SCK und CS) plus Stromversorgung und lässt sich daher leicht in jedes ESP32 S3 Projekt integrieren. Wenn Sie neu mit diesem Modul sind, lesen Sie das Tutorial ESP32 S3 - Micro-SD-Karte, das Pinbelegung, Verdrahtung und Einrichtung der Bibliothek ausführlich behandelt.

Wichtige Spezifikationen

Schnittstelle: SPI
Versorgungsspannung: 3,3 V oder 5 V (bei den meisten Modulen mit integriertem Spannungsregler)
Unterstützte Kartenformate: FAT16, FAT32
Maximale Kartengröße: 32 GB (FAT32)
Datenleitungen: MOSI, MISO, SCK, CS

Funktionsweise

Die Schlüssel-Wert-Paare werden vorab in einer Textdatei auf der Micro-SD-Karte gespeichert, und zwar in einem einfachen Format, das der ESP32 S3 effizient auswerten kann. Jedes Schlüssel-Wert-Paar steht in einer eigenen Zeile, und der Schlüssel wird durch ein =-Zeichen vom Wert getrennt. Die Datei benötigt daher keine speziellen Bibliotheken zur Erstellung und kann auf jedem PC mit einem einfachen Texteditor bearbeitet werden.

Formatregeln für Schlüssel

Jedes Schlüssel-Wert-Paar steht in einer eigenen Zeile und ist durch einen Zeilenumbruch von den anderen getrennt.
Schlüssel und Wert werden durch ein =-Zeichen getrennt; Leerzeichen drumherum sind nicht erforderlich.
Der ESP32 S3 Code durchsucht die Datei von oben nach unten nach einem passenden Schlüssel, daher spielt die Reihenfolge der Paare in der Datei keine Rolle.
Der Wert wird als String zurückgegeben und kann mit den Standard-Konvertierungsfunktionen von Arduino in int oder float umgewandelt werden.

Verdrahtungsdiagramm

Das Micro-SD-Kartenmodul wird über SPI mit dem ESP32 S3 verbunden. Verbinden Sie VCC mit 3,3 V (oder 5 V, wenn das Modul einen integrierten Spannungsregler hat), GND mit GND und die vier SPI-Datenleitungen mit den entsprechenden SPI-Pins des ESP32 S3, wie im folgenden Diagramm gezeigt.

ESP32 S3 Micro-SD-Kartenmodul Verdrahtungsplan

Dieses Bild wurde mit Fritzing erstellt. Klicken Sie, um das Bild zu vergrößern.

Sicherheitshinweise

Versorgen Sie das Micro-SD-Kartenmodul immer über die richtige Spannungsleitung für Ihre Modulvariante – 5 V an einem reinen 3,3-V-Modul können die Karte dauerhaft beschädigen. Stellen Sie sicher, dass die Micro-SD-Karte vollständig eingesteckt und als FAT16 oder FAT32 formatiert ist, bevor Sie die Schaltung einschalten, da die SD-Bibliothek eine unformatierte oder exFAT-Karte nicht initialisieren kann.

※ Notiz:

Wenn Sie ein Ethernet-Shield oder ein anderes Shield mit Micro-SD-Kartenhalter verwenden, benötigen Sie das Micro-SD-Kartenmodul nicht. Sie müssen die Micro-SD-Karte nur in den Micro-SD-Kartenhalter des Shields einsetzen.

So lesen Sie die Konfiguration in Variablen ein

Die folgenden Schritte führen Sie durch das Erstellen der Konfigurationsdatei auf Ihrem PC, das Kopieren auf die Micro-SD-Karte und das Ausführen des Arduino-Sketches, der die Schlüssel-Wert-Paare auswertet und in typisierte Variablen lädt. Der Code durchsucht für jeden Schlüssel die gesamte Datei und funktioniert daher unabhängig von der Reihenfolge der Paare.

Neu beim ESP32 S3? Arbeiten Sie zuerst unsere Anleitung Erste Schritte mit dem ESP32 S3 durch.
Erstellen Sie auf Ihrem PC mit Notepad oder Notepad++ eine Datei namens config.txt.
Kopieren Sie die folgenden Schlüssel-Wert-Paare und fügen Sie sie in config.txt ein:

myString_1=Hello myString_2=newbiely.com myInt_1=2 myInt_2=-105 myFloat_1=0.74 myFloat_2=-46.08

Verbinden Sie die Micro-SD-Karte über einen USB-3.0-SD-Kartenleser mit Ihrem PC.
Stellen Sie sicher, dass die Micro-SD-Karte als FAT16 oder FAT32 formatiert ist (suchen Sie online nach einer Anleitung für Ihr Betriebssystem).
Kopieren Sie config.txt in das Stammverzeichnis der Micro-SD-Karte.
Trennen Sie die Micro-SD-Karte vom PC.
Verbinden Sie die Micro-SD-Karte gemäß dem obigen Verdrahtungsplan über das Micro-SD-Kartenmodul mit dem ESP32 S3.
Kopieren Sie den folgenden Code und öffnen Sie ihn in der Arduino IDE:

/* * Dieser ESP32 S3 Code wurde von newbiely.de entwickelt * Dieser ESP32 S3 Code wird der Öffentlichkeit ohne jegliche Einschränkung zur Verfügung gestellt. * Für vollständige Anleitungen und Schaltpläne besuchen Sie bitte: * https://newbiely.de/tutorials/esp32-s3/esp32-s3-read-config-from-sd-card */ #include <SD.h> #define PIN_SPI_CS 10 // The ESP32 S3 pin connected to the CS pin of SD card module #define FILE_NAME "/config.txt" #define KEY_MAX_LENGTH 30 // change it if key is longer #define VALUE_MAX_LENGTH 30 // change it if value is longer // variables int myInt_1; int myInt_2; float myFloat_1; float myFloat_2; String myString_1; String myString_2; void setup() { Serial.begin(9600); if (!SD.begin(PIN_SPI_CS)) { while (1) { Serial.println(F("SD CARD FAILED, OR NOT PRESENT!")); delay(1000); } } Serial.println(F("SD Card initialized.")); myInt_1 = SD_findInt(F("myInt_1")); myInt_2 = SD_findInt(F("myInt_2")); myFloat_1 = SD_findFloat(F("myFloat_1")); myFloat_2 = SD_findFloat(F("myFloat_2")); myString_1 = SD_findString(F("myString_1")); myString_2 = SD_findString(F("myString_2")); Serial.print(F("myInt_1 = ")); Serial.println(myInt_1); Serial.print(F("myInt_2 = ")); Serial.println(myInt_2); Serial.print(F("myFloat_1 = ")); Serial.println(myFloat_1); Serial.print(F("myFloat_2 = ")); Serial.println(myFloat_2); Serial.print(F("myString_1 = ")); Serial.println(myString_1); Serial.print(F("myString_2 = ")); Serial.println(myString_2); } void loop() { } bool SD_available(const __FlashStringHelper * key) { char value_string[VALUE_MAX_LENGTH]; int value_length = SD_findKey(key, value_string); return value_length > 0; } int SD_findInt(const __FlashStringHelper * key) { char value_string[VALUE_MAX_LENGTH]; int value_length = SD_findKey(key, value_string); return HELPER_ascii2Int(value_string, value_length); } float SD_findFloat(const __FlashStringHelper * key) { char value_string[VALUE_MAX_LENGTH]; int value_length = SD_findKey(key, value_string); return HELPER_ascii2Float(value_string, value_length); } String SD_findString(const __FlashStringHelper * key) { char value_string[VALUE_MAX_LENGTH]; int value_length = SD_findKey(key, value_string); return HELPER_ascii2String(value_string, value_length); } int SD_findKey(const __FlashStringHelper * key, char * value) { File configFile = SD.open(FILE_NAME); if (!configFile) { Serial.print(F("SD Card: Issue encountered while attempting to open the file ")); Serial.println(FILE_NAME); return; } char key_string[KEY_MAX_LENGTH]; char SD_buffer[KEY_MAX_LENGTH + VALUE_MAX_LENGTH + 1]; // 1 is = character int key_length = 0; int value_length = 0; // Flash string to string PGM_P keyPoiter; keyPoiter = reinterpret_cast<PGM_P>(key); byte ch; do { ch = pgm_read_byte(keyPoiter++); if (ch != 0) key_string[key_length++] = ch; } while (ch != 0); // check line by line while (configFile.available()) { int buffer_length = configFile.readBytesUntil('\n', SD_buffer, 100); if (SD_buffer[buffer_length - 1] == '\r') buffer_length--; // trim the \r if (buffer_length > (key_length + 1)) { // 1 is = character if (memcmp(SD_buffer, key_string, key_length) == 0) { // equal if (SD_buffer[key_length] == '=') { value_length = buffer_length - key_length - 1; memcpy(value, SD_buffer + key_length + 1, value_length); break; } } } } configFile.close(); // close the file return value_length; } int HELPER_ascii2Int(char *ascii, int length) { int sign = 1; int number = 0; for (int i = 0; i < length; i++) { char c = *(ascii + i); if (i == 0 && c == '-') sign = -1; else { if (c >= '0' && c <= '9') number = number * 10 + (c - '0'); } } return number * sign; } float HELPER_ascii2Float(char *ascii, int length) { int sign = 1; int decimalPlace = 0; float number = 0; float decimal = 0; for (int i = 0; i < length; i++) { char c = *(ascii + i); if (i == 0 && c == '-') sign = -1; else { if (c == '.') decimalPlace = 1; else if (c >= '0' && c <= '9') { if (!decimalPlace) number = number * 10 + (c - '0'); else { decimal += ((float)(c - '0') / pow(10.0, decimalPlace)); decimalPlace++; } } } } return (number + decimal) * sign; } String HELPER_ascii2String(char *ascii, int length) { String str; str.reserve(length); str = ""; for (int i = 0; i < length; i++) { char c = *(ascii + i); str += String(c); } return str; }

Klicken Sie in der Arduino IDE auf die Schaltfläche Upload, um den Sketch zu kompilieren und auf den ESP32 S3 hochzuladen.
Öffnen Sie den Seriellen Monitor, stellen Sie die Baudrate passend zum Sketch ein und beobachten Sie die Ausgabe.
Profi-Tipp: Der Code hängt nicht von der Reihenfolge der Schlüssel-Wert-Paare in config.txt ab. Er durchsucht die Datei bei jeder Suche nach einem Schlüssel von Anfang an, sodass Sie Paare frei hinzufügen, entfernen oder umordnen können, ohne den Arduino-Sketch zu ändern.

Ausgabe im Seriellen Monitor

Nach erfolgreichem Hochladen und Initialisieren der Karte zeigt der Serielle Monitor jeden Variablennamen zusammen mit dem aus config.txt gelesenen Wert an. Die folgenden Messwerte wurden am 2026-06-16 mit einem ESP32 S3 WROOM N16R8 und einer 16-GB-FAT32-Micro-SD-Karte aufgezeichnet.

Newbiely | Arduino IDE 2.3.8

──

☐

Newbiely.ino

···

8 Serial.println("Hello World!");

Output

Serial Monitor

Message (Enter to send message to 'ESP32S3 Dev Module' on 'COM15')

New Line

9600 baud

[2026-06-16 08:12:01] SD Card initialized. [2026-06-16 08:12:01] myInt_1 = 2 [2026-06-16 08:12:01] myInt_2 = -105 [2026-06-16 08:12:02] myFloat_1 = 0.74 [2026-06-16 08:12:02] myFloat_2 = -46.08 [2026-06-16 08:12:02] myString_1 = Hello [2026-06-16 08:12:02] myString_2 = newbiely.com

Ln 11, Col 1

ESP32S3 Dev Module on COM15

Der Serielle Monitor bestätigt, dass jede Variable genau den Wert enthält, der im entsprechenden Schlüssel-Wert-Paar auf der Micro-SD-Karte gespeichert ist. Sie können die Konfigurationsdatei ändern und den ESP32 S3 neu starten, um die neuen Werte zu laden, ohne die Firmware neu zu flashen.

Anwendungen

Das Speichern der Konfiguration in einer Datei auf einer Micro-SD-Karte trennt Laufzeiteinstellungen von der Firmware. Das ist besonders nützlich bei installierten Systemen, deren Parameter sich ohne Neukompilierung ändern lassen sollen. Typische Anwendungsfälle sind:

WLAN-Zugangsdaten: Speichern Sie SSID und Passwort in der Konfigurationsdatei, damit sich das Gerät ohne Codeänderung mit dem richtigen Netzwerk verbindet.
Sensor-Schwellenwerte: Legen Sie Alarmgrenzen für Temperatur oder Luftfeuchtigkeit fest, die Betreiber vor Ort durch Bearbeiten von config.txt anpassen können.
Geräteidentität: Weisen Sie jedem Gerät einer Flotte einen eindeutigen Namen oder eine ID zu, indem Sie auf jede Karte eine andere Konfigurationsdatei schreiben.
Kalibrierungs-Offsets: Speichern Sie Kalibrierungsfaktoren von Sensoren als Gleitkommazahlen, damit sie ohne Neukompilierung der Firmware feinjustiert werden können.
Feature-Flags: Aktivieren oder deaktivieren Sie optionale Funktionen beim Start, indem Sie einen booleschen Schlüssel aus der Konfigurationsdatei lesen.

Video Tutorial

Wir erwägen die Erstellung von Video-Tutorials. Wenn Sie Video-Tutorials für wichtig halten, abonnieren Sie bitte unseren YouTube-Kanal , um uns zu motivieren, die Videos zu erstellen.

Sehen Sie sich unten die Schritt-für-Schritt-Videoanleitung für dieses ESP32 S3 Projekt an.

Herausforderungen

Diese Übungen helfen Ihnen, den einfachen Sketch zum Lesen der Konfiguration zu einer robusteren, produktionsreifen Firmware auszubauen. Beginnen Sie mit der Aufgabe für Anfänger und steigern Sie sich, sobald Sie sicherer werden.

Anfänger: Fügen Sie config.txt zwei weitere Schlüssel-Wert-Paare hinzu (zum Beispiel ledPin=2 und blinkRate=500) und passen Sie den Sketch an, damit er sie in eine int-Variable einliest und damit eine LED blinken lässt.
Fortgeschritten: Schreiben Sie eine Hilfsfunktion getConfigValue(key), die einen Schlüsselnamen entgegennimmt und den zugehörigen String-Wert zurückgibt. Überarbeiten Sie dann den Sketch, sodass er diese Funktion für alle Abfragen aufruft, statt die Suchlogik zu wiederholen.
Experte: Implementieren Sie eine Fehlerbehandlung, sodass der Sketch bei einem in config.txt fehlenden Schlüssel auf einen fest codierten Standardwert zurückgreift und eine Warnung im Seriellen Monitor ausgibt. So arbeitet das Gerät auch mit einer unvollständigen Konfigurationsdatei sicher weiter.