Concrete implementation of StorageManager using FatFs. More...

#include <FatFsStorageManager.h>

Inheritance diagram for FatFsStorageManager:

Collaboration diagram for FatFsStorageManager:

Public Member Functions
	FatFsStorageManager ()
	Construct a new FatFsStorageManager object.

bool	mount () override
	Mount the filesystem at the specified mount point.

bool	unmount () override
	Unmount the filesystem.

bool	exists (const std::string &path) override
	Check if the path exists.

bool	remove (const std::string &path) override
	Remove a file or directory at the specified path.

bool	rename (const std::string &from, const std::string &to) override
	Rename a file or directory.

bool	readFile (const std::string &path, std::vector< uint8_t > &buffer) override
	Read a file into a memory buffer.

bool	readFileString (const std::string &path, uint32_t startPosition, uint32_t length, std::string &buffer)
	Read a file string into a std::string.

bool	writeFile (const std::string &path, const std::vector< uint8_t > &data) override
	Write a memory buffer to a file.

bool	writeFile (const std::string &path, const unsigned char *data, size_t size) override
	Write raw data to a file.

bool	streamFile (const std::string &path, std::function< void(const uint8_t *, size_t)> chunkCallback) override
	Stream a file in chunks via callback.

bool	listDirectory (const std::string &path, std::vector< FileInfo > &out) override
	List the contents of a directory.

bool	createDirectory (const std::string &path) override
	Create a directory at the specified path.

bool	removeDirectory (const std::string &path) override
	Remove a directory at the specified path.

size_t	getFileSize (const std::string &path) override
	Get the size of a file.

bool	appendToFile (const std::string &path, const uint8_t *data, size_t size) override
	Append data to a file.

bool	isMounted () const override
	Check if the filesystem is currently mounted.

bool	formatStorage () override
	Format the storage device.

std::unique_ptr< StorageFileReader >	openReader (const std::string &path) override
	open a file for streaming read access.

Public Member Functions inherited from StorageManager
virtual	~StorageManager ()=default

Private Member Functions
std::string	resolvePath (const std::string &path) const
	Helper function to normalize full path based on mountPoint and relative path.

bool	ensureMounted ()

bool	probeMountPoint ()

void	refreshMountState ()

Private Attributes
bool	mounted = false
	Indicates if the filesystem is currently mounted.

std::string	mountPoint = "sd0"
	Default mount point.

SemaphoreHandle_t	mutex
	Optional lock for thread safety.

Detailed Description

Definition at line 30 of file FatFsStorageManager.h.

Constructor & Destructor Documentation

◆ FatFsStorageManager()

FatFsStorageManager::FatFsStorageManager ( )

Construct a new FatFsStorageManager object.

Definition at line 27 of file FatFsStorageManager.cpp.

27{}

Member Function Documentation

◆ appendToFile()

bool FatFsStorageManager::appendToFile	(	const std::string &	path,
		const uint8_t *	data,
		size_t	size
	)

overridevirtual

Append data to a file.

Parameters

path	Path to the file.
data	Pointer to the data buffer.
size	Size of the data buffer.

Returns: true if successful, false otherwise.

Note: If the file does not exist, it will be created. If the file exists, data will be appended to the end.

Parameters

path	Path to the file.
data	Pointer to the data buffer.
size	Size of the data buffer.

Returns: true if successful, false otherwise.

Note: If the file does not exist, it will be created. If the file exists, data will be appended to the end.

Implements StorageManager.

Definition at line 269 of file FatFsStorageManager.cpp.

{
    if (!ensureMounted())
    {
        TRACE("SD card not mounted — cannot append to file: %s\n", path.c_str());
        return false;
    }
    FF_FILE *file = ff_fopen(resolvePath(path).c_str(), "a");
    if (!file)
        return false;
 
    size_t written = ff_fwrite(data, 1, size, file);
    ff_fclose(file);
    return written == size;
}

References ensureMounted(), resolvePath(), and TRACE.

Here is the call graph for this function:

◆ createDirectory()

