Prior to asynchronous parsing.

Author: peterhinch

gps/README.md

@@ -14,9 +14,10 @@ on this excellent library [micropyGPS].
  based on the popular MTK3329/MTK3339 chips.
  * The above drivers are portable between [MicroPython] and Python 3.5 or above.
  * Timing drivers for [MicroPython] only extend the capabilities of the
- read-only and read-write drivers to provide precision μs class GPS timing. On
+ read-only and read-write drivers to provide accurate sub-ms GPS timing. On
  STM-based hosts (e.g. the Pyboard) the RTC may be set from GPS and calibrated
  to achieve timepiece-level accuracy.
+ * Can write `.kml` files for displaying journeys on Google Earth.
  * Drivers may be extended via subclassing, for example to support additional
  sentence types.
 
@@ -28,8 +29,8 @@ driver as they emit NMEA sentences on startup.
 
 NMEA sentence parsing is based on [micropyGPS] but with significant changes.
 
- * As asynchronous drivers they require `uasyncio` on [MicroPython] or asyncio
- under Python 3.5+.
+ * As asynchronous drivers they require `uasyncio` on [MicroPython] or
+ `asyncio` under Python 3.5+.
  * Sentence parsing is adapted for asynchronous use.
  * Rollover of local time into the date value enables worldwide use.
  * RAM allocation is cut by various techniques to lessen heap fragmentation.
@@ -359,8 +360,8 @@ The following are counts since instantiation.
  * `local_time` (property) [hrs: int, mins: int, secs: int] Local time.
  * `date` (property) [day: int, month: int, year: int] e.g. [23, 3, 18]
  * `local_offset` Local time offset in hrs as specified to constructor.
- * `epoch_time` Integer. Time since the epoch. Epoch start depends on whether
- running under MicroPython or Python 3.5+.
+ * `epoch_time` Integer. Time in seconds since the epoch. Epoch start depends
+ on whether running under MicroPython (Y2K) or Python 3.5+ (1970 on Unix).
 
 The `utc`, `date` and `local_time` properties updates on receipt of RMC
 messages. If a nonzero `local_offset` value is specified the `date` value will
@@ -532,6 +533,15 @@ cleared by power cycling the GPS.
 
 ### 3.3.1 Changing baudrate
 
+I have experienced failures on a Pyboard V1.1 at baudrates higher than 19200.
+Under investigation.                                                          **TODO UPDATE THIS**
+
+Further, there are problems (at least with my GPS firmware build
+['AXN_2.31_3339_13101700', '5632', 'PA6H', '1.0']) whereby setting baudrates
+only works for certain rates. 19200, 38400 and 115200 work. 4800 sets 115200.
+Importantly 9600 does nothing. This means that the only way to restore the
+default is to perform a `FULL_COLD_START`. The test programs do this.
+
 If you change the GPS baudrate the UART should be re-initialised immediately
 after the `baudrate` coroutine terminates:
 
@@ -605,7 +615,8 @@ and `GPS_RWTimer` for read/write access.
  * `as_GPS_utils.py` Additional formatted string methods for `AS_GPS`.
  * `as_rwGPS.py` Required if using the read/write variant.
  * `as_tGPS.py` The library. Provides `GPS_Timer` and `GPS_RWTimer` classes.
- * `as_GPS_time.py` Test scripts for above.
+ * `as_GPS_time.py` Test scripts for read only driver.
+ * `as_rwGPS_time.py` Test scripts for read/write driver.
 
 ### 4.1.1 Usage example
 
@@ -687,20 +698,21 @@ Optional positional args:
 
 ## 4.3 Public methods
 
-These return an accurate GPS time of day. As such they return as fast as
-possible. To achieve this they avoid allocation and dispense with error
-checking: these functions should not be called until a valid time/date message
-and PPS signal have occurred. Await the `ready` coroutine prior to first use.
-Subsequent calls may occur without restriction; see usage example above.
+The methods that return an accurate GPS time of day run as fast as possible. To
+achieve this they avoid allocation and dispense with error checking: these
+methods should not be called until a valid time/date message and PPS signal
+have occurred. Await the `ready` coroutine prior to first use. Subsequent calls
+may occur without restriction; see usage example above.
+
+These methods use the MicroPython microsecond timer to interpolate between PPS
+pulses. They do not involve the RTC. Hence they should work on any MicroPython
+target supporting `machine.ticks_us`.
 
  * `get_ms` No args. Returns an integer: the period past midnight in ms.
  * `get_t_split` No args. Returns time of day in a list of form
  `[hrs: int, mins: int, secs: int, μs: int]`.
