Device Tree Configuration Guidelines

[Alan Jones]

Can Nordic provide general guidelines for manipulating the device tree configuration files for custom boards?

For instance, does the application require the exact same pin mapping as the SPM loader? If not, what if there are pin mappings for a UART during boot for instance, but the application disables the UART and repurposes those pins to GPIO in either the application device tree or the project's overlay file? Is the application required to use only a subset of the SPM peripherals? How are peripheral or pin conflicts resolved by the current build process which defaults to generating a merged hex file?

There also seem to be build issues with locating the out of tree board directory in the application directory, which would be preferable for simplifying application version control.

[Simon]

The SPM sample (ncs\nrf\samples\nrf9160\spm) does not map any pins. The only thing the SPM sample does is to set the security attribute of the peripherals (It also configures flash/ram as secure/non-secure, but this is not relevant for your question) listed in periph_cfg periph[] to either secure or secure (depending on the configurations in ncs/nrf/subsys/spm/Kconfig).

However, some peripherals does not work with a non-secure application (e.g. PWM0), due to their absence in Kconfig or spm.c. You will have to add it, as the customer did here.

Best regards,

Simon

[Steven]

OfflineAlan Jonesover 2 years ago

What about this though?

"Can Nordic provide general guidelines for manipulating the device tree configuration files for custom boards?"

Can you point me to any examples please?

[Simon]

Check out this: https://devzone.nordicsemi.com/nordic/nrf-connect-sdk-guides/b/getting-started/posts/nrf-connect-sdk-tutorial---part-3-ncs-v1-4-0#h11sk6ks1jkp1figkuq6gxw1m1rctdp0 

[Steven]

With respect, I feel like you're coming from a place where you have a very good knowledge of the SDK and to you these things are obvious. To someone coming to this for the first time it's far from obvious!

If you take this paragraph...

If your board has LEDs and buttons connected to the chip's GPIOs, and you want to access it using the Zephyr API, you should include it into the Device Tree. This can be done by incorporating the nodes described in ../bindings/gpio/gpio-leds.yaml and ../bindings/gpio/gpio-keys.yaml into your dts files respectively. You simply select the pins the buttons and LEDs are connected to and choose a label. If you create aliases for the nodes, the generated names will be simplified and easier accessible in your samples. E.g. LED1_GPIO_PIN can be used instead of DT_GPIO_LEDS_LED_1_GPIO_PIN.

...it doesn't really help a very great deal!

For instance, you need to illustrate what you mean when you say "You simply select the pins the buttons and LEDs are connected to and choose a label. If you create aliases for the nodes, the generated names will be simplified and easier accessible in your samples"

Ok, well what does that look like? A worked example, using a development kit and some off board leds and switches, would be really useful. Something like this:

https://devzone.nordicsemi.com/nordic/nrf-connect-sdk-guides/b/peripherals/posts/adding-a-peripheral-to-an-ncs-zephyr-project 

Worked examples are really helpful and instructive way to  learn your way around the documentation and folder structure so you can understand how to manipulate the files and work towards building up an overlay file for a custom board. Because, ultimately, that's all we're interested in, right?

If I want to give my board overlay some meaningful labels, perhaps because I'm driving a relay or a buzzer, what does that look like? How do I move beyond predefined labels for the DK?

So, really, worked examples for each of the device peripherals, please.

PS I'd be happy to write a blog post(s) to document the process and help out, I could do with some guidance though!

[Simon]

