Document Operation Instructions

[中文]

Note

This document is automatically translated using AI. Please excuse any detailed errors. The official English version is still in progress.

Overview of Document Operations

Document operations refer to the actions of reading, writing, modifying, and managing data on storage media, which are the basic means for programs to interact with external data. Through document operations, applications can save states, log data, or other information, and re-read them when needed. Meanwhile, developers do not need to pay attention to the physical storage structure or erasing logic of the underlying flash memory, and can achieve data access and management by following the regular document operation process.

Document Operation Interface

POSIX (Portable Operating System Interface) and the C standard library provide a unified document operation interface. The advantages of this type of interface include:

• Strong cross-platform compatibility: The POSIX and C standard library interfaces are basically consistent across different operating systems, which is conducive to code porting.

• Rich functionality: Supports various operations such as file opening, reading, writing, closing, positioning, and permission control.

• Mature and stable: The interface has been used for a long time and is easy to debug and maintain.

In addition to POSIX and the C standard library, common document operation methods also include:

• Dedicated file system API: Interfaces provided by SPIFFS, LittleFS, etc., optimized for embedded flash memory, support file system integrity checks, garbage collection, etc.

• Storage abstraction library: NVS provides a key-value pair storage interface, which is more suitable for small configuration data storage.

Compared with these, POSIX/C standard library document operations are simple, the interface is unified, suitable for various storage devices, the logic is clear, but the overhead is larger, and the erasing management of flash memory is not as optimized as the dedicated file system, and direct use may increase wear.

File Systems and Storage Devices

Different types of storage devices and file systems support data operations in different ways. The following content only explains the storage devices and file systems involved in the current example, to help developers understand their adaptation relationship.

1. Storage devices: These are the actual hardware media used to store data.

On-chip flash (Flash): Suitable for storing small-scale, critical data, the number of erasures is limited, and lifespan management needs to be considered. SD card: Large capacity, usually uses the FAT file system, has good read and write compatibility, and can directly read and write files. Suitable for storing a large amount of file data.

2. File systems: This is the data management and access layer on the storage device, implementing the organization and operation interface of the file. For further explanation, refer to File Systems.

SPIFFS: The interface provided by SPIFFS can be mounted as a POSIX-style file system, so POSIX file operations can be used directly on SPIFFS, but the lifespan of flash memory should be considered. FAT file system: Provides a traditional file operation interface, POSIX/C file operations can be used directly, suitable for large-capacity data storage, usually used for SD cards. NVS (Non-Volatile Storage): Mounted on the on-chip flash, manages data in the form of key-value pairs, is not a traditional file system, POSIX file operations cannot be used directly, and need to be read and written through the relevant API.

3. Operation interface

• For SPIFFS or FAT file systems, regular file operation functions can be used directly.

• For NVS, you need to use a dedicated key-value API for reading and writing.

Document Operation Methods

Creating a File and Writing to It

• Call fopen() to open the specified file in the specified mode (here is the write-only w mode). If the file does not exist, a new file is created.

• Call fprintf() to write content to the target file.

• Invoke fclose() to close the file.

Check and rename the file

• Invoke stat() and pass in the target file path for renaming, check if the endpoint file of this path exists to determine whether it is necessary to delete the file first to avoid renaming conflicts.

• If it exists, invoke unlink() to delete the file to avoid renaming conflicts.

• Invoke rename() to rename the original file.

Read the file

• Invoke fopen() to open the specified file in a specified mode (here it is read-only r mode). If the file does not exist, it will return NULL.

• Invoke fgets() to read the file content. If you need to print, you need to handle the newline character.

• Invoke fclose() to close the file.

Process and print the read content

When invoking fgets() to read a line of data from the file, the end of the string usually contains a newline character \n. To facilitate printing or subsequent processing, this newline character needs to be removed.

• Invoke strchr() to find the first newline character in the target character array and return a pointer to the position of the newline character. If not found, it will return NULL.

• Determine whether the newline character is found. If found, replace the newline character with the string termination character \0, thereby truncating the string and removing the newline at the end of the line.

• Print the log, output relevant information for debugging or observing the reading result.

Unmount the file system

When you no longer need to access the file system, you should call the unmount operation to unmount Spiffs from the virtual file system. This operation can free system resources, prevent memory or file handle leaks, and ensure a clear system state, which is suitable for execution when the program ends or switches file systems.

• Invoke esp_vfs_spiffs_unregister() to unmount the partition and free resources.

File open mode

In the standard C library, the behavior of fopen() depends on the mode _type specified when opening the file.

Mode	Mode Description	File Exists	File Does Not Exist
"r"	Read-only mode	Open the file	Return NULL, will not create a new file
"w"	Write-only mode	Open the file and clear the content, will overwrite the existing file	Create a new file
"a"	Append mode	Open the file, the pointer points to the end, will not overwrite the original file content	Create a new file
"r+"	Read-write mode	Open the file	Return NULL, will not create a new file
"w+"	Read-write mode	Open the file and clear the content, will overwrite the existing file	Create a new file
"a+"	Read-write append mode	Open the file, the pointer points to the end, will not overwrite the original file content	Create a new file