Device Tree Configuration Guidelines

RE: Device Tree Configuration Guidelines

Steven — Fri, 05 Apr 2024 15:06:39 GMT

[quote userid="109035" url="~/f/nordic-q-a/47990/device-tree-configuration-guidelines/393565"]I won't bang on anymore than Steven has [/quote]

☺

RE: Device Tree Configuration Guidelines

Sigurd Hellesvik — Wed, 02 Nov 2022 09:39:54 GMT

Hi Mike,

Please create a new ticket for your new questions, to help us keep DevZone tidy.

You can link to this case in the new one as a reference.

Regards,
Sigurd Hellesvik

RE: Device Tree Configuration Guidelines

Mike Austin (LPI) — Wed, 02 Nov 2022 05:25:59 GMT

And then, how does this all come into the mix? Is this an alternative to device tree overlay files?

Cheers,

Mike

RE: Device Tree Configuration Guidelines

Mike Austin (LPI) — Wed, 02 Nov 2022 05:00:24 GMT

Sorry to rehash an older thread, but I stumbled across this after searching through the DevZone for some assistance on creating my own GPIO definitions in a .overlay file.

I won't bang on anymore than Steven has already about the challenges faced by newbies in navigating a lot of the stuff you need to learn to get up and running with NCS/Zephyr.

But I have what seems like a simple task - create my own GPIO pin reference in an overlay file that will enable me to turn a FET on or off so I can sample the battery voltage via an ADC input. I'm using P0.30 for my GPIO pin to control the FET, and P0.02 as the ADC input for measuring the battery voltage.

This is what my overlay file looks like (it builds, but I've not yet tested it to ensure it works). I've got to this point via a fair bit of trial and error, so if there is anything there that doesn't look 100% legit, please flag it up as I'll be honest - I've no real idea what I'm doing here!

/ {
	zephyr,user {
		io-channels = <&adc 0>;
	};


mypins {
    compatible = "gpio-keys";
    batteryen: batt_en {
        gpios = <&gpio0 30 (GPIO_PULL_DOWN | GPIO_ACTIVE_HIGH)>;
        label = "Battery Enable";
    };
};

};

A couple of questions:

1. Will io-channels = <&adc 0>; actually ensure I am accessing AIN0/P0.02? I'm basing this on what is already in the nRF52DK board file for the arduino_adc.

2. In my definition of the GPIO, what limits/restrictions/guidance is there in defining the references "batteryen", "batt_en". And more importantly, what are they used for?

3. In the DK board file, there are a bunch of aliases for the LEDs and buttons. Why would I use an alias instead of referencing whatever value I have at "batteryen"?

I think its this level of support that is lacking in any documentation I've seen around Nordic devices. Its like there is a certain level of competency you need to acquire in order to understand most of the info available, but getting to that point is akin to extracting the mythical "sword in the stone"

Cheers,

Mike

RE: Device Tree Configuration Guidelines

Simon — Tue, 18 May 2021 11:45:59 GMT

Thanks for the feedback. I've forwarded your suggestion internally.

Best regards,

Simon

RE: Device Tree Configuration Guidelines

Henk Pragt — Fri, 14 May 2021 09:37:10 GMT

Hi Simon,

I totally agree with Steven: the DTS is far too complicated to quickly start a custom design. Here's a thought: how about a simple wizzard where we can add a board name and tick some peripherals and I/O's from a menu, and have it create the DTS for us?

cheers,

Henk

RE: Device Tree Configuration Guidelines

Simon — Mon, 29 Mar 2021 12:39:33 GMT

I've forwarded your feedback to one of our tech writers. We aware that there is room for improvement in our getting started guides and are working on improving it.

RE: Device Tree Configuration Guidelines

Simon — Mon, 29 Mar 2021 11:27:00 GMT

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

RE: Device Tree Configuration Guidelines

Steven — Mon, 29 Mar 2021 10:13:16 GMT

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.

RE: Device Tree Configuration Guidelines

Simon — Sun, 28 Mar 2021 19:18:08 GMT

[quote user="SCrowe"]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?[/quote]

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

RE: Device Tree Configuration Guidelines

Steven — Fri, 26 Mar 2021 17:23:15 GMT

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?

RE: Device Tree Configuration Guidelines

Steven — Fri, 26 Mar 2021 15:52:40 GMT

"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.

RE: Device Tree Configuration Guidelines

Simon — Fri, 26 Mar 2021 10:20:06 GMT

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

RE: Device Tree Configuration Guidelines

Steven — Thu, 25 Mar 2021 16:21:04 GMT

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!

RE: Device Tree Configuration Guidelines

Simon — Thu, 25 Mar 2021 15:26:08 GMT

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

RE: Device Tree Configuration Guidelines

Steven — Thu, 25 Mar 2021 11:56:59 GMT

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?

RE: Device Tree Configuration Guidelines

Simon — Mon, 03 Jun 2019 14:28:11 GMT

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