From: Steven Baltakatei Sandoval Date: Fri, 16 Oct 2020 22:34:02 +0000 (+0000) Subject: doc(doc/time):Document time tracking setup X-Git-Url: https://zdv2.bktei.com/gitweb/EVA-2020-02.git/commitdiff_plain/88b5ae54ac488cd5f8780205829b668021ea7a11?hp=2d61e0ec29e21386608cc446e6dc5a5ba01d5a6d doc(doc/time):Document time tracking setup Also: - Add TODO item to use `chrony` instead of `ntpsec` - Modify `/doc/setup/README.org` to note need to disable bluetooth - Modify `/doc/location/README.org` to note possible need to modify `gpsd` configuration file again in order to provide ~pps~ signal to a time tracking program such as ~ntpsec~. --- diff --git a/TODO.org b/TODO.org new file mode 100644 index 0000000..c85e44f --- /dev/null +++ b/TODO.org @@ -0,0 +1,13 @@ +* Task List +** TODO ~doc/setup~: Disable bluetooth +** TODO ~/doc/time~: Migrate from ~ntpsec~ to ~chrony~ +The ~ntpsec~ package is in the ~dfsg~ Debian repository instead of the +~main~ Debian repository. This is likely due to ~ntpsec~ using a mix +of ~ntp~'s original "NTP License", ~BSD 2~, and ~MIT~ licenses. + +In contrast, ~chrony~ uses the ~GPLv2~ license which allows it to be +in the Debian main repository. + +~gpsd~ documentation for communicating to ~chrony~ via +~/run/chrony.XXXX.sock~ and ~/run/chrony.YYYY.sock~ sockets (for GPS +and PPS data respectively) can be found [[https://gpsd.gitlab.io/gpsd/gpsd-time-service-howto.html#_feeding_chrony_from_gpsd][here]]. diff --git a/doc/location/README.org b/doc/location/README.org index 4bbecfd..3676e32 100644 --- a/doc/location/README.org +++ b/doc/location/README.org @@ -5,7 +5,7 @@ ** About This document was created by Steven Baltakatei Sandoval on ~2020-06-29T12:14Z~ under a [[https://creativecommons.org/licenses/by-sa/4.0/][Creative Commons BY-SA 4.0 license]]. It -was updated by Steven Baltakatei Sandoval on ~2020-10-08T18:14Z~ +was updated by Steven Baltakatei Sandoval on ~2020-10-16T22:33Z~ ** Narrative Ninfacyzga-01 records (logs) its position in time and space using a @@ -27,12 +27,9 @@ file may be compressed by ~gzip~ and encrypted by ~age~. It is an executable file contained within this repository at ~exec/bklog~. It should be copied to ~$HOME/.local/bin~. -~bkgpslog~ : A legacy bash script similar to ~bklog~ but narrower in -scope in that it only records output from ~gpspipe~. - -~gpsd~ : A background daemon app capable of interfacing with the -Ozzmaker BerryGPS-IMU's GPS submodule. Installed and initialized by -~apt~. +[[https://tracker.debian.org/pkg/gpsd][~gpsd~]] : A background daemon app capable of interfacing with the +[[https://ozzmaker.com/berrygps-berrygps-imu-quick-start-guide/][Ozzmaker BerryGPS-IMU]]'s GPS submodule. Installed and initialized by +~apt~. Should be installed along with the ~gpsd-clients~ package. ~gpspipe~ : A command line app that polls ~gpsd~ and produces a stream stdout consisting of GPS data lines in NMEA format. Installed via @@ -121,20 +118,37 @@ serial?", answer ~No~. When prompted "Would you like the serial port hardware to be enabled?", answer ~Yes~. -***** Configure ~gpsd~ +***** Setup ~gpsd~ ~gpsd~ needs to know which serial port to look at for NMEA location data generated by the GPS unit. This can be done by modifying the ~gpsd~ configuration file at ~/etc/default/gpsd~. : sudo nano /etc/default/gpsd -Change +Make sure the following lines are present: + +#+BEGIN_EXAMPLE +START_DAEMON="true" +USBAUTO="false" +DEVICES="/dev/ttyAMA0" +GPSD_OPTIONS="-n" +#+END_EXAMPLE + +NOTE: The ~DEVICES=~ line must be adjusted if the the ~ninfacyzga~ +device is configured to also track time. + +NOTE: The ~-n~ option causes ~gpsd~ to begin polling GPS devices +without waiting for a client to connect. This is important if ~gpsd~ +provides data to other applications (ex: ~gpspipe~, ~ntpsec~, +~chrony~). + +Restart ~gpsd~ via: -: DEVICES="" +: $ sudo systemctl restart gpsd.service -to +Run ~gpsmon~ to verify that location data is being recorded. -: DEVICES="/dev/serial0" +: $ gpsmon ***** Automatic Start Configuration It is recommended to create a daily ~cron~ job that executes a bash diff --git a/doc/setup/README.org b/doc/setup/README.org index 7c5b63a..1a2f9fa 100644 --- a/doc/setup/README.org +++ b/doc/setup/README.org @@ -1,11 +1,11 @@ -#+TITLE:Ninfacyzga-01 Setup +#+TITLE:Ninfacyzga-1 Main Setup #+AUTHOR:Steven Baltakatei Sandoval #+EMAIL:baltakatei@gmail.com * Main Setup ** About This document created by [[http://baltakatei.com][Steven Baltakatei Sandoval]] on ~2020-10-07T18:39Z~ under a [[http://creativecommons.org/licenses/by-sa/4.0/][CC BY-SA 4.0]] license and last updated on -~2020-10-08T00:50Z~. +~2020-10-16T22:26Z~. This document contains information regarding setup of the ninfacyzga-01 hardware common to all operation modes. This includes: @@ -318,6 +318,47 @@ https://ideaheap.com/2013/07/stopping-sd-card-corruption-on-a-raspberry-pi/ Raspbian 10 Buster: https://www.raspberrypi.org/forums/viewtopic.php?p=1490692&sid=5c596a124b7805d6b10dab8d3d7caf16#p1490692 +***** Disable Bluetooth +In order to reduce power consumed by bluetooth transmissions, +bluetooth functionality should be disabled (see [[https://di-marco.net/blog/it/2020-04-18-tips-disabling_bluetooth_on_raspberry_pi/][link]]). + +Modify the ~/boot/config.txt~ file (the Pi's equivalent to BIOS +settings; see [[https://www.raspberrypi.org/documentation/configuration/config-txt/][link]]) to make sure the following lines are added: + +#+BEGIN_EXAMPLE +# Disable Bluetooth +dtoverlay=disable-bt +#+END_EXAMPLE + +The ~hciuart~ service is associated with bluetooth functionality via +UART which may conflict with location and time data provided via +~/dev/ttyAMA0~. It should be disabled like so: + +#+BEGIN_EXAMPLE +$ sudo systemctl disable hciuart +#+END_EXAMPLE + +***** Disable login console via serial port +Some ~ninfacyzga~ functions (location and time) require data transfer +via ~/dev/ttyAMA0~. In order to prevent serial login programs from +interfering with such functions, it is necessary to disable them. + +Run the following commands to disable login via ~ttyAMA0~: + +#+BEGIN_EXAMPLE +$ sudo systemctl stop serial-getty@ttyAMA0.service +$ sudo systemctl disable serial-getty@ttyAMA0.service +$ sudo systemctl disable hciuart +#+END_EXAMPLE + +Modify ~/boot/cmdline.txt~ to remove the console: + +#+BEGIN_EXAMPLE +$ sudo nano /boot/cmdline.txt +#+END_EXAMPLE + +Remove ~console=serial0,115200~ + ***** Log Transfer Configuration Log files may be shared to other machines via ~syncthing~. See [[https://docs.syncthing.net/][this]] manual for how to set up a shared folder and add Ninfacyzga-01 as a diff --git a/doc/time/README.org b/doc/time/README.org index 593b411..e662695 100644 --- a/doc/time/README.org +++ b/doc/time/README.org @@ -1,130 +1,15 @@ +#+TITLE: Ninfacyzga-1 Time Tracking +#+AUTHOR: Steven Baltakatei Sandoval +#+EMAIL: baltakatei@gmail.com * Time Tracking +** About This document was created by Steven Baltakatei Sandoval on ~2020-07-23T22:27Z~ under a [[https://creativecommons.org/licenses/by-sa/4.0/][Creative Commons BY-SA 4.0 license]]. It -was updated by Steven Baltakatei Sandoval on ~2020-10-13T18:02Z~ - -** Development Task list -*** Set up prototype unit -**** DONE Solder wire for PPS signal -***** 2020-07-25T20:03Z; bktei> Soldered pins to permit accessibility. - CLOSED: [2020-07-25 Sat 20:03] -**** Follow guide -- [[https://ozzmaker.com/forums/topic/connecting-gps-pps-pin/][Ozzmaker post]] on ~PPS~ wiring and a [[https://www.satsignal.eu/ntp/Raspberry-Pi-NTP.html][guide]] recommendation. -- [[http://www.satsignal.eu/raspberry-pi/Schmidt-RPZ-NTP-2016.pdf][Schmidt article]] on Raspberry Pi Zero time server. -- [[https://gpsd.gitlab.io/gpsd/gpsd-time-service-howto.html][GPSD dev ref]] page for ~gpsd~ interfacing with ~ntp~. -- [[https://raspberryautomation.com/connect-multiple-ds18b20-temperature-sensors-to-a-raspberry-pi/][Raspberry Autom]] article on specifying custom GPIO pin. -*** Document prototype unit -**** Summarize setup steps -***** Perform main setup steps -***** Install time-specific apps -: $ sudo apt install usbmount eject gpsd gpsd-clients python-gps pps-tools ntp - -Explanation: - -- ~python-gps~: (Add explanation here) -- ~pps-tools~: Package containing ~ppstest~ command useful for - checking status of PPS devices. -- ~ntpsec~: Security-hardened version of ~ntp~, the Network Time - Protocol package. Useful for automatically setting the system clock - according to time servers or local hardware. - - -**** TODO Integrate DHCP details from gregledet tutorial -http://www.gregledet.net/computers/building-a-stratum-1-ntp-server-with-a-raspberry-pi-4-and-adafruit-ultimate-gps-hat/ -**** TODO Note working ntp.conf file - -#+BEGIN_EXAMPLE -# /etc/ntp.conf, configuration for ntpd; see ntp.conf(5) for help - -driftfile /var/lib/ntp/ntp.drift -logfile /var/log/ntp.log - -# Leap seconds definition provided by tzdata -leapfile /usr/share/zoneinfo/leap-seconds.list - -# Enable this if you want statistics to be logged. -statsdir /var/log/ntpstats/ - -statistics loopstats peerstats clockstats -filegen loopstats file loopstats type day enable -filegen peerstats file peerstats type day enable -filegen clockstats file clockstats type day enable - - -# You do need to talk to an NTP server or two (or three). -#server ntp.your-provider.example -server time.nist.gov iburst minpoll 5 maxpoll 5 -server tick.usno.navy.mil iburst minpoll 5 maxpoll 5 -server 0.us.pool.ntp.org iburst minpoll 5 maxpoll 5 -server 0.us.pool.ntp.org iburst minpoll 5 maxpoll 5 -server 0.us.pool.ntp.org iburst minpoll 5 maxpoll 5 -server 0.us.pool.ntp.org iburst minpoll 5 maxpoll 5 - -# pool.ntp.org maps to about 1000 low-stratum NTP servers. Your server will -# pick a different set every time it starts up. Please consider joining the -# pool: -#pool 0.debian.pool.ntp.org iburst -#pool 1.debian.pool.ntp.org iburst -#pool 2.debian.pool.ntp.org iburst -#pool 3.debian.pool.ntp.org iburst - -# PPS Kernel mode -server 127.127.22.0 minpoll 4 maxpoll 4 true -fudge 127.127.22.0 flag3 1 refid kPPS - -# GPS PPS reference (NTP2) -server 127.127.28.2 minpoll 4 maxpoll 4 -fudge 127.127.28.2 refid SHM2 - -# GPS Serial data reference (NTP0) -server 127.127.28.0 minpoll 4 maxpoll 4 prefer -fudge 127.127.28.0 time1 +0.593 refid GPS - -# Fix False tickers -tos mindist 0.5 - -# Access control configuration; see /usr/share/doc/ntp-doc/html/accopt.html for -# details. The web page -# might also be helpful. -# -# Note that "restrict" applies to both servers and clients, so a configuration -# that might be intended to block requests from certain clients could also end -# up blocking replies from your own upstream servers. - -# By default, exchange time with everybody, but don't allow configuration. -restrict -4 default kod notrap nomodify nopeer noquery limited -restrict -6 default kod notrap nomodify nopeer noquery limited - -# Local users may interrogate the ntp server more closely. -restrict 127.0.0.1 -restrict ::1 - -# Needed for adding pool entries -restrict source notrap nomodify noquery - -# Clients from this (example!) subnet have unlimited access, but only if -# cryptographically authenticated. -#restrict 192.168.123.0 mask 255.255.255.0 notrust - - -# If you want to provide time to your local subnet, change the next line. -# (Again, the address is an example only.) -#broadcast 192.168.123.255 - -# If you want to listen to time broadcasts on your local subnet, de-comment the -# next lines. Please do this only if you trust everybody on the network! -#disable auth -#broadcastclient -#+END_EXAMPLE - -**** TODO Integreate References -- Some explanations for ~time1~, ~flag1~, ~flag3~, ~refid~, etc. strings in ntp.conf: [[http://doc.ntp.org/4.2.8/drivers/driver28.html][link]]. -- NTP Basics (what "system peer" means): [[https://kb.meinbergglobal.com/kb/time_sync/ntp/ntp_basics][link]]. -- GPSD guide indicating PPS signals should be preferred over GPS signals: [[https://gpsd.gitlab.io/gpsd/gpsd-time-service-howto.html#_feeding_ntpd_from_gpsd][link]] +was updated by Steven Baltakatei Sandoval on ~2020-10-16T22:26Z~ ** Narrative The ~ninfacyzga-01~ device is equipped with an Ozzmaker BerryGPS-IMU -module which provides time and location data to ~gpsd~ and ~ntp~. The +module which provides time and location data to ~gpsd~ and ~ntpsec~. The time is provided by GPS satellites which themselves are equipped [fn:nasa_20020408_atomicclock] with atomic clocks. This extremely accurate set of clocks are needed since a GPS receiver @@ -140,43 +25,74 @@ Date:2002-04-08; Website:NASA.gov; [[https://web.archive.org/web/20100429141752/ ** Description *** Hardware -Ozzmaker BerryGPS-IMU, Version 3 +Ozzmaker BerryGPS-IMU, Version 3 (see [[https://ozzmaker.com/berrygps-berrygps-imu-quick-start-guide/][ref]]). *** Software -This guide describes steps that may be used to convert a Raspberry Pi -into a time server using ~gpsd~. +- [[https://tracker.debian.org/pkg/gpsd][~gpsd~]] : A background daemon app capable of interfacing with the + [[https://ozzmaker.com/berrygps-berrygps-imu-quick-start-guide/][Ozzmaker BerryGPS-IMU]]'s GPS submodule. Installed and initialized by + ~apt~. Should be installed along with the ~gpsd-clients~ + package. This procedure was developed with ~gpsd~ version + +- [[https://tracker.debian.org/pkg/ntpsec][~ntpsec~]] : A security-hardned version of [[https://tracker.debian.org/pkg/ntp][~ntp~]] which is a "[[https://en.wikipedia.org/wiki/Network_Time_Protocol][Network + Time Protocol]]" app that synchronizes the system clock with local or + remote time servers or devices. It is capable of extracting time + data from a GPS signal handled by ~gpsd~. It is also capable of + using the high precision PPS (pulse-per-second) signal handled by + ~gpsd~. Installed via ~apt~. This procedure was developed with + ~ntpsec~ version ~1.1.3~. + ** Operating Procedures *** Initial Startup -**** Install Raspbian 10 (Buster) onto a Raspberry Pi Zero W. - - -**** Install Hardware +**** Perform initial setup. +See [[file:../setup/README.org][Main Setup]] procedure. +**** Install Hardware for time tracking See [[https://ozzmaker.com/forums/topic/connecting-gps-pps-pin/][this]] Ozzmaker forum topic about connecting the BerryGPS-IMU ~T_PULSE~ pin to GPIO 18. +#+CAPTION: An image showing how to connect the PPS signal from an Ozzmaker BerryGPS-IMU board to a Raspberry Pi Zero W. +#+NAME: fig:PPS_BERRYGPS_RASPIZW +[[../../img/Compact_Stratum_1_NTP_time_server_hardware,_October_2020.jpg]] + Connect the ~T_PULSE~ connection on the BerryGPS-IMU-3 to GPIO pin 18 (ex: with solder and wire) in order to provide the PPS data signal generated by the BerryGPS-IMU to the Raspberry Pi. Processing of this data signal is handled by adding a line to ~/boot/config.txt~ in the next section ("Install Software"). -**** Install Software -These instructions assume that ~gpsd~ has already been setup to -provide NMEA sentences to ~gpspipe~ for location. See the ~README.org~ -in ~doc/location~ for details. Basically, ~gpsd~ needs to be told via -its ~/etc/default/gpsd~ configuration file of which ~/dev/ttyS0~ will -provide the raw GPS module data. +Note: If it is desired to specify a custom GPIO pin besides the one +recommended, see this [[https://raspberryautomation.com/connect-multiple-ds18b20-temperature-sensors-to-a-raspberry-pi/][Raspberry Autom]] article. + +**** Install Software for time tracking +The time tracking function can be performed by two programs: ~gpsd~ +and ~ntpsec~. + +Basically, two things need to happen: + +1. ~gpsd~ needs to be pointed towards the correct device files for + incoming GPS data (in NMEA format) and the PPS signal ("pulse per + second"; a high precision time signal). + +2. ~ntpsec~ needs to be pointed towards the correct local IP addresses + where ~gpsd~ provides GPS data and the PPS signal. + +~gpsd~ then will provide GPS and PPS data to ~ntpsec~ via a "shared +memory driver". ***** Install packages via ~apt~ Run the following command to install the required packages. -: $ sudo apt install usbmount eject gpsd gpsd-clients python-gps pps-tools ntp +: $ sudo apt install gpsd gpsd-clients python-gps pps-tools ntpsec -***** Modify ~/boot/config.txt~ -In order to tell the Raspberry Pi to expect PPS data on ~BCM 18~ (pin -number 12; see [[https://pinout.xyz/][RaspPi pinout]]), add the following line to -~/boot/config.txt~ as described on [[https://ozzmaker.com/forums/topic/problems-with-pps-on-a-pi0w-running-raspian-and-attached-to-a-berrygps-imuv3/][this Ozzmaker page]]: +***** Enable PPS device +Modify the ~/boot/config.txt~ file in order to tell the Raspberry Pi +to expect PPS data on ~BCM 18~ (pin number 12; see [[https://pinout.xyz/][link]]). This is done +by adding the following line to ~/boot/config.txt~ as described on +[[https://ozzmaker.com/forums/topic/problems-with-pps-on-a-pi0w-running-raspian-and-attached-to-a-berrygps-imuv3/][this Ozzmaker page]]: : dtoverlay=pps-gpio,gpiopin=18 +The ~/boot/config.txt~ file can be modified via: + +: $ sudo nano /boot/config.txt + PPS data can be confirmed by running: #+BEGIN_EXAMPLE @@ -191,71 +107,374 @@ source 0 - assert 1595708076.003779580, sequence: 221 - clear 0.000000000, sequ source 0 - assert 1595708077.003850580, sequence: 222 - clear 0.000000000, sequence: 0 #+END_EXAMPLE -***** Add udev rule -As per [[https://www.slsmk.com/how-to-setup-a-gps-pps-ntp-time-server-on-raspberry-pi/][the slsmk.com]] guide, create symbolic links expected by ~ntp~ -pointing to the PPS device. This may be performed by creating the file: +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~: -: /etc/udev/rules.d/09-pps.rules +#+BEGIN_EXAMPLE +send host-name = gethostname(); +request subnet-mask, broadcast-address, time-offset, routers, + domain-name, domain-name-servers, domain-search, host-name, + dhcp6.name-servers, dhcp6.domain-search, dhcp6.fqdn, dhcp6.sntp-servers, + netbios-name-servers, netbios-scope, interface-mtu, + rfc3442-classless-static-routes, ntp-servers; +#+END_EXAMPLE -with the contents: +should be changed to: #+BEGIN_EXAMPLE -KERNEL=="ttyAMA0", SUBSYSTEM=="tty", DRIVER=="", OWNER=="root", GROUP=="tty", MODE=="0777", SYMLINK+="gps0" +send host-name = gethostname(); +request subnet-mask, broadcast-address, time-offset, routers, + domain-name, domain-name-servers, domain-search, host-name, + dhcp6.name-servers, dhcp6.domain-search, dhcp6.fqdn, + netbios-name-servers, netbios-scope, interface-mtu, + rfc3442-classless-static-routes; #+END_EXAMPLE -***** Modify ~/etc/modules~ -For older versions of Raspberry Pi, it may be necessary to explicitly -require the ~pps-gpio~ module to be loaded by making sure -~/etc/modules~ contains the line: +***** Disable CPU power saving +Power saving featurs of the Raspberry Pi Zero W may also be disabled +in order to improve accuracy. + +****** Configure CPU ~scaling_governor~ +If additional precision is required, the PPS signal may be made more +reliable at the cost of increasing CPU power by configuring the CPU to +always run at maximum frequency.[fn:se_20180320_raspicpugov] This +change can be performed by modifying the following file as root: + +: /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor + +The file should consist of one line. Change -: pps-gpio +: ondemand -According to [[https://www.raspberrypi.org/forums/viewtopic.php?p=757747#p757747][this]] post on 2015-05-13T09:14 by [[https://www.raspberrypi.org/forums/memberlist.php?mode=viewprofile&u=31454][ame]] on the Raspberry Pi -forums, +to -#+BEGIN_QUOTE -rowlandski wrote: -> Hi, -> -> I want the RPi to load/probe the w1-gpio module on boot. -> -> I have added: -> -> sudo modprobe w1-gpio -> -> To the etc/modules file, but on boot it is not loaded. -> I have checked this by the lsmod command. If i then enter the above line manually and then check it's there loaded. -> -> What's wrong with my line on code in the modules file? -> -> Thanks +: performance -You no longer need to load modules for some devices. It's handled by devicetree. +. -Search for "devicetree" on the forum, or start here: -https://www.raspberrypi.org/forums/viewtopic.php?f=28&t=97314 -#+END_QUOTE +This change can be performed via the ~nano~ text editor by running the +following commands: -As of 2020-07-25, using Raspbian Buster 10 with a BerryGPS-IMU v3, -~/etc/modules~ did not need to be modified. +: $ sudo su - +: # nano /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor -***** Remove DHCP client hooks -As per [[https://www.slsmk.com/how-to-setup-a-gps-pps-ntp-time-server-on-raspberry-pi/][this]] guide, "remove ntp DHCP hook (so that it doesn't override ntp settings)". +Additionally, in order to prevent the ~raspi-config~ init script from +reverting this text file back to ~ondemand~ after a reboot, this +script must be disabled via: -This can be performed by running the following command (shown in -script form for readability): +: $ sudo systemctl disable raspi-config + +****** Configure ~/boot/config.txt~ +Modify ~/boot/config.txt~ so that it contains these lines in order to +disable power saving functions: #+BEGIN_EXAMPLE -if [ -f "/etc/dhcp/dhclient-exit-hooks.d/ntp" ]; then - mv /etc/dhcp/dhclient-exit-hooks.d/ntp /etc/dhcp/dhclient-exit-hooks.d/xxxntp-orig; -else - echo "NTP exit hook does not exist"; -fi; +# Disable power saving +nohz=off #+END_EXAMPLE +[fn:se_20180320_raspicpugov] Title:[[https://raspberrypi.stackexchange.com/questions/9034/how-to-change-the-default-governor]["How to change the default governor?"]]; Author:[[https://raspberrypi.stackexchange.com/users/5538/goldilocks][goldilocks]]; Date: 2018-03-20; Website:stackexchange.com; + *** Normal Startup *** Normal Operation *** Normal Shutdown *** Unscheduled Shutdown +** Appendix A +*** Example ~ntp.conf~ for ~ntpsec~ +Below is an example ~ntp.conf~ file for use with ~ntpsec~. + +#+BEGIN_EXAMPLE +# /etc/ntpsec/ntp.conf, configuration for ntpd; see ntp.conf(5) for help + +# Drift file +driftfile /var/lib/ntpsec/ntp.drift + +# Leap seconds definition provided by tzdata +leapfile /usr/share/zoneinfo/leap-seconds.list + +# Log file +#logfile /var/log/ntp.log + + +# You must create /var/log/ntpsec (owned by ntpsec:ntpsec) to enable logging. +#statsdir /var/log/ntpsec/ +#statistics loopstats peerstats clockstats +#filegen loopstats file loopstats type day enable +#filegen peerstats file peerstats type day enable +#filegen clockstats file clockstats type day enable + + +# Comment this out if you have a refclock and want it to be able to discipline +# the clock by itself (e.g. if the system is not connected to the network). +#tos minclock 4 minsane 3 + + +# 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 + + +# Specify one or more NTP servers. + +# pool.ntp.org maps to about 1000 low-stratum NTP servers. Your server will +# pick a different set every time it starts up. Please consider joining the +# pool: +server time.nist.gov iburst +server tick.usno.navy.mil iburst +server 0.us.pool.ntp.org iburst +#server 0.us.pool.ntp.org iburst +#server 0.us.pool.ntp.org iburst +#server 0.us.pool.ntp.org iburst +pool 0.debian.pool.ntp.org iburst +#pool 1.debian.pool.ntp.org iburst +#pool 2.debian.pool.ntp.org iburst +#pool 3.debian.pool.ntp.org iburst + + +# Access control configuration; see /usr/share/doc/ntpsec-doc/html/accopt.html +# for details. +# +# Note that "restrict" applies to both servers and clients, so a configuration +# that might be intended to block requests from certain clients could also end +# up blocking replies from your own upstream servers. + +# By default, exchange time with everybody, but don't allow configuration. +restrict default kod nomodify nopeer noquery limited + +# Local users may interrogate the ntp server more closely. +restrict 127.0.0.1 +restrict ::1 +#+END_EXAMPLE + +* Discard + +** Transitional ntp to ntpsec config file snippet +# Kernel PPS (precision seconds; driver 22) +#server 127.127.22.0 minpoll 4 maxpoll 4 true +#fudge 127.127.22.0 flag3 1 refid kPPS stratum 1 +refclock pps unit 0 refid kPPS flag3 1 minpoll 4 maxpoll 4 stratum 1 + +# GPS PPS reference (precision seconds; driver 28; root) (NTP1) +#server 127.127.28.1 minpoll 4 maxpoll 4 iburst +#fudge 127.127.28.1 flag1 1 refid PPS +refclock shm unit 1 refid PPS minpoll 4 maxpoll 4 iburst stratum 1 + +# GPS Serial data reference (coarse time; driver28; root) (NTP0) +#server 127.127.28.0 minpoll 4 maxpoll 4 iburst prefer +#fudge 127.127.28.0 flag1 1 time1 0.109 refid GPS stratum 1 +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) +#server 127.127.28.2 minpoll 4 maxpoll 4 iburst +#fudge 127.127.28.2 flag1 1 refid PPSuser stratum 1 +refclock shm unit 2 refid PPSuser minpoll 4 maxpoll 4 iburst stratum 1 +# Tolerate outliers (useful for coarse clocks) +tos mindist 0.500 diff --git a/img/Compact_Stratum_1_NTP_time_server_hardware,_October_2020.jpg b/img/Compact_Stratum_1_NTP_time_server_hardware,_October_2020.jpg new file mode 100644 index 0000000..4f4bfda Binary files /dev/null and b/img/Compact_Stratum_1_NTP_time_server_hardware,_October_2020.jpg differ