System Modes Documentation - Suggestion


Unless I missed something the system modes documentation could be clearer about the need for a WiFi.on() and WiFi.connect() or similar commands to establish network connectivity for cellular when using SEMI-AUTOMATIC and I expect but haven’t tested MANUAL.

The examples all show the need for a Particle.connect() but no statement or commands that show you also need to turn on and connect WiFi. I read the text several times and didn’t find it clearly stated there either.

While it didn’t take me too long to figure out the need for those commands thanks to the LED status an addition to the documentation would have saved some time.



In case you weren’t aware, the docs are open source, and you can make edits by clicking the “edit” button in the top right corner. That’ll take you to the respective Github page where you can change it and make a respective pull request. Seeing as you’ve experience the pain-points, you’re most likely also the one who knows what additions would be most helpful and where.

@digitalhack @Moors7 Has answered your question about the documentation but not about the use of SEMI_AUTOMATIC mode?

You are referring to WiFi and Cellular in your first paragraph, I assume you are talking about a Photon and WiFi?

I won’t disagree about the documentation not being absolutely clear, it is correct but perhaps more to your point does not include ‘best practice’. There are several discussion threads covering all of this.

Important thing to understand is that you do not have to call WiFi.on(); followed by WiFi.connect(); WiFi.connect(); does both (if WiFi Module off), also it is not necessary to do WiFi.connect(); followed by Particle.connect(); you could just use Particle.connect(); there is also a difference as to when you make these calls either from setup() or from the loop() or a function called from there. Personally, I like to have control in my applications and hence I call WiFi.connect(); then waitFor(WiFi.ready, 6000); from setup() and if WiFi.ready() then call Particle.connect(); followed by WaitFor(Particle.connected,6000);


Since you haven’t really stated what platform you are refering to you might see different behaviour than what @armor has pointed out.

While it is true for Gen1 & 2 devices WiFi.connect(), Cellular.connect() and Particle.connect() implicitly perform all prerequisite steps in order to fullfill their duty that’s (unfortunately) not (yet) the case for Gen3 devices - hence the confusion maybe.

But for that there already is an issue reported

Other than that SYSTEM_MODE() wouldn’t be the place to document what constitutes a connection setup process. I’d rather see that as part of e.g. Particle.connect() to elaborate about the prerequisites.

@Moors7 @armor and @ScruffR,

Thank you for the feedback. I see that I missed several things. 1) I missed putting in my initial message that I saw the behavior on an Argon; 2) while I searched the forums and documentation I didn’t check issues in Github; and 3) I could have updated the documentation myself.



1 Like

Since the current behaviour isn’t as intended, I’ve added a note of caution to the docs for Particle.connect(), WiFi.connect() and Cellular.connect() on mesh devices.


Much appreciated.