C++ wrapper for the SPIFFS library for the Particle platform. More...

#include <SpiffsParticleRK.h>

Public Member Functions
	SpiffsParticle (SpiFlashBase &flash)
	Create a SpiffsParticle file system object. Note that you must mount the file system before using it! More...

SpiffsParticle &	withPhysicalSize (size_t value)
	Sets the size of the flash file system in bytes, relative to the physical start address.

SpiffsParticle &	withPhysicalAddr (size_t value)
	Sets the start address in the flash for the file system (default: 0)

SpiffsParticle &	withPhysicalBlockSize (size_t value)
	Sets the physical block size (default: 4096) More...

SpiffsParticle &	withLogicalBlockSize (size_t value)
	Sets the logical block size (default: 4096) More...

SpiffsParticle &	withLogicalPageSize (size_t value)
	Sets the logical page size (default: 256) More...

SpiffsParticle &	withMaxOpenFiles (size_t value)
	Sets the maximum number of open files (default: 4) More...

SpiffsParticle &	withCachePages (size_t value)
	Sets the desired not of cache pages (default: 2) More...

SpiffsParticle &	withLowLevelDebug (bool value=true)
	Enable (or disable) low level debug mode. More...

s32_t	mount (spiffs_check_callback callback=0)
	Mount the file system. More...

void	unmount ()
	Unmount the file system. All file handles will be flushed of any cached writes and closed. More...

s32_t	mountAndFormatIfNecessary (spiffs_check_callback callback=0)
	Mount the file system and format if necessary.

s32_t	format ()
	Format the file system. More...

s32_t	erase ()
	Erase the sectors used by the file system. Obviously all data will be lost. More...

void	flush ()
	Flush all cached writes for all file handles, but leave the files open and the volume mounted. More...

s32_t	creat (const char *path, spiffs_mode mode=0777)
	Creates a new file. More...

spiffs_file	open (const char *path, spiffs_flags flags, spiffs_mode mode=0777)
	Opens or creates a file. More...

SpiffsParticleFile	openFile (const char *path, spiffs_flags flags, spiffs_mode mode=0777)
	Open a file and return a SpiffsParticleFile object to easily manipulate it using Arduino/Wiring style calls. More...

s32_t	read (spiffs_file fh, void *buf, s32_t len)
	Reads from given filehandle. More...

s32_t	write (spiffs_file fh, const void *buf, s32_t len)
	Writes to given filehandle. More...

s32_t	lseek (spiffs_file fh, s32_t offs, int whence)
	Moves the read/write file offset. More...

s32_t	eof (spiffs_file fh)
	Check if EOF reached. More...

s32_t	tell (spiffs_file fh)
	Get position in file. More...

s32_t	remove (const char *path)
	Removes a file by path. More...

s32_t	fremove (spiffs_file fh)
	Removes a file by filehandle. More...

s32_t	truncate (const char *path, s32_t len)
	Truncate a file by path. More...

s32_t	ftruncate (spiffs_file fh, s32_t len)
	Truncate a file by filehandle. More...

s32_t	stat (const char path, spiffs_stat s)
	Gets file status by path. More...

s32_t	fstat (spiffs_file fh, spiffs_stat *s)
	Gets file status by filehandle. More...

s32_t	fflush (spiffs_file fh)
	Flushes all pending write operations from cache for given file. More...

s32_t	close (spiffs_file fh)
	Closes a filehandle. If there are pending write operations, these are finalized before closing. More...

s32_t	rename (const char old, const char newPath)
	Renames a file. More...

s32_t	spiffs_errno ()
	Returns last error of last file operation.

void	spiffs_clearerr ()
	Clears last error. More...

spiffs_DIR *	opendir (const char name, spiffs_DIR d)
	Opens a directory stream corresponding to the given name. The stream is positioned at the first entry in the directory. On hydrogen builds the name argument is ignored as hydrogen builds always correspond to a flat file structure - no directories. More...

struct spiffs_dirent *	readdir (spiffs_DIR d, struct spiffs_dirent e)
	Reads a directory into given spifs_dirent struct. More...

s32_t	closedir (spiffs_DIR *d)
	Closes a directory stream. More...

s32_t	check ()
	Runs a consistency check on given filesystem. More...

s32_t	info (u32_t total, u32_t used)
	Returns number of total bytes available and number of used bytes. This is an estimation, and depends on if there a many files with little data or few files with much data. NB: If used number of bytes exceeds total bytes, a SPIFFS_check should run. This indicates a power loss in midst of things. In worst case (repeated powerlosses in mending or gc) you might have to delete some files. More...

