Re-organise files. Add as_tGPS.py.

Author: peterhinch

gps/README.md

@@ -14,6 +14,10 @@ sentences on startup. An optional read-write driver is provided for
 MTK3329/MTK3339 chips as used on the above board. This enables the device
 configuration to be altered.
 
+A further driver, for the Pyboard and other boards based on STM processors,
+provides for using the GPS device for precision timing. The chip's RTC may be
+precisely set and calibrated using the PPS signal from the GPS chip.
+
 ###### [Main README](../README.md)
 
 ## 1.1 Overview
@@ -26,7 +30,8 @@ to access data such as position, altitude, course, speed, time and date.
 ### 1.1.1 Wiring
 
 These notes are for the Adafruit Ultimate GPS Breakout. It may be run from 3.3V
-or 5V. If running the Pyboard from USB it may be wired as follows:
+or 5V. If running the Pyboard from USB, GPS Vin may be wired to Pyboard V+. If
+the Pyboard is run from a voltage >5V the Pyboard 3V3 pin should be used.
 
 | GPS |  Pyboard   | Optional |
 |:---:|:----------:|:--------:|
@@ -37,9 +42,9 @@ or 5V. If running the Pyboard from USB it may be wired as follows:
 | Rx  | X1 (U4 tx) |          |
 
 This is based on UART 4 as used in the test programs; any UART may be used. The
-X1-Rx connection is only necessary if using the read/write driver to alter the
-GPS device operation. The PPS connection is required only if using the device
-for precise timing (`as_GPS_time.py`). Any pin may be used.
+UART Tx-GPS Rx connection is only necessary if using the read/write driver. The
+PPS connection is required only if using the device for precise timing
+(`as_tGPS.py`). Any pin may be used.
 
 ## 1.2 Basic Usage
 
@@ -81,7 +86,8 @@ The following are relevant to the default read-only driver.
  `uasyncio`.
 
 Additional files relevant to the read/write driver are listed
