API, Documentation and examples

[marceltrapman]

While moving my sketches from 1.5 to 2.2 I noticed that most examples do not really follow the same logic.

I sometimes have a hard time to understand how and why things are done, not only because of the above but also because there seems to be no agreement on conventions.

I understand why this is but for people with less programmer experience than I have (and mine is 'only' Java, Python, Xojo, SQL etc but not C++) it must be hard to interpret all examples.

On question I have at the moment is the following:

I see that there a some methods I can use:

// Before radio initialization
void preHwInit();

// Before node initialization
void before();

// While node initialization
void presentation();

// Setup?
void setup();

// Running
void loop();

// Receive messages
void receive( const MyMessage &message );

What I would like to understand is the difference between presentation and setup because both are used.

[hek]

We added presentation() to allow controller to re-request presentation from a node during runtime. Should contain all present()-statements.

setup() is a good place to initialise one-time only things like pin settings.

[marceltrapman]

@hek Hi Henrik, that is exactly why I ask.

When I take the RelayActuator for example I see that the setup/initialise stuff is happening in the before method.

Or did I find an exception (I have not checked all sketches)?

[hek]

Yes, that seem to be an exception. Not sure why someone (me?) put it in before().

[user2684]

Kind of off topic but maybe can save somebody's else time: presentation() is called before setup(). For some unknown reasons I was convinced setup() was called first due to its name and it took me a while to find this out even if in all the examples the order is correct. So if there is any need to do something which will be used during presentation(), this has to go into before().

[rejoe2]

@user2684 The order of the calls presentation() and setup() have been changed somewhere between 2.1.0 and 2.1.1 . This was when I first noticed the before()-call.

I used this for correct initialisation of a second SPI-device (resistor) sharing all the PINS with the nRF. Now I am wondering, whether it is better to stick to this procedure or better move this part to preHwInit(). Can someone explain the "right way" to deal with this kind of hardware-setup?

[marceltrapman]

@rejoe2 I second your question.
Maybe it is good to have a good explanation of what to do when.
I have the order correct in my original post I believe.
But especially the setup method confuses me...

[rejoe2]

@marceltrapman setup() I found to be pretty self-explanating: I came across this wrt some DS18B20-sketches using more than one of these on one 1-wire-bus: I just sent the Dallas-Addresses of them als "ID" once when the node was starting. Before, this had to be placed in the loop() with an additional marker, if this was already send.
So the controller could check, if all of the chips where reported under the same ChildID. This could change using the "normal" skech in case of additional or less sensors on the bus.

[alowhum]

@user2684 said:

Kind of off topic but maybe can save somebody's else time: presentation() is called before setup()

@rejoe2 said:

The order of the calls presentation() and setup() have been changed somewhere between 2.1.0 and 2.1.1

What is the current order of the calls?

And is there a downside to putting setup things in the presentation function? As I'm looping over nodes I'd like to also do some other things while I'm at it.

[rejoe2]

@alowhum AFAIK, now the order of execution is preHwInit(), before(), presentation() and setup(), then loop().
As you may call the presentation function to be redone from controller side you should decide whether this is desired or not; depends on your needs imo.

Personally, I prefer having all kind of controller-independent initialisation in before() (especially turning relays off/desired state and so on; this allows also to use additional SPI stuff on hardware SPI PINs), put all controller-communication stuff in presentation() and the other things in setup(). For e.g. asking acutal values of counters setup() might be a good choice, as one typically want to do that only once after node has started.

[mfalkvidd]

@alowhum MySensors allows customization, which unfortunately makes it very hard to describe the order. An attempt has been made in https://github.com/mysensors/MySensors/issues/927 but we have not found a clear way to document it.