bool	mounted ()
	Returns nonzero if spiffs is mounted, or zero if unmounted.

Static Public Member Functions
static void	infoLog (const char *fmt,...)
	Used internally to generate an info level log for app.spiffs.

static void	traceLog (const char *fmt,...)
	Used internally to generate an trace level log for app.spiffs.

Detailed Description

C++ wrapper for the SPIFFS library for the Particle platform.

Constructor & Destructor Documentation

◆ SpiffsParticle()

SpiffsParticle::SpiffsParticle ( SpiFlashBase & flash )

Create a SpiffsParticle file system object. Note that you must mount the file system before using it!

It's safe (and common) to create the SpiffsParticle object as a global variable.

Member Function Documentation

◆ check()

s32_t SpiffsParticle::check ( )

inline

Runs a consistency check on given filesystem.

This takes a while to run so you probably don't want to do this very often.

◆ close()

s32_t SpiffsParticle::close ( spiffs_file fh )

inline

Closes a filehandle. If there are pending write operations, these are finalized before closing.

Parameters

fh	the filehandle of the file to close

◆ closedir()

s32_t SpiffsParticle::closedir ( spiffs_DIR * d )

inline

Closes a directory stream.

Parameters

d	the directory stream to close

◆ creat()

s32_t SpiffsParticle::creat	(	const char *	path,
		spiffs_mode	mode = `0777`
	)

inline

Creates a new file.

Parameters

path	the path of the new file
mode	ignored, for posix compliance. This is an optional parameter.

Note that there are no subdirectories in SPIFFS and the maximum filename length is 32.

◆ eof()

s32_t SpiffsParticle::eof ( spiffs_file fh )

inline

Check if EOF reached.

Parameters

fh	the filehandle of the file to check

◆ erase()

s32_t SpiffsParticle::erase ( )

Erase the sectors used by the file system. Obviously all data will be lost.

This function returns error SPIFFS_ERR_MOUNTED if the file system is currently mounted; you must unmount it before erasing.

◆ fflush()

s32_t SpiffsParticle::fflush ( spiffs_file fh )

inline

Flushes all pending write operations from cache for given file.

Parameters

fh	the filehandle of the file to flush

It is not necessary to flush before close; close will flush any data if necessary.

◆ flush()

void SpiffsParticle::flush ( )

inline

Flush all cached writes for all file handles, but leave the files open and the volume mounted.

You'd typically do this before doing a stop mode sleep (pin + time) where the RAM contents are preserved but you want to make sure the data is saved. This saves having to mount the volume again.

If you are using SLEEP_MODE_DEEP you should use unmount() instead.

◆ format()

s32_t SpiffsParticle::format ( )

inline

Format the file system.

You typically do this when mount returns SPIFFS_ERR_NOT_A_FS. Note that you cannot format a valid file system, you'll need to erase the sectors first. Also, you must try mounting again after format.

◆ fremove()

s32_t SpiffsParticle::fremove ( spiffs_file fh )

inline

Removes a file by filehandle.

Parameters

fh	the filehandle of the file to remove

◆ fstat()

s32_t SpiffsParticle::fstat	(	spiffs_file	fh,
		spiffs_stat *	s
	)

inline

Gets file status by filehandle.

Parameters

fh	the filehandle of the file to stat
s	the stat struct to populate

You will typically only need the type and name fields of the stats structure. type is SPIFFS_TYPE_FILE or SPIFFS_TYPE_DIR name is the name (c-string)

◆ ftruncate()

s32_t SpiffsParticle::ftruncate	(	spiffs_file	fh,
		s32_t	len
	)

inline

Truncate a file by filehandle.

Parameters

fh	the filehandle of the file to remove
len	the length to truncate to

Note: In POSIX, len can be larger than the file size to make the file larger, but this does not work in SPIFFS. len must be less than or equal to the file size. See: https://github.com/pellepl/spiffs/issues/107

◆ info()

s32_t SpiffsParticle::info	(	u32_t *	total,
		u32_t *	used
	)

inline

Returns number of total bytes available and number of used bytes. This is an estimation, and depends on if there a many files with little data or few files with much data. NB: If used number of bytes exceeds total bytes, a SPIFFS_check should run. This indicates a power loss in midst of things. In worst case (repeated powerlosses in mending or gc) you might have to delete some files.

Parameters

total	total number of bytes in filesystem
used	used number of bytes in filesystem

◆ lseek()

s32_t SpiffsParticle::lseek	(	spiffs_file	fh,
		s32_t	offs,
		int	whence
	)

inline

Moves the read/write file offset.

Parameters

