Clarify Documentation and Example for Custom Driver Implementation in Freestanding Applications

[zhaw-moss]

Dear Nordic Team,

I've been working extensively on creating a custom sensor driver building on Zephyr's sensor API. Throughout this process, I've utilized many available resources, including:

• The Zephyr driver's tutorial video YouTube

• Example repositories like teslabs' driver app, the Zephyr example-application, and ncs-example-application

• The Zephyr documentation on device tree and driver development (Zephyr docs)

However, despite following these resources, I struggled for quite some time with an undefined reference to __device_dts_ord_<N> error during linking. While trying to debug, I referred to the official troubleshooting documentation (troubleshooting guide), but the issue persisted. It took a while for me to finally understand the root cause: the way Nordic suggests structuring applications through the VS Code extension leads to what are essentially freestanding or out-of-tree applications, and it appears that the available documentation doesn’t address this approach very well (I was lucky to stumble over this forum entry)

In particular, I realized that the Nordic VS Code extension, with its focus on keeping the nRF Connect SDK (ncs) and Zephyr centralized while keeping applications in a separate folder, introduces some nuances for integrating custom drivers. This freestanding setup makes sense from a storage and maintenance perspective, as it avoids having multiple redundant copies of ncs/Zephyr. However, this leads to challenges when trying to implement custom drivers, and there seems to be a lack of clear documentation or consistent examples for how to properly set up and link such drivers in this specific freestanding context.

Furthermore, I noticed that the official ncs-sample-application doesn't follow the same freestanding structure that the VS Code extension nudges developers towards. This inconsistency is confusing, and it led me to misunderstand how to properly integrate a custom driver for quite some time.

My Suggestions:

1. Documentation Update: Please consider adding specific sections to the documentation that cover how to create and use custom drivers with the freestanding application structure, especially focusing on how to integrate them as modules.

2. Consistent Sample Applications: It would be immensely helpful if you could update the ncs-sample-application to follow the same structure suggested by the VS Code extension (i.e., a freestanding application setup). Alternatively, adding a dedicated sample that demonstrates integrating a custom driver in a freestanding app would be very valuable.

3. Practical Examples with Custom Drivers: Given that many developers need to implement custom hardware solutions, providing a sample with a custom driver included would save a lot of time and reduce the learning curve for those following the freestanding model.

I believe these changes would make the experience of working with nRF Connect SDK significantly smoother for those of us building applications that require custom drivers, and align better with the approach promoted through your tooling.

Thank you for your consideration, and for the great work you do on the SDK.

Best regards,
Simon

[Edvin]

Hello Simon,

Thank you very much for your detailed and constructive feedback. It is very valuable for us. I will forward your feedback to some relevant stakeholders. 

I believe this is somewhat covered in our Developer Academy, in the NRF Connect SDK Intermediate course, Lesson 7. So in case you are not aware of the DevAcademy portal, you may find this useful in the future. 

However, I agree that this shouldn't replace documentation. 

Best regards,

Edvin

[zhaw-moss]

Hi Edvin,

Thank you for your response, and I appreciate you pointing out the section in the Developer Academy.

You're correct that there is a lesson about custom drivers in the Dev Academy. However, I noticed that for it to work, they define a workspace application, which effectively creates a West workspace that redundantly downloads Zephyr and nRF Connect SDK. It also works specifically with the ncs-example-application, whereas all other samples don't follow this approach and are set up as freestanding applications.

If the intention is that all projects should be structured as workspace applications — with Zephyr and ncs redundantly downloaded each time — then it would make sense for all sample projects to be consistent with that approach. Additionally, the convenience features in the VS Code extension, such as the Manage Toolchain and Manage SDKs buttons, could potentially be streamlined, as a centralized instance of Zephyr and ncs wouldn't be necessary. (Just a joke, please don't do that!)

On the other hand, if the freestanding application structure is still an intended and valid approach, then as I mentioned before, there should be clear documentation on how to integrate custom drivers properly in this context — as a Zephyr module. It’s also a bit confusing that in the Dev Academy lesson on custom drivers, the setup involves a workspace application, while other lessons and samples consistently use freestanding applications—without explaining why this divergence exists.

Also, in the documentation on the different types of application structures, there isn't any clear information on the implications of choosing one structure over another, or why a workspace application might be preferred in specific situations.

Perhaps I've overlooked some crucial documentation, but I think my point is clear: this inconsistency is confusing, and clarifying the reasoning or standardizing the approach would go a long way in improving the developer experience.

Thank you again for considering my feedback, and I look forward to seeing how these materials evolve. If there are no further actions needed from your side, please feel free to close the ticket.

Best regards,
Simon