SDK 3.0.0 custom board definition

[Tiit]

I'm having trouble porting my project from the older SDK (2.6.0) to the new SDK. 

I thought the most straightforward way to do that would be to start with a sample project similar to what I want to do. So I took the Matter Window Cover Sample. I have the nRF54L15-DK so I compiled the project for that board and it seems to work.

Now I use the VSCode button to create a new board. After closing VSCode and opening it again I can select my new custom board as the target for the build. It fails as my custom board is pretty much just boilerplate empty board definitions. So I start copying the contents of the nRF54L15-DK board definitions to my own custom board folder. The aim being to get the project to compile for the same dev kit with my custom board as the target. Ideally I would make no changes to the files but due to custom name I still have to do that. This also means I have to make another partition manager static definition file. I just copy the one used for the DK build and rename it for my custom board.

After fighting with some very hard to fix devicetree errors I get compilation process to reach the partition manager stage and there is something weird happening there. I have the exact same contents for the static definition file as the DK but for my board the build fails complaining about too many gaps in the partitions. I'm attaching the actual file I use for this.

pm_static_blindy_v3_nrf54l15_cpuapp.zip

The error I get from partition manager is this:

-- Found partition manager static configuration : /home/tiit/code/nordic/blindy_matter/pm_static_blindy_v3_nrf54l15_cpuapp.yml
Partition 'mcuboot' is not included in the dynamic resolving since it is statically defined.
Partition 'mcuboot_pad' is not included in the dynamic resolving since it is statically defined.
Partition 'mcuboot_primary' is not included in the dynamic resolving since it is statically defined.
Partition 'mcuboot_primary_app' is not included in the dynamic resolving since it is statically defined.
Partition 'settings_storage' is not included in the dynamic resolving since it is statically defined.
Partition 'mcuboot_secondary' is not included in the dynamic resolving since it is statically defined.
Partition manager failed: Incorrect amount of gaps found in static configuration. There must be exactly one gap in the static configuration to support placing the dynamic partitions (such as 'app'). Gaps found (2):0xd800-0x165000 0x17d000-0x172000 The most common solution to this problem is to fill the smallest of these gaps with statically defined partition(s) until there is only one gap left. Alternatively re-order the already defined static partitions so that only one gap remains.
Failed to partition region flash_primary, size of region: 1462272
Partition Configuration:
app:
  size: 1460224
factory_data:
  size: 4096
mcuboot:
  size: 53248
mcuboot_pad:
  size: 2048
mcuboot_primary:
  size: 1462272
mcuboot_primary_app:
  size: 1460224
settings_storage:
  size: 40960

-- Configuring incomplete, errors occurred!

Can you please check what I'm doing wrong here to cause this. This is somehow caused by using the custom board definition. I'm also attaching the whole custom board folder here just in case you can see something weird in there. This is just the folder that has to be extracted into the boards folder and after a VSCode restart it appears as a target for the build.

soma.zip

Hoping to hear back from you after the Easter Holidays,

Tiit

[AHaug]

Hello Tiit,

A couple of starting points here before I get back to you early in the coming week,

1. You state that you've based your project on the Matter window cover sample, is this from 2.6.0 or is it from a newer version of NCS (if so which version are you referring to with "to the new SDK"?  Nonetheless, there will be quite a few changes between 2.6.0 and 2.9.1 or 3.0.0 (of those are the versions you're referring to), so we'll just go through the hoops until we get there.
   
   
2. The first thing I would like you to verify is the hardware model you're using. Since you're based on 2.6.0 I assume it is hwm2, but could you verify if you've gone through the steps here? https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/releases_and_maturity/migration/migration_hwmv2.html 
   
   
3. The next is, which revision of the nRF54L15 SoC are you using? I.e what I'm asking is if your SoC revision is compatible with the SDK version you intend to use
   

