WiFi generic object interface

[nkolban]

Background: Forum article post

As more board types start to offer WiFi services such as:

• connect as station
• list access points
• be an access point

Unless we do something, we will see fragmented implementations and different styles of interaction. This work item will include the requirements gathering, design, documentation and implementation of a general purpose interface that is board agnostic.

One of the early implementors of the interface will be the ESP8266 port.

A WiKi page has been created to capture discussion items for all on this work item.

[nkolban]

This work item needs coupled with #630.

[nkolban]

Initial lower level design work has started but we immediately ran into a major design question. Should the wifi object be a class or a library? Can we store state of the wifi object in this class or library? For example, if one calls the connect() method and passes in a callback function, can we store a reference to the callback function off some JS object instance that represents the wifi object? And if so, how?

[gfwilliams]

I'd a library. I know you hate me saying 'look at the code', but:

JSNetwork stores callbacks in a hidden net variable:

https://github.com/espruino/Espruino/blob/master/libs/network/js/network_js.c

And the other network stuff stores data (pins, etc) in JsNetworkData, which it accesses like:

  JsNetwork net;
  if (!networkGetFromVar(&net)) return;

  // do stuff

  // if it changed, then
  networkSet(&net);

  networkFree(&net);

• https://github.com/espruino/Espruino/blob/master/libs/network/cc3000/jswrap_cc3000.c
• https://github.com/espruino/Espruino/blob/master/libs/network/wiznet/jswrap_wiznet.c

I'd be tempted to stick with the hidden net variable though, because it'll be more resilient to save()/etc.

If you were to store all data in a single user-accessible class then it's possible someone might do something like create another, or clone the existing and it'd really screw you up.

[nkolban]

Howdy @gfwilliams I looked at the code of cc3000 and of wiznet ... and think I realize that their is a misunderstanding on what I am thinking. I see that the JsNetwork object contains the callbacks to the generic TCP/IP functions such as createsocket, closesocket, accept etc etc and the ESP8266 falls in line with that architecture today.

However ... the ESP8266 needs ESP8266 specific callbacks remembered as well. For example, the ESP8266 needs to remember a callback for connecting to an access point.

eg.

wifi.connect(ssid, password, function() {
   print("We connected");
});

The function passed into wifi.connect() needs to be remembered.

[nkolban]

Work is actively underway on this issue. Currently implemented functions are:

• jswrap_ESP8266_wifi_connect
• jswrap_ESP8266_wifi_createAP
• jswrap_ESP8266_wifi_disconnect
• jswrap_ESP8266_wifi_getIP
• jswrap_ESP8266_wifi_scan

Now comparing in detail against wiki design specs.

The latest binaries now have these functions included.

Comments posted on the gitter stream inviting users to test the function and see how close we are to what is desired.

[tve]

In reviewing the esp8266 Wifi implementation it strikes me that each implementation will have its peculiarities. Some things will be supported and others not. Some functions may behave in a slightly odd way. Some functions may be added as device-specific. All this will want documentation. I'm wondering whether as a result the following set-up wouldn't be nice:

• each implementation creates its device-specific wifi object, such as esp8266_wifi, esp8266AT_wifi, emw3165_wifi`, ...
• the device-specific objects are listed in the documentation and all device specific docs are attached to these, so there's a clear place to go to find out about the esp8266's wifi odditites
• device-specific extensions are implemented by the device-specific object
• there is a generic wifi object, which is just an indirection to load the device specific object and point to it, so code that uses generic functions can use Wifi.foo() and be oblivious to which device it's running on
• generic documentation is attached to the generic Wifi object

[gfwilliams]

That's a really good idea... It might require a small change to build_jswrapper, but shouldn't be big at all. It'd make the documentation easier too - much better than if we somehow had to combine docs for different implementations called the same thing.

[nkolban]

Addition of "dnsServers" option for wifi.connect().

[nkolban]

After some more thought, I decided to change the concepts of how the settings for defaults at boot should work. Here are the new concepts:

wifi.connect() now has an options object which contains default. For example:

wifi.connect(..., { default: true }, ...);

Will make this connect and settings the default at the next boot.

wifi.createAP() now has an options object which contains default. For example:

wifi.createAP(..., { default: true }, ...);

Will make this access point and settings the default at the next boot.

wifi.disconnect() now has an options object which contains default. For example:

wifi.disconnect(..., { default: true }, ...);

Will remove any default station connect at next boot.

wifi.stopAP() now has an options object which contains default. For example:

wifi.stopAP(..., { default: true }, ...);

Will remove any default creation of an access point at next boot.

[tve]

What are the semantics of omitting the default option?

[nkolban]

If we omit the default option or set the default value to false ... then the current "default" settings remain the same. Literally following a reboot with "default = false" or "default omitted" then it will be as though the API that had default = false had not happened.

[nkolban]

As I continue to "play" at being a consumer of the new generic wifi interface, I found that I needed to know the set of stations connected to my device when it was being an access point. To that end, I have chosen to introduce the concept of wifi.getStatus(). This returns an object that represents the status of the WiFi environment. It has been documented in the User Guide for the ESP8266 port. I believe it will be tweaked before we are done as community members request changes ... however with this as a starting point, changes will be able to be made quickly.