What is the reason of making nRF APIs that complicated?

RE: What is the reason of making nRF APIs that complicated?

Jarmo — Sun, 11 Dec 2016 11:35:17 GMT

Yes, that mbed example looks very much like a thing I was thinking about when complaining the complexity of Nordic's APIs. A good API is just that intuitive to use – to drive a car you don't need to know how the engine works, so to speak. The level of abstraction is really much higher here than with Nordic's examples. So, I am wondering is that a strategic decision to stay in such a low level, or just lack of resources, or maybe even kind of inability to design good APIs?

RE: What is the reason of making nRF APIs that complicated?

Jon Helge — Sat, 10 Dec 2016 22:22:30 GMT

No idea. But it it seems to be at a different level of abstraction.

RE: What is the reason of making nRF APIs that complicated?

endnode — Sat, 10 Dec 2016 21:50:12 GMT

And are mBed stack and API more efficient and powerful then Nordic's SoftDevice?;)

RE: What is the reason of making nRF APIs that complicated?

Jon Helge — Sat, 10 Dec 2016 21:01:13 GMT

Here's a simple heart rate monitor example on mbed. It is quite simple to read and understand in my opinion.

developer.mbed.org/.../main.cpp

RE: What is the reason of making nRF APIs that complicated?

Jarmo — Tue, 15 Dec 2015 14:01:43 GMT

Yes, thanks for discussion this far. Let's see if I have time to find something suitable :)

RE: What is the reason of making nRF APIs that complicated?

endnode — Tue, 15 Dec 2015 13:52:20 GMT

My comments were not suppose to be personal (although it might sound like that, sorry). I'm simply curious and opened to learn, I just really met only SDKs for ARM Cortex-M things which are very similar to nRF5x SDK. I don't expect to have any further feedback from Nordics here but if you will find good example which you find better structured and more modern please link it here, I'd love to give a try;) Cheers Jan

RE: What is the reason of making nRF APIs that complicated?

Jarmo — Tue, 15 Dec 2015 13:23:27 GMT

Okay, there is a rationale in my opinion, and there is opposite rationale in your opinion. I think that the nRF APIs are kind of "old-fashioned", or at least over-complicated, not cleanly designed, but it may be argued to be an opinion only. So I changed the title of my original question to become less aggressive. "What is the reason of making nRF APIs that complicated?"

RE: What is the reason of making nRF APIs that complicated?

endnode — Tue, 15 Dec 2015 13:08:36 GMT

It seems so ("question of taste") but you've originally indicated that no one is using this approach any more (= the approach Nordic's used for their nRF5x Seoft Device and SDK) and also that it's well known that the other approach is much better for programmers (in general, proven). I was just expecting some good examples to learn something new. If we end up in quoting 16th century's philosophers then I totally agree with you, it's just question of taste.

RE: What is the reason of making nRF APIs that complicated?

Jarmo — Tue, 15 Dec 2015 13:03:17 GMT

A philosopher Francis Bacon (1561-1626) formulated that if a man once adopts an opinion, after that he bends everything to support his opinion. So I don't believe this is a fruitful discussion anymore. You have an opion, and I have mine. It is not a question of rationale, but more like a question of taste.

RE: What is the reason of making nRF APIs that complicated?

endnode — Tue, 15 Dec 2015 12:48:49 GMT

How do you work with default values in the scheme where you pass ALL the parameters to the function? How would it help filling default values into each call? Or you expect functions which basically cuts the variability and allow to set just half or quarter of parameters while they fill the rest by defaults? Isn't it exactly what is done in my example above (= if you decide that your app is using just some configs you do your applicative layer)? Or you expect SDK offering dozens of such functions just to be able to cover all different scenarios in order to satisfy different "users"? Not convincing (at all).

RE: What is the reason of making nRF APIs that complicated?

Jarmo — Tue, 15 Dec 2015 11:50:52 GMT

