{"id":6807,"date":"2020-10-13T13:56:18","date_gmt":"2020-10-13T20:56:18","guid":{"rendered":"https:\/\/visualgdb.com\/w\/?p=6807"},"modified":"2025-09-09T19:27:54","modified_gmt":"2025-09-10T02:27:54","slug":"using-spiffs-partitions-with-esp32-projects","status":"publish","type":"post","link":"https:\/\/visualgdb.com\/tutorials\/esp32\/spiffs\/","title":{"rendered":"Using SPIFFS Partitions with ESP32 Projects"},"content":{"rendered":"

This tutorial shows how to manage SPIFFS FLASH partitions for ESP32 projects built with the ESP-IDF framework. SPIFFS partitions can contain arbitrary files (i.e. resources) used by the application. You can use them to store web pages, images, configuration files, or any other information.<\/p>\n

In this tutorial we will create a basic “blinking LED” project and change it to read the blinking script from a text file in an SPIFFS partition. We will then show how to modify the program behavior by changing the SPIFFS partition contents without modifying the program itself.<\/p>\n

Before you begin, install VisualGDB 5.5 or later.<\/p>\n

    \n
  1. Start Visual Studio and locate the VisualGDB ESP-IDF Project Wizard:\"\"<\/a><\/li>\n
  2. Enter the name and location of the project: \"\"<\/a><\/li>\n
  3. Proceed wit the default project type (new application using CMake): \"\"<\/a><\/li>\n
  4. On the Toolchain selection page pick your ESP32 toolchain and the ESP-IDF checkout. If you are using the Custom edition of VisualGDB, you can configure it to automatically open a terminal at a certain COM port when debugging the program. If not, you can view the COM port output using SmarTTY<\/a>: \"\"<\/a>Update:<\/strong> For better compatibility with the latest ESP32 tools, we recommend selecting the consolidated toolchain<\/a> instead.<\/li>\n
  5. Pick a sample you would like to clone for the project. Although ESP-IDF includes the spiffsgen<\/strong> sample demonstrating SPIFFS, we will instead pick the blink<\/strong> sample and show how to add SPIFFS-specific functionality manually:\"\"<\/a><\/li>\n
  6. Connect your development board to the USB port and make sure VisualGDB detects the debugging settings. Click the “Test” button to verify them: \"\"<\/a> Once the settings have been verified, click “Finish” to generate the project.<\/li>\n
  7. VisualGDB will create a basic “blinking LED” project containing the default partition table (with no SPIFFS partitions). Locate the partition table in Solution Explorer, right-click on it and select “Add New SPIFFS Partition”: \"\"<\/a><\/li>\n
  8. Proceed with switching the project to a custom partition table layout:\"\"<\/a><\/li>\n
  9. VisualGDB will copy the default layout file (partitions.csv<\/strong>) to the project directory and will configure the project to use it. You can change this setting later via VisualGDB Project Properties:\"\"<\/a><\/li>\n
  10. Proceed with the default name and size of the partition: \"\"<\/a>Note that the partition contents will be stored in the <Project Directory>\\spiffs_image<\/strong> folder. Each time you build the project, the SPIFFS image will be rebuilt based on that directory contents, and will be programmed into the FLASH memory together with your project.<\/li>\n
  11. VisualGDB will automatically edit the partitions.csv<\/strong> file for you, adding the new partition. Now you can begin adding files to it. Right-click on the partition and select “Add->New Item<\/strong>“:\"\"<\/a><\/li>\n
  12. Enter “program.txt” as the file name:\"\"<\/a>You can also add files to SPIFFS partitions via “Add->Existing Item<\/strong>” or by simply copying them into the <Project Directory>\\spiffs_image<\/strong> folder.<\/li>\n
  13. Enter the following text in program.txt:\n
    on\r\nwait 100\r\noff\r\nwait 500<\/pre>\n
    \"\"<\/a><\/li>\n
  14. Try building the project. You may get an error stating that the created partition doesn’t fit into the FLASH memory:\"\"<\/a><\/li>\n
  15. If this happens, reduce the partition size via Solution Explorer. This will have the same effect as manually editing partitions.csv<\/strong>: \"\"<\/a><\/li>\n
  16. Include the <esp_spiffs.h><\/strong> and <string.h><\/strong> files from blink.c<\/strong>. Then, update app_main()<\/strong> to mount the partition by calling esp_vfs_spiffs_register()<\/strong>:\n
        esp_vfs_spiffs_conf_t conf = {\r\n        .base_path = \"\/spiffs\",\r\n        .partition_label = NULL,\r\n        .max_files = 5,\r\n        .format_if_mount_failed = false};\r\n\r\n    esp_err_t ret = esp_vfs_spiffs_register(&conf);\r\n\r\n    if (ret != ESP_OK)\r\n        asm(\"break 1, 1\");<\/pre>\n
    This will mount the partition contents (i.e. program.txt<\/strong>) under the virtual \/spiffs<\/strong> path that can be used with fopen()<\/strong>. Replace the blinking loop in main()<\/strong> with the following code:<\/p>\n
        for (;;)\r\n    {\r\n        FILE *f = fopen(\"\/spiffs\/program.txt\", \"r\");\r\n\r\n        if (f == NULL)\r\n            asm(\"break 1, 1\");\r\n\r\n        for (char buffer[256], *line; (line = fgets(buffer, sizeof(buffer), f));)\r\n        {\r\n            for (int i = 0; i < sizeof(buffer); i++)\r\n                if (buffer[i] == '\\r' || buffer[i] == '\\n')\r\n                {\r\n                    buffer[i] = 0;\r\n                    break;\r\n                }\r\n\r\n            if (!strcmp(line, \"on\"))\r\n                gpio_set_level(BLINK_GPIO, 0);\r\n            else if (!strcmp(line, \"off\"))\r\n                gpio_set_level(BLINK_GPIO, 1);\r\n            else if (!strncmp(line, \"wait \", 5))\r\n                vTaskDelay(atoi(line + 5) \/ portTICK_PERIOD_MS);\r\n        }\r\n\r\n        fclose(f);\r\n    }<\/pre>\n
    This code reads the \/spiffs\/program.txt<\/strong> file line-by-line and controls the LED based on the commands stored in it.<\/li>\n
  17. Set a breakpoint inside the loop and begin debugging the project by pressing F5. VisualGDB will automatically program the FLASH memory and start a debugging session:\"\"<\/a><\/li>\n
  18. The breakpoint will soon trigger, showing the first line of program.txt<\/strong> read into buffer<\/strong>: \"\"<\/a>Remove the breakpoint and resume debugging. The LED will now blink in shorter impulses with longer pauses.<\/li>\n
  19. The SPIFFS partition can be rebuilt and programmed separately from the program itself. Try changing “wait 100” to “wait 1000” and then build the “storage-flash<\/strong>” target:\"\"<\/a>The ESP-IDF framework will automatically update and program the image, making the LED stay on for longer.<\/li>\n<\/ol>\n
    You can find the project shown in this tutorial in our GitHub repository<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"
    This tutorial shows how to manage SPIFFS FLASH partitions for ESP32 projects built with the ESP-IDF framework. SPIFFS partitions can<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[142],"tags":[138,225],"_links":{"self":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts\/6807"}],"collection":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/comments?post=6807"}],"version-history":[{"count":2,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts\/6807\/revisions"}],"predecessor-version":[{"id":9035,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts\/6807\/revisions\/9035"}],"wp:attachment":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/media?parent=6807"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/categories?post=6807"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/tags?post=6807"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}