IoT File

Table of Contents

• Static memory access
• Flash memory access
• Configuration parameters
  • IOT_FILE_DISABLE_LOGS
  • IOT_FILE_DISABLE_API_PARAM_CHECK
• Specifics and limitations
  • Implemented features
  • Limitations

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
• PStorage RAW 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);

}

Flash memory access

The flash memory access file port shows how to use the file abstract for memory that requires an asynchronous API. In order to support that, the file abstract defines the event structure (iot_file_evt_t) where the file port assigns a user callback that is passed during initialization of the specified file instance. Currently the IoT SDK supports the PStorage RAW port of file abstraction, presented below.

Initialization:

#include "iot_file.h"
#include "iot_file_pstorage_raw.h"
#include "mem_manager.h"

static iot_file_t m_file;

void app_file_cb(iot_file_t * p_file, iot_file_evt_t event, uint32_t result, void * p_data, uint32_t size);

int main(void)
{
    ...
    nrf_sdk_mem_init();
    IOT_FILE_PSTORAGE_RAW_INIT(&m_file, "flash.dat", 0x4D000, app_file_cb);
    ...
}

The callback can be defined to create a chain of operations (like fopen-fread-fclose), to notify the application when data is ready, or to unlock another procedure. In the following example the static variable m_lock is used to wait for completion.

Note

The following example shows when a read and write operation is asynchronous, and we have to wait for a completion event.

#define ERROR    2
#define LOCKED   1
#define UNLOCKED 0

static uint32_t   m_lock;

// File callback which modifies operation lock.
void app_file_cb(iot_file_t * p_file, iot_file_evt_t event, uint32_t result, void * p_data, uint32_t size)
{
    switch(event)
    {
        IOT_FILE_OPENED:
        IOT_FILE_WRITE_COMPLETE:
        IOT_FILE_READ_COMPLETE:
        IOT_FILE_CLOSED:
            if (result == NRF_SUCCESS)
            {
                m_lock = UNLOCKED;
                break;
            }
        IOT_FILE_ERROR:
        default:
            m_lock = ERROR;
            break;
    }
}

void read_file(void)
{
    uint8_t buffer[100];

    m_lock = LOCKED;
    iot_file_fopen(&m_file, 0x1000);
    while (m_lock == LOCKED)
    {
        ; // Wait for completion.
    }

    if (m_lock != UNLOCKED)
    {
        //handle error
    }

    m_lock = LOCKED;
    iot_file_fread(&m_file, buffer, 100);
    while (m_lock == LOCKED)
    {
        ; // Wait for completion.
    }

    if (m_lock != UNLOCKED)
    {
        //handle error
    }

    m_lock = LOCKED;
    iot_file_fclose();
    while (m_lock == LOCKED)
    {
        ; // Wait for completion.
    }

    if (m_lock != UNLOCKED)
    {
        //handle error
    }
}

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 ENABLE_DEBUG_LOG_SUPPORT must be set to 1.

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

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.