Google Groups no longer supports new Usenet posts or subscriptions. Historical content remains viewable.
Dismiss

Simple network information API

1,510 views
Skip to first unread message

Jonas Sicking

unread,
Feb 20, 2012, 5:08:33 AM2/20/12
to dev-webapi
Here's what I was thinking as a simple WiFi API:

interface WiFiManager {
DOMRequest getNetworks(); // request.result set to JS array of wifi
networks in range
DOMRequest connectTemp(any parameters); // request fires success if
successfully able to connect, error otherwise

any connected; // JSON object (frozen) which contains info on the
connected network
Function onconnect; // Fires event when we connect to a new wifi network
Function ondisconnect; // Fires event when we connect to a new wifi network
}

To set up the list of networks which we should simply use the settings API.

/ Jonas

Vivien

unread,
Feb 20, 2012, 8:45:23 AM2/20/12
to Jonas Sicking, dev-webapi
Will it be possible to add a property that tell you the signal level of
networks?

Jonas Sicking

unread,
Feb 20, 2012, 9:46:17 AM2/20/12
to Vivien, dev-webapi
Yes, that should definitely be in there too. Good catch. Together with
an event which is fired when the level changes.

/ Jonas

Jonas Sicking

unread,
Feb 21, 2012, 5:54:53 AM2/21/12
to Vivien, dev-webapi
Here's the updated API based on Viven's feedback, as well as help from DougT:

interface WiFiManager {
DOMRequest getNetworks(); // request.result set to JS array of wifi
networks in range
DOMRequest connectTemp(any parameters); // request fires success if
successfully able to connect, error otherwise

any connected; // JSON object (frozen) which contains info on the
connected network

int signalStrength; // Not sure what the range is here

Function onconnect; // Fires event when we connect to a new wifi network
Function ondisconnect; // Fires event when we connect to a new wifi network
Function onsignalstrengthchange; // Fires event signal strength changes
}

The JSON objects returned from getNetworks and .connected have the
following structure:

{
name: "foo",
mac: "12-ab-...",
signal: 5, // doesn't appear in .connected
crypt: "wpa2"
}

We may also need a "channel" parameter, but I'm not sure. Feedback welcome.

For the connectTemp method the JS object would look something like:

{
name: "foo",
password: "secret"
}

I'm not sure if we should also allow passing mac and crypt parameters
to connectTemp to ensure that we don't connect to a network that just
happens to have the same name?

/ Jonas

Gervase Markham

unread,
Feb 21, 2012, 10:05:18 AM2/21/12
to Jonas Sicking, dev-webapi, Vivien
On 21/02/12 10:54, Jonas Sicking wrote:
> int signalStrength; // Not sure what the range is here

I'd go for a percentage, if it has to work across various different
types of network interface.

BTW, is this always WiFi? You call it a Simple Network Information API,
but you call it interface WiFiManager. What about 4G, 3G, wide area
networking, Bluetooth, and technologies yet to be invented?

> Function onsignalstrengthchange; // Fires event signal strength changes

Signals fluctuate a lot. Are you going to implement some sort of
threshold? E.g. the event fires whenever the signal has changed 10% or
more from the last time it fired.

Gerv

Gervase Markham

unread,
Feb 21, 2012, 10:05:18 AM2/21/12
to Jonas Sicking, dev-webapi, Vivien
On 21/02/12 10:54, Jonas Sicking wrote:
> int signalStrength; // Not sure what the range is here

I'd go for a percentage, if it has to work across various different
types of network interface.

BTW, is this always WiFi? You call it a Simple Network Information API,
but you call it interface WiFiManager. What about 4G, 3G, wide area
networking, Bluetooth, and technologies yet to be invented?

> Function onsignalstrengthchange; // Fires event signal strength changes

Gervase Markham

unread,
Feb 21, 2012, 10:05:18 AM2/21/12
to Jonas Sicking, dev-webapi, Vivien
On 21/02/12 10:54, Jonas Sicking wrote:
> int signalStrength; // Not sure what the range is here

