nuttx-apps/system/settings/readme.md

Introduction

The settings storage can be used to store and retrieve various configurable parameters. This storage is a RAM-based map (for fast access), but one or more files can be used too (so values can persist across system reboots).

This is a thread-safe implementation. Different threads may access the settings simultaneously.

Setting Definition

Each setting is a key/value pair.

The key is always a string, while there are many value types supported.

Strings

All strings, whether they represent a key or a string value, must use a specific format. They must be ASCII, NULL-terminated strings, and they are always case-sensitive. They must obey to the following rules:

• they cannot start with a number.
• they cannot contain the characters '=', ';'.
• they cannot contain the characters '\n', '\r'.

Setting Type

Since each setting has its own type, it is the user's responsibility to access the setting using the correct type. Some "casts" are possible (e.g. between bool and int), but generally reading with the wrong type will lead to failure.

The following types are currently supported.

• String.
• int
• bool
• ip address
• float

Setting Storage Size

Kconfig is used to determine the size of the various fields used:

• CONFIG_SYSTEM_SETTINGS_MAP_SIZE     the total number settings allowed
• CONFIG_SYSTEM_SETTINGS_MAX_STORAGES the number of storage files that can be used
• CONFIG_SYSTEM_SETTINGS_VALUE_SIZE   the storage size of a STRING value
• CONFIG_SYSTEM_SETTINGS_KEY_SIZE     the size of the KEY field
• CONFIG_SYSTEM_SETTINGS_MAX_FILENAME the maximum filename size

Signal

A POSIX signal can be chosen via Kconfig and is used to send notifications when a setting has been changed. <CONFIG_SYSTEM_SETTINGS_MAX_SIGNALS> is used to determine the maximum number of signals that can be registered for the settings storage functions.

Files

There are also various types of files that can be used. Each file type is using a different data format to parse the stored data. Every type is expected to be best suited for a specific file system or medium type, or be better performing while used with external systems. In any case, all configured files are automatically synchronized whenever a value changes.

Cached Saves

It is possible to enable cached saves, via Kconfig, along with the time (in ms) that should elapse after the last storage value was updated before a write to the file or files should be initiated.

Storage Types

The current storage types are defined in and are as follows.

STORAGE_BINARY

Data is stored as "raw" binary. Bool, int and float data are stored using the maximum number of bytes needed, as determined by the size of the union used for these settings; this will be architecture dependent.

STORAGE_TEXT

All data is converted to ASCII characters making the storage easily human-readable.

Usage

Most common

This is the usual sequence of calls to use the settings utility.

1. Call settings_init();
2. Call settings_setstorage("path", storage_type); for every/any file storage in use

• for example settings_setstorage("/dev/eeprom", STORAGE_EPROM);

3. Call settings_create(key_name, settings_type, default value) for every setting required
4. settings_notify().

• for example settings_create("KEY1", SETTINGS_STRING, "Hello");

5. If a settings value needs to be read, call the variadic function settings_get(key_name, settings_type, &variable, size);. "size" is only needed for STRING types.

• for example settings_get("KEY1", SETTINGS_STRING, &read_str, sizeof(readstr));

6. If a settings value needs to be changed, call the variadic function settings_set(key_name, settings_type, &value, size); "size" is only needed for STRING types.

• for example settings_set("KEY1", SETTINGS_STRING, &new_string);

Other functions

Other functions exist to assist the user program.

1. settings_sync(wait_dump). This will synchronise the settings between file storages if more than 1 are in use. if cached saves are enabled, the wait_dump parameter, if true, will force the sync function to wait until any saves are actually written out.
2. settings_iterate(idx, &setting). This gets a copy of a setting at the specified position. It can be used to iterate over the entire settings map, by using successive values of idx.
3. settings_type(key_name, &type). Gets the type of a given setting.
4. settings_clear(). Clears all settings and sata in all storages is purged.
5. settings_hash(&hash). Gets the hash of the settings storage. This hash represents the internal state of the settings map. A unique number is calculated based on the contents of the whole map. This hash can be used to check the settings for any alterations: i.e. any setting that may had its value changed since last check.

Error codes

The settings functions provide negated error return codes that can be used as required by the user application to deal with unexpected behaviour.

Example App

There is an example app available to demonstrate the usage of many of the settings features CONFIG_EXAMPLES_SETTINGS.