How do I add another board and .conf file to an existing project?

I have been working with some code for a nrf5340 DK and now want to add a custom board to the project as an additional build configuration, but I need to now pull out configurations which are set in the prj.conf as they conflict. For example the dk uses a st7789 display and the custom board uses a gc9a01. In my prj.conf I have CONFIG_ST7789V=y which now should not be in the prj.conf but a specific conf for the configured DK.

I had the dk overlay in the root directory. Do I create another directory under boards for my specific configuration of the DK and create a .conf file for it? Will that make it get automatically picked up? Since it's a nrf5340 dk, should I name the directory something else as not to conflict with the existing structure? By naming the conf file the same as the overlay (just different extension, conf vs overlay) does that mean it will get picked up? 
By putting the overlay in a different directory and referencing it in the build, does zephry know to look for a corresponding conf file automatically? 

This might be simple, but I haven't found a good explanation of this specific process which a novice like me could consume.

I'm using vs code and nrf connect (2.6) and zephyr.

  • Hi lcj,

    For the specific purpose of setting up Devicetree and Kconfig for some specific boards, please check out the Permanent configuration changes to child images in this page: Multi-image builds — nRF Connect SDK 2.6.0 documentation (
    Even though you might not be using Multi-image build, it describes how use <board>.conf and <board>.overlay files to achieve what you want.
    Almost all projects will want to use DFU, at which point, you will have Multi-image build anyway.

    For how to use some generic Devicetree and Kconfig files that are only used in certain builds, please refer to these links:
    Setting Kconfig configuration values — Zephyr Project documentation (nRF Connect SDK) (
    Devicetree HOWTOs — Zephyr Project documentation (nRF Connect SDK) (

    For all the links above, if time allows, I recommend giving their entire parent topic a read, not just the specific sections I linked.


  • Ok. These are good links. Thank you. I do need to understand the process more completely and will read through them. I don't know if what I'm doing is considered a child image.

    The second link includes coverage of _deconfig, which may be an option, but it's not really in the overlay is not in the boards directory because I'm using a DK. The third link covers the overlay, which is what I'm using. I suppose it's a legitimate question to ask if I am creating a prototype using a nrf5340 dk, do I create a directory in boards if I'm going to test on other similar boards, as I am doing now and evolve the prototype into a custom board.

    For one build I have a nrf5340dk_nrf5340_cpuapp.overlay in the root and I was wondering if I created a nrf5340dk_nrf5340_cpuapp.conf in root if it would get merged with the prj.conf. This way the CONFIG_ST7789V=y line could be moved out of the prj.conf and into the nrf5340dk_nrf5340_cpuapp.conf and not interfere with the configuration of the 2nd build.

    I will need to know how to create a custom board, but I built my code on a dk with a certain configuration and am now trying to see if it works on board somebody else built.

    This link which you provided seemed the most helpful. I think this falls into the application configuration category. Maybe I need to do #2 "Otherwise, prj_<BOARD>.conf is used if it exists in the application configuration directory.", if the application configuration directory is the root with the prj.conf in it.


    I read How to Optimize Zephyr Configuration and Overlays which was helpful as well.

  • Hello,

    In our Developer Academy tutorial, there is a chapter explaining how to add custom board support to the nRF Connect SDK. You can find exercises on creating new board definitions and hardware specifications.

    Kind Regards,


  • I went through the tutorial. It was very helpful. I still am left with questions. I see three scenarios I need to support: 

    1. Prototype on a DK
    2. Use an existing custom board
    3. Create my own custom board

    My question is moving from scenario 1 to 2 I need to alter the configuration to support both. There are some things I have in the prj.conf which I put in there to support the DK, which I still want to support. However, they also conflict with the existing custom board configuration, such as the display (ST7789 on the prototype and GC9A01A on the custom board). Therefore, the current setting of CONFIG_ST7789V=y in the prj.conf needs to be moved out into a configuration file which is only used if the nrf5340dk is used.

    It seems like the prj.conf should be used for any configuration required for all board configurations (in this example dk, existing custom, personal custom). There are custom configuration options in the existing custom board, but I should not mess with too many of them. So how do I have a configuration file for each of the three scenarios above? A board specific configuration I can control. It may only be required for the first one but in that case should not be in the prj.conf. So where does it go and what is it named?

    I referenced this link in my previous reply which I believe means that a file in the application root named:

    I believe it would get incorporated, but the language is hard to decipher:

    2. Otherwise, prj_<BOARD>.conf is used if it exists in the application configuration directory.

    Does that mean it gets merged as "otherwise" seems to imply it's used in place of the prj.conf.

    When I add the prj_nrf5340dk_nrf5340_cpuapp.conf I didn't see it merge when building. I see no reference to it but I do se:

    Loaded configuration '/opt/nordic/ncs/v2.5.2/zephyr/boards/arm/nrf5340dk_nrf5340/nrf5340dk_nrf5340_cpuapp_defconfig'
    Merged configuration '/Users/lj/Projects/GitHub/lj/xprototype/prj.conf'

  • The Dev Academy coverage on creating custom boards is great, btw, but I would love a little more depth on this topic. What would help me is the file structure for a project with multiple builds, each one targeting a different board. One board would be the DK with some peripheral attached, like a display, for a prototype. The second one would be a custom board, as discussed in the Dev Academy scenario.

    It would show how the an overlay and conf file for each option along with a prj.conf. As the Dev Academy coverage of a custom board shows, there would be a conf and overlay file created in the custom board directory.

    For the prototype DK the overlay default seems to be in the root and I don't know where the conf file is. When you create a new project the conf file is the prj.conf, but when you add the 2nd board, a customized board in this case, where do you put the settings for the original board if you need to pull them out of the prj.conf?

    I read the link on configuration and tried to replicate, but a visual of the directory structure would be super helpful. I'm assuming the prj.conf would be merged with the prototype/dk board when that build is selected and merged with the custom board when that is selected. I just haven't been able to get it to work.