WiFi.status() not documented

I wish Arduino team does a better job than just showing a bunch of loose beads with no thread, such as only providing a list of wifi functions without a real manual.

The following sample code uses both return value of WiFi.begin() and an UNDOCUMENTED function WiFi.status(), why not calling WiFi.status() in both cases?

 #include <WiFi.h>

char ssid[] = "yourNetwork";     //  your network SSID (name) 
char pass[] = "secretPassword";  // your network password
int status = WL_IDLE_STATUS;     // the Wifi radio's status

void setup() {
  //Initialize serial and wait for port to open:
  Serial.begin(9600); 
  while (!Serial) {
    ; // wait for serial port to connect. Needed for Leonardo only
  }
  
  // check for the presence of the shield:
  if (WiFi.status() == WL_NO_SHIELD) {
    Serial.println("WiFi shield not present"); 
    // don't continue:
    while(true);
  } 
  
 // attempt to connect to Wifi network:
  while ( status != WL_CONNECTED) { 
    Serial.print("Attempting to connect to WPA SSID: ");
    Serial.println(ssid);
    // Connect to WPA/WPA2 network:    
    status = WiFi.begin(ssid, pass);

    // wait 10 seconds for connection:
    delay(10000);
  }
   
  // you're connected now, so print out the data:
  Serial.print("You're connected to the network");
  printCurrentNet();
  printWifiData();

}

Yeah, just getting started on this whole "Arduino thing", myself, and that's one of the things I'm noticing, myself.

Their example code is creating a global integer value, which they manually set to a "not connected" state, before even entering the setup function.

Then, before executing WiFi.begin(), they're calling the undocumented function WiFi.status(), and checking it against the undocumented status, WL_NO_SHIELD.

Then, if they detect that the shield is present (and I like the fact that their example code does this. So often, example code doesn't really check for possible errors. I like example code that actually checks for things), then they go to a while loop (that's why they had to manually initialize their integer variable to a "not connected" status: To make sure that the while look executes. Otherwise, if their integer weren't initialized to a known value, it's possible for the code to think it's connected, and skip the while loop, without ever calling WiFi.begin()).

(I don't see why their value isn't local to the setup() function, nor why they don't change the while loop to a do...until, thus guaranteeing that it gets executed at least once.)

I assume my code is going to do things that way (assuming that my way works. I'm not really sure I have the credentials to be challenging the artistic style of The Founding Fathers, so to speak). And I'm going to break it out into a WiFiSetup() function, simply because I like my setup() and loop() functions to be as small and easy to read as possible.

But what gets to me (and the reason I Googled, and found this comment) is the undocumented nature of these functions and return values. I assume I'm competent to go pull up the source code for the library, myself, and MAYBE figure out full documentation, for myself. (Probably learn something from the attempt, at least. Which is rather part of my intent for fooling with this stuff, in the first place.) But even if I'm capable of doing that, I'll still have the nagging feeling that "if this stuff isn't officially documented, then am I running the risk of "my documentation" being wiped out by a future revision?"

I happen to be looking for the same info. This is from /arduino-1.0.5/libraries/WiFi/utility/wl_definitions.h

typedef enum { WL_NO_SHIELD = 255, WL_IDLE_STATUS = 0, WL_NO_SSID_AVAIL, WL_SCAN_COMPLETED, WL_CONNECTED, WL_CONNECT_FAILED, WL_CONNECTION_LOST, WL_DISCONNECTED } wl_status_t;

That means WL_NO_SHIELD = 255, WL_IDLE_STATUS = 0, WL_NO_SSID_AVAIL = 1 WL_SCAN_COMPLETED = 2 WL_CONNECTED = 3 WL_CONNECT_FAILED = 4 WL_CONNECTION_LOST = 5 WL_DISCONNECTED = 6

The best way to check this is to look at the library source.

On a Windows machine this will probably be in

C:\Program Files (x86)\Arduino\libraries\WiFi

on a Mac you need to open the Arduino bundle and find a similar folder

in wifi.cpp you find

uint8_t WiFiClass::status() { return WiFiDrv::getConnectionStatus(); }

and in begin you find

if (WiFiDrv::wifiSetKey(ssid, strlen(ssid), key_idx, key, strlen(key)) != WL_FAILURE) { do { delay(WL_DELAY_START_CONNECTION); status = WiFiDrv::getConnectionStatus(); }while ((( status == WL_IDLE_STATUS)||(status == WL_SCAN_COMPLETED))&&(--attempts>0)); }else{ status = WL_CONNECT_FAILED; } return status;

which shows that they make the same call....