The 

SmartMesh network stack

 includes a file system that allows your application to persist its data in internal flash. The exposed API allows your application to create, delete, read and write files. Functions in the API also allow your application to obtain information about the file system's content and free space. The file system is flat, i.e. there are no directories. The application shares the file system with the 

SmartMesh network stack

 which uses it to store persistent settings and temporary files created during an Over-The-Air-Programming (OTAP) operation.

Features

The built-in file system incorporates the following features:

• Wear-Leveling: flash sectors needed for internal storage are chosen uniformly to increase longevity of the embedded flash.
• Fault-Tolerance: support for shadowed files guarantees that each individual write operation either completes, or does not occur at all, even in the face of power loss.

File Naming

The file system is flat and does not support directories. For that reason, each file needs to have a unique name, with a maximum of 12 characters. All file names must start with an single digit numeric identifier. Identifiers 0 and 1 are reserved for use by the stack, and the application should only access/create files starting with number 2. While non-printing characters are allowed after the starting character, we suggest using printable ASCII characters if filenames are to be human readable.

Examples:

File Types

An application that creates files has an option to specify whether the files should be shadowed or raw, depending on the requirements and access patterns. 

Shadowed Files

A write to a shadowed file is fault-tolerant. If an error occurs during the write operation, or power is lost, the file will remain in the unchanged state - as it was prior to the faulted write operation. To support such behavior, the file system creates a copy of each modified sector (a shadow) on every write. The old sector becomes unused only after the write completes successfully. While this operation provides a very convenient abstraction, the energy cost associated with each write may be significant. In the worst case, the underlying operation requires rewrite and/or erase of multiple sectors. 

Raw Files

Compared with shadowed files, raw files are not fault-tolerant. If a write fails or power is lost, the file may contain partial or otherwise corrupt data. The file system translates each write API call into a direct flash write. While the performance and energy cost of writes to raw file is smaller, the application must observe the following restrictions:

• Each word (4 bytes) in the file may be written at most once
• A write offset must be on a word (4 bytes) boundary
  

Raw files may be a good match for use cases such as logging of infrequent events, where data is only appended and never modified.

Temporary Files

Files marked as temporary will be automatically deleted from the file system upon mote start-up, and at the beginning of Over-The-Air-Programming (OTAP) session. 

If an OTAP transfer starts while a temporary file is in use, the application may get an access error as the file will be deleted. If this is a valid use case, your application should either be prepared to process such errors, or you should implement a command to suspend file system activity for the duration of OTAP operation.

Space Usage

Other notable limitations of the file system are:

• Maximum number of files that can be stored in the file system is 32 
• Maximum file length supported is 261632 bytes
• The file system requires 2 unused sectors for its operation

In general, your application should reserve 8 files and at least 10KB for use by the

SmartMesh network stack

 network stack. The rest can be used by your application and OTAP files.