I'd go for a percentage, if it has to work across various different
types of network interface.

BTW, is this always WiFi? You call it a Simple Network Information API,
but you call it interface WiFiManager. What about 4G, 3G, wide area
networking, Bluetooth, and technologies yet to be invented?

> Function onsignalstrengthchange; // Fires event signal strength changes

Jonas Sicking

unread,
Feb 22, 2012, 6:57:34 AM2/22/12
to Gervase Markham, dev-webapi, Vivien
On Tue, Feb 21, 2012 at 4:05 PM, Gervase Markham <ge...@mozilla.org> wrote:
> On 21/02/12 10:54, Jonas Sicking wrote:
>>
>>  int signalStrength; // Not sure what the range is here
>
> I'd go for a percentage, if it has to work across various different types of
> network interface.
>
> BTW, is this always WiFi? You call it a Simple Network Information API, but
> you call it interface WiFiManager. What about 4G, 3G, wide area networking,
> Bluetooth, and technologies yet to be invented?

I have a sneaking suspicion that different network technologies will
be different enough that the same API doesn't make sense, at least the
pieces beyond getNetworks(). So it seems to me to make more sense to
keep all the wifi functionality together, the bluetooth functionality
together etc, than to reuse the getNetworks function across multiple
technologies.

>>  Function onsignalstrengthchange; // Fires event signal strength changes
>
> Signals fluctuate a lot. Are you going to implement some sort of threshold?
> E.g. the event fires whenever the signal has changed 10% or more from the
> last time it fired.

Something like that sounds like a good idea yes.

/ Jonas

Philipp von Weitershausen

unread,
Mar 8, 2012, 12:30:28 AM3/8/12
to Jonas Sicking, dev-webapi
I kinda missed this thread, probably due to the work week that was
going on simultaneously :/

Anyway, at the same work week, Jonas and I also came up with an API to
represent a mobile data connection:
https://wiki.mozilla.org/WebAPI/WebMobileConnection. I would suggest
that we try to make these APIs look similar as much as possible. Some
of this may as well be bikeshedding, though I think developers would
appreciate consistency -- I know I would.

Some points inlined below:

