Please document wifi.sleep function in official API docs

[alex3kov]

Did #725 and #731 made it into official public API? I don't see this function in the docs.
If it is official - can you document its behaviour please? What should users expect from it, what will wifi.sta.status() return when in sleep, do I need to set wifi config and/or connect anew after waking up, how it works with wifi.autoconnect(1) etc.
I tried to use it using cloud-built nodemcu-master-11-modules-2016-02-29-10-49-49-integer firmware - after putting wifi to sleep with wifi.sleep(1) wifi.sta.status() returns 255. After waking it up (wifi.sleep(0)) wifi.sta.status() also returns 255 and after trying to connect to WiFi I'm getting some garbage on serial console (using ESPlorer), losing serial communication with the module and have to restart it. Tried all of the above using either wifi.sleeptype(wifi.LIGHT_SLEEP) or wifi.sleeptype(wifi.MODEM_SLEEP) - same results. I'm not claiming it's a bug (yet) - because I don't know what to expect at this point :)

[dnc40085]

I must have forgot to add the documentation after the PRs were merged.

After you bring wifi out of sleep with wifi.sleep(0), the command wifi.getmode() will return 0 indicating that the ESP8266 is in NULL_MODE. from there you just use wifi.setmode() to change back to Station, SoftAP, or StationAP mode and go about your business.

I'll submit a PR with the documentation as soon as I get the chance.

[TerryE]

@dnc40085 This issue of how to safely use non-compliant (see #991) modules is possibly linked to this. I'd like to chat to you about this either as an issue here, by email or Skype. Up to you. I want to document a simple sequence / process for winding down and restarting the WiFi / net stacks so that is you want to run something with interrupts masked for an extended period then you can recover you comms without the ESP cratering. If you want you can PM me your email details at esp8266.com

[alex3kov]

@dnc40085 Thanks for clarification.
After playing with it adding "sleeping" (and "awake"?) to the list of states for wifi.sta.eventMonReg seems like a reasonable idea to me. What do you think?

[dnc40085]

@alex3kov You're welcome.
As for adding to wifi.sta.eventMonxxx(), I'm not sure if it would fit well there since those states are the same that are returned by wifi.sta.status and only runs in Station and StationAP modes.

On a side note, I was thinking before documenting this that I should expose the timed sleep functionality that also has a callback that can execute on wake up, or not at all if user wakes the chip before the timer runs out.

[dnc40085]

@TerryE I think you're right, forcing the wifi into sleep mode before using non-compliant functions would most likely stop any wifi related crashes. I'll do what i can to help.

I don't mind talking here in the issues section, unless you think it would be better to talk on esp8266.com or via email. I just like having conversations in the open, so if someone is looking for the same info it can be found and maybe even be helpful.

[alex3kov]

@dnc40085

As for adding to wifi.sta.eventMonxxx(), I'm not sure if it would fit well there since those states are the same that are returned by wifi.sta.status and only runs in Station and StationAP modes.

Can it fit somewhere else? :) I'm just looking to set up a callback function on some event monitor (not necessarily wifi.sta.eventMonxxx()) that gets triggered when WiFi is guaranteed to have woken up; so I don't have to worry about my wifi.sta.connect() or other operations occuring when WiFi is in the process of waking up. EDD and all that.

On a side note, I was thinking before documenting this that I should expose the timed sleep functionality that also has a callback that can execute on wake up, or not at all if user wakes the chip before the timer runs out.

Can callback be used without the timer please? I'm trying to react to events - as opposed to doing things at time intervals.

[dnc40085]

@alex3kov

I'm just looking to set up a callback function on some event monitor that gets triggered when WiFi is guaranteed to have woken up

When using the forced sleep API (wifi.sleep), the application developer determines when the transition occurs, it does not occur automatically.
So after you run wifi.sleep(0) you can immediately set station mode and connect with no problems.

If you really need this functionality, you can setup a timer(tmr.alarm) to monitor the return value of wifi.sleep and when there is a sleep to wake(1->0) transition, change mode and connect.

Can callback be used without the timer please?

Unfortunately, I have no control over this as it is part of the SDK functionality.

[TerryE]