bool FatFsStorageManager::createDirectory ( const std::string & path )

overridevirtual

Parameters

path	Path to create the directory.

Returns: true if successful, false otherwise.

Implements StorageManager.

Definition at line 120 of file FatFsStorageManager.cpp.

{
    if (!ensureMounted())
    {
        TRACE("SD card not mounted — cannot create directory: %s\n", path.c_str());
        return false;
    }
    TRACE("[FatFs] Creating directory: %s\n", path.c_str());
    return ff_mkdir(resolvePath(path).c_str()) == FF_ERR_NONE;
}

References ensureMounted(), resolvePath(), and TRACE.

Here is the call graph for this function:

◆ ensureMounted()

bool FatFsStorageManager::ensureMounted ( )

private

Definition at line 319 of file FatFsStorageManager.cpp.

{
    if (!mounted)
    {
        return mount();
    }
    return true;
}

References mount(), and mounted.

Referenced by appendToFile(), createDirectory(), exists(), getFileSize(), listDirectory(), openReader(), readFile(), readFileString(), remove(), removeDirectory(), rename(), streamFile(), writeFile(), and writeFile().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ exists()

bool FatFsStorageManager::exists ( const std::string & path )

overridevirtual

Check if the path exists.

Returns: true if so, false otherwise.

Returns: true if so, false otherwise.

Implements StorageManager.

Definition at line 65 of file FatFsStorageManager.cpp.

{
   TRACE("[FatFs] Checking if path exists: %s\n", path.c_str());
    if (!ensureMounted())
    {
        printf("[FatFs] SD card not mounted — cannot check path exists: %s\n", path.c_str());
        return false;
    }
    TRACE("[FatFs] Checking if exists: %s\n", resolvePath(path).c_str());
    FF_Stat_t xStat;
 
    // Use ff_stat to check if the file or directory exists
    TRACE("[FatFs] Calling ff_stat on path: %s\n",resolvePath(path).c_str());
    int err = ff_stat(resolvePath(path).c_str(), &xStat);
    TRACE("[FatFs] ff_stat returned: %d\n", err);
    if (err == FF_ERR_NONE){
        TRACE("[FatFs] Path exists: %s, size: %ld bytes\n", resolvePath(path).c_str(), xStat.st_size);
        return true;
    }
    TRACE("Path does not exist: %s\n", path.c_str());
    return false;
}

References ensureMounted(), resolvePath(), and TRACE.

Here is the call graph for this function:

◆ formatStorage()

bool FatFsStorageManager::formatStorage ( )

overridevirtual

Returns: true if successful, false otherwise.

Note: This will erase all data on the device and reinitialize the filesystem.

Implements StorageManager.

Definition at line 350 of file FatFsStorageManager.cpp.

{
    if (!mounted) {
        printf("[FatFs] Cannot format: card not mounted\n");
        return false;
    }
 
    if (!format(mountPoint.c_str())) {
        printf("[FatFs] Format failed for device: %s\n", mountPoint.c_str());
        return false;
    }
 
    printf("[FatFs] Format successful for device: %s\n", mountPoint.c_str());
 
    // Optionally re-mount to refresh filesystem state
    unmount();
    mount();
 
    return mounted;
}

References mount(), mounted, mountPoint, and unmount().

Here is the call graph for this function:

◆ getFileSize()

size_t FatFsStorageManager::getFileSize ( const std::string & path )

overridevirtual

Get the size of a file.

Parameters

path	Path to the file.

Returns: Size of the file in bytes, or 0 if the file does not exist.

Parameters

path	Path to the file.

Returns: Size of the file in bytes, or 0 if the file does not exist.

Implements StorageManager.

Definition at line 250 of file FatFsStorageManager.cpp.

{
    if (!ensureMounted())
    {
        TRACE("SD card not mounted — cannot get file size: %s\n", path.c_str());
        return false;
    }
    FF_FILE *file = ff_fopen(resolvePath(path).c_str(), "r");
    if (!file)
        return 0;
 
    ff_fseek(file, 0, SEEK_END);
    long size = ff_ftell(file);
    ff_fclose(file);
 
    return (size >= 0) ? static_cast<size_t>(size) : 0;
}