-
-These methods use the MicroPython microsecond timer to interpolate between PPS
-pulses. They do not involve the RTC. Hence they should work on any MicroPython
-target supporting `machine.ticks_us`. These methods are currently based on the
-default 1s update rate. If this is increased they may return incorrect values.
+ * `close` No args. Shuts down the PPS pin interrupt handler. Usage is optional
+ but in test situations avoids the ISR continuing to run after termination.
 
 See [Absolute accuracy](./README.md#45-absolute-accuracy) for a discussion of
 the accuracy of these methods.

gps/as_GPS.py

@@ -21,6 +21,8 @@
 except ImportError:
     const = lambda x : x
 
+from math import modf
+
 # Angle formats
 DD = const(1)
 DMS = const(2)
@@ -50,6 +52,8 @@
 
 
 class AS_GPS(object):
+    # Can omit time consuming checks: CRC 6ms Bad char and line length 9ms
+    FULL_CHECK = True
     _SENTENCE_LIMIT = 76  # Max sentence length (based on GGA sentence)
     _NO_FIX = 1
 
@@ -71,7 +75,7 @@ def _week_day(year, month, day, offset = [0, 31, 59, 90, 120, 151, 181, 212, 243
         day_of_week = day_of_week if day_of_week else 7
         return day_of_week
 
-    # 8-bit xor of characters between "$" and "*"
+    # 8-bit xor of characters between "$" and "*". Takes 6ms on Pyboard!
     @staticmethod
     def _crc_check(res, ascii_crc):
         try:
@@ -137,6 +141,8 @@ def __init__(self, sreader, local_offset=0, fix_cb=lambda *_ : None, cb_mask=RMC
         # precise timing use PPS signal and as_tGPS library.
         self.local_offset = local_offset  # hrs
         self.epoch_time = 0  # Integer secs since epoch (Y2K under MicroPython)
+        # Add ms if supplied by device. Only used by timing drivers.
+        self.msecs = 0
 
         # Position/Motion
         self._latitude = [0, 0.0, 'N']  # (°, mins, N/S)
@@ -151,6 +157,7 @@ def __init__(self, sreader, local_offset=0, fix_cb=lambda *_ : None, cb_mask=RMC
         self._last_sv_sentence = 0  # for GSV parsing
         self._total_sv_sentences = 0
         self._satellite_data = dict()  # for get_satellite_data()
+        self._update_ms = 1000  # Update rate for timing drivers. Default 1 sec.
 
         # GPS Info
         self.satellites_in_view = 0
@@ -182,20 +189,22 @@ async def _run(self):
     # Update takes a line of text
     def _update(self, line):
         line = line.rstrip()
-        try:
-            next(c for c in line if ord(c) < 10 or ord(c) > 126)
-            return None  # Bad character received
-        except StopIteration:
-            pass  # All good
+        if self.FULL_CHECK:  # 9ms on Pyboard
+            try:
+                next(c for c in line if ord(c) < 10 or ord(c) > 126)
+                return None  # Bad character received
+            except StopIteration:
+                pass  # All good
 
-        if len(line) > self._SENTENCE_LIMIT or not '*' in line:
-            return None  # Too long or malformed
+            if len(line) > self._SENTENCE_LIMIT or not '*' in line:
+                return None  # Too long or malformed
 
         a = line.split(',')
         segs = a[:-1] + a[-1].split('*')
-        if not self._crc_check(line, segs[-1]):
-            self.crc_fails += 1  # Update statistics
-            return None
+        if self.FULL_CHECK:  # 6ms on Pyboard
+            if not self._crc_check(line, segs[-1]):
+                self.crc_fails += 1  # Update statistics
+                return None
         self.clean_sentences += 1  # Sentence is good but unparsed.
         segs[0] = segs[0][1:]  # discard $
         segs = segs[:-1]  # and checksum
@@ -261,11 +270,28 @@ def _set_date_time(self, utc_string, date_string):
             return False
         try:
             hrs = int(utc_string[0:2])  # h
+            if hrs > 24 or hrs < 0:
+                return False
             mins = int(utc_string[2:4])  # mins
-            secs = int(utc_string[4:6])  # secs from chip is a float but FP is always 0
+            if mins > 60 or mins < 0:
+                return False
+            # Secs from MTK3339 chip is a float but others may return only 2 chars
+            # for integer secs. If a float keep epoch as integer seconds and store
+            # the fractional part as integer ms (ms since midnight fits 32 bits).
+            fss, fsecs = modf(float(utc_string[4:]))
+            secs = int(fsecs)
+            if secs > 60 or secs < 0:
+                return False
+            self.msecs = int(fss * 1000)
             d = int(date_string[0:2])  # day
+            if d > 31 or d < 1:
+                return False
             m = int(date_string[2:4])  # month
+            if m > 12 or m < 1:
+                return False
             y = int(date_string[4:6]) + 2000  # year
+            if y < 2018 or y > 2030:
+                return False
         except ValueError:  # Bad date or time strings
             return False
         wday = self._week_day(y, m, d)
@@ -284,16 +310,18 @@ def _set_date_time(self, utc_string, date_string):
 # The ._received dict entry is initially set False and is set only if the data
 # was successfully updated. Valid because parsers are synchronous methods.
 
+# Chip sends rubbish RMC messages before first PPS pulse, but these have data
+# valid False
     def _gprmc(self, gps_segments):  # Parse RMC sentence
         self._valid &= ~RMC
-        # UTC Timestamp and date.
-        if not self._set_date_time(gps_segments[1], gps_segments[9]):
-            return False
-
         # Check Receiver Data Valid Flag
         if gps_segments[2] != 'A':
             return True  # Correctly parsed
 
+        # UTC Timestamp and date.
+        if not self._set_date_time(gps_segments[1], gps_segments[9]):
+            return False
+
         # Data from Receiver is Valid/Has Fix. Longitude / Latitude
         if not self._fix(gps_segments, 3, 5):
             return False

gps/as_GPS_time.py

@@ -1,5 +1,6 @@
-# as_GPS_time.py Test scripts for as_tGPS
+# as_GPS_time.py Test scripts for as_tGPS.py read-only driver.
 # Using GPS for precision timing and for calibrating Pyboard RTC
+
 # This is STM-specific: requires pyb module.
 # Requires asyn.py from this repo.
 
@@ -37,6 +38,7 @@ async def setup():
 
 # Test terminator: task sets the passed event after the passed time.
 async def killer(end_event, minutes):
+    print('Will run for {} minutes.'.format(minutes))
     await asyncio.sleep(minutes * 60)
     end_event.set()
 
@@ -59,11 +61,14 @@ async def drift_test(terminate, gps_tim):
         await asyncio.sleep(10)
     return dt - dstart
 
-async def do_drift(terminate, minutes):
+async def do_drift(minutes):
     print('Setting up GPS.')
     gps_tim = await setup()
     print('Waiting for time data.')
     await gps_tim.ready()
+    terminate = asyn.Event()
+    loop = asyncio.get_event_loop()
+    loop.create_task(killer(terminate, minutes))
     print('Setting RTC.')
     await gps_tim.set_rtc()
     print('Measuring drift.')
@@ -73,32 +78,31 @@ async def do_drift(terminate, minutes):
     print('Rate of change {}μs/hr {}secs/year'.format(ush, spa))
 
 def drift(minutes=5):
-    terminate = asyn.Event()
     loop = asyncio.get_event_loop()
-    loop.create_task(killer(terminate, minutes))
-    loop.run_until_complete(do_drift(terminate, minutes))
+    loop.run_until_complete(do_drift(minutes))
 
 # ******** Time printing demo ********
 # Every 10s print the difference between GPS time and RTC time
-async def do_time(terminate):
+async def do_time(minutes):
     fstr = '{}ms Time: {:02d}:{:02d}:{:02d}:{:06d}'
     print('Setting up GPS.')
     gps_tim = await setup()
     print('Waiting for time data.')
     await gps_tim.ready()
     print('Setting RTC.')
     await gps_tim.set_rtc()
+    terminate = asyn.Event()
+    loop = asyncio.get_event_loop()
+    loop.create_task(killer(terminate, minutes))
     while not terminate.is_set():
         await asyncio.sleep(1)
         # In a precision app, get the time list without allocation:
         t = gps_tim.get_t_split()
         print(fstr.format(gps_tim.get_ms(), t[0], t[1], t[2], t[3]))
 
 def time(minutes=1):
-    terminate = asyn.Event()
     loop = asyncio.get_event_loop()
-    loop.create_task(killer(terminate, minutes))
-    loop.run_until_complete(do_time(terminate))
+    loop.run_until_complete(do_time(minutes))
 
 # ******** Measure accracy of μs clock ********
 # Callback occurs in interrupt context
@@ -122,7 +126,7 @@ async def us_setup(tick):
                              fix_cb=lambda *_: red.toggle(),
                              pps_cb=us_cb, pps_cb_args=(tick, blue))
 
-async def do_usec(terminate):
+async def do_usec(minutes):
     tick = asyn.Event()
     print('Setting up GPS.')
     gps_tim = await us_setup(tick)
@@ -133,6 +137,9 @@ async def do_usec(terminate):
     sd = 0
     nsamples = 0
     count = 0
+    terminate = asyn.Event()
+    loop = asyncio.get_event_loop()
+    loop.create_task(killer(terminate, minutes))
     while not terminate.is_set():
         await tick
         usecs = tick.value()
@@ -151,7 +158,5 @@ async def do_usec(terminate):
     print('Timing discrepancy is: {:5d}μs max {:5d}μs min.  Standard deviation {:4d}μs'.format(max_us, min_us, sd))
 
 def usec(minutes=1):
-    terminate = asyn.Event()
     loop = asyncio.get_event_loop()
-    loop.create_task(killer(terminate, minutes))
-    loop.run_until_complete(do_usec(terminate))
+    loop.run_until_complete(do_usec(minutes))

gps/as_GPS_utils.py

@@ -0,0 +1,48 @@
+# as_GPS_utils.py Extra functionality for as_GPS.py
+# Put in separate file to minimise size of as_GPS.py for resource constrained
+# systems.
+
+# Copyright (c) 2018 Peter Hinch
+# Released under the MIT License (MIT) - see LICENSE file
+from as_GPS import MDY, DMY, LONG
+
+_DIRECTIONS = ('N', 'NNE', 'NE', 'ENE', 'E', 'ESE', 'SE', 'SSE', 'S', 'SSW',
+               'SW', 'WSW', 'W', 'WNW', 'NW', 'NNW')
+
+def compass_direction(gps):  # Return cardinal point as string.
+    # Calculate the offset for a rotated compass
+    if gps.course >= 348.75:
+        offset_course = 360 - gps.course
+    else:
+        offset_course = gps.course + 11.25
+    # Each compass point is separated by 22.5°, divide to find lookup value
+    return _DIRECTIONS[int(offset_course // 22.5)]
+
+_MONTHS = ('January', 'February', 'March', 'April', 'May',
+            'June', 'July', 'August', 'September', 'October',
+            'November', 'December')
+
+def date_string(gps, formatting=MDY):
+    day, month, year = gps.date
+    # Long Format January 1st, 2014
+    if formatting == LONG:
+        dform = '{:s} {:2d}{:s}, 20{:2d}'
+        # Retrieve Month string from private set
+        month = _MONTHS[month - 1]
+        # Determine Date Suffix
+        if day in (1, 21, 31):
+            suffix = 'st'
+        elif day in (2, 22):
+            suffix = 'nd'
+        elif day in (3, 23):
+            suffix = 'rd'
+        else:
+            suffix = 'th'
+        return dform.format(month, day, suffix, year)
+
+    dform = '{:02d}/{:02d}/{:02d}'
+    if formatting == DMY:
+        return dform.format(day, month, year)
+    elif formatting == MDY:  # Default date format
+        return dform.format(month, day, year)
+    raise ValueError('Unknown date format.')

gps/as_rwGPS.py

@@ -77,6 +77,7 @@ async def update_interval(self, ms=1000):
             raise ValueError('Invalid update interval {:d}ms.'.format(ms))
         sentence = bytearray('$PMTK220,{:d}*00\r\n'.format(ms))
         await self._send(sentence)
+        self._update_ms = ms  # Save for timing driver
 
     async def enable(self, *, gll=0, rmc=1, vtg=1, gga=1, gsa=1, gsv=5, chan=0):
         fstr = '$PMTK314,{:d},{:d},{:d},{:d},{:d},{:d},0,0,0,0,0,0,0,0,0,0,0,0,{:d}*00\r\n'