@dnc40085, a question. (I am on my tablet so I don't have easy access to the source.) Is this SDK call async? I assume it is. In which case the application programmer will need to do a one shot alarm and cb to allow the sleep to occur. It's just that if the app does a sleep API call and immediately starts bit banging or whatever, then the WiFi stack might still due messily. Just a thought, and time for shut-eye for me.

[dnc40085]

@TerryE I'm pretty sure it's asynchronous.

From the notes section of wifi_fpm_do_sleep in the Espressif programming guide:

...the ESP8266 will not enter sleep mode immediately, it is going to
sleep in the system idle task. Please do not call other WiFi related
function right after calling this API.

When wifi.sleep(1) is executed, the following is done to force wifi in to sleep mode(MODEM_SLEEP_T):

• (If in station mode,) Disconnect from AP (wifi_station_disconnect)
• Switch wifi opmode to NULL (wifi_set_opmode(NULL_MODE))
• Enable forced sleep function (wifi_fpm_open)
• Force wifi into sleep mode (wifi_fpm_do_sleep(FPM_SLEEP_MAX_TIME))

Then when it is time to wake up (wifi.sleep(0)):

• Wake wifi up from forced sleep (wifi_fpm_do_wakeup)
• Disable forced sleep function (wifi_fpm_close)

[alex3kov]

@dnc40085 Doesn't your last comment confirm that we need callbacks on wifi.sleep for proper EDD coding? In line with what @TerryE wrote - if it's all asynchronous, then even this code could fail:

wifi.sleep(0)
wifi.setmode(wifi.STATION)

A timer can be set up as you mentioned - I just noticed in your post that wifi.sleep() returns a value, so I'm guessing something like this:

tmr.alarm(0, 200, tmr.ALARM_AUTO, function()
    if wifi.sleep(0) = 0 then
        wifi.setmode(wifi.STATION)
        -- connect to WiFi, do some things
        tmr.unregister(0)
    end
end)

But that's a rather hackish approach, no? This would be cleaner and more EDD-like:

wifi.sleep(0, function() -- <- callback that will be called when WiFi fully wakes up
    wifi.setmode(wifi.STATION)
    -- do things with WiFi
    end
)

[alex3kov]

@dnc40085 And another thing:

On a side note, I was thinking before documenting this that I should expose the timed sleep functionality that also has a callback that can execute on wake up, or not at all if user wakes the chip before the timer runs out.
Can callback be used without the timer please? I'm trying to react to events - as opposed to doing things at time intervals.
Unfortunately, I have no control over this as it is part of the SDK functionality.

Can this "wake up timer" be set up while WiFi is sleeping? If yes, then it can be used with a timeout of 1 ms and a callback function, accomplishing what I described in previous comment.

[TerryE]

@alex3kov Aleksei, your model isn't quite right here. Think of turning off the WiFi in the same way that you might ask the power utility to turn off power to your house because you need to do essential repairs. Just because you have made the request doesn't mean that it is going to have been done instantly. Start sticking your fingers into the electrical sockets and you will get electrocuted.

In this case the SDK will let any in progress activities complete gracefully, for example the network chip might still be in the process of sending a packet. The "in system idle task" comment is important. This means that even a node.task.post() call wouldn't be sufficient as this is still at a higher priority than idle. You need to schedule an alarm after say X msec and when this is delivered then the WiFi will be off. You can now bit-bang and ignore the 15 msec max task time rule, and when you are done then wake up the WiFi again. You don't necessarily want to wake it up immediately. You might also want to sleep for 10 mins or whatever until time to take your next reading.

[alex3kov]

@TerryE

Aleksei, your model isn't quite right here. Think of turning off the WiFi in the same way that you might ask the power utility to turn off power to your house because you need to do essential repairs. Just because you have made the request doesn't mean that it is going to have been done instantly. Start sticking your fingers into the electrical sockets and you will get electrocuted.

If you're talking about my last comment regarding setting wake up timer while WiFi is sleeping - that was just a wild guess at a possible workaround. I have no knowledge of Espressif SDK, so I don't claim that things work one way or another - just asking questions.

In this case the SDK will let any in progress activities complete gracefully, for example the network chip might still be in the process of sending a packet. The "in system idle task" comment is important. This means that even a node.task.post() call wouldn't be sufficient as this is still at a higher priority than idle. You need to schedule an alarm after say X msec and when this is delivered then the WiFi will be off. You can now bit-bang and ignore the 15 msec max task time rule, and when you are done then wake up the WiFi again. You don't necessarily want to wake it up immediately. You might also want to sleep for 10 mins or whatever until time to take your next reading.

It seems you're taking me for a more SDK-savvy person than I am :) I'm just looking for "as pure EDD as possible" ways to do things on Lua side. Do you agree with my reasoning in previous comment?

[TerryE]

@alex3kov Aleksei, We've been sorting issue out for a couple of years and are still trying to understand some things! This is as much a 2-way discussion.