RFC: API for Neighbouring Cell Info

RFC: API for Neighbouring Cell Info

[Bastian, Waldo]

[-- Attachment #1: Type: text/plain, Size: 3111 bytes --]

Hi all,

I would like to propose an API for exposing neighbouring cell info. 
Since the exact information provided is rather modem specific my thinking is to use the following API as the generic framework and then the actual per-cell information attributes that a driver provides can be different from modem to modem with the constraint that _if_ a modem provides a certain attribute that is specified by this API definition the driver must format it as specified.

Your feedback is highly appreciated, especially from those who plan to use this information for location purposes.

Once there is agreement on the API we can discuss whether it makes sense to add some skeleton support in the oFono core or leave it to each individual modem plugin to implement the DBUS service in its entire.

Cheers,
Waldo


Neighbouring Cell Info hierarchy
=================================

Service		org.ofono
Interface	org.ofono.NeighbouringCellInfo
Object path	[variable prefix]/{modem0,modem1,...}

Methods	dict GetProperties()

			Returns all neighbouring cell info properties. See the
			properties section for available properties.

			Possible Errors: [service].Error.InvalidArguments

		void SetProperty(string name, variant value)

			Changes the value of the specified property. Only
			properties that are listed as read-write are
			changeable. On success a PropertyChanged signal
			will be emitted.

			Possible Errors: [service].Error.InvalidArguments
					 [service].Error.DoesNotExist

Signals	PropertyChanged(string property, variant value)

			This signal indicates a changed value of the given
			property.

Properties	boolean Enabled [readwrite]

			Boolean representing whether the interface provides
			neighbouring cell information.

		array{dict} Info [readonly, only when Enabled]

			List of neighbouring cells with the following information for each cell:

			string Type [readonly]

				Describes the type of Cell.

				The possible values are: "GSM serving cell",
						"GSM neighbour cell",
						"UMTS serving cell",
						"UMTS neighbour cell",
						"UMTS detected cell"

			string MobileCountryCode [readonly]

				Contains the Mobile Country Code (MCC).
	
			string MobileNetworkCode [readonly]

				Contains the Mobile Network Code (MNC)

			uint16 LocationAreaCode [readonly]

				Contains the location area code of the cell.

			uint32 CellId [readonly]

				Contains the network cell id.

			byte RxLevel [readonly, GSM only]
		
				Received signal strength as defined by [3GPP TS 45.008 s8.1.4] [0-63]			

			uint32 TimingAdvance [readonly, GSM serving cell only]

				Timing advance for serving GSM cell [0-???]

			uint16 ScramblingCode [readonly, UMTS only]

				Scrambling code [0-511]

			uint16 DownlinkFreq [readonly, UMTS only]

				Downlink frequency [0-16383]

			int8 RSCP [readonly, UMTS only]

				Received Signal Code Power [3GPP TS 25.133 s9.1.1.3] in dBm [-120...-25]

			int8 ECNO [readonly, UMTS only]

				CPICH Ec/No [3GPP TS 25.133 s9.1.2.3] in dB  [-24...0]
			

Re: RFC: API for Neighbouring Cell Info

[Aki Niemi]

[-- Attachment #1: Type: text/plain, Size: 3320 bytes --]

to, 2010-01-28 kello 19:03 +0100, ext Bastian, Waldo kirjoitti:
> I would like to propose an API for exposing neighbouring cell info. 
> Since the exact information provided is rather modem specific my
> thinking is to use the following API as the generic framework and then
> the actual per-cell information attributes that a driver provides can
> be different from modem to modem with the constraint that _if_ a modem
> provides a certain attribute that is specified by this API definition
> the driver must format it as specified.

There are two parts to neighbor cell information. The first part
provides meta-information on the second part, which is the actual
measurement data.

Like you propose, the first part is a dict, with keys like cell type and
current MCC and MNC.

The second part is the measurement data, and that is different for
different types of cells. Not all information is mandatory for all
modems and all cell types.

For the measurement data, there is a standard available. OMA SUPL, User
Plane Location Protocol describes the sets of measurements available for
different types of cells:

http://www.openmobilealliance.org/Technical/release_program/supl_v2_0.aspx

> Your feedback is highly appreciated, especially from those who plan to
> use this information for location purposes.

I think the pattern you use here is wrong. This needs to be a method
call; a signal won't work. The measurement data is constantly changing,
and you don't want a constant stream of PropertyChanged() signals.

So I think something like this instead:

GetNeighborCells() -> a{sv}, aa{sv}

That is: a dict for the meta-data, and an array of dicts for cell
measurements. That response signature looks a bit intimidating, but I've
implemented it, it's not a big deal.

The important property here is that the location system has a single
method call that retrieves all relevant information from the modem, so
that they can then do their triangulation magic.

> Once there is agreement on the API we can discuss whether it makes
> sense to add some skeleton support in the oFono core or leave it to
> each individual modem plugin to implement the DBUS service in its
> entire.

I think it's reasonable to assume that most modems support this. There
is a standard to follow, and at least isimodem will have a driver for
it. So I would make it a proper atom from the beginning.

The modem plugin API should distinguish between different types of
cells; there should be ops to retrieve cell type specific measurements.

Other comments on the interface:

> Properties boolean Enabled [readwrite] 
> 
> 			Boolean representing whether the interface provides
> 			neighbouring cell information.
> 

This is useless. If a modem driver doesn't support neighbor cell info,
it won't registered a driver and the interface just doesn't show up.

> 			int8 RSCP [readonly, UMTS only]
> 
> 				Received Signal Code Power [3GPP TS 25.133 s9.1.1.3] in dBm [-120...-25]
> 
> 			int8 ECNO [readonly, UMTS only]
> 
> 				CPICH Ec/No [3GPP TS 25.133 s9.1.2.3] in dB  [-24...0]

This is already part of the measurement data, which I think should be in
the per-cell information (the serving cell measurement data is still
measurement data).

Cheers,
Aki

Re: RFC: API for Neighbouring Cell Info

[Denis Kenzior]

[-- Attachment #1: Type: text/plain, Size: 2005 bytes --]

Hi Aki,

> > Your feedback is highly appreciated, especially from those who plan to
> > use this information for location purposes.
> 
> I think the pattern you use here is wrong. This needs to be a method
> call; a signal won't work. The measurement data is constantly changing,
> and you don't want a constant stream of PropertyChanged() signals.
> 
> So I think something like this instead:
> 
> GetNeighborCells() -> a{sv}, aa{sv}

How is this information obtained from the modem? Is the modem polled? Does it 
signal this data as it changes?  Honestly I don't like either approach, the 
Agent pattern would be a much better fit here.  This would allow us to specify 
the polling/update interval and stop neighbor cell updates when no one is 
interested in them.

> > Once there is agreement on the API we can discuss whether it makes
> > sense to add some skeleton support in the oFono core or leave it to
> > each individual modem plugin to implement the DBUS service in its
> > entire.
> 
> I think it's reasonable to assume that most modems support this. There
> is a standard to follow, and at least isimodem will have a driver for
> it. So I would make it a proper atom from the beginning.

I'd like to see the low level driver API proposal first.  The Nokia isimodem 
interface is actually quite sane, AT command modems are usually not so...  If 
we make this into a proper atom we have to make this work for all hardware 
from the beginning.

> Other comments on the interface:
> > Properties boolean Enabled [readwrite]
> >
> > 			Boolean representing whether the interface provides
> > 			neighbouring cell information.
> 
> This is useless. If a modem driver doesn't support neighbor cell info,
> it won't registered a driver and the interface just doesn't show up.

Being able to turn this capability off is useful.  If there are no consumers, 
then these types of notifications should be turned off to save power / wakeups.

Regards,
-Denis

Re: RFC: API for Neighbouring Cell Info

[Aki Niemi]

[-- Attachment #1: Type: text/plain, Size: 2158 bytes --]

pe, 2010-01-29 kello 16:56 +0100, ext Denis Kenzior kirjoitti:
> > > Your feedback is highly appreciated, especially from those who plan to
> > > use this information for location purposes.
> > 
> > I think the pattern you use here is wrong. This needs to be a method
> > call; a signal won't work. The measurement data is constantly changing,
> > and you don't want a constant stream of PropertyChanged() signals.
> > 
> > So I think something like this instead:
> > 
> > GetNeighborCells() -> a{sv}, aa{sv}
> 
> How is this information obtained from the modem? Is the modem polled? Does it 
> signal this data as it changes?

It is polled, by design.

> Honestly I don't like either approach, the Agent pattern would be a
> much better fit here.  This would allow us to specify 
> the polling/update interval and stop neighbor cell updates when no one
> is interested in them.

In my experience, the positioning guys don't need periodic updates at
all. The data needs to be fetched on demand. Like whenever the user
starts up a location-aware application.

> > > Once there is agreement on the API we can discuss whether it makes
> > > sense to add some skeleton support in the oFono core or leave it to
> > > each individual modem plugin to implement the DBUS service in its
> > > entire.
> > 
> > I think it's reasonable to assume that most modems support this. There
> > is a standard to follow, and at least isimodem will have a driver for
> > it. So I would make it a proper atom from the beginning.
> 
> I'd like to see the low level driver API proposal first.  The Nokia isimodem 
> interface is actually quite sane, AT command modems are usually not so...  If 
> we make this into a proper atom we have to make this work for all hardware 
> from the beginning.

Right, we perhaps need a datapoint from an AT modem to know for sure,
but the fact that OMA SUPL standardizes this, and the ISI interface is
close to that standard already, makes me think the AT modems can't be
that far off.

I could take a stab at a driver API for this as soon as I clear up some
space on my todo list.

Cheers,
Aki

Re: RFC: API for Neighbouring Cell Info

[Denis Kenzior]

[-- Attachment #1: Type: text/plain, Size: 1854 bytes --]

Hi Aki,

> > Honestly I don't like either approach, the Agent pattern would be a
> > much better fit here.  This would allow us to specify
> > the polling/update interval and stop neighbor cell updates when no one
> > is interested in them.
> 
> In my experience, the positioning guys don't need periodic updates at
> all. The data needs to be fetched on demand. Like whenever the user
> starts up a location-aware application.

Fair enough, but we also have to consider the case of multiple applications 
being interested in this information.  We can't assume that it will be polled 
on demand by just one...

> 
> > > > Once there is agreement on the API we can discuss whether it makes
> > > > sense to add some skeleton support in the oFono core or leave it to
> > > > each individual modem plugin to implement the DBUS service in its
> > > > entire.
> > >
> > > I think it's reasonable to assume that most modems support this. There
> > > is a standard to follow, and at least isimodem will have a driver for
> > > it. So I would make it a proper atom from the beginning.
> >
> > I'd like to see the low level driver API proposal first.  The Nokia
> > isimodem interface is actually quite sane, AT command modems are usually
> > not so...  If we make this into a proper atom we have to make this work
> > for all hardware from the beginning.
> 
> Right, we perhaps need a datapoint from an AT modem to know for sure,
> but the fact that OMA SUPL standardizes this, and the ISI interface is
> close to that standard already, makes me think the AT modems can't be
> that far off.

I have a few modems that support this capability, so we can definitely check.

> 
> I could take a stab at a driver API for this as soon as I clear up some
> space on my todo list.

Yes, that would be great.

Regards,
-Denis

RE: RFC: API for Neighbouring Cell Info

[Bastian, Waldo]

[-- Attachment #1: Type: text/plain, Size: 1145 bytes --]

> Hi Aki,
> 
> > > Honestly I don't like either approach, the Agent pattern would be a
> > > much better fit here.  This would allow us to specify
> > > the polling/update interval and stop neighbor cell updates when no one
> > > is interested in them.
> >
> > In my experience, the positioning guys don't need periodic updates at
> > all. The data needs to be fetched on demand. Like whenever the user
> > starts up a location-aware application.
> 
> Fair enough, but we also have to consider the case of multiple
> applications
> being interested in this information.  We can't assume that it will be
> polled on demand by just one...

Ny understanding is that typically there would be a location service that queries this information from oFono and converts it into actual coordinates through voodoo and black magic and that location-aware applications will ask this location service for coordinates. E.g. you would have something like GeoClue providing a single API for providing coordinates to applications and under GeoClue there is the location service, and the location service in turn talks to oFono.

Cheers,
Waldo

Re: RFC: API for Neighbouring Cell Info

[Denis Kenzior]

[-- Attachment #1: Type: text/plain, Size: 1753 bytes --]

Hi Waldo,

> > Hi Aki,
> >
> > > > Honestly I don't like either approach, the Agent pattern would be a
> > > > much better fit here.  This would allow us to specify
> > > > the polling/update interval and stop neighbor cell updates when no
> > > > one is interested in them.
> > >
> > > In my experience, the positioning guys don't need periodic updates at
> > > all. The data needs to be fetched on demand. Like whenever the user
> > > starts up a location-aware application.
> >
> > Fair enough, but we also have to consider the case of multiple
> > applications
> > being interested in this information.  We can't assume that it will be
> > polled on demand by just one...
> 
> Ny understanding is that typically there would be a location service that
>  queries this information from oFono and converts it into actual
>  coordinates through voodoo and black magic and that location-aware
>  applications will ask this location service for coordinates. E.g. you
>  would have something like GeoClue providing a single API for providing
>  coordinates to applications and under GeoClue there is the location
>  service, and the location service in turn talks to oFono.
> 

You're absolutely correct.  My point is that if only one entity is ever going 
to be interested in this information (e.g. GeoClue) then a full blown atom / 
DBus API is not even necessary.  We can do this similarly to the history atom 
and leave it up to the system integrator to decide how and what service to 
use.

DBus API implies that multiple user applications are interested in the 
information provided.  If this is the case, then in my view a procedural, 
application-driven polling API is not the best approach.

Regards,
-Denis

Re: RFC: API for Neighbouring Cell Info

[Jussi Kukkonen]

[-- Attachment #1: Type: text/plain, Size: 1181 bytes --]

Hi,

First, as a general comment: if this sort of info was available, I'd 
definitely use it (see http://github.com/jku/geoclue/commits/new-stuff 
for a first version using currently available API). Neighbor cell info 
would make non-complete cell location databases so much more useful...

Aki Niemi wrote:
> pe, 2010-01-29 kello 16:56 +0100, ext Denis Kenzior kirjoitti:
>> Honestly I don't like either approach, the Agent pattern would be a
>> much better fit here.  This would allow us to specify 
>> the polling/update interval and stop neighbor cell updates when no one
>> is interested in them.
> 
> In my experience, the positioning guys don't need periodic updates at
> all. The data needs to be fetched on demand. Like whenever the user
> starts up a location-aware application.

I'm willing to bet this is a chicken-egg problem: Why design software 
that uses periodic location updates if they aren't available?

Only exposing plain polling is fine if it makes sense in a powersaving 
(and api simplicity) sense: a version of periodic updating can always be 
implemented at the position service (geoclue) level if it seems useful.

  - Jussi

Re: RFC: API for Neighbouring Cell Info

[Marcel Holtmann]

[-- Attachment #1: Type: text/plain, Size: 1800 bytes --]

Hi Jussi,

> >> Honestly I don't like either approach, the Agent pattern would be a
> >> much better fit here.  This would allow us to specify 
> >> the polling/update interval and stop neighbor cell updates when no one
> >> is interested in them.
> > 
> > In my experience, the positioning guys don't need periodic updates at
> > all. The data needs to be fetched on demand. Like whenever the user
> > starts up a location-aware application.
> 
> I'm willing to bet this is a chicken-egg problem: Why design software 
> that uses periodic location updates if they aren't available?
> 
> Only exposing plain polling is fine if it makes sense in a powersaving 
> (and api simplicity) sense: a version of periodic updating can always be 
> implemented at the position service (geoclue) level if it seems useful.

there is no problem in polling the hardware if we have to. However if
that is the case, then we obviously should only poll when we have a
user/client asking for the information. And we should poll in an
interval that the user/client needs this information.

As Denis mentioned, if we have a D-Bus API for retrieving these
information then we need to able to handle multiple users in a smart way
without wasting system resources or blocking each other.

I consider this similar to usage statistics. And in ConnMan I went for
an agent concept to solve this. The similar approach seems to fit here
perfectly if we wanna expose these information over D-Bus. That is the
only way, we have control over clients. If nothing has changed there is
not point in waking up more processes and let the determine noting has
changed to only go back to sleep afterwards. If these clients actually
have UI components that redraw, it is even worse.

Regards

Marcel

RE: RFC: API for Neighbouring Cell Info

[Bastian, Waldo]

[-- Attachment #1: Type: text/plain, Size: 1646 bytes --]

> There are two parts to neighbor cell information. The first part
> provides meta-information on the second part, which is the actual
> measurement data.
> 
> Like you propose, the first part is a dict, with keys like cell type and
> current MCC and MNC.
> 
> The second part is the measurement data, and that is different for
> different types of cells. Not all information is mandatory for all
> modems and all cell types.

The formatting might have been a bit confusing, but I was actually proposing  a single property ("Info") containing an array (one entry for each cell) of dicts, with the dicts having measurement and other info on that particular cell.

> I think the pattern you use here is wrong. This needs to be a method
> call; a signal won't work. The measurement data is constantly changing,
> and you don't want a constant stream of PropertyChanged() signals.

Ok.

> The important property here is that the location system has a single
> method call that retrieves all relevant information from the modem, so
> that they can then do their triangulation magic.

Yes, it's important to keep things atomic.

> > 			int8 RSCP [readonly, UMTS only]
> >
> > 				Received Signal Code Power [3GPP TS 25.133
> s9.1.1.3] in dBm [-120...-25]
> >
> > 			int8 ECNO [readonly, UMTS only]
> >
> > 				CPICH Ec/No [3GPP TS 25.133 s9.1.2.3] in dB  [-
> 24...0]
> 
> This is already part of the measurement data, which I think should be in
> the per-cell information (the serving cell measurement data is still
> measurement data).

Yes, all this is per-cell, sorry if that wasn't clear.

Cheers,
Waldo