On Mon, Feb 20, 2012 at 2:08 AM, Jonas Sicking <jo...@sicking.cc> wrote:
> Here's what I was thinking as a simple WiFi API:
>
> interface WiFiManager {

What is the intended API name of this object? navigator.wiFiManager?
For SMS, Telephony, we just do navigator.sms, navigator.telephony,
"manager" bit, so I would suggest we stick with that convention and do
navigator.wifi or something similar. Weird camel casing (even though
perhaps technically correct) is asking for lots of frustrating typos.
Another data point: WebMobileConnection, I initially saw it as an
excention to navigator.connection, but perhaps it should be more than
that. Then again, we could create a new "connection" family and do
navigator.wifiConnection.

>  DOMRequest getNetworks(); // request.result set to JS array of wifi
> networks in range

WebMobileConnection calls this listAvailableNetworks, but getNetworks
is shorter and probably just as clear, so I'll change
WebMobileConnection.

>  DOMRequest connectTemp(any parameters); // request fires success if
> successfully able to connect, error otherwise

What's with the "Temp"? Does it stand for temporary? If so, why?

I like the idea of passing an object for parameters. I think we should
definitely spec it out, probably containing lots of optional
attributes.

Another question: where do we expect wifi keys to be stored? In Gecko?
In the UI (e.g. Gaia), perhaps via settings API, perhaps in its own
little DB? Basically, do we expect the UI to simply store all that
information itself and then pass it into connectTemp() each time we
connect? This would have pretty severe implications, because it would
mean that the UI would also have to watch networks becoming available,
connecting to them when they do and are "known", etc. This *feels*
like a Gecko-level task to me, but I'm not sure. My initial idea of
the system would have been a bit more like we do HTTP Basic Auth:
Gecko prompts the UI if it doesn't know credentials yet, otherwise it
just connects.

>  any connected; // JSON object (frozen) which contains info on the
> connected network

In WebMobileConnection this is a bool, with "operator", etc. providing
the information about the current connection. Should we adopt a more
nested approach for WebMobileConnection, too? Or live with the
inconsistency?

>  Function onconnect; // Fires event when we connect to a new wifi network
>  Function ondisconnect; // Fires event when we connect to a new wifi network

In WebMobileConnection you suggested "onconnectionchange", and then
consumers would have to look at the individual state flags. I would
certainly advocate for this as well. In particular, I imagine more
states than just "connect" and "disconnect". At least "connecting"
would be good for UI feedback.


As for signal strength, please see WebMobileConnection. We also had
some good discussion on that in
https://bugzilla.mozilla.org/show_bug.cgi?id=729173. I haven't looked
into the Wifi pieces yet on how we get the information, but again,
consistency across APIs would be great (e.g. a number ranging from 0
to 1.0).

Lastly, I think Wifi also allows you to get the signal strength of
networks you're not connected to currently. So the question is whether
maybe signal strength shouldn't be exposed on WiFiManager but on the
"connected" object, or whatever. This would mean making that object
more complicated than just being frozen JSON, though.

Jonas Sicking

unread,
Mar 8, 2012, 5:51:18 AM3/8/12
to Philipp von Weitershausen, dev-webapi
On Wed, Mar 7, 2012 at 9:30 PM, Philipp von Weitershausen
<phil...@googlemail.com> wrote:
> I kinda missed this thread, probably due to the work week that was
> going on simultaneously :/
>
> Anyway, at the same work week, Jonas and I also came up with an API to
> represent a mobile data connection:
> https://wiki.mozilla.org/WebAPI/WebMobileConnection. I would suggest
> that we try to make these APIs look similar as much as possible. Some
> of this may as well be bikeshedding, though I think developers would
> appreciate consistency -- I know I would.
>
> Some points inlined below:
>
> On Mon, Feb 20, 2012 at 2:08 AM, Jonas Sicking <jo...@sicking.cc> wrote:
>> Here's what I was thinking as a simple WiFi API:
>>
>> interface WiFiManager {
>
> What is the intended API name of this object? navigator.wiFiManager?
> For SMS, Telephony, we just do navigator.sms, navigator.telephony,
> "manager" bit, so I would suggest we stick with that convention and do
> navigator.wifi or something similar. Weird camel casing (even though
> perhaps technically correct) is asking for lots of frustrating typos.

Good point. The camelCasing is horrible. Calling it navigator.wifi works for me.

> Another data point: WebMobileConnection, I initially saw it as an
> excention to navigator.connection, but perhaps it should be more than
> that. Then again, we could create a new "connection" family and do
> navigator.wifiConnection.

That would also work for me. I think I'd like to keep it separate from
.connection since .connection will be exposed to normal pages and used
for very different use cases.

>>  DOMRequest connectTemp(any parameters); // request fires success if
>> successfully able to connect, error otherwise
>
> What's with the "Temp"? Does it stand for temporary? If so, why?

I really hate how you on iPhone always end up remembering any network
that you connect to. If I'm out of town at an airport or internet
caffee, I don't want the phone to permanently remember a network. I
just want it to connect to it right now, and once it looses connection
not automatically reconnect. OSX has this ability and it's what I use
by default.

This function lets you implement that feature. Though of course it's
entirely up to the UI what any default behaviors will be.

> I like the idea of passing an object for parameters. I think we should
> definitely spec it out, probably containing lots of optional
> attributes.

Yup.

> Another question: where do we expect wifi keys to be stored? In Gecko?
> In the UI (e.g. Gaia), perhaps via settings API

I was thinking settings.

>>  any connected; // JSON object (frozen) which contains info on the
>> connected network
>
> In WebMobileConnection this is a bool, with "operator", etc. providing
> the information about the current connection. Should we adopt a more
> nested approach for WebMobileConnection, too? Or live with the
> inconsistency?

I'm fine either way. Feels like wifi has more information so it makes
more sense to use a JSON object there. Though maybe that's not
actually true and I just don't know GSM well enough :)

>>  Function onconnect; // Fires event when we connect to a new wifi network
>>  Function ondisconnect; // Fires event when we connect to a new wifi network
>
> In WebMobileConnection you suggested "onconnectionchange", and then
> consumers would have to look at the individual state flags. I would
> certainly advocate for this as well. In particular, I imagine more
> states than just "connect" and "disconnect". At least "connecting"
> would be good for UI feedback.

Yeah, that's a good point.

> Lastly, I think Wifi also allows you to get the signal strength of
> networks you're not connected to currently. So the question is whether
> maybe signal strength shouldn't be exposed on WiFiManager but on the
> "connected" object, or whatever. This would mean making that object
> more complicated than just being frozen JSON, though.

The idea is that the getNetworks function asynchronously returns an
array of JSON objects. One of the properties in those objects is the
signal strength.

/ Jonas

Mounir Lamouri

unread,
Mar 8, 2012, 12:47:37 PM3/8/12
to dev-w...@lists.mozilla.org
On 02/21/2012 11:54 AM, Jonas Sicking wrote:
> DOMRequest connectTemp(any parameters); // request fires success if
> successfully able to connect, error otherwise

I would prefer to have a boolean parameter to a connect() method that
would say if the wifi should be saved.

> any connected; // JSON object (frozen) which contains info on the
> connected network
>
> int signalStrength; // Not sure what the range is here

Seems like I could get that information from .connected, couldn't I?

> The JSON objects returned from getNetworks and .connected have the
> following structure:
>
> {
> name: "foo",

Why not 'ssid'? Seems like the appropriate term.

> mac: "12-ab-...",
> signal: 5, // doesn't appear in .connected
> crypt: "wpa2"
> }

Generally speaking, I wonder why we are returning JSON objects instead
of real DOM objects like a WifiNetwork object. That would allow us to
define 'signalStrengthChange' event on the object and that seems more
robust in general.

Cheers,
--
Mounir

Jonas Sicking

unread,
Mar 12, 2012, 3:18:46 AM3/12/12
to Mounir Lamouri, dev-w...@lists.mozilla.org
On Thu, Mar 8, 2012 at 9:47 AM, Mounir Lamouri <mou...@lamouri.fr> wrote:
> On 02/21/2012 11:54 AM, Jonas Sicking wrote:
>>  DOMRequest connectTemp(any parameters); // request fires success if
>> successfully able to connect, error otherwise
>
> I would prefer to have a boolean parameter to a connect() method that
> would say if the wifi should be saved.

We don't have a 'connect' method for permanent WiFi networks. Instead
you configure (using the Settings API) which network you want the
phone to automatically connect to, and then the phone will take care
of the rest.

>>  any connected; // JSON object (frozen) which contains info on the
>> connected network
>>
>>  int signalStrength; // Not sure what the range is here
>
> Seems like I could get that information from .connected, couldn't I?

I think I'd prefer to have the signal strength separate. That way we
can keep the .connected property as a frozen JSON object that only
changes when we actually connect to a new network.

>> The JSON objects returned from getNetworks and .connected have the
>> following structure:
>>
>> {
>>   name: "foo",
>
> Why not 'ssid'? Seems like the appropriate term.

That'd be fine with me.

>>   mac: "12-ab-...",
>>   signal: 5, // doesn't appear in .connected
>>   crypt: "wpa2"
>> }
>
> Generally speaking, I wonder why we are returning JSON objects instead
> of real DOM objects like a WifiNetwork object. That would allow us to
> define 'signalStrengthChange' event on the object and that seems more
> robust in general.

It just seems to create more API. Firing events on fewer objects seems
like a win to me. Otherwise the page has to listen to an event which
is fired every time that the connected network changes, and in that
even handler register a new event handler on the new .connected
object. That seems more complex for pages.

/ Jonas
0 new messages