Yeah, you got the point perfectly :) I was eventually speaking both things you mention because they are a bit interleaved. Prefer many simple functions to a few complex ones. Prefer giving working default values to requiring setting all bits and pieces every time.

RE: What is the reason of making nRF APIs that complicated?

Jarmo — Tue, 15 Dec 2015 07:55:26 GMT

Yes, from the "machine perspective" the answer is what it is. However, after working decades in this profession, I have started to prefer "human perspective", because we ourselves have so limited resources. Developer's "cognitive load" shouldn't be increased by purpose. I mean that it is mostly better to write code that is "easy-to-read" than code that is "easy-to-execute", so to say. This paradigm produces less errors, and eventually better code.

RE: What is the reason of making nRF APIs that complicated?

Clem Taylor — Tue, 15 Dec 2015 04:48:12 GMT

For the sd_*() calls, this style of data passing a side effect of the minimal number of arguments to via SVC calls.

If it wasn't for the memset, most of this would compile down to const references to flash memory which would use up way less code space then passing parameters on the stack. The use of memset() is to make the code compatible with future libraries that might add additional parameters.

If everything is constant you can do something like:

const ble_blah_blah_init_t blah_init =
{
     .blah1 = blah
     ....
};

and it will all happily compile away. The same is often (but not always) true for functions with a large number of const arguments that are only called once (-flto is your friend).

RE: What is the reason of making nRF APIs that complicated?

Jarmo — Sat, 12 Dec 2015 11:56:47 GMT

Yes, actually I was thinking that too, and kind of waiting for this answer :) On the other hand, it would still be possible to hide those complicated "init structures" behind a more comfortable function API. In my opinion, Bluetooth LE "Hello World" should fit into 10..20 lines, instead of almost a thousand.

RE: What is the reason of making nRF APIs that complicated?

Frederik — Fri, 11 Dec 2015 09:51:47 GMT

Another problem when making the API for the SoftDevice is that we are using SVC calls, which have restrictions on the number and types of parameters supported. Therefore we need to use pointers to pass complex structs to the SoftDevice.

RE: What is the reason of making nRF APIs that complicated?

Jarmo — Thu, 10 Dec 2015 18:48:10 GMT

The good thing in Nordic's code is that it seems to be written using strict conventions, and the quality seems to be good, also. What I do not like is the underlying coding paradigm making the resulting code very difficult to read. An experienced programmer can read well-written code almost like a natural language, but that's not the case with Nordic's coding style.

RE: What is the reason of making nRF APIs that complicated?

Jarmo — Thu, 10 Dec 2015 18:40:36 GMT

And really, there is never real need for "dozens of arguments". In case a function seems to need more than four arguments, you can simply split it into two smaller functions making the code also more readable, and more self-documenting. Using a structure to pass "dozens of arguments" does not solve the issue.

For example, instead of providing a single fuzzy "ble_conn_params_init()" you might provide ble_set_conn_delays() and ble_set_conn_handlers() and maybe a third one for something else (it is hard to say what is really needed, based on your approach). The result would be much more readable that way.

RE: What is the reason of making nRF APIs that complicated?

Alex — Thu, 10 Dec 2015 17:30:27 GMT

RK, I like Nordic style of code but I disagree with you about stack. In that particular implementation cp_init will be allocated dynamically in stack because it is defined inside the function. Benefit of structure will be only if it is defined as global var.

RE: What is the reason of making nRF APIs that complicated?

Jarmo — Thu, 10 Dec 2015 12:38:34 GMT

Yes, actually I planned to have a look to the competitive systems. Don't know if they are at all simpler than yours :) Thanks for comments!

RE: What is the reason of making nRF APIs that complicated?

endnode — Thu, 10 Dec 2015 12:23:50 GMT

I hope your feedback will be taken into account by Nordic team. Would be even better if you could link some "good" examples of such SDK/API for ARM Cortex-M or similar system...

RE: What is the reason of making nRF APIs that complicated?

Jarmo — Thu, 10 Dec 2015 11:22:38 GMT

