Skip to content

Generic WiFi Design

Jump to bottom Edit New page
Gordon Williams edited this page Sep 30, 2015 · 30 revisions

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:

###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.

Comments

  • gw: setMode was suggested here - I think something like that makes more sense?

###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?
  • Sameh Hady: I guess callback should occur once connected and ready. ( My vote )
  • 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?
  • Sameh Hady: Maybe an option to set auto connect true or false

###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?
  • Sameh Hady: Vote for scan

###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?
  • gw: Unsure. Maybe it makes sense to merge this and getConnectedDevices?

###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.
  • gw: My preference is an object too - with sensible defaults (is there a channel that can be used legally in all regions? 5?)

###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.

####Comments

  • Sameh Hady: I prefer to make this function generic, something like wifi.info(function(err, wifi) { ... }) that returns an object ( wifi.ip, wifi.mac, etc )
  • gw: The suggestion is that this is generic (in all but name), returning all that info. Choice of name is because that's what is currently implemented, but it could be changed. If it were changed I think there must be something more informative than info though. Probably needs to be getX to mirror a setX too.

###setIP wifi.setIP(data, function(err) { ... });

Call the function with address details - items left out are not changed: {ip:string, mac:string, ...?}

Current behaviour on CC3000/WIZnet is to do DHCP if called without arguments.

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

Add a custom footer
Add a custom sidebar
Clone this wiki locally