References ensureMounted(), resolvePath(), and TRACE.

Here is the call graph for this function:

◆ isMounted()

bool FatFsStorageManager::isMounted ( ) const

overridevirtual

Returns: true if mounted, false otherwise.

Note: This can be used to check if the filesystem is ready for operations.

Implements StorageManager.

Definition at line 328 of file FatFsStorageManager.cpp.

{
    return mounted;
}

References mounted.

◆ listDirectory()

bool FatFsStorageManager::listDirectory	(	const std::string &	path,
		std::vector< FileInfo > &	out
	)

overridevirtual

List the contents of a directory.

Parameters

path	Path to the directory.
out	Output vector to fill with FileInfo objects.

Returns: true if successful, false otherwise.

Parameters

path	Path to the directory.
out	Output vector to fill with FileInfo objects.

Returns: true if successful, false otherwise.

Implements StorageManager.

Definition at line 89 of file FatFsStorageManager.cpp.

{
    if (!ensureMounted()) {
        TRACE("SD card not mounted — cannot list directory: %s\n", path.c_str());
        return false;
    }
    TRACE("[FatFs] Listing directory: %s\n", path.c_str());
    FF_FindData_t xFindStruct{};
    std::string searchPath = resolvePath(path.empty() ? "/" : path);
    TRACE("[FatFs] Search path: %s\n", searchPath.c_str());
    int result = ff_findfirst(searchPath.c_str(), &xFindStruct);
 
    if (result != FF_ERR_NONE) {
        printf("[FatFs] ff_findfirst failed with error: %d\n", result);
        return false;
    }
 
    do {
        if (xFindStruct.pcFileName && strlen(xFindStruct.pcFileName) > 0) {
            FileInfo info;
            info.name = xFindStruct.pcFileName;
            info.isDirectory = xFindStruct.ucAttributes & FF_FAT_ATTR_DIR;
            info.isReadOnly = xFindStruct.ucAttributes & FF_FAT_ATTR_READONLY;
            info.size = static_cast<size_t>(xFindStruct.ulFileSize);
            out.push_back(info);
        }
    } while (ff_findnext(&xFindStruct) == FF_ERR_NONE);
 
    return true;
}

References ensureMounted(), FileInfo::isDirectory, FileInfo::isReadOnly, FileInfo::name, resolvePath(), FileInfo::size, and TRACE.

Here is the call graph for this function:

◆ mount()

bool FatFsStorageManager::mount ( )

overridevirtual

Mount the filesystem at the specified mount point.

Returns: true if successful, false otherwise.

Returns: true if successful, false otherwise.

Implements StorageManager.

Definition at line 30 of file FatFsStorageManager.cpp.

{
    if (mounted)
        return true;
 
    TRACE("Mounting SD card at: %s\n", mountPoint.c_str());
    mounted = ::mount(mountPoint.c_str());
 
    if (mounted && !probeMountPoint())
    {
        TRACE("SD mount appears successful, but directory listing failed — treating as mount failure\n");
        mounted = false;
    }
 
    if (!mounted)
    {
        TRACE("ERROR: SD mount FAILED for %s\n", mountPoint.c_str());
    }
    else
    {
        TRACE("SD card mounted successfully\n");
    }
 
    return mounted;
}

References mount(), mounted, mountPoint, probeMountPoint(), and TRACE.

Referenced by ensureMounted(), formatStorage(), and mount().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ openReader()

std::unique_ptr< StorageFileReader > FatFsStorageManager::openReader ( const std::string & path )

overridevirtual

Parameters

path	The file path

Returns: A new reader object, or nullptr on failure

Implements StorageManager.

Definition at line 414 of file FatFsStorageManager.cpp.

                                                                                      {
    if (!ensureMounted()) return nullptr;
 
    auto reader = std::make_unique<FatFsFileReader>();
    if (!reader->open(resolvePath(path))) return nullptr;
    return reader;
}

