Documentation for WiFi.persistent() is misleading

[herm]

Documentation at http://arduino-esp8266.readthedocs.io/en/latest/esp8266wifi/generic-class.html says
Setting persistent to false will get SSID / password written to flash only if currently used values do not match what is already stored in flash.

But the code does something different:

Arduino/libraries/ESP8266WiFi/src/ESP8266WiFiSTA.cpp

Lines 136 to 151 in 35d5fab

	if(sta_config_equal(current_conf, conf)) {
	DEBUGV("sta config unchanged");
	}
	else {
	ETS_UART_INTR_DISABLE();
	if(WiFi._persistent) {
	// workaround for #1997: make sure the value of ap_number is updated and written to flash
	// to be removed after SDK update
	wifi_station_ap_number_set(2);
	wifi_station_ap_number_set(1);
	wifi_station_set_config(&conf);
	} else {
	wifi_station_set_config_current(&conf);
	}

It writes settings to flash if they don't match the values in flash if persistent is set to true. If it is false it will not write to flash independent of the current value in flash.

[tablatronix]

All functions that use persistent and config equal or saves needs to have default/current conditional based on persistent. There are a few, I will make note of them.

[tablatronix]

ESP8266WiFiAPClass::softAP
ESP8266WiFiSTAClass::begin

This also affects functions that check mode, but save persistent
ESP8266WiFiGenericClass::mode

    if(wifi_get_opmode() == (uint8) m) {
        return true;
    }

It is also special note, that the docs say
This API can be called only if ESP8266 Station is enabled.
I am not sure if this applies to *_default config (docs only mention flash) or what the consequences are, it may be necessary to add a sanity check if it is prohibited.

The main problem with persistent is that is assumes current config has not been changed from default, which it can be by toggling persistent on and off. So both need to be checked in comparisons.

[tablatronix]

This is what I am thinking

#3798

[herm]

I'm not sure if the changes you propose are required or not. However they are unrelated to this issue. The problem here was that the code does something else than the documentation says. But the code's behavior is good so the documentation has to be changed.

[tablatronix]

Then I will create another issue, because I believe it is wrong and badly implemented. I see what you mean about the negated persistent functionality now, I missed that before.

[Raynman77]

@herm Just curious, whats the reason for the underscore in your line containing WiFi._persistent?

[tablatronix]

That is the name of the variable used in the library.

[Raynman77]

I haven't looked into it yet. Was looking at storing wireless credentials, read the esp8266 core general class docs, and "WiFi.persistent(false)" didn't contain the underscore. Was just curious if this was going to be a "gotcha" when I finally come around to coding for the esp8266

…

On Wed, Apr 25, 2018, 2:28 PM Shawn A ***@***.***> wrote: That is the name of the variable used in the library. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#3641 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/APr_s0oDxICm-8Y5m-dp3nRys4sm70bRks5tsMBjgaJpZM4Phpgi> .

[tablatronix]

No thats the private variable you have a function call your good

[Raynman77]

Cool, thanx Shawn

…

On Wed, Apr 25, 2018, 3:22 PM Shawn A ***@***.***> wrote: No thats the private variable you have a function call your good — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#3641 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/APr_sxfkIGRyXDq9rMvMqnnxlUXmlgctks5tsMzygaJpZM4Phpgi> .

[tablatronix]

Frequently calling these functions could cause wear on the flash memory

Only if ! notconfigequals, perhaps we should add debugging strings when doing set config defaults to help debug that?

[devyte]

Paranoia is your friend in these cases, so I agree.

[tablatronix]

there is currently
DEBUGV("sta config unchanged");
but that is the opposite of what you would want
Ill open an issue and try to pr it in the 2-3 places that it happens, would help find really bad stuff like loops