twisted.positioning.nmea.NMEAAdapter

class documentation

class NMEAAdapter: (source)

Constructor: NMEAAdapter(receiver)

Implements interfaces: twisted.positioning.ipositioning.INMEAReceiver

An adapter from NMEAProtocol receivers to positioning receivers.

Method	`__init__`	Initializes a new NMEA adapter.
Method	`clear`	Resets this adapter.
Method	`sentenceReceived`	Called when a sentence is received.
Instance Variable	`currentSentence`	Undocumented
Instance Variable	`yearThreshold`	The earliest possible year that data will be interpreted as. For example, if this value is `1990`, an NMEA 0183 two-digit year of "96" will be interpreted as 1996, and a two-digit year of "13" will be interpreted as 2013.
Method	`_cleanCurrentSentence`	Cleans the current sentence.
Method	`_combineDateAndTime`	Combines a `datetime.date` object and a `datetime.time` object, collected from one or more NMEA sentences, into a single `datetime.datetime` object suitable for sending to the `IPositioningReceiver`.
Method	`_convert`	A simple conversion fix.
Method	`_fireSentenceCallbacks`	Fires sentence callbacks for the current sentence.
Method	`_fixCoordinateFloat`	Turns the NMEAProtocol coordinate format into Python float.
Method	`_fixDatestamp`	Turns an NMEA datestamp format into a `datetime.date` object.
Method	`_fixGSA`	Extracts the information regarding which satellites were used in obtaining the GPS fix from a GSA sentence.
Method	`_fixGSV`	Parses partial visible satellite information from a GSV sentence.
Method	`_fixHemisphereSign`	Fixes the sign for a hemisphere.
Method	`_fixTimestamp`	Turns the NMEAProtocol timestamp notation into a datetime.time object. The time in this object is expressed as Zulu time.
Method	`_fixUnits`	Fixes the units of a certain value. If the units are already acceptable (metric), does nothing.
Method	`_getHemisphereSign`	Returns the hemisphere sign for a given coordinate type.
Method	`_mergeBeaconInformation`	Merges beacon information in the adapter state (if it exists) into the provided beacon information. Specifically, this merges used and seen beacons.
Method	`_sentenceSpecificFix`	Executes a fix for a specific type of sentence.
Method	`_statefulUpdate`	Does a stateful update of a particular positioning attribute. Specifically, this will mutate an object in the current sentence data.
Method	`_updateBeaconInformation`	Updates existing beacon information state with new data.
Method	`_updateState`	Updates the current state with the new information from the sentence.
Method	`_updateUsedBeacons`	Searches the adapter state and sentence data for information about which beacons where used, then adds it to the provided beacon information object.
Method	`_validateCurrentSentence`	Tests if a sentence contains a valid fix.
Constant	`_ACCEPTABLE_UNITS`	A set of NMEA notations of units that are already acceptable (metric), and therefore don't need to be converted.
Constant	`_FIXERS`	Set of unary callables that take an NMEAAdapter instance and extract useful data from the sentence data, usually modifying the adapter's sentence data in-place.
Constant	`_SPECIFIC_SENTENCE_FIXES`	A mapping of sentece types to specific fixes that are required to extract useful information from data from those sentences.
Constant	`_STATEFUL_UPDATE`	Information on how to update partial information in the sentence data or internal adapter state. For more information, see `_statefulUpdate`'s docstring.
Constant	`_UNIT_CONVERTERS`	Mapping of NMEA notations of units that are not acceptable (not metric) to converters that take a quantity in that unit and produce a metric quantity.
Instance Variable	`_receiver`	The positioning receiver that will receive parsed data.
Instance Variable	`_sentenceData`	The data present in the sentence currently being processed. Starts empty, is filled as the sentence is parsed.
Instance Variable	`_state`	The current internal state of the receiver.

def __init__(self, receiver): (source) ¶

Initializes a new NMEA adapter.

Parameters
receiver:`ipositioning.IPositioningReceiver`	The receiver for positioning sentences.

def clear(self): (source) ¶

Resets this adapter.

This will empty the adapter state and the current sentence data.

def sentenceReceived(self, sentence): (source) ¶

from twisted.positioning.ipositioning.INMEAReceiver

Called when a sentence is received.

