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.

[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

[Steven]

Yes, certainly that would be helpful. My broader point is that the documentation is incomplete and that the application notes are essential, from a users perspective.

[Simon]

Thanks for your feedback, I'll forward it internally. I'll incorporate the mentioned section into the tutorial some time after easter.