References ensureMounted(), and resolvePath().

Here is the call graph for this function:

◆ probeMountPoint()

bool FatFsStorageManager::probeMountPoint ( )

private

Definition at line 342 of file FatFsStorageManager.cpp.

{
    FF_FindData_t xFindStruct = {};
    std::string root = "/" + mountPoint;
    int result = ff_findfirst(root.c_str(), &xFindStruct);
    return result == FF_ERR_NONE;
}

References mountPoint.

Referenced by mount(), and refreshMountState().

Here is the caller graph for this function:

◆ readFile()

bool FatFsStorageManager::readFile	(	const std::string &	path,
		std::vector< uint8_t > &	buffer
	)

overridevirtual

Read a file into a memory buffer.

Parameters

path	Path to the file.
buffer	Output buffer to fill with data.

Returns: true if successful, false otherwise.

Parameters

path	Path to the file.
buffer	Output buffer to fill with data.

Returns: true if successful, false otherwise.

Implements StorageManager.

Definition at line 142 of file FatFsStorageManager.cpp.

{
    if (!ensureMounted())
    {
        TRACE("SD card not mounted — cannot read file: %s\n", path.c_str());
        return false;
    }
    FF_FILE *file = ff_fopen(resolvePath(path).c_str(), "r");
    if (!file)
        return false;
 
    ff_fseek(file, 0, SEEK_END);
    long fileSize = ff_ftell(file);
    ff_fseek(file, 0, SEEK_SET);
 
    if (fileSize < 0)
    {
        ff_fclose(file);
        return false;
    }
 
    buffer.resize(fileSize);
    ff_fread(buffer.data(), 1, fileSize, file);
    ff_fclose(file);
    return true;
}

References ensureMounted(), resolvePath(), and TRACE.

Here is the call graph for this function:

◆ readFileString()

bool FatFsStorageManager::readFileString	(	const std::string &	path,
		uint32_t	startPosition,
		uint32_t	length,
		std::string &	buffer
	)

virtual

Parameters

path	Path to the file.
startPosition	Start position in the file.
length	Length of data to read.
buffer	Output string to fill with data.

Returns: true if successful.

Implements StorageManager.

Definition at line 371 of file FatFsStorageManager.cpp.

{
    if (!ensureMounted())
    {
        TRACE("SD card not mounted — cannot read file string: %s\n", path.c_str());
        return false;
    }
 
    FF_FILE *file = ff_fopen(resolvePath(path).c_str(), "r");
    if (!file)
    {
        TRACE("Failed to open file: %s\n", path.c_str());
        return false;
    }
 
    ff_fseek(file, 0, SEEK_END);
    size_t fileSize = ff_ftell(file);
    if (startPosition >= fileSize)
    {
        ff_fclose(file);
        buffer.clear();
        return true;
    }
 
    size_t readLength = std::min<size_t>(length, fileSize - startPosition);
    ff_fseek(file, startPosition, SEEK_SET);
 
    buffer.resize(readLength);
    size_t bytesRead = ff_fread(buffer.data(), 1, readLength, file);
    ff_fclose(file);
 
    if (bytesRead != readLength)
    {
        buffer.resize(bytesRead);
        TRACE("Read only %zu bytes from file: %s\n", bytesRead, path.c_str());
    }
 
    return true;
}

References ensureMounted(), resolvePath(), and TRACE.

Here is the call graph for this function:

◆ refreshMountState()

void FatFsStorageManager::refreshMountState ( )

private

Definition at line 333 of file FatFsStorageManager.cpp.

{
    if (mounted && !probeMountPoint())
    {
        TRACE("SD no longer accessible — marking as unmounted\n");
        mounted = false;
    }
}

References mounted, probeMountPoint(), and TRACE.

Here is the call graph for this function:

◆ remove()

bool FatFsStorageManager::remove ( const std::string & path )

overridevirtual

Remove a file or directory at the specified path.

Returns: true if successful, false otherwise.

Note: For directories, this will only succeed if the directory is empty.

Returns: true if successful, false otherwise.