Will clean the received NMEAProtocol sentence up, and then update the adapter's state, followed by firing the callbacks.

If the received sentence was invalid, the state will be cleared.

Parameters
sentence:`NMEASentence`	The sentence that is received.

currentSentence = (source) ¶

Undocumented

yearThreshold: int = (source) ¶

The earliest possible year that data will be interpreted as. For example, if this value is 1990, an NMEA 0183 two-digit year of "96" will be interpreted as 1996, and a two-digit year of "13" will be interpreted as 2013.

def _cleanCurrentSentence(self): (source) ¶

Cleans the current sentence.

def _combineDateAndTime(self): (source) ¶

Combines a datetime.date object and a datetime.time object, collected from one or more NMEA sentences, into a single datetime.datetime object suitable for sending to the IPositioningReceiver.

def _convert(self, key, converter): (source) ¶

A simple conversion fix.

Parameters
key:native string (Python identifier)	The attribute name of the value to fix.
converter:unary callable	The function that converts the value.

def _fireSentenceCallbacks(self): (source) ¶

Fires sentence callbacks for the current sentence.

A callback will only fire if all of the keys it requires are present in the current state and at least one such field was altered in the current sentence.

The callbacks will only be fired with data from _state.

def _fixCoordinateFloat(self, coordinateType): (source) ¶

Turns the NMEAProtocol coordinate format into Python float.

Parameters
coordinateType:One of `Angles.LATITUDE` or `Angles.LONGITUDE`.	The coordinate type.

def _fixDatestamp(self): (source) ¶

Turns an NMEA datestamp format into a datetime.date object.

Raises
`ValueError`	When the day or month value was invalid, e.g. 32nd day, or 13th month, or 0th day or month.

def _fixGSA(self): (source) ¶

Extracts the information regarding which satellites were used in obtaining the GPS fix from a GSA sentence.

