Add function wifi.sleep

[dnc40085]

This pull request adds functionality to force wifi radio into sleep mode without restart.

This is also workaround for the deep sleep issue #721 where executing node.dsleep(us, 4) does not disable radio upon waking up

wifi.sleep()

Description

Force wifi radio into sleep mode.

Note:

• if wifi radio was disabled using node.dsleep(us, 4) executing wifi.sleep(0) WILL NOT re-enable wifi radio.
• Wifi mode MUST BE SET after re-enabling wifi radio, since wifi.sleep(1) sets wifi mode to NULL.

Syntax

wifi.sleep()
wifi.sleep(desired_sleep_state)

Parameters

desired_sleep_state: (if sleep state was changed, return new sleep state. otherwise return current sleep state)

• 0 : Disable sleep mode
• 1 : Enable sleep mode
• nil : Do not change sleep state, return current sleep state.

Returns

Current WiFi sleep mode

Example

    --get current wifi sleep state
    print("wifi sleep mode is currently set to"..wifi.sleep())

    --enable forced wifi radio sleep
    print("forced wifi sleep mode is now set to "..wifi.sleep(1))

    --disable forced wifi radio sleep
    print("forced wifi sleep mode is now set to "..wifi.sleep(0))
    wifi.setmode(wifi.STATION) --WIFI MODE MUST BE SET AFTER WIFI RADIO IS RE-ENABLED
    wifi.sta.connect()

[jmattsson]

I like the idea here, but it feels like there's a mismatch between the exposed Lua API and the underlying SDK API. Using wifi.sleep(1) will only put the radio to sleep for a maximum of 268 seconds (less than 5min) if I'm reading this correctly. The expectation I would have as a user would be that the wifi is put to sleep until I call wifi.sleep(0).

[dnc40085]

Judging by what the SDK programming guide(v 1.4.0) says on page 86 under the function wifi_fpm_do_sleep if the sleep time is set to 0xFFFFFFF and wifi_fpm_set_sleep_type is set to MODEM_SLEEP_T. The wifi radio will only wake by executing the function wifi_fpm_do_wakeup.

Also, I've found that in my own testing the wifi radio stays asleep much longer than 268.4 seconds.

[jmattsson]

That's what I get for not RTFM'ing the full thing and only looking at user_interface.h. This is looking pretty good then! My only question is whether there is any particular reason why the new flag variable isn't declared static?

Unless someone has objections, I'd be happy to merge this in this week.

[TerryE]

+1 It should be static bool FLAG_wifi_force_sleep_enabled=0; I'd better go through my luac.cross patch and make sure that I've not missed any! 😄

[dnc40085]

My only question is whether there is any particular reason why the new flag variable isn't declared static?

Oops, I forgot to add the keyword, thanks for pointing that out.

I was thinking of adding code to return an error if wifi_fpm_do_sleep does not return a 0. I left it out to keep the code as short as possible, maybe it could be added for debugging purposes with #ifdef DEVELOP_VERSION to exclude it during normal use.

Any other ideas or suggestions?

[TerryE]

I was thinking of adding code to return an error if wifi_fpm_do_sleep does not return a 0.

As a general rule if a system routine returns a status, then we should not ignore this, as doing so causes silent failures that are incredibly difficult to debug. So either a lua_error() or a return status IMO, and the latter is probably easier for everybody.

[dnc40085]

So either a lua_error() or a return status IMO, and the latter is probably easier for everybody.

how about adding the return value so it is also returned with current wifi status similar to this: new_wifi_sleep_state, wifi_fpm_do_sleep_retval=wifi.sleep(1)

[TerryE]

My ideas was similar. Why not follow the pcall() model. Either the return is new_wifi_sleep_state, nil on a normal return or nil, error_return on an invalid return. This is upwards compatible with sloppy programs that only do a:

new_wifi_sleep_state = wifi.sleep(1)

[dnc40085]

@TerryE I made the changes you suggested and submitted a PR(#731)