Incorrect documentation on WiFi module (wifi.sta.config)

[msurikov]

The WiFi module documentation states that event callbacks in wifi.sta.config() have names connected_cb and disconnected_cb. Actually (according to the code) they should be named as connect_cb and disconnect_cb. Also, the disconnect_cb callback returns item reason instead of the specified REASON (in wifi.sta.disconnect too).

[marcelstoer]

Haven't confirmed but we'd be happy to accept a PR with a fix.

[FrankX0]

IMO the used calback names are accurate (enough). Both callback functions are called when the station is either connected to or disconnected from an access point. So both used names are accurate. But then again, these are just names for placeholders to specify the actual callback functions. Your other observation is correct: it should state reason instead of REASON.

wifi.sta.disconnect(function(T)
    print(T.reason) -- returns 8
    print(T.REASON) -- returns nil
end)

[marcelstoer]

Hope I didn't miss any in c8d2937.

[msurikov]

Guys, I am talking about item names passed to wifi.sta.config but not about callback names passed to wifi.sta.connect and wifi.sta.disconnect! The WiFi module does not accept items with names connected_cb and disconnected_cb passed to wifi.sta.config. Instead, you should use item names connect_cb and disconnect_cb, otherwise your callback will never be called. The doc is wrong in this part.

[msurikov]

Please, see my code that demonstrates this issue:

station_cfg={}
station_cfg.ssid="NODE-AABBCC"
station_cfg.pwd="password"
-- The documented configuration item that should specify "Callback to execute when station is connected to an access point."
station_cfg.connected_cb = function(T)
    -- Will never be called!
    print("The documented connect callback.")
end
-- The documented configuration item that should specify "Callback to execute when station is disconnected from an access point. "
station_cfg.disconnected_cb = function(T)
    -- Will never be called!
    print("The documented disconnect callback.")
end
-- The undocumented configuration item to specify "Callback to execute when station is connected to an access point."
station_cfg.connect_cb = function(T)
    -- Will be called in reality!
    print("The undocumented connect callback.")
end
-- The undocumented configuration item to specify "Callback to execute when station is disconnected from an access point. "
station_cfg.disconnect_cb = function(T)
    -- Will be called in reality!
    print("The undocumented disconnect callback.")
end
wifi.sta.config(station_cfg)

[msurikov]

Guys,

You are too hurried to close this issue. I have no doubts that callback names in wifi.sta.connect and in wifi.sta.disconnect are just placeholders. But I raised this issue against wifi.sta.config which has items that should specify connect/disconnect callbacks and the documented names of these items are wrong.

Please, reopen this issue.

Thanks, Michael

Вторник, 27 февраля 2018, 1:24 +03:00 от Marcel Stör [email protected]:

Closed #2275 . — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub , or mute the thread .

[devsaurus]

Good catch @msurikov! The code example demonstrates pretty clearly the inconsistency between doc and implementation.

[schneis]

I just ran into this issue with some code I'm working on.

I am reading the documentation from here: https://nodemcu.readthedocs.io/en/release/modules/wifi/#wifistaconfig

This says the CB names are "connected_cb" and "disconnected_cb".

I built firmware using nodemcu-build.com recently and the example code in this issue shows that the "undocumented" callbacks are being used. This is the full version information that I have:

NodeMCU 3.0.0.0 built on nodemcu-build.com provided by frightanic.com branch: release commit: d4ae3c364bd8ae3ded8b77d35745b7f07879f5f9 release: release DTS: 202105102018 SSL: true build type: integer LFS: 0x0 bytes total capacity modules: crypto,file,gpio,http,mqtt,net,node,tmr,uart,wifi,tls build 2021-10-02 06:50 powered by Lua 5.1.4 on SDK 3.0.1-dev(fce080e)

It would be extremely helpful if the documentation online matched what the firmware does. Can the documentation please get updated??

[HHHartmann]

Unfortunately this issue is valid again. I would suggest to fix it by changing the doc to connect_cb and disconnect_cb. That would better match the other callbacks.

[marcelstoer]

It was fixed with #2282 but (accidentally?) undone with #2287 six weeks later. In #2282 it was argued that

align the implementation to the doc (and not vice versa) since the *ed_cb terminology fits better to the underlying SDK (e.g. EVENT_STAMODE_CONNECTED)