IoT File

nRF5 SDK v15.3.0

Table of Contents

This information applies to the following SoftDevice: S132

Our file abstract library provides a unified definition of calls for accessing any object, which can be treated as a file.

Applications can use this library as a common API for read and write operations. Currently there are two file ports defined:

  • Static memory port

The generic API is shown below:

API Description
iot_file_fopen Open the file instance with given size.
iot_file_fread Read given number of bytes from the file
iot_file_fwrite Write given number of bytes to the file.
iot_file_fseek Move file's cursor to given position.
iot_file_ftell Read actual cursor position.
iot_file_frewind Set file cursor position to the beginning of the file.
iot_file_fclose Close file, reset cursor.

Creating a new file port consists of a few steps:

  • Adding a file type definition inside iot_file_type_t enumeration (iot_file_port.h).
  • Defining port functions (like fopen/flcose). Each unspecified API call (assigning NULL) returns NRF_SUCCESS.
  • Creating a function for assigning API callbacks to a file instance.
  • Usually a port has one macro function (like IOT_FILE_PORTNAME_INIT) to provide a single call initialization for a user application.

Static memory access

In order to use the IoT File Static port, you need to include two files. One which includes the instance definition and API (file abstract) and another which defines the selected file type.

#incdlue "iot_file.h" // File instance and API definition.
#include "iot_file_static.h" // Definition of calls and assign function.

The second step is to define and initialize the file instance and components needed by that file type (like static buffer).

Note
Memory for file instance should be allocated and not freed during file use.
static iot_file_t m_file; // New file instance.
static uint8_t m_file_memory[256]; // Memory allocated for static file instance.
int main( void )
{
...
IOT_FILE_STATIC_INIT (&m_file, "static_mem.dat" , m_file_memory, 256); // Assignment of static memory and file API calls.
...
}

The file API can now be used for accessing the assigned buffer.

void app_file_play( void )
{
// Store data.
iot_file_fopen (&m_file, 256);
iot_file_fwrite (&m_file, "Hello!" , 6);
iot_file_fclose (&m_file);
// Read data.
uint8_t buffer[5];
iot_file_fopen (&m_file, 0); // Pass 0 to use the previous file size.
iot_file_fread (&m_file, buffer, sizeof (buffer));
iot_file_fclose (&m_file);
// Append data.
iot_file_fopen (&m_file, 0);
iot_file_fseek (&m_file, m_file. file_size );
iot_file_fwrite (&m_file, "EOF" , 3);
iot_file_fclose (&m_file);
// Write data, then read it.
uint8_t buffer[10];
uint32_t cursor;
iot_file_fopen (&m_file, 0);
iot_file_ftell (&m_file, &cursor); // Remember the cursor position.
iot_file_fwrite (&m_file, "Data!" , 5);
iot_file_fseek (&m_file, cursor); // Restore the cursor position.
iot_file_fread (&m_file, buffer, sizeof (buffer));
iot_file_fclose (&m_file);
}

Configuration parameters

The following configuration parameters should be defined in sdk_config.h .

IOT_FILE_DISABLE_LOGS

Disables debug tracing in the module. To enable tracing, this flag must be set to 0 and NRF_LOG_ENABLED must be set to 1.

Description Value
Enable debug trace 0
Disable debug trace 1
Dependencies NRF_LOG_ENABLED

IOT_FILE_DISABLE_API_PARAM_CHECK

Disables API parameter checks in the module. Set this define to 1 to disable checks on API parameters in the module.

API parameter checks are added to ensure that the correct parameters are passed to the module. These checks are useful during development phase, but they might be redundant when the application is finalized. Disabling these checks might improve performance.

Description Value
Enable API parameters check 0
Disable API parameters check 1
Dependencies None

Specifics and limitations

The following sections describe the specifics and limitations of the current implementation.

Implemented features

  • Synchronous and asynchronous API.
  • RAM memory access port with many instances.
  • RAW flash memory access port with many instances.

Limitations

  • RAW flash port requires memory manager.
  • There is no file port for accessing data in flash memory. It is stored by the regular version of the PStorage module.