Precondition: A GSA sentence was fired. Postcondition: The current sentence data (self._sentenceData will contain a set of the currently used PRNs (under the key _usedPRNs.

def _fixGSV(self): (source) ¶

Parses partial visible satellite information from a GSV sentence.

def _fixHemisphereSign(self, coordinateType, sentenceDataKey=None): (source) ¶

Fixes the sign for a hemisphere.

This method must be called after the magnitude for the thing it determines the sign of has been set. This is done by the following functions:

self.FIXERS['magneticVariation']
self.FIXERS['latitudeFloat']
self.FIXERS['longitudeFloat']

Parameters
coordinateType	Coordinate type. One of `Angles.LATITUDE`, `Angles.LONGITUDE` or `Angles.VARIATION`.
sentenceDataKey:`str` (unless `None`)	The key name of the hemisphere sign being fixed in the sentence data. If unspecified, `coordinateType` is used.

def _fixTimestamp(self): (source) ¶

Turns the NMEAProtocol timestamp notation into a datetime.time object. The time in this object is expressed as Zulu time.

def _fixUnits(self, unitKey=None, valueKey=None, sourceKey=None, unit=None): (source) ¶

Fixes the units of a certain value. If the units are already acceptable (metric), does nothing.

None of the keys are allowed to be the empty string.

Parameters
unitKey:`str`	The name of the key/attribute under which the unit can be found in the current sentence. If the `unit` parameter is set, this parameter is not used.
valueKey:`str`	The key name in which the data will be stored in the `_sentenceData` instance attribute. If unset, attempts to remove "Units" from the end of the `unitKey` parameter. If that fails, raises `ValueError`.
sourceKey:`str`	The name of the key/attribute that contains the current value to be converted (expressed in units as defined according to the `unit` parameter). If unset, will use the same key as the value key.
unit:`str`	The unit that is being converted from. If unspecified or `None`, asks the current sentence for the `unitKey`. If that also fails, raises `AttributeError`.

def _getHemisphereSign(self, coordinateType): (source) ¶

Returns the hemisphere sign for a given coordinate type.

Parameters
coordinateType:`Angles.LATITUDE`, `Angles.LONGITUDE` or `Angles.VARIATION`.	The coordinate type to find the hemisphere for.
Returns
`int`	The sign of that hemisphere (-1 or 1).

def _mergeBeaconInformation(self, newBeaconInformation): (source) ¶

Merges beacon information in the adapter state (if it exists) into the provided beacon information. Specifically, this merges used and seen beacons.

If the adapter state has no beacon information, does nothing.

Parameters
newBeaconInformation:`twisted.positioning.base.BeaconInformation`	The beacon information object that beacon information will be merged into (if necessary).

def _sentenceSpecificFix(self): (source) ¶

Executes a fix for a specific type of sentence.

def _statefulUpdate(self, sentenceKey): (source) ¶

Does a stateful update of a particular positioning attribute. Specifically, this will mutate an object in the current sentence data.

Using the sentenceKey, this will get a tuple containing, in order, the key name in the current state and sentence data, a factory for new values, the attribute to update, and a converter from sentence data (in NMEA notation) to something useful.

If the sentence data doesn't have this data yet, it is grabbed from the state. If that doesn't have anything useful yet either, the factory is called to produce a new, empty object. Either way, the object ends up in the sentence data.

Parameters
sentenceKey:`str`	The name of the key in the sentence attributes, `NMEAAdapter._STATEFUL_UPDATE` dictionary and the adapter state.

def _updateBeaconInformation(self): (source) ¶

Updates existing beacon information state with new data.

def _updateState(self): (source) ¶

Updates the current state with the new information from the sentence.

def _updateUsedBeacons(self, beaconInformation): (source) ¶

Searches the adapter state and sentence data for information about which beacons where used, then adds it to the provided beacon information object.

If no new beacon usage information is available, does nothing.

Parameters
beaconInformation:`twisted.positioning.base.BeaconInformation`	The beacon information object that beacon usage information will be added to (if necessary).

def _validateCurrentSentence(self): (source) ¶

Tests if a sentence contains a valid fix.

_ACCEPTABLE_UNITS: frozenset of bytestrings = (source) ¶

A set of NMEA notations of units that are already acceptable (metric), and therefore don't need to be converted.

Value

frozenset(['M'])

_FIXERS: dict of native strings to unary callables = (source) ¶

Set of unary callables that take an NMEAAdapter instance and extract useful data from the sentence data, usually modifying the adapter's sentence data in-place.

Value

{'type': (lambda self: self._sentenceSpecificFix()),
 'timestamp': (lambda self: self._fixTimestamp()),
 'datestamp': (lambda self: self._fixDatestamp()),
 'latitudeFloat': (lambda self: self._fixCoordinateFloat(Angles.LATITUDE)),
 'latitudeHemisphere': (lambda self: self._fixHemisphereSign(Angles.LATITUDE, 'l↵
atitude')),
 'longitudeFloat': (lambda self: self._fixCoordinateFloat(Angles.LONGITUDE)),
...

_SPECIFIC_SENTENCE_FIXES: dict of sentence types to callables that take self and modify it in-place = (source) ¶

A mapping of sentece types to specific fixes that are required to extract useful information from data from those sentences.

Value

{'GPGSV': _fixGSV, 'GPGSA': _fixGSA}

_STATEFUL_UPDATE: See _statefulUpdate's docstring = (source) ¶

Information on how to update partial information in the sentence data or internal adapter state. For more information, see _statefulUpdate's docstring.

Value

{'trueHeading': ('heading', base.Heading, '_angle', float),
 'magneticVariation': ('heading',
                       base.Heading,
                       'variation',
                       (lambda angle: base.Angle(float(angle), Angles.VARIATION)↵
)),
 'horizontalDilutionOfPrecision': ('positionError', base.PositionError, 'hdop', float↵
...

_UNIT_CONVERTERS: dict of bytestrings to unary callables = (source) ¶

Mapping of NMEA notations of units that are not acceptable (not metric) to converters that take a quantity in that unit and produce a metric quantity.

Value

{'N': (lambda inKnots: base.Speed(float(inKnots) * base.MPS_PER_KNOT)),
 'K': (lambda inKPH: base.Speed(float(inKPH) * base.MPS_PER_KPH))}

_receiver: ipositioning.IPositioningReceiver = (source) ¶

The positioning receiver that will receive parsed data.

_sentenceData: dict = (source) ¶

The data present in the sentence currently being processed. Starts empty, is filled as the sentence is parsed.

_state: dict = (source) ¶

The current internal state of the receiver.