id	summary	reporter	owner	description	type	status	priority	milestone	component	resolution	keywords	cc	branch	branch_author	launchpad_bug
3926	twisted.positioning -- a better positioning framework	lvh		"As some of you have undoubtedly noticed, Twisted's current GPS support (`twisted.protocols.gps`) has issues:

    1. The public API sucks:
        1. __Fourteen__ arguments? All of them __positional__? Really?
        2. ``fooReceived`` methods are organized by what happens to be easy for NMEA sentences, not what makes sense
        2. It's hard to extend, raw objects are passed instead of pretty wrappers that abstract technology details away
        3. It's very protocol centric: the API changes between NMEA and Zodiac, a good API would look the same for any positioning technology
    2. There are no unit tests.
    3. It assumes we're using satellite navigation (well, not really, but only because there's no interface that says what it does)

This ticket is about a proposed alternative, `twisted.positioning`, which hopefully will:

    1. deprecate the existing code
    2. support more than satellite-based navigation (such as cell triangulation) or maybe just more than GPS ([http://en.wikipedia.org/wiki/Galileo_(satellite_navigation) Galileo] comes to mind)

After reviewing preliminary code and discussing the issue, we came to the following conclusions:

We need to have an interface (tentative name: IPositioningDataReceiver) that implements a number of methods, such as:

    1. `positionRecieved(self, position)`
    2. `altitudeReceived(self, altitude)`
    3. `headingReceived(self, heading)`
    4. ...

The parameters of these methods should not be simple objects (like floats or strs or bools), but Position, Heading... objects so that more API can be added later as required.

The classes that implement this should not continuously update their own state. Doing that is the job of the application that uses the framework.

Originally we thought it would be cool if accuracy data came together with positioning data, however this idea was dropped because it was unrealistic with real world positioning devices.

We should try to keep this API as general as possible (making as few assumptions about the underlying protocol as possible).

First thing to do should probably be finalizing the `IPositioningReceiver` interface. Getting it right is extremely important and has big implementation consequences: NMEA might present data in an illogical or useless order, but this shouldn't change our interface significantly.

This raises problems with the `fooReceived` methods, since data that is made available in chunks (`headingRecieved` doing both magnetic and true headings for example) might not have that data made available in the underlying implementation (some NMEA sentences only provide true heading, some proprietary ones only provide magnetic heading, and some sentences provide both -- it doesn't make sense to ignore the data from the first two types of sentence simply because they didn't have both kinds of heading).

The easy way out is to make the objects that the interface deals with as abstract as possible. With enough eyes, every problem is tiny, so your comments are much appreciated as usual.

You can find the code on Github: http://www.github.com/lvh/twisted has a `positioning-3926` branch."	enhancement	new	normal		core		protocols gps positioning review		branches/positioning-3926-2	lvh