+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.
+
+- ~... refid [string]~ : Tells ~ntpsec~ a string used to label the source.
+
+- ~fudge~ : An ~ntp~ keyword that ~ntpsec~ developers do not recommend
+ using; ~ntpsec~ documentation for ~fudge~ is widthdrawn. For local
+ hardware providing GPS and PPS time information, ~fudge~ can mostly
+ be replaced with use of the ~refclock~ keyword instead.
+
+- ~fudge [address]~ : Tells ~ntpsec~ to consider additional options
+ when evaluating the accuracy of time from a given address.
+
+- ~fudge [address] ... flag3 1~ : An option that tells ~ntpsec~ to
+ enable "kernel PPS discipline" when interpreting the PPS signal at
+ the address. (see [[http://doc.ntp.org/4.2.8p7/drivers/driver22.html][ref]]).
+
+- ~stratum 1~ : Tells ~ntpsec~ to label the source as a "stratum 1"
+ time server. This means that it is a clock using NTP that is a
+ canonical (?) time source. For example, a stratum 0 NTP time server
+ would be an atomic clock. A stratum 1 NTP time server could be a
+ clock that uses a GPS receiver to synchronize to said atomic clock.
+
+- ~iburst~ : Tells ~ntpsec~ how often to query a source.
+
+- ~fudge [address] ... flag1 [float]~ : See description of ~... shm
+ ... time1 [float]~.
+
+- ~tos mindist [float]~ : Tells ~ntpsec~ to increase the tolerance for
+ outliers in the clock selection algorithm. Units of ~[float]~ are
+ seconds. The default value is ~0.001~ seconds. This [[http://doc.ntp.org/4.2.6/miscopt.html][reference]]
+ indicates that it is acceptable to raise this value for "clocks with
+ high jitter and a PPS signal". For the device being configured in
+ this guide, this is the case. ~ntpsec~ receives a kernel PPS signal
+ on ~127.127.22.0~ indicating when each second occurs but without
+ information about which second of the day is being ticked. ~ntpsec~
+ receives a coarse time from ~127.127.28.0~ supplied by ~gpsd~ that
+ is derived from the NMEA sentences generated by the GPS receiver;
+ this coarse time (high jitter) lacks the precision of the PPS signal
+ since NMEA sentence transmission times are not well-controlled.
+
+****** Disable DHCP services affecting ~ntpsec~
+Some processes that use [[https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol][DHCP]] (Dynamic Host Configuration Protocol) may
+cause configuration changes to configuration files of ~ntp~. Since
+~ntpsec~ is similar to ~ntp~, it is reasonable to take action to
+prevent this.
+
+Remove some files:
+
+: $ sudo rm /etc/dhcp/dhclient-exit-hooks.d/ntp
+: $ sudo rm /lib/dhcpcd/dhcpcd-hooks/50-ntp.conf
+
+In the "request" block of ~dhclient.conf~, remove ~dhcp6.sntp-servers~
+and ~ntp-servers~.
+
+: $ sudo nano /etc/dhcp/dhclient.conf
+
+For example, the following section of ~dhclient.conf~:
projects / EVA-2020-02.git / blobdiff