1.. zephyr:code-sample:: settings
2   :name: Settings API
3   :relevant-api: settings settings_rt settings_name_proc
4
5   Load and save configuration values using the settings API.
6
7Overview
8********
9
10This is a simple application demonstrating use of the settings runtime
11configuration module. In this application some configuration values are loaded
12from persistent storage and exported to persistent storage using different
13settings method. The example shows how to implement module handlers, how to
14register them.
15
16Requirements
17************
18
19* A board with settings support, for instance: nrf52840dk/nrf52840
20* Or qemu_x86 target
21* A nvs_sector_size <= 0xFFFF
22
23Building and Running
24********************
25
26This sample can be found under :zephyr_file:`samples/subsys/settings` in
27the Zephyr tree.
28
29The sample can be built for several platforms, the following commands build the
30application for the qemu_x86.
31
32.. zephyr-app-commands::
33   :zephyr-app: samples/subsys/settings
34   :host-os: unix
35   :board: qemu_x86
36   :goals: run
37   :compact:
38
39After running the image to the board the output on the console shows the
40settings manipulation messages.
41
42Sample Output
43=============
44
45.. code-block:: console
46
47   ***** Booting Zephyr OS build v2.1.0-rc1-123-g41091eb1d5e0 *****
48
49   *** Settings usage example ***
50
51   settings subsys initialization: OK.
52   subtree <alpha> handler registered: OK
53   subtree <alpha/beta> has static handler
54
55   ##############
56   # iteration 0
57   ##############
58
59   =================================================
60   basic load and save using registered handlers
61
62   load all key-value pairs using registered handlers
63   loading all settings under <beta> handler is done
64   loading all settings under <alpha> handler is done
65
66   save <alpha/beta/voltage> key directly: OK.
67
68   load <alpha/beta> key-value pairs using registered handlers
69   <alpha/beta/voltage> = -3025
70   loading all settings under <beta> handler is done
71
72   save all key-value pairs using registered handlers
73   export keys under <beta> handler
74   export keys under <alpha> handler
75
76   load all key-value pairs using registered handlers
77   export keys under <beta> handler
78   export keys under <alpha> handler
79
80   =================================================
81   loading subtree to destination provided by the caller
82
83   direct load: <alpha/length/2>
84   direct load: <alpha/length/1>
85   direct load: <alpha/length>
86     direct.length = 100
87     direct.length_1 = 41
88     direct.length_2 = 59
89
90   =================================================
91   Delete a key-value pair
92
93   immediate load: OK.
94     <alpha/length> value exist in the storage
95   delete <alpha/length>: OK.
96     Can't to load the <alpha/length> value as expected
97
98   =================================================
99   Service a key-value pair without dedicated handlers
100
101   <gamma> = 0 (default)
102   save <gamma> key directly: OK.
103   ...
104