Custom Board definition

I am starting an experimentation effort with Nordic Mesh SDK. I am using Segger Embedded Studio.

I can open/compile/download the Mesh SDK examples.

I wish to start to modify the supplied examples, and I have a few question related on how to and "best practice" to achieve the following.

  1. Create a copy of an existing example, so I can mess it up without affecting the whole MeshSDK and the linked nRF5_SDK. Can you tell me if it is enough to copy the example folder and rename it? (may be because all the files are linked with relative paths with no exceptions?). Or there is a way to export a project and re-import it along with some sort of refactoring to change its root name?
  2. I need to work using different board definitions (NOT only with a single new one named/referenced as BOARD_CUSTOM). Of course I can create all the correct "boardnames.h" files (deriving them from the closest one from your SDK: pca10056.h for instance) in the nRF5_SDK_15.2.0_9412b96\components\boards folder, but then what? Do I need to modify the board.h and board.c files to add the elif switches and potentially add some specific code to the board.c to support custom functionalities? I really feel not at ease when messing with the SDK files, I rather wish to keep my own custom code completely separated from the SDK... Can you comment/suggest something?
  3. Once I will have the custom board definitions ready and available by means of some #define like BOARD_PROJECT_A, BOARD_PROJECT_B, which is the correct way to select the board? I read that one can have the #define inherited by MANUALLY messing inside the project definition XML file (light_switch_dimming_server_nrf52840_xxAA_s140_6_1_0.emProject for instance)?? Is that the preferred way to work? Can you comment/suggest something?
  4. Same question as #3: how to switch a project from nRF52840 chip to nRF52832 and vice versa? Again need I to manually modify the XML project file?

I tried to find how to proceed browsing the developer network and the internet, but I found partial answers and usually not recently posted.

Can you give me the right hints and/or point me to the right documentation for these "basic" topics?

Many thanks in advnace and

 Best Regards

Davide De Nardis

  • Hi,

    1. Copy and rename an existing example folder would be enough.
    2. I suggest that you make a custom_board.h and in that file you have a new switchboard for including the correct board file. You can have custom_board.h and all custom board files in an include directory within your project instead of in an SDK folder, and that way you can implement the switchboard and all board files without altering the SDK.
    3. It sounds a bit strange that you would have to do this manually. What change is this, I might be able to find a way to do that from within SES. If it is only what preprocessor define to use for the board then you could just change it in the "Common" options for the project. You should find "Preprocessor Definitions" there under "Code" -> "Preprocessor".
    4. The way we do that for our SDK examples is that we have one project file for each device, but they share the same source files. That means you must update all the project files with new include paths or source files, however. Alternatively automate the process of propagating changes from one project to the others.


  • It sounds a bit strange that you would have to do this manually. What change is this, I might be able to find a way to do that from within SES. If it is only what preprocessor define to use for the board then you could just change it in the "Common" options for the project. You should find "Preprocessor Definitions" there under "Code" -> "Preprocessor".

    This is poor answer. Why do you (Nordic) not give detailed, clear direction on how to start out with designing for custom boards? The SDK docs give the briefest treatment:

    Adding support for a custom board

    To add support for a custom board, you must create a custom board support file with the name custom_board.h. This file must be located in a directory in the Include path. You can then select to use the custom board by adding the define statement #define BOARD_CUSTOM.

    The easiest way to create the custom_board.h file is to start with an existing platform definition file (for example pca10040.h) and adapt it to your needs.


    That's it?

    Is that really all there is to say?!

    Detailed application notes would be extremely helpful. For each peripheral and for helping users adapt the SDK to their designs.

    How on earth you are successful as a company with this kind of support is beyond me.

  • Hi,

    Thank you for your valuable feedback. While we strive to provide the documentation, guides and support needed for reaching your goals, we are aware that we have blind spots. Pointing out those blind spots is appreciated!

    Are there particular points in the "Adding support for a custom board" documentation that are unclear, or is the main issue that we do not have a full tutorial-like document?


  • I'm glad you feel it's valuable.

    To be clear, no, it's not that the documentation is unclear, it's that you don't provide any guidance on this aspect at all.

    This is the fundamental part of embedded development!

    You provide examples in the SDK but they are not thoroughly documented and commented. 

    The frequently cited advice to copy and paste an example amounts to little more than cargo cult programming. 

    As I posted elsewhere, you don't have any application notes. I offer this as an example of how it is done well:

    If you delve into their documentation there are examples for each peripheral with schematic diagrams and code samples. The examples are minimal and clear and follow a consistent format.

    This layer of documentation is vital and is yet it is entirely absent from the Nordic canon.

  • Hi,

    Thanks, I think I understand a bit more what you are referring to now. From what I can understand, this is in part a difference in approach, and in part - as you write - lack of guidance on one or more given aspects.

    What we do have, is for each SoC the full hardware documentation for the peripherals, with registers, and in some instances also a couple of lines of code. See e.g. the SPI master documentation in the nRF52832 Product Specification.

    What we also do have, is documentation for the high-level libraries in the SDK, both general information about the libraries and API documentation. See e.g. the SPI transaction manager library documentation (with some example lines of code) and the SPI transaction manager API documentation. From what I understand, this is one point where better overall documentation including to-the-point code excerpts are lacking.

    Then there are the examples in the SDK. See e.g. the SPI Transaction Manager Example. Today these work as "quickly getting something up and running". But they are less suited for "figuring out how things work" / "build custom applications from", in particular due to lack of documentation providing a thorough understanding of how each component works.

    For some aspects of development we have tutorial like guides, including guides for some aspects related to the SDK. For some of the issues raised in this thread this could be a good place to add more guides.

    For some aspects of development we have Application Notes and White Papers, albeit predominantly hardware related. There seems to be some missing pieces for the software side of things.

    We are aware that we have little or no low-level application notes / guides / documentation for how to use peripherals/registers directly. Simply put, as is, we expect anyone interested in direct registry manipulation to read the product specifications and look at the low-level header files directly. We expect the vast majority of developers to use our higher level libraries and never need to manipulate registers directly. Therefore, the higher levels of the SDK is where we primarily put our documentation efforts.

    So in summary, I see that there are some missing connections on the higher SDK levels, regarding getting an understanding of how things fit together. I also get what you mean by "cargo culture programming", in particular when starting on a new project. This is definitely something I will bring up internally, and see what we can do to improve on. Any further feedback might be useful in that regard. If you have the slightest feeling or idea that I might have gotten something wrong here, then please let me know.