doc/subsystems/settings/settings.rst

.. _settings:

Settings subsystem with non-volatile storage
############################################

The settings subsystem gives modules a way to store persistent
per-device configuration and runtime state.

Settings items are stored as key-value pair strings.  By convention,
the keys can be organized by the package and subtree defining the key,
for example the key ``id/serial`` would define the ``serial`` configuration
element for the package ``id``.

Convenience routines are provided for converting a key value to
and from a string type.

Handlers
********

Settings handlers for subtree implement a set of handler functions.
These are registered using a call to ``settings_register()``.

**h_get**
    This gets called when asking for a settings element value
    by its name using ``settings_get_value()``.

**h_set**
    This gets called when the value is being set using ``settings_set_value()``,
    and also when setting is loaded from persisted storage with
    ``settings_load()``.

**h_commit**
    This gets called after the settings have been loaded in full.
    Sometimes you don't want an individual setting value to take
    effect right away, for example if there are multiple settings
    which are interdependent.

**h_export**
    This gets called to write all current settings. This happens
    when ``settings_save()`` tries to save the settings or transfer to any
    user-implemented back-end.

Persistence
***********

Backend storage for the settings can be either FCB, a file in the filesystem,
or both.

You can declare multiple sources for settings; settings from
all of these are restored when ``settings_load()`` is called.

There can be only one target for writing settings; this is where
data is stored when you call ``settings_save()``, or ``settings_save_one()``.

FCB read target is registered using ``settings_fcb_src()``, and write target
using ``settings_fcb_dst()``. As a side-effect,  ``settings_fcb_src()``
initializes the FCB area, so it must be called before calling
``settings_fcb_dst()``. File read target is registered using
``settings_file_src()``, and write target by using ``settings_file_dst()``.

Example: Device Configuration
*****************************

This is a simple example, where the settings handler only implements ``h_set``
and ``h_export``. ``h_set`` is called when the value is restored from storage
(or when set initially), and ``h_export`` is used to write the value to
storage thanks to ``storage_func()``. The user can also implement some other
export functionality, for example, writing to the shell console).

.. code-block:: c

    static int8 foo_val;

    struct settings_handler my_conf = {
        .h_name = "foo",
        .h_set = foo_settings_set,
        .h_export = foo_settings_export
    }

    static int foo_settings_set(int argc, char **argv, char *val)
    {
        if (argc == 1) {
            if (!strcmp(argv[0], "bar")) {
                return SETTINGS_VALUE_SET(val, SETTINGS_INT8, foo_val);
            }
        }

        return -ENOENT;
    }

    static int foo_settings_export(void (*storage_func)(char *name, char *val),
                               enum settings_export_tgt tgt)
    {
        char buf[4];

        settings_str_from_value(SETTINGS_INT8, &foo_val, buf, sizeof(buf));
        storage_func("foo/bar", buf)

        return 0;
    }

Example: Persist Runtime State
******************************

This is a simple example showing how to persist runtime state. In this example,
only ``h_set`` is defined, which is used when restoring value from
persisted storage.

In this example, the ``foo_callout`` function increments ``foo_val``, and then
persists the latest number. When the system restarts, the application calls
``settings_load()`` while initializing, and ``foo_val`` will continue counting
up from where it was before restart.

.. code-block:: c

    static int8 foo_val;

    struct settings_handler my_conf = {
        .h_name = "foo",
        .h_set = foo_settings_set
    }

    static int foo_settings_set(int argc, char **argv, char *val)
    {
        if (argc == 1) {
            if (!strcmp(argv[0], "bar")) {
                return SETTINGS_VALUE_SET(val, SETTINGS_INT8, foo_val);
            }
        }

        return -ENOENT;
    }

    static void foo_callout(struct os_event *ev)
    {
        struct os_callout *c = (struct os_callout *)ev;
        char buf[4];

        foo_val++;
        settings_str_from_value(SETTINGS_INT8, &foo_val, buf, sizeof(buf));
        settings_save_one("foo/bar", bar);

        k_sleep(1000);
        sys_reboot(SYS_REBOOT_COLD);
    }

API
***

The Settings subsystem APIs are provided by ``settings.h``:

.. doxygengroup:: settings
   :project: Zephyr