Note: For directories, this will only succeed if the directory is empty.

Implements StorageManager.

Definition at line 205 of file FatFsStorageManager.cpp.

{
    if (!ensureMounted())
    {
        TRACE("SD card not mounted — cannot remove file: %s\n", path.c_str());
        return false;
    }
    return ff_remove(resolvePath(path).c_str()) == FF_ERR_NONE;
}

References ensureMounted(), resolvePath(), and TRACE.

Here is the call graph for this function:

◆ removeDirectory()

bool FatFsStorageManager::removeDirectory ( const std::string & path )

overridevirtual

Parameters

path	Path to the directory to remove.

Returns: true if successful, false otherwise.

Note: This will only succeed if the directory is empty.

Implements StorageManager.

Definition at line 131 of file FatFsStorageManager.cpp.

{
    if (!ensureMounted())
    {
        TRACE("SD card not mounted — cannot remove directory: %s\n", path.c_str());
        return false;
    }
    return ff_rmdir(resolvePath(path).c_str()) == FF_ERR_NONE;
}   

References ensureMounted(), resolvePath(), and TRACE.

Here is the call graph for this function:

◆ rename()

bool FatFsStorageManager::rename	(	const std::string &	from,
		const std::string &	to
	)

overridevirtual

Rename a file or directory.

Parameters

from	Current path of the file or directory.
to	New path for the file or directory.

Returns: true if successful, false otherwise.

Note: This will fail if the destination already exists.

Parameters

from	Current path of the file or directory.
to	New path for the file or directory.

Returns: true if successful, false otherwise.

Note: This will fail if the destination already exists.

Implements StorageManager.

Definition at line 216 of file FatFsStorageManager.cpp.

{
    if (!ensureMounted())
    {
        TRACE("SD card not mounted — cannot rename file %s to file: %s\n", from.c_str(), to.c_str());
        return false;
    }
    return ff_rename(resolvePath(from).c_str(), resolvePath(to).c_str(), false) == 0;
}

References ensureMounted(), resolvePath(), and TRACE.

Here is the call graph for this function:

◆ resolvePath()

std::string FatFsStorageManager::resolvePath ( const std::string & path ) const

private

Definition at line 286 of file FatFsStorageManager.cpp.

{
    std::string fullPath = "/" + mountPoint;
    if (!path.empty())
    {
        if (path[0] != '/')
            fullPath += "/";
        fullPath += path;
    }
 
    // Normalize duplicate slashes
    std::string normalized;
    bool lastWasSlash = false;
    for (char c : fullPath)
    {
        if (c == '/')
        {
            if (!lastWasSlash)
            {
                normalized += c;
                lastWasSlash = true;
            }
        }
        else
        {
            normalized += c;
            lastWasSlash = false;
        }
    }
 
    return normalized;
}

References mountPoint.

Referenced by appendToFile(), createDirectory(), exists(), getFileSize(), listDirectory(), openReader(), readFile(), readFileString(), remove(), removeDirectory(), rename(), streamFile(), writeFile(), and writeFile().

Here is the caller graph for this function:

◆ streamFile()

bool FatFsStorageManager::streamFile	(	const std::string &	path,
		std::function< void(const uint8_t *, size_t)>	chunkCallback
	)

overridevirtual

Stream a file in chunks via callback.

Parameters

path	Path to the file.
chunkCallback	Callback function to handle each chunk of data.

Returns: true if successful, false otherwise.

Note: The callback will be called multiple times with chunks of data from the file.

Parameters

path	Path to the file.
chunkCallback	Callback function to handle each chunk of data.

Returns: true if successful, false otherwise.

Note: The callback will be called multiple times with chunks of data from the file.

Implements StorageManager.

Definition at line 227 of file FatFsStorageManager.cpp.

{
    if (!ensureMounted())
    {
        TRACE("SD card not mounted — cannot stream file: %s\n", path.c_str());
        return false;
    }
    FF_FILE *file = ff_fopen(resolvePath(path).c_str(), "r");
    if (!file)
        return false;
 
    uint8_t buffer[HTTP_BUFFER_SIZE];
    size_t bytes;
    while ((bytes = ff_fread(buffer, 1, sizeof(buffer), file)) > 0)
    {
        chunkCallback(buffer, bytes);
    }
 
    ff_fclose(file);
    return true;
}