fh	the filehandle
offs	how much/where to move the offset. Can be negative.
whence	if SPIFFS_SEEK_SET, the file offset shall be set to offset bytes if SPIFFS_SEEK_CUR, the file offset shall be set to its current location plus offset if SPIFFS_SEEK_END, the file offset shall be set to the size of the file plus offset, which should be negative

Returns: Resulting offset is returned or negative if error.

◆ mount()

s32_t SpiffsParticle::mount ( spiffs_check_callback callback = 0 )

Mount the file system.

Returns: SPIFFS_OK (0) on success or a negative error code. The most common error is SPIFFS_ERR_NOT_A_FS (-10025) which means you need to format the file system.

Note that you must always try to mount the file system before performing any other operations, including format. It allocates buffers for the work buffer, file handles, and cache buffer, so you should do it early in setup if possible to make sure there is memory available.

In addition to the standard SPIFFS_ERR errors, the SpiffsParticle port can also return SPIFFS_ERR_OUT_OF_MEMORY if the buffers cannot be allocated during mount.

The memory allocated to buffers when mounting is:

Work buffers (2 * logical page size), default is 2 * 256 = 512
File descriptor buffers (32 * max open files), default is 32 * 4 = 128
Cache (logical page size + 32) * cachePages + 40 byte, default is (256 + 32) * 2 + 40 = 616

Thus the total RAM allocated during mount is by default is 1256 bytes.

◆ open()

spiffs_file SpiffsParticle::open	(	const char *	path,
		spiffs_flags	flags,
		spiffs_mode	mode = `0777`
	)

inline

Opens or creates a file.

Parameters

path	the path of the new file
flags	the flags for the open command, can be combinations of SPIFFS_O_APPEND, SPIFFS_O_TRUNC, SPIFFS_O_CREAT, SPIFFS_O_RDONLY, SPIFFS_O_WRONLY, SPIFFS_O_RDWR, SPIFFS_O_DIRECT, SPIFFS_O_EXCL
mode	ignored, for posix compliance. This is an optional parameter.

You can combine these options, so for example to create (if necessary) and open, use SPIFFS_O_CREAT|SPIFFS_O_RDWR.

Note that there are no subdirectories in SPIFFS and the maximum filename length is 32.

◆ opendir()

spiffs_DIR* SpiffsParticle::opendir	(	const char *	name,
		spiffs_DIR *	d
	)

inline

Opens a directory stream corresponding to the given name. The stream is positioned at the first entry in the directory. On hydrogen builds the name argument is ignored as hydrogen builds always correspond to a flat file structure - no directories.

Parameters

name	the name of the directory
d	pointer the directory stream to be populated

◆ openFile()

SpiffsParticleFile SpiffsParticle::openFile	(	const char *	path,
		spiffs_flags	flags,
		spiffs_mode	mode = `0777`
	)

inline

Open a file and return a SpiffsParticleFile object to easily manipulate it using Arduino/Wiring style calls.

Parameters

path	the path of the new file
flags	the flags for the open command, can be combinations of SPIFFS_O_APPEND, SPIFFS_O_TRUNC, SPIFFS_O_CREAT, SPIFFS_O_RDONLY, SPIFFS_O_WRONLY, SPIFFS_O_RDWR, SPIFFS_O_DIRECT, SPIFFS_O_EXCL
mode	ignored, for posix compliance. This is an optional parameter.

You can combine these options, so for example to create (if necessary) and open, use SPIFFS_O_CREAT|SPIFFS_O_RDWR.

Note that there are no subdirectories in SPIFFS and the maximum filename length is 32.

◆ read()

s32_t SpiffsParticle::read	(	spiffs_file	fh,
		void *	buf,
		s32_t	len
	)

inline

Reads from given filehandle.

Parameters

fh	the filehandle
buf	where to put read data
len	how much to read

Returns: number of bytes read, or -1 if error

◆ readdir()

struct spiffs_dirent* SpiffsParticle::readdir	(	spiffs_DIR *	d,
		struct spiffs_dirent *	e
	)

inline

Reads a directory into given spifs_dirent struct.

Parameters

d	pointer to the directory stream
e	the dirent struct to be populated

Returns: null if error or end of stream, else given dirent is returned

◆ remove()

s32_t SpiffsParticle::remove ( const char * path )

inline

Removes a file by path.

Parameters

path	the path of the file to remove

◆ rename()

s32_t SpiffsParticle::rename	(	const char *	old,
		const char *	newPath
	)

inline

Renames a file.

Parameters

old	path of file to rename
newPath	new path of file

◆ spiffs_clearerr()

void SpiffsParticle::spiffs_clearerr ( )

