docs/guides/nrfconnect_examples_configuration.md

   1 # Configuring nRF Connect SDK examples
   2
   3 The nRF Connect SDK example applications all come with a default configuration
   4 for building. Check the information on this page if you want to modify the
   5 application configuration or add new functionalities to build your own
   6 application based on the provided example. This page also contains information
   7 about the configuration structure, which can be useful to better understand the
   8 building process.
   9
  10 This guide can be used with the following examples:
  11
  12 -   [CHIP nRF Connect Lock Example Application](../../examples/lock-app/nrfconnect/README.md)
  13 -   [CHIP nRF Connect Lighting Example Application](../../examples/lighting-app/nrfconnect/README.md)
  14 -   [CHIP nRF Connect Pigweed Example Application](../../examples/pigweed-app/nrfconnect/README.md)
  15
  16 <hr>
  17
  18 ## Configuring application
  19
  20 Changing the default application configuration can be done either temporarily or
  21 permanently. Changing configuration temporarily is useful for testing the impact
  22 of changes on the application behavior. Making permanent changes is better if
  23 you want to develop your own application, as it helps avoid repeating the
  24 configuration process.
  25
  26 <hr>
  27
  28 ### Temporary changes to configuration
  29
  30 You can change the configuration temporarily by editing the `.config` file in
  31 the `build/zephyr/` directory, which stores all configuration options for the
  32 application generated as a result of the build process. As long as you do not
  33 remove the current build directory or delete this file, your changes will be
  34 kept. However, if you do a clean build, your changes are gone, so it is not
  35 possible to save changes permanently this way.
  36
  37 Complete the following steps:
  38
  39 1.  Build the application by typing the following command in the example
  40     directory, with _build-target_ replaced with the build target name of the
  41     kit, for example _nrf52840dk_nrf52840_:
  42
  43          $ west build -b build-target
  44
  45 2.  Run the terminal-based interface called menuconfig by typing the following
  46     command:
  47
  48          $ west build -t menuconfig
  49
  50     The menuconfig terminal window appears, in which you can navigate using
  51     arrow keys and other keys, based on the description at the bottom of the
  52     window.
  53
  54 3.  Make the desired changes by following the menuconfig terminal instructions.
  55 4.  Press `Q` to save and quit.
  56 5.  Rebuild the application.
  57
  58 At this point, the configuration changes are applied to the output file and it
  59 can be flashed to the device.
  60
  61 <hr>
  62
  63 ### Permanent changes to configuration
  64
  65 The permanent solution is based on modifying the Kconfig configuration files,
  66 which are used as components of the building process. This makes the changes
  67 persistent across builds.
  68
  69 The best practice to make permanent changes is to edit the main application
  70 configuration file `prj.conf`, which is located in the example directory. This
  71 will result in overriding the existing configuration values.
  72
  73 This method is valid for the majority of cases. If you are interested in
  74 understanding the big picture of the configuration process, read the
  75 [Configuration structure overview](#configuration-structure-overview) section
  76 below.
  77
  78 #### Assigning values to Kconfig options
  79
  80 Assigning value to a configuration option is done by typing its full name
  81 preceded by the `CONFIG_` prefix, and adding the `=` mark and the value.
  82
  83 Configuration options have different types and it is only possible to assign
  84 them values of proper type. Few examples:
  85
  86 -   Assigning logical boolean true value to the option:
  87     `CONFIG_SAMPLE_BOOLEAN_OPTION=y`
  88 -   Assigning numeric integer 1234 value to the option:
  89     `CONFIG_SAMPLE_INTEGER_OPTION=1234`
  90 -   Assigning text string "some_text" value to the option:
  91     `CONFIG_SAMPLE_STRING_OPTION="some_text"`
  92
  93 For more detailed information, read about
  94 [setting Kconfig values](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/zephyr/guides/kconfig/setting.html#setting-configuration-values)
  95 in the nRF Connect SDK documentation.
  96
  97 Because Kconfig configuration files are used in the building process, make sure
  98 that you rebuild your application after editing them by typing the following
  99 command in the example directory, with _build-target_ replaced with the build
 100 target name of the kit, for example _nrf52840dk_nrf52840_:
 101
 102         $ west build -b build-target
 103
 104 <hr>
 105
 106 <a name="configuration-structure-overview"></a>
 107
 108 ## Configuration structure overview
 109
 110 Zephyr RTOS and related software components, like drivers and libraries, provide
 111 a set of Kconfig files which define available configuration options and assign
 112 them default values for any application.
 113
 114 The application configuration is specified using Kconfig configuration files
 115 (`*.conf`), where available Kconfig options can be used and their default values
 116 overrided. Typically, there are many files having impact on the final
 117 configuration shape.
 118
 119 There is no need to modify all these files separately. See the following list
 120 for types of files you can find in the project and which of them are important
 121 from your perspective:
 122
 123 -   **Build target configuration files.** These are hardware-platform-dependent
 124     configuration files, which are automatically included based on the
 125     compilation build target name. They contain configuration for the kit and
 126     its peripherals.
 127
 128 -   **Project configuration file.** Every example application has its main
 129     configuration file called `prj.conf` that is located in the example
 130     directory. This file contains application-specific configuration or the most
 131     frequently changed options. Almost every configuration can be overridden in
 132     this file and probably this file is the most important one.
 133
 134 -   **Overlays.** Overlays are optional files usually used to extract
 135     configuration for some specific case or feature from the general application
 136     configuration. The main difference between them and the application
 137     `prj.conf` file is that they are not included automatically, so you can
 138     decide whether to build sample with or without them. Overlay files can be
 139     added to build by typing the following command in the example directory,
 140     with _build-target_ replaced with the build target name (e.g.
 141     _nrf52840dk_nrf52840_) and _overlay_file_name_ replaced with the overlay
 142     configuration file name (e.g. _overlay-usb_support.conf_):
 143
 144           $ west build -b build-target -- -DOVERLAY_CONFIG=overlay_file_name
 145
 146 Read the
 147 [Kconfig](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/zephyr/guides/kconfig/index.html#kconfig)
 148 guide in the nRF Connect SDK's Zephyr documentation if you are interested in
 149 getting more advanced and detailed information about the configuration
 150 structure.