References ensureMounted(), HTTP_BUFFER_SIZE, resolvePath(), and TRACE.

Here is the call graph for this function:

◆ unmount()

bool FatFsStorageManager::unmount ( )

overridevirtual

Unmount the filesystem.

Returns: true if successful, false otherwise.

Returns: true if successful, false otherwise.

Implements StorageManager.

Definition at line 57 of file FatFsStorageManager.cpp.

{
    ::unmount(mountPoint.c_str());
    mounted = false;
    return true;
}

References mounted, mountPoint, and unmount().

Referenced by formatStorage(), and unmount().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ writeFile() [1/2]

bool FatFsStorageManager::writeFile	(	const std::string &	path,
		const std::vector< uint8_t > &	data
	)

overridevirtual

Write a memory buffer to a file.

Parameters

path	Path to the file.
data	Data to write.

Returns: true if successful, false otherwise.

Parameters

path	Path to the file.
data	Data to write.

Returns: true if successful, false otherwise.

Implements StorageManager.

Definition at line 170 of file FatFsStorageManager.cpp.

{
    if (!ensureMounted())
    {
        TRACE("SD card not mounted — cannot write to file: %s\n", path.c_str());
        return false;
    }
    FF_FILE *file = ff_fopen(resolvePath(path).c_str(), "w");
    if (!file)
        return false;
 
    ff_fwrite(data.data(), 1, data.size(), file);
    ff_fclose(file);
    return true;
}

References ensureMounted(), resolvePath(), and TRACE.

Here is the call graph for this function:

◆ writeFile() [2/2]

bool FatFsStorageManager::writeFile	(	const std::string &	path,
		const unsigned char *	data,
		size_t	size
	)

overridevirtual

Parameters

path	Path to the file.
data	Pointer to the data buffer.
size	Size of the data buffer.

Returns: true if successful, false otherwise.

Implements StorageManager.

Definition at line 186 of file FatFsStorageManager.cpp.

{
    if (!ensureMounted())
    {
        TRACE("SD card not mounted — cannot write to file: %s\n", path.c_str());
        return false;
    }
 
    FF_FILE* file = ff_fopen(resolvePath(path).c_str(), "w");
    if (!file)
        return false;
 
    size_t written = ff_fwrite(data, 1, size, file);
    ff_fclose(file);
 
    return (written == size);
}

References ensureMounted(), resolvePath(), and TRACE.

Here is the call graph for this function:

Member Data Documentation

◆ mounted

bool FatFsStorageManager::mounted = false

private

Definition at line 181 of file FatFsStorageManager.h.

Referenced by ensureMounted(), formatStorage(), isMounted(), mount(), refreshMountState(), and unmount().

◆ mountPoint

std::string FatFsStorageManager::mountPoint = "sd0"

private

Definition at line 182 of file FatFsStorageManager.h.

Referenced by formatStorage(), mount(), probeMountPoint(), resolvePath(), and unmount().

◆ mutex

SemaphoreHandle_t FatFsStorageManager::mutex

private

Definition at line 184 of file FatFsStorageManager.h.

The documentation for this class was generated from the following files:

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ FatFsStorageManager()

Member Function Documentation

◆ appendToFile()

◆ createDirectory()

◆ ensureMounted()

◆ exists()

◆ formatStorage()

◆ getFileSize()

◆ isMounted()

◆ listDirectory()

◆ mount()

◆ openReader()

◆ probeMountPoint()

◆ readFile()

◆ readFileString()

◆ refreshMountState()

◆ remove()

◆ removeDirectory()

◆ rename()

◆ resolvePath()

◆ streamFile()

◆ unmount()

◆ writeFile() [1/2]

◆ writeFile() [2/2]

Member Data Documentation

◆ mounted

◆ mountPoint

◆ mutex