The first part (2.1 The board files) are just theoretical explanations. I should probably have pointed you to the practical part (2.2 Walkthrough) which demonstrates step-by-step how to create a new custom board in NCS v1.4.0 (shouldn't be too different from NCS v1.5.0).

If you follow the steps in 2.2 Walkthrough you will end up with a custom board folder in zephyr/boards/arm/test_nrf9160, and you can manipulate the device tree configurations by modifying the files ending with dts (please tell me if I should elaborate on the different dts files).

Now you know what files to modfiy to change the device tree configurations for your custom board. However, how you should modify it is another question. That require some knowledge about how the device tree works, and for that I would recommend you to read the following: Devicetree API. Sometimes, if you just want to do some simple things, you may not need that deep knowledge of the device tree, you can just look at other board files and its dts files to understand how to go about it.

If you have some inputs of how 2.2 Walkthrough could get improved, I would be happy to hear. Do you think it would be useful for another blog post exending on this, that focuses on how to modify the dts files?

Best regards,

Simon

[Steven]

"That require some knowledge about how the device tree works, and for that I would recommend you to read the following: Devicetree API."

"you can just look at other board files and its dts files to understand how to go about it"

Sorry but that won't do. With respect, you cannot seriously imagine that this is good practise or good customer support?!

I can tell you that I am already doing just that, which is how I got to posting on the forum asking for help!

I can see that other people are asking similar questions and getting the same response. Which is read the 3-4 section "getting started blog" and then read all the API docs.

By the way, when you read the getting started blog it leads you into a multitude of rabbit holes, many, many tabs open on the browser and a maze of information to assimilate.

You've done a fine job of documenting your work, I'll give you that. These are all fine reference documents but it seems to me that there is a layer of documentation missing here.

In my experience, coming from an embedded development and engineering (not software) background, there are three kinds of documents:
- Specifications
- Datasheets
- Application notes

- Specifications give a broad overview of the features and capabilities of a device. This might be useful when you are trying to evaluate which device to use for a project.
- Datasheets are the reference material that give the fine grain detail about the device architecture at both hardware and software/register level.
- Applications notes provide examples and detailed descriptions, including diagrams and code samples, of how to use the device and its peripherals from the most basic, fundamental level.

My work flow when I am bringing up a custom board is that I approach it in sections, starting at a very basic level by getting an output and LED working, perhaps adding an input (pushbutton) button then maybe an interrupt and a timer or time delay.
Then a uart so I can get some detailed debug messages. After that maybe SPI and I2c bus, working through each of the support chips and getting basic drivers/functionality in place.

This is obviously greatly simplified. But by the time I have done all that I am thoroughly acquainted with the hardware, registers, datasheets and documentation and I can go on and build up my application with a measure of confidence.

The application notes are fundamental in guiding you through these first steps. For any fine grain details I can look at the datasheet but it mostly just serves as a reference.

YOU DON'T NECCESARILY START A PROJECT BY READING DATASHEETS AND API DOCUMENTS!

It's not practical when the docs are 1000s of pages long. You learn by DOING, experimenting and in incremental stages building up your knowledge and understanding, by reading and referring to the relevant parts of the docs as you go.

It seems like you're trying to offer a complete solution and expecting us, the user to get to grips with this voluminous body of work with a modicum of guidance and support.

This is a fiendishly complex thing that you have made and I'm not sure if you all appreciate it from a users perspective?

Perhaps it might be instructive to get a new starter to sit down with a dev board and few basic components and watch how they set about learning how to use this thing?

I have had similar views about the previous SDK (with its 13000 line configuration files and layer on layer of macros). In contrast, I offer this as a "better way":

ww1.microchip.com/.../TB3215-Getting-Started-with-SPI-DS90003215.pdf

If you delve into their documentation there are similar examples for each of the peripheral devices. It may not be perfect and granted, it's a far simpler device but it's based on years of experience and customer engagement and it's a much more manageable and accessable format for a new user to get up to snuff.

[Steven]

To add to that, I'd say that 2.2 Walkthrough doesn't really demonstrate a custom board as you're only copying and pasting files from another demo. It doesn't say anything about adding additional functionality. Is that fair?

[Simon]

Steven said:

To add to that, I'd say that 2.2 Walkthrough doesn't really demonstrate a custom board as you're only copying and pasting files from another demo. It doesn't say anything about adding additional functionality. Is that fair?

That is correct. The 2.2 Walkthrough only shows how to create a new custom board folder, that you can use as a base for your specific board. It does not show how to add additional functionality to your board.

Would it be useful with a new section "2.3 Modify the board folder to your custom board"? Where I go through some different scenarios:

• If your board only has one button, connected to GPIO 30
  • Then you have to remove the other button instances, and change the GPIO of button1 to 30
• If you have an adxl362 device on you board, connected to some specific GPIOs
  • Then you could look at the board folder for the Thingy:91 to see how to add it to the board folder. Change the SPI instance if you want to use another, and select the pins according to how the adxl362 is connected.
  • Then you can build the adxl362 sample with your custom board name and it should work out of the box
  • (Be aware that this can also get added to an overlay file, but if the sensor is part of the custom board, the proper way is to add it to the dts board files)
• If you don't have an nrf52840 on your custom board
  • Here I demonstrate what should be removed. E.g. interface_to_nrf52840, nrf52840_reset++

Regarding the other comments, I'll forward it to the ones responsible for the blogs/tutorials.

Best regards,

Simon