Library V2.x API error

[BearWithBeard]

@skywatch

Sorry, I don't quite follow. I don't think you want to say that the snippet is missing the MySensors.h include and such, are you?

[skywatch]

@BearWithBeard I am only saying that if someone new were looking for an example to follow then that 'example' might be a problem for them as is. Or maybe I should find something else to do ;)

[BearWithBeard]

@skywatch Got it, you pretended to be a newbie all along. Was it too boring to show your intentions right away? :D

I understand your point, but I guess that brings us back to the discussion we had a few months ago about the state of the documentation / guides and how beginner friendly it needs to be and where it starts to be too verbose. IMHO, in the context of that page, it's fine and it should be clear that it isn't a complete sketch.

If I can come up with a meaningful sketch that makes use of both timed and external interrupts without using additional libraries and such, I'll post it so that someone with rights to edit those articles can update it if they want.

Edit: Well, not that meaningful, but it brings the point across and isn't too long:

#define MY_RADIO_RF24
#include <MySensors.h>

#define CHILD_ID 1
MyMessage msg(CHILD_ID, V_STATUS);

#define INT_PIN 3
#define LED_PIN 5
bool ledState = false;

#define SLEEP_TIME 9000000 // 15 min
uint32_t sleepTime = SLEEP_TIME;
int8_t wakeupReason = MY_WAKE_UP_BY_TIMER; // Initial value, will be set by sleep after the first run

void presentation()
{
	sendSketchInfo("Sleep + Interrupts", "1.0");
	present(CHILD_ID, S_BINARY);
}

void setup()
{
	pinMode(LED_PIN, OUTPUT);
	digitalWrite(LED_PIN, ledState);
}

void loop()
{
	if (wakeupReason == digitalPinToInterrupt(INT_PIN)) {
		sleepTime = getSleepRemaining();
		// Do interrupt-triggered stuff here
		// Sends the pin state when woken up by external interrupt
		send(msg.set(digitalRead(INT_PIN)));
	} else if (wakeupReason == MY_WAKE_UP_BY_TIMER) {
		sleepTime = SLEEP_TIME;
		// Do periodical stuff here
		// Toggles the LED every 15 minutes
		ledState = !ledState;
		digitalWrite(LED_PIN, ledState);
	}
	wakeupReason = sleep(digitalPinToInterrupt(INT_PIN), CHANGE, sleepTime);
}

[evb]

@mfalkvidd can you please update the article? :-)

Each little thing that can help, is a step forwards ;-)

[TheoL]

As a designer I don't think we can or should decide what a newbie needs so that he or she can start using MySensors. Hence it's very difficult to define what a Newbie is. Because instantly 3 different personas come to my mind. 1. the electronic enthusiast that knows all about circuits, but has no or low coding experience. 2. the software engineer that wants to start building his own devices. 3. A random person with no electronic nor coding knowledge. I I think that doesn't cover all different types of people that wanted to try out or start using MySensors.

My start point for creating good tutorials and examples would first be a thorough user analysis. So to define the different kind of new users with their needs. And from there I'd try to design for each user type. Because I don't believe you can cover each needs very easy. But that's just my 50 cents :)

[mfalkvidd]

@evb done

[skywatch]

@BearWithBeard I thought everyone knew I was a noob!

Good that you got the point i was trying to make.

@TheoL Then the first thing we need to do and make clear is who mysensors is aimed at. What prerequsites are needed to understand and use mysensors. This will save a lot of people from wasting their time.

[TheoL]

@skywatch I'm always willing to help with that. I love doing user research xd.

[skywatch]

@TheoL Great! - There are too many positngs on here asking for help and then the user never posts again. There are 2 possibilities. 1. They got it working themselves and never told us. 2. They gave up and got Alexa/Google/Siri etc to do it instead.

I would be happy to donate some time to docs if it would help.

[BearWithBeard]

I don't think there's are direct causal relationship between the quality of a documentation and the number of users asking for help on a forum.

People usually register to get help and you'll likely find that most people in this (or any) forum asked a question in their first post (me included) and most of them never came back after their issue has been solved or they lost interest. This forum has almost 10k registered users, of which 8k wrote five posts or less. From this we can't infer that most users trying to use MySensors encounter problems, nor that the documentation is flawed. That's just the nature of a support forum, or any forum, really.

Regarding this forum specifically, my gut feeling tells me that most questions are related to connection issues between nodes, which are usually caused by wrong or flimsy wiring, weak power supplies, too much noise, range issues, etc. The solutions for those issues are documented in articles as well as the FAQ, but people are still asking.

Maybe my gut feeling is wrong and it might be worthwile for us to browse through the troubleshooting forum. Comparing what people actually asked or were looking for and comparing it to how well those topics are covered in the articles and guides might be a more practical approach to improving the documentation.

[TheoL]

@BearWithBeard Well there are more things in play. Making assumptions now. Most people don't want to read the trouble shooting section, they just want to be helped quickly. And from a usability perspective written documentation isn't the most optimized form of transferring knowledge. Because it is almost impossible to write things in such a way every one can understand it. A simple comic on radio trouble shooting might help more people. But again, that is just assumptions.

I always try to find the solution myself. But have seen people asking question that were documented well. In this an other forums.

[skywatch]

@BearWithBeard I think that an 80% loss rate is not good whatever the reason.

I have suggested a 'knowledge base' in another thread today as a place to keep all updated and more advanced info in one place for reference. For starters I suggest 5 areas that crop up again and again.....

• Bootloaders
• Battery Powered nodes
• Signing
• Encryption
• FOTA

So have a knowledge base for each of the above with all the hints and tips up-to-date in one place with example code snippets.