• I just copy the one used for the DK build and rename it for my custom board.
I would say that this is the way to go, unless there are certain things that are set up in the nrf54l15Dk's board files that you've not attached somehow. Could you verify if you've done the following:
1. Build the window cover sample for the nrf54l15dk
2. Checked the generated partitions.yml located within build (or build/your_app/ or build/your_app/zephyr I can't quite remember, but there should only be one)
3. Copy the contents of that and attach in a static partitioning file that your custom board will use
4. Since you're migrating from child/parent images used in NCS 2.6.0 I would also recommend you to have a look at the sysbuild academy lesson unless you've already done so: https://academy.nordicsemi.com/courses/nrf-connect-sdk-intermediate/lessons/lesson-8-sysbuild/topic/sysbuild-explained/ 

Let me know about this and I'll get back to you when I get back in office next week

Kind regards,
Andreas

[Tiit]

Hi Andreas,

Thank you for getting back to me so fast and sorry I wasn't able to respond sooner.

1. I used VSCode to install SDK 3.0.0 and created a new application from the example included with that (using the built in button for that). I changed nothing in that example and built it for my nRF54L15-DK. This worked and I was able to flash and add the device to Alexa through the Echo with Matter support (it did complain about the device not being certified but that is normal as I understand).

2. My original code is based on SDK 2.5.0 with some changes it does work with 2.6.0 and that is what I have been using to develop the Matter branch of our firmware. There are still issues with that but the Matter build itself works and can also be added to most Matter controllers with the warning about certification. I spent two days trying to port that to SDK 3.0.0 without luck. So in frustration I decided to just take the clean example from 3.0.0 and get that example to build on my custom board as a starting point. I have a button and an RGB led on my board so the example should be very close to compatible. I also have the exact same external memory chip and had experience with doing a similar thing when we first started our firmware on 2.5.0. Now I'm guessing the hardware model thing should be correct when I start from the example in 3.0.0. SO what I want to do first is take the code that is working on the dev board and get this to compile on a custom board that still describes the exact same dev board. I'm not sure if I'm explaining this right. What I want to do is compile the clean example code but instead of selecting "nrf54l15dk/nrf54l15/cpuapp" I want to select "blindy_v3/nrf54l15/cpuapp". I clicked create new board and named it "blindy_v3". This created the board and I can select it as the target. But this fails because the board created is pretty much empty. Now I tried copying in all the required things from the SDK folders that defined the devkit but it still fails to build.

3. I think my dev kit has the engineering sample. The markings on the chip say QFAABB. The sticker on the dev kit says PCA10156, 0.9.1, 2024.44

The example does build and it does generate the partitions.yml file. But there is already a static partition file that is defined for each board in the project folder and I copied the one for the DK with no changes and I can see in the build process that the correct file does get included (Found partition manager static configuration :/home/tiit/code/nordic/blindy_matter/pm_static_blindy_v3_nrf54l15_cpuapp.yml). Should I just replace that with the one from the successful DK build? If so - why would it not work with the copy that works for the DK build? I would feel hesitant using this in production without understanding the reason for the problem.

4. I will definitely take a look. I did use sysbuild for the Matter version already but I don't really understand it. I just know that whenever I make a build configuration I have to select sysbuild or things will fail in weird and interesting ways.

Tiit

[AHaug]

Hi Tiit,

Thank you for elaborating

Tiit said:

1. I used VSCode to install SDK 3.0.0 and created a new application from the example included with that (using the built in button for that). I changed nothing in that example and built it for my nRF54L15-DK. This worked and I was able to flash and add the device to Alexa through the Echo with Matter support (it did complain about the device not being certified but that is normal as I understand).

All here sounds good to me

Tiit said:

I spent two days trying to port that to SDK 3.0.0 without luck

From 2.5 to 3.0 there are several significant changes in the SDK, including Matter, so yeah.. I understand the struggle when doing such a big leap.

Tiit said:

Now I'm guessing the hardware model thing should be correct when I start from the example in 3.0.0.

Correct, the default from 2.7.0 and is Hwm2.

Tiit said:

'm not sure if I'm explaining this right.

I'm following.

Tiit said:

But this fails because the board created is pretty much empty. Now I tried copying in all the required things from the SDK folders that defined the devkit but it still fails to build.

I think this topic in our academy pages might be exactly what we need: https://academy.nordicsemi.com/courses/nrf-connect-sdk-intermediate/lessons/lesson-3-adding-custom-board-support/. Could you have a look through here and see if there's something you've missed when creating the files for your custom board based on the DK?

Tiit said:

3. I think my dev kit has the engineering sample. The markings on the chip say QFAABB. The sticker on the dev kit says PCA10156, 0.9.1, 2024.44

That should be within the supported devices, so the issue you're seeing should not be due to the revision not being too old.

Tiit said:

Should I just replace that with the one from the successful DK build?

I would recommend this as a starting point to verify that it works with that memory layout and then move to something more custom for your use case and your custom board in case required

Tiit said:

If so - why would it not work with the copy that works for the DK build? I would feel hesitant using this in production without understanding the reason for the problem.

Could you clarify one thing for me; what would not work with the copy for the successfull DK build? There are a few versions up in the air at this point in our discussion. For instance

• Custom board with sample from 3.0.0 with overlay from DK built successfully with 3.0.0
• Custom board with sample from 2.5.0 ported to 3.0.0 with overlay from DK built successfully with 3.0.0
• Custom board with sample from 3.0.0 with overlay from DK built successfully from 2.5.0
• other?

Tiit said:

I just know that whenever I make a build configuration I have to select sysbuild or things will fail in weird and interesting ways.

It should make more sense soon, hopefully. The course explains the difference between child/parent images and sysbuild quite well in my opinion, but if you have any follow ups from the sysbuild topic I'm more than happy to discuss them.

Kind regards,
Andreas

[Tiit]

Hi Andreas,

I looked at the linked linked academy guide and it seems I did pretty much exactly what is recommended there. And while I was working on that I did get a lot of devicetree errors until I reached my current state where I'm now stuck. Since the board I have defined for now is pretty much just SDK definitions copied into the custom board files I can safely share that here publicly.

2210.soma.zip

Maybe you can see what is happening with that. To try that all you have to do is unpack this into the boards folder of the Matter Window Cover sample and add the pm_static file from my first post to the root folder of the sample. 

At the moment I'm not worrying at all about sysbuild or child/parent images. All I wan tot do is take the clean example from SDK 3.0.0 and compile that with toolchain 3.0.0. Instead of selecting the nRF54L15-DK as the target board I want to be able to select a board named "blindy_v3". The custom board definition can just be a copy of the dev board. I want to do that to have a starting point for changing the board into my actual custom board. That is the way I did that once before and it went kind of smoothly.

I spent all day yesterday with another person from your support team coming to the conclusion that there is something wrong with SDK/toolchain 2.7.0 specifically that breaks when any newer versions are installed on Linux. So I seem to be in a really unfortunate position where I think I basically have to take the clean example from 3.0.0 and just port all of the business logic of my application over manually. I guess having a clean start can't really hurt. But for some reason I'm stuck getting the very first step of the custom board to working on the dev board. I hope you can take a look at the custom board I have attached here and let me know why this is happening.

Tiit

[AHaug]

Hello again Tiit,

I saw the discussion you had with Hieu in the other support case. Looks like you're on track there and in good hands.

Back to this case. I've spent quite a while looking into how to make your custom board work with the Matter Window Covering sample, and I think I'm starting to get there. I'll take you through the process so you can follow along and pick up something in case this happens later. Here's what I've done

1. Compare your board folder with https://github.com/nrfconnect/sdk-zephyr/tree/main/boards/nordic/nrf54l15dk
   1. See that the most important parts are identical, in cases where there are differences I added those items also. It might be that you've chosen not to add those lines due to your board not having those features.
      
      
2. I added the board folder to this location: <fres_standing_application_space>\<my_app>\boards\blindy_v3, in my case: C:\ncs\my_projects\344711\wc\boards, where the contents of \wc is the Matter Window cover sample from nrf/samples/matter in NCS 3.0.1.
   
   
3. Added the custom board folder to the extension by opening the extension settings -> extension settings -> Add item to Board Roots, resulting in being able to select your board through the extensions build configuration
    ->  -> 
    ->
4. Create a static file for your board based on the 54l15dk_54l15_cpuapp (i.e copy paste the content) and rename it to "pm_static_blindy_v3_nrf54l15_cpuapp.yml". I made no modifications here other than the name.
   
   
5. Within the boards/ directory I added a .conf and .overlay for your custom board and named them blindy_v3_nrf54l15_cpuapp.conf and .overlay respectively
   1. To the .conf file I added the contents of nrf54l15dk_nrf54l15_cpuapp.conf and the additional CONFIG_ZMS=y since the ZMS cache optimization configs depend on them (warnings were thrown when building that the optimization configs were set to y but were missing this dependency). CONFIG_ZMS is automatically selected for the nRF54L15 SoC, but I don't think the build system picked this up for your board.
   2. To the .overlay I added the same overlays as are present within nrf54l15dk_nrf54l15_cpuapp.overlay
      
      

At this point in time we're seing that we're getting a successfull application building, but we're struggling with building mcuboot: 

'FAILED: zephyr/zephyr_pre0.elf zephyr/zephyr_pre0.map C:/ncs/my_projects/344711/wc/build/mcuboot/zephyr/zephyr_pre0.map' tells me that it is the MCUboot image that's failing, and that it is because of it can't find these two devices in the board files:

c:/ncs/toolchains/0b393f9e1b/opt/zephyr-sdk/arm-zephyr-eabi/bin/../lib/gcc/arm-zephyr-eabi/12.2.0/../../../../arm-zephyr-eabi/bin/ld.bfd.exe: C:\Users\anh4\AppData\Local\Temp\ccuRt88H.ltrans0.ltrans.o:(.rodata.spi_nor_0_config+0x0): undefined reference to `__device_dts_ord_106'
c:/ncs/toolchains/0b393f9e1b/opt/zephyr-sdk/arm-zephyr-eabi/bin/../lib/gcc/arm-zephyr-eabi/12.2.0/../../../../arm-zephyr-eabi/bin/ld.bfd.exe: C:\Users\anh4\AppData\Local\Temp\ccuRt88H.ltrans0.ltrans.o:(.rodata.spi_nor_0_config+0xc): undefined reference to `__device_dts_ord_23'

We can check what it refers to by navigating to the generated devicetree header for MCUboot. Navigate to: build/mcuboot/zephyr/include/generated/zephyr/devicetree_generated.h and look for lines matching number 23 and 106, i.e 

 *   23  /soc/peripheral@50000000/gpio@50400 and *   106 /soc/peripheral@50000000/spi@4a000. This means that either these two peripherals are not defined in the board files, or that they've not defined within sysbuild/mcuboot/boards/<your_board>.

Looking through the board-repository for the nRF54L15DK, the gpio address corresponds to gpio2 and the spi address corresponds to spi00, and since mcuboot is complaining the solution is to add an overlay and configuration to sysbuild/mcuboot/boards.

1. Within sysbuild/mcuboot/boards there's overlays for various boards. Similar to item 2, create a .conf and overlay with the contents of the 54l15dk files. I added the contents of the sysbuild/mcuboot/boards/nrf54l15dk_nrf54l15_cpuapp.conf and .overlay respectively and named the files:
   1. blindy_v3_nrf54l15_cpuapp.conf
   2. blindy_v3_nrf54l15_cpuapp.overlay

When building now for blindy_v3/54l15/cpuapp the build now compiles. There are some warnings there, and testing of the firmware, but that is something that you'll have to investigate.

Conclusion: Even though we both thought that the board files looked correct, (and they might still be, but since I added a few items to them before fixing item 2-6 I can't conclude with that) there were still things missing when looking closer at the custom board files. Zip with modified Window Cover sample is attached:

6661.wc.zip

Let me know the description and/or sample compiles for you as well (maybe even without the modifications I've done to the custom board, and just include the added overlay, statics and configuration files within the mentioned repositories).

Kind regards,
Andreas

[Tiit]

Hi Andreas,

Thank you for the detailed response to this. Unfortunately I had to delete the newer SDK versions since they seem to break v2.7.0 builds somehow. So I will only be able to test this next week after reinstalling everything again. 

But I do have a question. In the fix for MCUboot you say I have to add the overlay and conf in the sysbuild/mcuboot/boards directory. As I understand that is basically the overlay that only MCUboot will use. I'm not 100% sure how these conf and overlay things work but my understanding was that they basically get merged with the devicetree and conf files for the selected board and if I wanted to I could just manually merge and skip the overlay parts. I'm asking this because having the board definition broken into multiple folders seems like a place where we can easily forget to change something duplicated and cause issues some time later when we make changes to our board again. The current version we have the whole devicetree and board conf nicely contained in one folder. If that is not possible I can live with this as well but I just wanted to ask to be sure.

I'm not sure why step 3 is necessary. The thing about adding the board to board roots. For me the extension picked up the custom board after a relaunch if it was created in the project folder in the correct place. I'm asking this because we keep our project in a git repository and having all developer always have to add something in VSCode seems like it would not be ideal.

Tiit

[AHaug]

Hello,

Tiit said:

Unfortunately I had to delete the newer SDK versions since they seem to break v2.7.0 builds somehow. So I will only be able to test this next week after reinstalling everything again. 

No worries, take your time.

Tiit said:

As I understand that is basically the overlay that only MCUboot will use.

Correct, this is the overlay and configurations specifically for the MCUboot image.

Tiit said:

I'm not 100% sure how these conf and overlay things work but my understanding was that they basically get merged with the devicetree and conf files for the selected board and if I wanted to I could just manually merge and skip the overlay parts.

If you don't have any overlay and configurations added to sysbuild/<companion_component>/, where companion component in this case is mcuboot, then the build system will only build a default mcuboot given that you've defined said config within sysbuild.conf. 

None of the changes within app.overlay, prj.conf or sysbuild.conf present in the root level of your project is applied to any of the companion components.

This is similar to how it previously was done with child/parent images, where you had a structure with child_image/mcuboot/prj.conf and mcuboot.overlay instead.

Tiit said:

. I'm asking this because having the board definition broken into multiple folders seems like a place where we can easily forget to change something duplicated and cause issues some time later when we make changes to our board again.

Tiit said:

The current version we have the whole devicetree and board conf nicely contained in one folder. If that is not possible I can live with this as well but I just wanted to ask to be sure.

Here's an important clarification that I think might reassure you. The board definition itself is not broken into multiple places.

Everything w.r.t your board will be placed within the boards folder (the one you sent me), which you can place wherever you wish as long as the build system and the extension knows where it is residing (see my comments w.r.t your question about step 3 for more details). I placed it within the boards folder of the project because I wanted to have it located somewhere locally on my computer related to this specific case.

In the case of the exercise I did with getting the sample to build with the "custom" board, i.e basically a 54l15dk with a different name, was to make modifications to the board for just that project by adding some required features that a Matter application needs. Among these change I had to state that we should use an external flash, that MCUboot needs to be aware that the secondary partition should reside on the external flash and that MCUboot should use a specific SPI to communicate with the external flash. For a nRF52840 based project this would've been the same, but I could've chosen to use QSPI instead of SPI.

For your project the same will apply. If your bootloader needs modifications, the build system will not know about the features you need to add unless you add the configurations to the sysbuild folder for the companion component

The overlays are as you said laid over top for that specific project, and it has nothing to do with the board configuration themselves. This allows you (and us) to have one board configuration, lets say the nRF54L15DK configuration, and then modify it for each unique project by changing the board through overlays that only applies for that project. The change could be as minimal as for project A we want to use GPIO1.0 for driving a peripheral, whereas for project B we want to use GPIO1.1.

This image from  https://academy.nordicsemi.com/courses/nrf-connect-sdk-fundamentals/lessons/lesson-1-nrf-connect-sdk-introduction/topic/nrf-connect-sdk-structure-and-content/ should illustrate this somewhat more.

That said, if you have a board that will only be used for 1 project and the base will never see the need to be slightly modified to fit another application, then you can have your boards placed locally within the project themselves.

Just linking this once more for reference: https://academy.nordicsemi.com/courses/nrf-connect-sdk-intermediate/lessons/lesson-8-sysbuild/topic/sysbuild-explained/ 

Tiit said:

I'm not sure why step 3 is necessary. The thing about adding the board to board roots. For me the extension picked up the custom board after a relaunch if it was created in the project folder in the correct place.

If you've added the board to a folder that the build system knows as a board root (for instance <sdk>/zephyr/boards or <sdk>/nrf/boards which are default added as board root folders), then the board will automatically be picked up by any project within that SDK instance.

Ah, I didn't see the board when adding it to the project structure before I added the path to board.root. I guess that's because I didn't relaunch the extension before trying to add the build configuration.

Here's an explanation I got w.r.t how this should work: if you add it to your projects board folder, it will be recognized as a board you can use for that project after relaunching/reloading the app. 

TLDR (for this item), the step is not mandatory, but it is an alternative to make sure that the custom board is found by the build system.

Let me know if that makes sense and feel free to ask follow ups if anything is unclear

And also, I recommend you getting your custom board working in NCS 2.7.0 (or newer where sysbuild is used) with simpler applications than a Matter sample first. For instance <sdk>zephyr/samples/sysbuild/with_mcuboot is a good start. This is a hello world sample that enables MCUboot through sysbuild.conf

Kind regards,
Andreas