Ambiguous documentation?

The documentation for Spark.sleep() says:
Spark.sleep(int seconds) does NOT stop the execution of
user code (non-blocking call). User code will continue running while the Wi-Fi module is in standby mode. During sleep, WiFi.status() will return WIFI_OFF. Once sleep time has expired and the Wi-FI module attempts reconnection, WiFi.status() will return value WIFI_CONNECTING and WIFI_ON.

This implied to me that the code in the neverending loop part of the firmware would do just that, loop forever. However, it appears that the code also runs the setup section of the code every time it wakes up after sleep. Thus the code ran from initial conditions after every sleep and my variables kept being reset to initial values. I have had to modify my code so that manual intervention soon after startup sets the intial conditions, not the setup part of the code. At least it works now and things are not mysteriously reset without my permission (so to speak). I think the docs should be changed to indicate that code runs from the beginning and doesn’t stay within the “forever” loop when sleep is involved. I am not using deep sleep by the way.



While the forum is a great place for asking questions, voicing comments, and sharing projects, comments like this, “bad documentation”, are literally what GitHub “issues” are for. When you run into incomplete or unclear documentation like this feel free to submit an issue here ( so the guys and gals @ Spark working on improving the documentation know what needs to be done.

That being said thanks for the report, I would have also assumed that sleep() runs the user loop() code indefinitely.

I disagree. Raise issues here. There are even topics in the forum intended precisely for the raising of documentation deficiencies. Ordinary users (which numbers most of us here) MUST NOT be discouraged from raising issues. Why should someone have to additionally sign up for a github account to report an issue with the Spark Core?


Let’s put it this way; the prefered method of reporting bugs is through the GitHub issues system. If there are really big problems, then please do post them here. If you’re capable of doing so on the GitHub, then please use that, since it’s a lot easier for the staff to work with that.
Besides that, if you’re planning on tinkering around with software, a github account isn’t really out of place(?)

The acolytes in the cathedral have the knowledge, they don’t need docs, they are familiar with the source code.

But it defies comprehension that could shoot itself in the foot in this way. If what you say is correct about github being no barrier then why did they bother with the easy web IDE, building in the cloud? No, that’s a nonsense. The user documentation must be correct and complete. And reporting deficiencies must be encouraged.

The problem is that is confused about who the users are. Or at least they send mixed signals.

I am not affiliated with the company or project in any way other than owning several Cores and being endlessly frustrated at the quality of the documentation. I have made a note of the doc issue you, @gotopcs, have identified at which is where I thought the well-established consensus said documentation deficiencies should be collated. Speaking only for myself please continue to raise each and every documentation issue separately, just as you have done and don’t be dissuaded from doing so by administrative barriers put in your way.

To my knowledge the Spark staff has no plans to construct any “administrative barriers” so let’s ease up on the tone here.

My original post was less of a “hey dummy, you posted in the wrong place” and more of a “thanks, and in case you didn’t know there is actually a specific location for posting documentation issues.” Anyone interested in using the Spark Core & in programming the Spark Core would benefit from being familiar with GitHub so I don’t think the GitHub account creation issue exists.

And as I said earlier, thanks for the post @gotopcs, it was informative.

Up until now no one has been suggesting to ordinary users of Sparks that they need to report documentation issues on github(). That is a discouragement to even report an issue.

The tone you object to is not the one where a Spark user is left 13days after his last post ( ) about this issue and is then told best to go get a github() account.

Note, @psb777 was referencing this post:

Nobody is demanding he go out and get a github account. I was suggesting that documentation issues are best reported in the documentation github.

That being said, after looking at the both this post’s issue and the referenced post, these two issues are both related to sleep but not directly related to each other. Users may continue to ask for help if no one replies. In the referenced post, a 13 day old last post suggests, at least to me, that the user probably figured the issue out. That being said, I will be on the lookout for such posts in the future.

The SparkCore is an (open source) development platform. People buying into the Spark Core are buying into the development platform. While there is no expectation for anyone who uses it to be part of that development I will continue to suggest that, given the open-source nature of the Core, they submit bug reports, feature requests, documentation errors, etc in the correct location. I am not discouraging users to report issues. I’m simply trying to direct them to the best location so that their issues are best handled in a fast and correct manner.

1 Like

“correct location”: Up until this thread the decided correct location for users to report documentation deficiencies has not been where you say it is. There has been a decided place.

I know I overuse this metaphor, but if you speak ex-cathedra then, when you do, you need to say when you are doing so, just like the Pope.

Where do we now report errors in the documentation?

If it is github please advise how many bug reports (of any type) have been made there by anyone in the last 12 months who is not an “Elite” or higher?


“Correct” Locations to report bug, feature requests, documentation issues, etc:

  • the correct Spark Github repo as an issue
  • the Spark forums as a post
  • a text to a friend who knows more about Spark then you
  • you local newspaper as a classified
  • pretty much anywhere you want

Best Locations to report a bug, feature requests, documentation issues, etc:

  • the correct Spark Github repo as an issue

Good locations:

  • the Spark forums as a post

I personally believe that the major reason for a lack of GitHub issues is a lack of public exposure. Many people who are using the SparkCore are casual Arduino converts who have never even heard of version control. I’m trying to both educate people and also solve problems as fast as possible.

Zero instances?

Let’s see, so now we ordinary users have to monitor github as well as the forum. Until now, before we report a problem here the considerate amongst us would check to see if the issue had already been dealt with. In the forum. And now we must check here, but also at github? And where will the discussion about the imperfectly reported non-bug, misunderstanding, workaround happen? Here, or at github?

And how does one decide, as a newbie, or as someone who is not intimately familiar with the source code, or as someone who just doesn’t want to be that involved, whether the error is with the documentation, or with the function? So which github repository? And we must understand version control.

These are the administrative barriers to which I referred.

Out of the nine i checked at random I saw 6. yes, a large portion of them are Spark staff but I hope to change that

And the others were Elites?

We’ve moved well within the bounds of being “off topic.” Any additional comments in that thread not referring directly to OP’s original post will be removed. Sorry :frowning:

@gotopcs, sorry for all the messages, your little message balloon count must be blowing up.