Thanks for anwer. Still, 900 lines in your "BLE Hello world" makes no sense. I have made most of my career with embedded systems, since 1983. And by the wat, the newcomer is often the guy who points out the things that do not work.

RE: What is the reason of making nRF APIs that complicated?

Jarmo — Thu, 10 Dec 2015 11:09:04 GMT

Yeah, good conversation :) The history of coding styles is interesting and funny, full of opposite opinions. "Dozens of arguments" is by the way very misleading, because in most cases three or four would be more than enough. Those "init" structures are just overkill making a simple thing to look complicated. Again an opinion :D

RE: What is the reason of making nRF APIs that complicated?

endnode — Thu, 10 Dec 2015 10:28:32 GMT

Hard to argue without having time to rewrite it and measure;) However all SDKs for ARM Cortex-M chips I've seen are using rather structures then arguments so either these guys know what they are doing or they just stacked in 90s as you are saying with their fear that dozens of arguments in the call will kill the stack and code readability quickly. And to be honest looking into it this way I'm fain to stay in the 90s with my SDK and FW...

RE: What is the reason of making nRF APIs that complicated?

endnode — Thu, 10 Dec 2015 10:23:54 GMT

Well then you are probably referring to some example and depending on what exactly your app is doing you either use parts of that code or not. Bare in mind that your are using SDK which basically sits on "bare metal" so you are writing the OS not just the app sitting on top of it. If you demand another layer of abstraction then there is reason why no such "OS + API" exists on these systems: they are so restricted in terms of resources (single threaded not powerful CPU, power restrictions, NVM and RAM in the rang of few dozens of kB) that you never fit some "general" layer there which would serve perfectly to all apps. You actually need to be touching so many low level points if you want to make efficient production FW on this kind of chip that predict all use cases by any smarter API is impossible. And if you are dissatisfied with the examples then you can be sure that most of "high rolling" production FWs are not using that, just derived their better and more efficient templates from it. For the newcomer it might be quite a "hit" to work in such complicated SDK but embedded programming isn't PC "Hello World" programming through win32 API, it's actually quite hard;)

Cheers Jan

Edit 2015-12-15

Sorry but I still don't get the point. Are you mad at having some "standard" sequence of function calls in the main which you will copy from project to project? Something like

int main(void) {
    // Initiate HW.
    board_configure();

    // Initiate application timer.
    rtc1_init();

    // Initiate your specific applicative configuration.
    config_init();

    // Initiate BT stack in Soft Device.
    ble_stack_init();

    // Do all application logic (inside the infinite loop).
    do_work();
}

Or are you saying that there are studies that instead of initiating parameters into the structure like this

// Prepare Write parameters.
write_params.write_op = BLE_GATT_OP_WRITE_CMD;
write_params.handle = m_central_cccd_handle;
write_params.offset = 0;
write_params.len = sizeof(write_value);
write_params.p_value = (uint8_t *)&write_value;

// Central writes to CCCD of peripheral to receive indications.
err_code = sd_ble_gattc_write(m_central_conn_handle, &write_params);

they should be passed in the parameters (e.g. like this):

// Central writes to CCCD of peripheral to receive indications.
err_code = sd_ble_gattc_write(m_central_conn_handle, BLE_GATT_OP_WRITE_CMD, m_central_cccd_handle, 0, sizeof(write_value), (uint8_t *)&write_value);

to better trigger humans' (specifically programmers') cognitive functions? Could you please give me some references? Because I start to doubt I'm OK...;)

Thx Jan

RE: What is the reason of making nRF APIs that complicated?

Jarmo — Thu, 10 Dec 2015 10:17:57 GMT

My mention of Symbian was not meant to be taken that way. After starting my career with 6502 processor, I do know what is a resource limited system. And I also do know the absolutely most resource limited system is our own brain. That's too often forgotten, and strange arguments to save microprocessor power instead of our brain power start to fly. I would even bet there's more final binary code in that structure-filling system than with argument passing.