Skip to content

Updated preferences and FAQ documentation (added SPIFFS) #8150

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
May 11, 2023
Merged

Updated preferences and FAQ documentation (added SPIFFS) #8150

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bb87561
Updated preferences.rst
PilnyTomas May 3, 2023
b8bae5f
Added into FAQ info about SPIFFS failed mount
PilnyTomas May 3, 2023
9c80ac9
Merge branch 'espressif:master' into doc_update
PilnyTomas May 3, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions docs/source/faq.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,3 +15,20 @@ How to compile libs with different debug level?
-----------------------------------------------

The short answer is ``esp32-arduino-lib-builder/configs/defconfig.common:44``. A guide explaining the process can be found here <guides/core_debug>

SPIFFS mount failed
-------------------
When you come across and error like this:

.. code-block:: shell

E (588) SPIFFS: mount failed, -10025
[E][SPIFFS.cpp:47] begin(): Mounting SPIFFS failed! Error: -1

Try enforcing format on fail in your code by adding ``true`` in the ``begin`` method such as this:

.. code-block:: c++

SPIFFS.begin(true);

See the method prototype for reference: ``bool begin(bool formatOnFail=false, const char * basePath="/spiffs", uint8_t maxOpenFiles=10, const char * partitionLabel=NULL);``
49 changes: 31 additions & 18 deletions docs/source/tutorials/preferences.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -233,9 +233,9 @@ Like so:

.. code-block:: arduino

String myString = myPreferences.getString("myStringKey");
float myFloat = myPreferences.getFloat("pi");

This will retrieve the String value from the namespace key ``"myStringKey"`` and assign it to the String type variable ``myString``.
This will retrieve the float value from the namespace key ``"pi"`` and assign it to the float type variable ``myFloat``.


Summary
Expand Down Expand Up @@ -277,9 +277,10 @@ When started, the system has no way of knowing which of the above conditions is
// not the complete setup(), but in setup(), include this...

stcPrefs.begin("STCPrefs", RO_MODE); // Open our namespace (or create it
// if it doesn't exist) in in RO mode.
// if it doesn't exist) in RO mode.

bool tpInit = stcPrefs.isKey("nvsInit"); // Test for the existence of the "already initialized" key.
bool tpInit = stcPrefs.isKey("nvsInit"); // Test for the existence
// of the "already initialized" key.

if (tpInit == false) {
// If tpInit is 'false', the key "nvsInit" does not yet exist therefore this
Expand All @@ -289,13 +290,15 @@ When started, the system has no way of knowing which of the above conditions is


// The .begin() method created the "STCPrefs" namespace and since this is our
// first-time run we will create our keys and store the initial "factory default" values.
// first-time run we will create
// our keys and store the initial "factory default" values.
stcPrefs.putUChar("curBright", 10);
stcPrefs.putString("talChan", "one");
stcPrefs.putLong("talMax", -220226);
stcPrefs.putBool("ctMde", true);

stcPrefs.putBool("nvsInit", true); // Create the "already initialized" key and store a value.
stcPrefs.putBool("nvsInit", true); // Create the "already initialized"
// key and store a value.

// The "factory defaults" are created and stored so...
stcPrefs.end(); // Close the namespace in RW mode and...
Expand Down Expand Up @@ -456,10 +459,12 @@ This is best explained with an example. Here the ``Bytes`` methods are used to s
Serial.begin(115200);
delay(250);

mySketchPrefs.begin("myPrefs", RW_MODE); // open (or create) the namespace "myPrefs" in RW mode
mySketchPrefs.begin("myPrefs", RW_MODE); // open (or create) the namespace
// "myPrefs" in RW mode
mySketchPrefs.clear(); // delete any previous keys in this namespace

// Create an array of test values. We're using hex numbers throughout to better show how the bytes move around.
// Create an array of test values. We're using hex numbers
// throughout to better show how the bytes move around.
int16_t myArray[] = { 0x1112, 0x2122, 0x3132, 0x4142, 0x5152, 0x6162, 0x7172 };

Serial.println("Printing myArray...");
Expand All @@ -468,22 +473,28 @@ This is best explained with an example. Here the ``Bytes`` methods are used to s
}
Serial.println("\r\n");

// In the next statement, the second sizeof() needs to match the data type of the elements of myArray
Serial.print("The number of elements in myArray is: "); Serial.println( sizeof(myArray) / sizeof(int16_t) );
Serial.print("But the size of myArray in bytes is: "); Serial.println( sizeof(myArray) );
// In the next statement, the second sizeof() needs
// to match the data type of the elements of myArray
Serial.print("The number of elements in myArray is: ");
Serial.println( sizeof(myArray) / sizeof(int16_t) );
Serial.print("But the size of myArray in bytes is: ");
Serial.println( sizeof(myArray) );
Serial.println("");

Serial.println("Storing myArray into the Preferences namespace \"myPrefs\" against the key \"myPrefsBytes\".");
Serial.println(
"Storing myArray into the Preferences namespace \"myPrefs\" against the key \"myPrefsBytes\".");
// Note: in the next statement, to store the entire array, we must use the
// size of the arrray in bytes, not the number of elements in the array.
mySketchPrefs.putBytes( "myPrefsBytes", myArray, sizeof(myArray) );
Serial.print("The size of \"myPrefsBytes\" is (in bytes): "); Serial.println( mySketchPrefs.getBytesLength("myPrefsBytes") );
Serial.print("The size of \"myPrefsBytes\" is (in bytes): ");
Serial.println( mySketchPrefs.getBytesLength("myPrefsBytes") );
Serial.println("");

int16_t myIntBuffer[20] = {}; // No magic about 20. Just making a buffer (array) big enough.
int16_t myIntBuffer[20] = {}; // No magic about 20. Just making a buffer (array) big enough.
Serial.println("Retrieving the value of myPrefsBytes into myIntBuffer.");
Serial.println(" - Note the data type of myIntBuffer matches that of myArray");
mySketchPrefs.getBytes( "myPrefsBytes", myIntBuffer, mySketchPrefs.getBytesLength("myPrefsBytes") );
mySketchPrefs.getBytes("myPrefsBytes", myIntBuffer,
mySketchPrefs.getBytesLength("myPrefsBytes"));

Serial.println("Printing myIntBuffer...");
// In the next statement, sizeof() needs to match the data type of the elements of myArray
Expand All @@ -492,9 +503,11 @@ This is best explained with an example. Here the ``Bytes`` methods are used to s
}
Serial.println("\r\n");

Serial.println("We can see how the data from myArray is actually stored in the namespace as follows.");
uint8_t myByteBuffer[40] = {}; // No magic about 40. Just making a buffer (array) big enough.
mySketchPrefs.getBytes( "myPrefsBytes", myByteBuffer, mySketchPrefs.getBytesLength("myPrefsBytes") );
Serial.println(
"We can see how the data from myArray is actually stored in the namespace as follows.");
uint8_t myByteBuffer[40] = {}; // No magic about 40. Just making a buffer (array) big enough.
mySketchPrefs.getBytes("myPrefsBytes", myByteBuffer,
mySketchPrefs.getBytesLength("myPrefsBytes"));

Serial.println("Printing myByteBuffer...");
for (int i = 0; i < mySketchPrefs.getBytesLength("myPrefsBytes"); i++) {
Expand Down