+Note: For older Raspberry Pi models, it may be necessary to enable
+~pps-gpio~ via modifications to ~/etc/modules~ (see [[https://www.raspberrypi.org/forums/viewtopic.php?p=757747#p757747][link]]).
+
+***** Enable GPS device
+The Ozzmaker BerryGPS-IMU makes NMEA sentences available via the
+serial "UART" device ~/dev/ttyAMA0~. If bluetooth has not been
+disabled, the Raspberry Pi OS automatically creates a software "UART"
+device at ~/dev/serial0~. See the "[[file:~/git-OC/ninfacyzga-01/doc/setup/README.org::*Disable%20Bluetooth][Disable Bluetooth]]" section in the
+[[file:../setup/README.org][Main Setup]] Initial Startup procedure for instructions on how to
+disable bluetooth to free up ~/dev/ttyAMA0~ for use by ~gpsd~.
+
+Note: Older ~ntp~ documentation indicates that ~ntp~ (and presumably
+~ntpsec~ might be able to access GPS data (ex: NMEA sentences) without
+the aid of ~gpsd~ itself if the data is available at a device named
+~/dev/ggp0~. Similarly, the same might apply to PPS data and the
+~/dev/gpspps0~ device. However, since the Raspberry Pi OS overlay
+system automatically creates ~/dev/pps0~ using the modifications to
+~/boot/config.txt~ (described [[*Enable PPS device][elsewhere]] in this procedure).
+
+***** Setup ~gpsd~
+See the "[[file:~/git-OC/ninfacyzga-01/doc/location/README.org::*Setup%20~gpsd~][Setup ~gpsd~]]" subsection within the "Initial Startup" section
+of the Location Logging [[file:~/git-OC/ninfacyzga-01/doc/location/README.org][~README.org~]] file. There is one additional
+change that must be made which is to add a ~/dev/pps0~ item to the
+~DEVICES=~ line in ~/etc/default/gpsd~ like so:
+
+: DEVICES="/dev/ttyAMA0 /dev/pps0"
+
+~/dev/ttyAMA0~ is where ~gpsd~ can get NMEA data from the GPS unit.
+
+~/dev/pps0~ is where ~gpsd~ can get a PPS signal.
+
+As an example, the following lines will be present in
+~/etc/default/gpsd~ if both location and time tracking are set up:
+
+#+BEGIN_EXAMPLE
+START_DAEMON="true"
+USBAUTO="false"
+DEVICES="/dev/ttyAMA0 /dev/pps0"
+GPSD_OPTIONS="-n"
+#+END_EXAMPLE
+
+***** Setup ~ntpsec~
+The ~ntpsec~ configuration file at ~/etc/ntpsec/ntp.conf~ must be
+modified to tell ~ntpsec~ how to retrieve and interpret the GPS and
+PPS data provided by ~gpsd~.
+
+In summary, lines need to be added telling ~ntpsec~ how often to poll
+certain sources (local or remote) for time information as well as how
+to prioritize and label information from each source.
+
+~ntpsec~ uses syntax simplified from that of ~ntp~. Specifically, it
+recommends use of the ~refclock~ keyword for configuring local
+hardware clocks such as GPS and PPS devices.
+
+Below is an example of lines that may be added to
+~/etc/ntpsec/ntp.conf~ in order to ensure that the system clock will always have
+
+#+BEGIN_EXAMPLE
+# Local time sources
+
+# Kernel PPS (precision seconds; driver 22)
+refclock pps unit 0 refid kPPS flag3 1 minpoll 4 maxpoll 4 stratum 1
+
+# GPS PPS reference (precision seconds; driver 28; root) (NTP1)
+refclock shm unit 1 refid PPS minpoll 4 maxpoll 4 iburst stratum 1
+
+# GPS Serial data reference (coarse time; driver28; root) (NTP0)
+refclock shm unit 0 refid GPS prefer time1 0.109 minpoll 4 maxpoll 4 iburst stratum 1
+
+# GPS PPS reference (precision seconds; driver 28; user) (NTP2)
+refclock shm unit 2 refid PPSuser minpoll 4 maxpoll 4 iburst stratum 1
+
+# Tolerate outliers (useful for coarse clocks)
+tos mindist 0.500
+#+END_EXAMPLE
+
+A complete working example of an ~ntp.conf~ file is found in Appendix
+A of this document.
+
+Commands useful for examining the shared memory driver used by ~gpsd~
+and ~ntpsec~ are:
+
+- ~sudo ntpshmmon~ : Shows live output of data using the shared memory
+ driver. ([[https://gpsd.gitlab.io/gpsd/gpsd-time-service-howto.html][ref]])
+
+- ~sudo ipcs -m~ : Show live segments of the shared memory. ([[https://gpsd.gitlab.io/gpsd/gpsd-time-service-howto.html][ref]])
+
+General references for this configuration file are:
+
+- "Raspberry Pi as a Stratum-1 NTP Server - Updating to the final NTP
+ configuration file" by David Taylor. [[http://www.satsignal.eu/ntp/Raspberry-Pi-NTP.html#ntp-conf][Link]]. Date: 2020-03-24. Note:
+ An example of kernel PPS transfer from ~gpsd~ to ~ntp~ via
+ ~127.127.22.0~.
+
+- "GPSD Time Service HOWTO" by Garry E. Miller. [[https://gpsd.gitlab.io/gpsd/gpsd-time-service-howto.html][Link]]. Date:
+ 2020-06-28. Note: Explains how shared memory segments available at
+ ~127.127.28.0~, ~127.127.28.1~, ~127.127.28.2~, etc. work in context
+ of an ~ntp~ configuration file.
+
+- "Building a Stratum 1 NTP Server with a Raspberry Pi 4 and Adafruit
+ Ultimate GPS Hat". [[http://www.gregledet.net/computers/building-a-stratum-1-ntp-server-with-a-raspberry-pi-4-and-adafruit-ultimate-gps-hat/][Link]]. Date: 2020-02-23. Note: A concise example
+ between ~gpsd~ and ~ntp~ setup for a Raspberry Pi 4 using
+ ~127.127.28.0~ and ~127.127.28.1~. Recommends use of ~ntpsec~
+ instead of ~ntp~.
+
+Expalantions of some ~ntpsec~ [[https://docs.ntpsec.org/latest/comdex.html][commands and options]] used in the
+configuration file include:
+
+- ~refclock~ : An ~ntpsec~ keyword not present in ~ntp-4.2.8~ that is
+ meant to simplify configuration of reference clocks that use certain
+ [[https://docs.ntpsec.org/latest/refclock.html][drivers]] including ~pps~ ([[https://docs.ntpsec.org/latest/driver_pps.html][PPS Clock Discipline]]), ~shm~ ([[https://docs.ntpsec.org/latest/driver_shm.html][Shared Memory
+ Driver]]) . In ~ntp-4.2.8~ and earlier, in order to configure a clock,
+ instead of ~ntpsec~'s one keyword (~refclock~), two keywords would
+ be required (~server~ and ~fudge~).
+
+- ~server [address]~ : Tells ~ntpsec~ the address to query for time
+ information. May be IP address or URL. Additional options such as
+ ~minpoll~, ~maxpoll~, ~prefer~, and ~true~ may be added.
+
+- ~prefer~ : Indicates the source should be prioritized in some
+ way. How exactly the ~ntpsec~ mitigation rules (see [[https://docs.ntpsec.org/latest/prefer.html][ref]]) use the
+ ~prefer~ option is complicated but in the context of dealing with a
+ GPS source and a PPS source, the GPS source should have a ~prefer~
+ option. The PPS source may have a ~prefer~ option but it is not
+ necessary; adding ~prefer~ to a PPS source is useful in the corner
+ case that the GPS source is less reliable than another source (ex: a
+ remote clock specified by ~server~).
+
+- ~... shm ... flag1 1~ : For an ~shm~ driver, tells ~ntpsec~ to
+ ignore the default sanity check that discards any time that is more
+ than 4-hours off from the system clock. Note that ~ntpsec~ treats
+ ~shm flag1 1~ in the opposite manner as ~ntp~ (see [[https://docs.ntpsec.org/latest/driver_shm.html][ref]]).
+
+- ~... shm ... time1 [float]~ : Tells ~ntpsec~ that a latency
+ time of ~[float]~ seconds is required for data to travel from the
+ address to ~ntpsec~ (ex: a USB hub in the case of a GPS device that
+ connects via USB). (see [[https://gpsd.gitlab.io/gpsd/gpsd-time-service-howto.html#_feeding_ntpd_from_gpsd][ref]]) This number of seconds should be
+ adjusted to reduce the `offset` time of the address indicated in the
+ output of the ~ntpq -pn~ command to near ~0.000~. Note that the
+ units of ~offset~ displayed by ~ntpq -pn~ are in milliseconds.
projects / EVA-2020-02.git / blobdiff