inline

Clears last error.

Parameters

fs	the file system struct

◆ stat()

s32_t SpiffsParticle::stat	(	const char *	path,
		spiffs_stat *	s
	)

inline

Gets file status by path.

Parameters

path	the path of the file to stat
s	the stat struct to populate

You will typically only need the type and name fields of the stats structure. type is SPIFFS_TYPE_FILE or SPIFFS_TYPE_DIR name is the name (c-string)

◆ tell()

s32_t SpiffsParticle::tell ( spiffs_file fh )

inline

Get position in file.

Parameters

fh	the filehandle of the file to check

◆ truncate()

s32_t SpiffsParticle::truncate	(	const char *	path,
		s32_t	len
	)

inline

Truncate a file by path.

Parameters

path	the path of the file to remove
len	the length to truncate to

Note: In POSIX, len can be larger than the file size to make the file larger, but this does not work in SPIFFS. len must be less than or equal to the file size.

◆ unmount()

void SpiffsParticle::unmount ( )

Unmount the file system. All file handles will be flushed of any cached writes and closed.

This also frees the file descriptor, work, and cache buffers.

◆ withCachePages()

SpiffsParticle& SpiffsParticle::withCachePages ( size_t value )

inline

Sets the desired not of cache pages (default: 2)

The cache requires (logical page size + 32) * cachePages + 40 bytes. For the default logical page size of 256 and cache pages of 2, this is 616 bytes allocated at mount time.

Note that you must call this before mount(). Calling it after will have no effect.

◆ withLogicalBlockSize()

SpiffsParticle& SpiffsParticle::withLogicalBlockSize ( size_t value )

inline

Sets the logical block size (default: 4096)

This can't be smaller than the physical block size or sector size (4096), but it could be larger. Making it larger might make sense if you have a small number of really large files, but usually 4096 is a reasonable value.

◆ withLogicalPageSize()

SpiffsParticle& SpiffsParticle::withLogicalPageSize ( size_t value )

inline

Sets the logical page size (default: 256)

This must be greater than or equal to the physical page size, which is typically 256 for most flash chips. Note that there's a work buffer of 2 * logical page size required for mounting a volume. It's rarely helpful to change this from the default, and it can't be larger than the logical block size, and doesn't really make any sense to make it larger than the physical block size (4096 bytes). So just leave it at 256.

◆ withLowLevelDebug()

SpiffsParticle& SpiffsParticle::withLowLevelDebug ( bool value = true )

inline

Enable (or disable) low level debug mode.

This mainly logs individual read and write calls. The SPIFFS file system likes to write two byte values as part of the magic, and low-level debug will print these out. If you're having weird file system corruption errors, using this along with enabling trace logging may be helpful.

◆ withMaxOpenFiles()

SpiffsParticle& SpiffsParticle::withMaxOpenFiles ( size_t value )

inline

Sets the maximum number of open files (default: 4)

Each open file descriptor requires 32 bytes of RAM. For the default of 4, this is 128 bytes allocated at mount time.

Note that you must call this before mount(). Calling it after will have no effect.

◆ withPhysicalBlockSize()

SpiffsParticle& SpiffsParticle::withPhysicalBlockSize ( size_t value )

inline

Sets the physical block size (default: 4096)

This is the size of the erase block, or the sector size in the SpiFlash class. It can't be smaller than the sector size, and it can't be larger than the logicalBlockSize, so pretty much 4096 is what you should leave it at.

◆ write()

s32_t SpiffsParticle::write	(	spiffs_file	fh,
		const void *	buf,
		s32_t	len
	)

inline

Writes to given filehandle.

Parameters

fh	the filehandle
buf	the data to write
len	how much to write

Returns: number of bytes written, or -1 if error

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

src/SpiffsParticleRK.h
src/SpiffsParticleRK.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ SpiffsParticle()

Member Function Documentation

◆ check()

◆ close()

◆ closedir()

◆ creat()

◆ eof()

◆ erase()

◆ fflush()

◆ flush()

◆ format()

◆ fremove()

◆ fstat()

◆ ftruncate()

◆ info()

◆ lseek()

◆ mount()

◆ open()

◆ opendir()

◆ openFile()

◆ read()

◆ readdir()

◆ remove()

◆ rename()

◆ spiffs_clearerr()

◆ stat()

◆ tell()

◆ truncate()

◆ unmount()

◆ withCachePages()

◆ withLogicalBlockSize()

◆ withLogicalPageSize()

◆ withLowLevelDebug()

◆ withMaxOpenFiles()

◆ withPhysicalBlockSize()

◆ write()