Lack of SDK documentation? & poor example code annotation.

[SeanHowsonTB]

I am finding myself seriously lacking in proper explanations of how aspects of the SDK work. For example i am currently trying to gain a full & in-depth understanding of the TWIM functions. I've spent years working at register level & dealing with assembly instructions & op-codes. Hence i would like to fully understand what each of the SDK functions actually does.

Yet i am continually left searching for forum posts to fill in knowledge gaps. I find this unreliable as many of the posts i find are either conflicting or outdated.

Or, I am directed to examples. I do not have time to sift through (poorly-annotated) example code. I have tried searching the infocentre, but I am then left looking at explanations like the ones in the picture below, these explanations are just reflections of the annotations of the code in the SDK. I dont understand how the below can possibly pass for a detailed explantion? When i then go to explore the SDK files referenced by the infocentre, i find i further lack of annotation, or a long string of fairly meaningless annotations, (descriptions of functions that are just a mirror of the function name), no explanation of conditional compilations etc etc).

Most of the explanations i find for data structures and functions on the infocentre are simply re-worded iterations of the function or variable name name itself. such as "type" = "type of transfer". Really, the amount of information available is insufficient.

Am i missing something here? Usually most of the embedded SDK's i've used in the past have a considerably more in-depth user manual available. Have i just not found this, or is the infocentre really the only thing out there. I am finding it very frustrating to navigate and dont really have time to wait for a forum reply every time i run into an issue.

I am trying to remain open minded & adapt and commit to the nordic SDK & documentation as this is the CPU my company has adopted. But it is becoming increasingly difficult and I have concerns about putting a product out onto the market without properly understanding the code i've used.

If i've missed some serious documentation somewhere please please point me at it? Is anyone else having the same issue?

[Edvin]

Hello,

I am sorry that you feel that way. 

I assume that it is not the details on these specific parameters you are looking for, but rather use this as an example of the documentation, right?

Our "library" section on infocenter is a bit more detailed, but most of the drivers documentation are in fact generated from the source code (or vise versa, I don't remember). 

In my opinion, one of the strengths of the nRF5 SDK is the  mount of example projects demonstrating most of the peripherals, so that you can easily see how the drivers can be used. 

I don't know whether you are aware, but we are currently working on the nRF Connect SDK, which is a new SDK series, and it has it's own documentation platform. Perhaps this is something you want to look into?

Best regards,

Edvin

[SeanHowsonTB]

Edvin,

Appreciate the reply, yes i'd intended the specific parameters in my original message as an example. Allbeit a good example, as i am still struggling to understand the exact implications of the TWIM driver code 2 days after starting a sprint.

I think my issue is that most of the documentation IS generated from the source code (or vise versa). The source code really is poorly annotated. Maybe this is something you can take on as the SDK progresses.

The trouble i have with example code is that, yes, it shows me one way the SDK can be used. But it doesn't tell me why such code is used. Or, all the other ways the SDK can be used. I feel as though I am learning in a copy & paste style. Which then means that later down the line, when i come to developing production tools for the product I am working on, i will not have a full grasp of, for example, the way the linker treats the code. So dealing with the raw binary files can then become a messy business. I do however, appreciate that you used the phrase "in my opinion" in your message - so I guess my point is that everyone has a different approach to learning.

That being said.... i've taken a glance over the Connect SDK documentation and generally, the platform feels much better. Better presented explanations. Actually even to the point that the "viewing window" in which the documentation is presented, is much bigger. On my monitor, the horizontal banner/menu on the infocentre encompasses half the screen, leaving a tiny space to read from. While this is a petty thing, i'm glad it's not present in the Connect SDK documentation. So i will perhaps endevour to shift to the new SDK

Can you explain to me the relevance of the connect SDK? I seems to be aimed at a number of the NRF chips, How does it differ from the original SDK? Is it simply intended to encompass a wider range of products?... what's the goal/aim?

Thanks,

Sean

[Edvin]

Hello Sean,

Sorry for the late reply. We had a public holiday in Norway, but we are back in the office now.

The nRF Connect SDK (NCS) was introduced with the arrival of nRF91 and nRF53, but it is in fact the SDK that will be further developed going forward, while the nRF5 SDK is more or less in maintenance mode, meaning future updates will be more or less dependent on critical bug fixes (mostly to the Bluetooth stack, if any issues are being discovered).

While the nRF5 SDK is generally a "bare metal" SDK, NCS is built on an RTOS (Zephyr). The reasoning for moving to an RTOS based SDK is made due to the fact that both nRF91 and nRF53 are dual core chips, and it makes it easier to maintain the two cores. That being said, NCS is also supporting the nRF52 series, although it only has one core.

I hope this answered some of your questions regarding the "old" and "new" SDKs. Let me know if anything was unclear.

Best regards,

Edvin