Generic WiFi Design

Here we are capturing the design of a generic WiFi interface that will be implemented by the likes of ESP8266. The name of the interface has not been finalized but in this document, we will assume it will be called wifi.

This page will be deleted and/or used for the basis of proper documentation when work has been completed. There is a forum thread discussing this work item. There is also an explicit work item tracking the detailed implementation and design (#589).

Before we go deep into design thoughts, it is always good to see what others have done. There is absolutely no reason that we don't just do exactly what has been done before. Here are some variants:

• particle.io
• smart.js
• Windows WiFIDirectDevice
• Android WiFiManager
• Others???

---

###setPower wifi.setPower(onOrOff, function(err) { ... })

Initialise WiFi, or turn it off. That could be handy?

• onOrOff [Boolean] - Switch on or off the WiFi interface. Useful to switch off WiFi to reduce power consumption.

---

###connect wifi.connect(ssid, key, [options], function(err) { ... });

Connect to the given access point. The options could be an object extra stuff like the security type.

The callback is called with err==null on success. Could maybe also return the IP?

####Comments

• Kolban: When should the callback occur? Choices include when connected or when connected AND ready for use?
• Kolban: My vote would be an object of properties as opposed to positional parameters.
• Kolban: What should be in the options like data? For example static IP address, hostname etc etc?

---

###disconnect Disconnect from an access point (assumes a previous connect()).

wifi.disconnect(function(err) { ... });

---

###getAPs wifi.getAPs(function(err, aps) { ... });

Call the callback with a list of discovered access points, of the form aps = [ { ssid, enc, signal_strength, mac_address } ].

The callback is called with err==null on success.

• err - Error indication.
• aps - Array of objects, one per found access point.

####Comments

• tve: Should this be called scan as opposed to getAPs?

---

###getConnectedAP wifi.getConnectedAP(function(err, ap) { ... });

Call the callback with the name of the currently connected access point. The callback is called with err==null on success.

• err - Error indication.
• ap - Details of the currently connected access point.

####Comments

• Kolban: What should be included in the response data?

---

###createAP wifi.createAP(ssid, key, channel, enc, function(err) { ... })

Create an access point with the given ssid, key, channel, and encoding. Encoding can be 0, undefined, "open", "wep", "wpa_psk", "wpa2_psk" or "wpa_wpa2_psk".

Example: wifi.createAP("ESP123","HelloWorld",5,"w­pa2_psk",print)

####Comments

• Kolban: I had thought that a good name would have been becomeAP but I think I am now liking createAP better.
• Kolban: My vote would be an object of properties as opposed to positional parameters.

---

###getConnectedDevices wifi.getConnectedDevices(function(err, devices) { ... });

If if AP mode (with wifi.createAP), call the callback with the second argument as an array of { ip, mac } objects - one for each connected device.

####Comments

• Kolban: I am not a fan of the name of the function. I would suggest something like getConnectedStations as it aren't devices which connect to access points but rather stations.

---

###getIP wifi.getIP(function(err, ip) { ... });

Call the callback with the current address details: {ip:string, mac:string, ...?}

The callback is called with err==null on success.