-[here](./README.md#31-files).
+[here](./README.md#31-files). Files for the timing driver are listed
+[here](./README.md#41-files).
 
 ## 1.4 Installation
 
@@ -94,7 +100,9 @@ Adafruit [Ultimate GPS Breakout] module. If memory errors are encountered on
 resource constrained devices install as a [frozen module].
 
 For the [read/write driver](./README.md#3-the-gps-class-read/write-driver) the
-file `as_rwGPS.py` must also be installed.
+file `as_rwGPS.py` must also be installed. For the
+[timing driver](./README.md#4-using-gps-for-accurate-timing) `as_tGPS.py`
+should also be copied across.
 
 ### 1.4.2 Python 3.5 or later
 
@@ -128,8 +136,7 @@ Optional positional args:
  Default `RMC`: the callback will occur on RMC messages only (see below).
  * `fix_cb_args` A tuple of args for the callback (default `()`).
 
-Notes:  
-`local_offset` does not affect the date value.  
+Note:  
 If `sreader` is `None` a special test mode is engaged (see `astests.py`).
 
 ### 2.1.1 The fix callback
@@ -284,13 +291,19 @@ The following are counts since instantiation.
 
 ### 2.4.3 Date and time
 
-As received from most recent GPS message.
-
- * `timestamp` [hrs, mins, secs] e.g. [12, 15, 3.0]. Values are integers except
- for secs which is a float (perhaps dependent on GPS hardware).
- * `date` [day, month, year] e.g. [23, 3, 18]
+ * `utc` [hrs: int, mins: int, secs: float] UTC time e.g. [23, 3, 58.0]. Note
+ that some GPS hardware may only provide integer seconds. The MTK3339 chip
+ provides a float.
+ * `local_time` [hrs: int, mins: int, secs: float] Local time.
+ * `date` [day: int, month: int, year: int] e.g. [23, 3, 18]
  * `local_offset` Local time offset in hrs as specified to constructor.
 
+The `utc` bound variable updates on receipt of RMC, GLL or GGA messages.
+
+The `date` and `local_time` variables are updated when an RMC message is
+received. A local time offset will result in date changes where the time
+offset causes the local time to pass midnight.
+
 ### 2.4.4 Satellite data
 
  * `satellites_in_view` No. of satellites in view. (GSV).
@@ -478,45 +491,47 @@ be used to set and to calibrate the Pyboard realtime clock (RTC).
 
 ## 4.1 Files
 
- * `as_GPS_time.py` Supports the `GPS_Timer` class.
+ * `as_tGPS.py` The library. Supports the `GPS_Timer` class.
+ * `as_GPS_time.py` Test scripts for above.
 
 ## 4.2 GPS_Timer class Constructor
 
 This takes the following arguments:
  * `gps` An instance of the `AS_GPS` (read-only) or `GPS` (read/write) classes.
  * `pps_pin` An initialised input `Pin` instance for the PPS signal.
+ * `led` Default `None`. If an `LED` instance is passed, this will toggle each
+ time a PPS interrupt is handled.
 
 ## 4.3 Public methods
 
-With the exception of `delta` these return immediately. Times are derived from
-the GPS PPS signal. 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. These functions do not check this for themselves to ensure
-fast return.
+These return immediately. Times are derived from the GPS PPS signal. 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.
 
  * `get_secs` No args. Returns a float: the period past midnight in seconds.
  * `get_t_split` No args. Returns time of day tuple of form
  (hrs: int, mins: int, secs: float).
- * `set_rtc` No args. Sets the Pyboard RTC to GPS time.
- * `delta` No args. Returns no. of μs RTC leads GPS. This method blocks for up
- to a second.
 
 ## 4.4 Public coroutines
 
  * `ready` No args. Pauses until  a valid time/date message and PPS signal have
  occurred.
+ * `set_rtc` No args. Sets the Pyboard RTC to GPS time. Coro pauses for up to
+ 1s as it waits for a PPS pulse.
+ * `delta` No args. Returns no. of μs RTC leads GPS. Coro pauses for up to 1s.
  * `calibrate` Arg: integer, no. of minutes to run default 5. Calibrates the
- Pyboard RTC and returns the  calibration factor for it.
+ Pyboard RTC and returns the calibration factor for it. This coroutine sets the
+ RTC (with any existing calibration removed) and measures its drift with
+ respect to the GPS time. This measurement becomes more precise as time passes.
+ It calculates a calibration value at 10s intervals and prints progress
+ information. When the calculated calibration factor is repeatable within 1
+ digit (or the spcified time has elapsed) it terminates. Typical run times are
+ on the order of two miutes.
 
 Achieving an accurate calibration factor takes time but does enable the Pyboard
 RTC to achieve timepiece quality results. Note that calibration is lost on
 power down: solutions are either to use an RTC backup battery or to store the
-calibration factor in a file and re-apply it on startup.
-
-The coroutine calculates the calibration factor at 10 second intervals and will
-return early if three consecutive identical calibration factors are calculated.
-Note that, because of the need for precise timing, this coroutine blocks at
-intervals for periods of up to one second.
+calibration factor in a file (or in code) and re-apply it on startup.
 
 # 5. Supported Sentences
 

gps/as_GPS.py

@@ -8,6 +8,9 @@
 # Copyright (c) 2018 Peter Hinch
 # Released under the MIT License (MIT) - see LICENSE file
 
+# astests.py runs under CPython but not MicroPython because mktime is missing
+# from Unix build of utime
+
 try:
     import uasyncio as asyncio
 except ImportError:
@@ -45,6 +48,7 @@
 DATE = const(RMC)
 COURSE = const(RMC | VTG)
 
+
 class AS_GPS(object):
     _SENTENCE_LIMIT = 76  # Max sentence length (based on GGA sentence)
     _NO_FIX = 1
@@ -54,6 +58,25 @@ class AS_GPS(object):
                 'June', 'July', 'August', 'September', 'October',
                 'November', 'December')
 
+    # Return day of week from date. Pyboard RTC format: 1-7 for Monday through Sunday.
+    # https://stackoverflow.com/questions/9847213/how-do-i-get-the-day-of-week-given-a-date-in-python?noredirect=1&lq=1
+    # Adapted for Python 3 and Pyboard RTC format.
+    @staticmethod
+    def _week_day(year, month, day):
+        offset = [0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334]
+        aux = year - 1700 - (1 if month <= 2 else 0)
+        # day_of_week for 1700/1/1 = 5, Friday
+        day_of_week  = 5
+        # partial sum of days betweem current date and 1700/1/1
+        day_of_week += (aux + (1 if month <= 2 else 0)) * 365
+        # leap year correction
+        day_of_week += aux // 4 - aux // 100 + (aux + 100) // 400
+        # sum monthly and day offsets
+        day_of_week += offset[month - 1] + (day - 1)
+        day_of_week %= 7
+        day_of_week = day_of_week if day_of_week else 7
+        return day_of_week
+
     # 8-bit xor of characters between "$" and "*"
     @staticmethod
     def _crc_check(res, ascii_crc):
@@ -74,17 +97,21 @@ def __init__(self, sreader, local_offset=0, fix_cb=lambda *_ : None, cb_mask=RMC
         self.cb_mask = cb_mask
         self._fix_cb_args = fix_cb_args
 
-        # Import utime or time for fix time handling
+        # CPython compatibility. Import utime or time for fix time handling.
         try:
             import utime
             self._get_time = utime.ticks_ms
             self._time_diff = utime.ticks_diff
+            self._localtime = utime.localtime
+            self._mktime = utime.mktime
         except ImportError:
             # Otherwise default to time module for non-embedded implementations
             # Should still support millisecond resolution.
             import time
             self._get_time = time.time
             self._time_diff = lambda start, end: 1000 * (start - end)
+            self._localtime = time.localtime
+            self._mktime = time.mktime
 
         # Key: currently supported NMEA sentences. Value: parse method.
         self.supported_sentences = {'GPRMC': self._gprmc, 'GLRMC': self._gprmc,
@@ -112,8 +139,9 @@ def __init__(self, sreader, local_offset=0, fix_cb=lambda *_ : None, cb_mask=RMC
         # Data From Sentences
         # Time. Ignore http://www.gpsinformation.org/dale/nmea.htm, hardware
         # returns a float.
-        self.timestamp = [0, 0, 0.0]  # [h, m, s]
-        self.date = [0, 0, 0]  # [d, m, y]
+        self.utc = [0, 0, 0.0]  # [h: int, m: int, s: float]
+        self.local_time = [0, 0, 0.0]  # [h: int, m: int, s: float]
+        self.date = [0, 0, 0]  # [dd: int, mm: int, yy: int]
         self.local_offset = local_offset  # hrs
 
         # Position/Motion
@@ -232,15 +260,46 @@ def _fix(self, gps_segments, idx_lat, idx_long):
 
     # Set timestamp. If time/date not present retain last reading (if any).
     def _set_timestamp(self, utc_string):
-        if utc_string:  # Possible timestamp found
-            try:
-                self.timestamp[0] = int(utc_string[0:2]) + self.local_offset  # h
-                self.timestamp[1] = int(utc_string[2:4])  # mins
-                self.timestamp[2] = float(utc_string[4:])  # secs from chip is a float
-                return True
-            except ValueError:
-                pass
-        return False
+        if not utc_string:
+            return False
+        # Possible timestamp found
+        try:
+            self.utc[0] = int(utc_string[0:2])  # h
+            self.utc[1] = int(utc_string[2:4])  # mins
+            self.utc[2] = float(utc_string[4:])  # secs from chip is a float
+            return True
+        except ValueError:
+            return False
+        for idx in range(3):
+            self.local_time[idx] = self.utc[idx]
+        return True
+
+    # A local offset may exist so check for date rollover. Local offsets can
+    # include fractions of an hour but not seconds (AFAIK).
+    def _set_date(self, date_string):
+        if not date_string:
+            return False
+        try:
+            d = int(date_string[0:2])  # day
+            m = int(date_string[2:4])  # month
+            y = int(date_string[4:6]) + 2000  # year
+        except ValueError:  # Bad Date stamp value present
+            return False
+        hrs = self.utc[0]
+        mins = self.utc[1]
+        secs = self.utc[2]
+        wday = self._week_day(y, m, d) - 1
+        t = self._mktime((y, m, d, hrs, mins, int(secs), wday, 0, 0))
+        t += int(3600 * self.local_offset)
+        y, m, d, hrs, mins, *_ = self._localtime(t)  # Preserve float seconds
+        y -= 2000
+        self.local_time[0] = hrs
+        self.local_time[1] = mins
+        self.local_time[2] = secs
+        self.date[0] = d
+        self.date[1] = m
+        self.date[2] = y
+        return True
 
     ########################################
     # Sentence Parsers
@@ -255,20 +314,9 @@ def _set_timestamp(self, utc_string):
     def _gprmc(self, gps_segments):  # Parse RMC sentence
         self._valid &= ~RMC
         # UTC Timestamp.
-        try:
-            self._set_timestamp(gps_segments[1])
-        except ValueError:  # Bad Timestamp value present
-            return False
-
-        # Date stamp
-        try:
-            date_string = gps_segments[9]
-            if date_string:  # Possible date stamp found
-                self.date[0] = int(date_string[0:2])  # day
-                self.date[1] = int(date_string[2:4])  # month
-                self.date[2] = int(date_string[4:6])  # year 18 == 2018
-
-        except ValueError:  # Bad Date stamp value present
+        if not self._set_timestamp(gps_segments[1]):
+            return False # Bad Timestamp value present
+        if not self._set_date(gps_segments[9]):
             return False
 
         # Check Receiver Data Valid Flag
@@ -599,8 +647,9 @@ def speed_string(self, unit=KPH):
             return sform.format(speed, 'knots')
         return sform.format(speed, 'km/h')
 
-    def time(self):
-        return '{:02d}:{:02d}:{:2.3f}'.format(*self.timestamp)
+    def time(self, local=True):
+        t = self.local_time if local else self.utc
+        return '{:02d}:{:02d}:{:2.3f}'.format(*t)
 
     def date_string(self, formatting=MDY):
         day, month, year = self.date