SpiffsParticleRK
Public Member Functions | Static Public Member Functions
SpiffsParticle Class Reference

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...
 
SpiffsParticlewithPhysicalSize (size_t value)
 Sets the size of the flash file system in bytes, relative to the physical start address.
 
SpiffsParticlewithPhysicalAddr (size_t value)
 Sets the start address in the flash for the file system (default: 0)
 
SpiffsParticlewithPhysicalBlockSize (size_t value)
 Sets the physical block size (default: 4096) More...
 
SpiffsParticlewithLogicalBlockSize (size_t value)
 Sets the logical block size (default: 4096) More...
 
SpiffsParticlewithLogicalPageSize (size_t value)
 Sets the logical page size (default: 256) More...
 
SpiffsParticlewithMaxOpenFiles (size_t value)
 Sets the maximum number of open files (default: 4) More...
 
SpiffsParticlewithCachePages (size_t value)
 Sets the desired not of cache pages (default: 2) More...
 
SpiffsParticlewithLowLevelDebug (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_DIRopendir (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_direntreaddir (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
fhthe filehandle of the file to close

◆ closedir()

s32_t SpiffsParticle::closedir ( spiffs_DIR d)
inline

Closes a directory stream.

Parameters
dthe directory stream to close

◆ creat()

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

Creates a new file.

Parameters
paththe path of the new file
modeignored, 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
fhthe 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
fhthe 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
fhthe filehandle of the file to remove

◆ fstat()

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

Gets file status by filehandle.

Parameters
fhthe filehandle of the file to stat
sthe 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
fhthe filehandle of the file to remove
lenthe 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
totaltotal number of bytes in filesystem
usedused 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
fhthe filehandle
offshow much/where to move the offset. Can be negative.
whenceif 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
paththe path of the new file
flagsthe 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
modeignored, 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
namethe name of the directory
dpointer 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
paththe path of the new file
flagsthe 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
modeignored, 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
fhthe filehandle
bufwhere to put read data
lenhow 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
dpointer to the directory stream
ethe 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
paththe path of the file to remove

◆ rename()

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

Renames a file.

Parameters
oldpath of file to rename
newPathnew path of file

◆ spiffs_clearerr()

void SpiffsParticle::spiffs_clearerr ( )
inline

Clears last error.

Parameters
fsthe file system struct

◆ stat()

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

Gets file status by path.

Parameters
paththe path of the file to stat
sthe 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
fhthe filehandle of the file to check

◆ truncate()

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

Truncate a file by path.

Parameters
paththe path of the file to remove
lenthe 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
fhthe filehandle
bufthe data to write
lenhow much to write
Returns
number of bytes written, or -1 if error

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