doc/time/README.org

   1 * Ninfacyzga-1 Time Tracking
   2 #+TITLE: Ninfacyzga-1 Time Tracking
   3 #+AUTHOR: Steven Baltakatei Sandoval
   4 #+EMAIL: baltakatei@gmail.com
   5 #+DATE: 2023-03-14
   6
   7 ** About
   8 This document was created by Steven Baltakatei Sandoval on
   9 ~2020-07-23T22:27+00~ under a [[https://creativecommons.org/licenses/by-sa/4.0/][Creative Commons BY-SA 4.0 license]]. It
  10 was updated by Steven Baltakatei Sandoval on ~2023-03-14T19:47+00~.
  11
  12 ** Narrative
  13 The ~ninfacyzga-01~ device is equipped with an Ozzmaker BerryGPS-IMU
  14 module which provides time and location data to ~gpsd~ and
  15 ~chrony~. The time is provided by GPS satellites which themselves are
  16 equipped [fn:nasa_20020408_atomicclock] with atomic clocks. This
  17 extremely accurate set of clocks is needed since a GPS receiver
  18 determines its position in space using a [[https://en.wikipedia.org/wiki/Error_analysis_for_the_Global_Positioning_System#Special_and_general_relativity][General Relativity]]
  19 calculation that uses the small variations in the time stamps received
  20 from each satellite. This means that ~gpsd~ may be used to set the
  21 system clock without a need for an internet connection to a default
  22 Debian time server; ~ninfacyzga-01~ can be its own time server.
  23
  24 [fn:nasa_20020408_atomicclock] Title:[[https://science.nasa.gov/science-news/science-at-nasa/2002/08apr_atomicclock/][Tick-Tock Atomic Clock]];
  25 Date:2002-04-08; Website:NASA.gov; [[https://web.archive.org/web/20100429141752/http://science.nasa.gov/science-news/science-at-nasa/2002/08apr_atomicclock/][Archive-link]]; Archive-date:
  26 2010-04-29
  27
  28 ** Description
  29 *** Hardware
  30 Ozzmaker BerryGPS-IMU, Version 3 (see [[https://ozzmaker.com/berrygps-berrygps-imu-quick-start-guide/][ref]]).
  31 *** Software
  32 - [[https://www.raspberrypi.org/downloads/raspberry-pi-os/][Raspberry Pi OS]] : A GNU/Linux operating system derived from
  33   Debian 10. This procedure was developed with version ~August 2020~.
  34
  35 - [[https://tracker.debian.org/pkg/gpsd][~gpsd~]] : A background daemon app capable of interfacing with the
  36   [[https://ozzmaker.com/berrygps-berrygps-imu-quick-start-guide/][Ozzmaker BerryGPS-IMU]]'s GPS submodule. Installed and initialized by
  37   ~apt~. Should be installed along with the ~gpsd-clients~
  38   package. This procedure was developed with ~gpsd~ version
  39
  40 - [[https://chrony.tuxfamily.org/][~chrony~]] : A set of programs capable of continuously adjusting the
  41   system clock until it is synchronized with configurable time sources
  42   such as GPS and PPS data provided by ~gpsd~. ~chrony~ may be
  43   configured to act as an NTP time client or server. It uses the same
  44   protocol as ~ntp~ but is a GPLv2 implementation. This procedure was
  45   developed with ~chrony~ version ~3.4-4~.
  46
  47 ** Operating Procedures
  48 *** Initial Startup
  49 **** Perform initial setup.
  50 See [[file:../setup/README.org][Main Setup]] procedure.
  51
  52 **** Install Hardware for time tracking
  53 See [[https://ozzmaker.com/forums/topic/connecting-gps-pps-pin/][this]] Ozzmaker forum topic about connecting the BerryGPS-IMU
  54 ~T_PULSE~ pin to GPIO 18.
  55
  56 #+CAPTION: An image showing how to connect the PPS signal from an Ozzmaker BerryGPS-IMU board to a Raspberry Pi Zero W.
  57 #+NAME: fig:PPS_BERRYGPS_RASPIZW
  58 [[../../img/Compact_Stratum_1_NTP_time_server_hardware,_October_2020.jpg]]
  59
  60 Connect the ~T_PULSE~ connection on the BerryGPS-IMU-3 to GPIO pin 18
  61 (ex: with solder and wire) in order to provide the PPS data signal
  62 generated by the BerryGPS-IMU to the Raspberry Pi. Processing of this
  63 data signal is handled by adding a line to ~/boot/config.txt~ in the
  64 next section ("Install Software").
  65
  66 Note: If it is desired to specify a custom GPIO pin besides the one
  67 recommended, see this [[https://raspberryautomation.com/connect-multiple-ds18b20-temperature-sensors-to-a-raspberry-pi/][Raspberry Autom]] article.
  68
  69 **** Install Software for time tracking
  70 The time tracking function can be performed by two programs: ~gpsd~
  71 and ~chrony~.
  72
  73 Basically, two things need to happen:
  74
  75 1. ~gpsd~ needs to be pointed towards the correct device files for
  76    incoming GPS data (in NMEA format) and the PPS signal ("pulse per
  77    second"; a high precision time signal).
  78
  79 2. ~chrony~ needs to be pointed towards the correct local IP addresses
  80    where ~gpsd~ provides GPS data and the PPS signal.
  81
  82 ~gpsd~ then will provide GPS and PPS data to ~chrony~ via a "shared
  83 memory driver".
  84
  85 ***** Install packages via ~apt~
  86 Run the following command to install the required packages.
  87 : $ sudo apt install gpsd gpsd-clients python-gps pps-tools chrony
  88
  89 ***** Enable PPS device
  90 Modify the ~/boot/config.txt~ file in order to tell the Raspberry Pi
  91 to expect PPS data on ~BCM 18~ (pin number 12; see [[https://pinout.xyz/][link]]). This is done
  92 by adding the following line to ~/boot/config.txt~ as described on
  93 [[https://ozzmaker.com/forums/topic/problems-with-pps-on-a-pi0w-running-raspian-and-attached-to-a-berrygps-imuv3/][this Ozzmaker page]]:
  94
  95 : # Enable PPS on GPIO 18
  96 : dtoverlay=pps-gpio,gpiopin=18
  97
  98 The ~/boot/config.txt~ file can be modified via:
  99
 100 : $ sudo nano /boot/config.txt
 101
 102 PPS data can be confirmed by running:
 103
 104 #+BEGIN_EXAMPLE
 105 $ sudo su -
 106 # ppstest /dev/pps0
 107 trying PPS source "/dev/pps0"
 108 found PPS source "/dev/pps0"
 109 ok, found 1 source(s), now start fetching data...
 110 source 0 - assert 1595708074.003644641, sequence: 219 - clear  0.000000000, sequence: 0
 111 source 0 - assert 1595708075.003709620, sequence: 220 - clear  0.000000000, sequence: 0
 112 source 0 - assert 1595708076.003779580, sequence: 221 - clear  0.000000000, sequence: 0
 113 source 0 - assert 1595708077.003850580, sequence: 222 - clear  0.000000000, sequence: 0
 114 #+END_EXAMPLE
 115
 116 Note: For older Raspberry Pi models, it may be necessary to enable
 117 ~pps-gpio~ via modifications to ~/etc/modules~ (see [[https://www.raspberrypi.org/forums/viewtopic.php?p=757747#p757747][link]]).
 118
 119 ***** Enable GPS device
 120 The Ozzmaker BerryGPS-IMU makes NMEA sentences available via the
 121 serial "UART" device ~/dev/ttyAMA0~. If bluetooth has not been
 122 disabled, the Raspberry Pi OS automatically creates a software "UART"
 123 device at ~/dev/serial0~. See the "[[file:../setup/README.org::*Disable%20Bluetooth][Disable Bluetooth]]" section in the
 124 [[file:../setup/README.org][Main Setup]] Initial Startup procedure for instructions on how to
 125 disable bluetooth to free up ~/dev/ttyAMA0~ for use by ~gpsd~.
 126
 127 ***** Setup ~gpsd~
 128 See the "[[file:../location/README.org::*Setup%20~gpsd~][Setup ~gpsd~]]" subsection within the "Initial Startup" section
 129 of the Location Logging [[file:../location/README.org][~README.org~]] file. There is one additional
 130 change that must be made which is to add a ~/dev/pps0~ item to the
 131 ~DEVICES=~ line in ~/etc/default/gpsd~ like so:
 132
 133 : DEVICES="/dev/ttyAMA0 /dev/pps0"
 134
 135 ~/dev/ttyAMA0~ is where ~gpsd~ can get NMEA data from the GPS unit.
 136
 137 ~/dev/pps0~ is where ~gpsd~ can get a PPS signal.
 138
 139 As an example, the following lines will be present in
 140 ~/etc/default/gpsd~ if both location and time tracking are set up:
 141
 142 #+BEGIN_EXAMPLE
 143 START_DAEMON="true"
 144 USBAUTO="false"
 145 DEVICES="/dev/ttyAMA0 /dev/pps0"
 146 GPSD_OPTIONS="-n"
 147 #+END_EXAMPLE
 148
 149 Make sure to enable ~gpsd~ to automatically start as a system service.
 150
 151 : $ sudo systemctl enable gpsd
 152 : $ sudo systemctl start gpsd
 153
 154 ***** Setup ~chrony~
 155 Modify the configuration file for ~chrony~ at ~/etc/chrony/chrony.conf~.
 156
 157 : $ sudo nano /etc/chrony/chrony.conf
 158
 159 Add the following lines:
 160
 161 #+BEGIN_EXAMPLE
 162 # Get time from GPS (/dev/XXXX) and PPS (/dev/YYYY)
 163 #refclock SOCK /run/chrony.XXXX.sock refid GPS precision 1e-1 offset 0.0000
 164 #refclock SOCK /run/chrony.YYYY.sock refid PP precision 1e-7
 165 refclock SHM 0 refid GPS precision 1e-1 offset 0.0000 delay 0.2 stratum 1
 166 refclock SHM 1 refid PPS precision 1e-7 stratum 1
 167 #+END_EXAMPLE
 168
 169 Where
 170 - ~XXXX~ : the basename of the GPS device's serial port. In this guide
 171   it should be ~ttyAMA0~; other setups may use ~ttyS0~, ~ttyACM0~, or
 172   ~serial0~.
 173
 174 - ~YYYY~ : the basename of the PPS device's serial port. In this guide
 175   it should be ~pps0~.
 176
 177 Note: The ~refclock SOCK~ lines are left as comments in case ~gpsd~
 178 incorrectly maps the GPS and PPS data.
 179
 180 The following commands may be useful for testing ~gpsd~ and ~chrony~
 181 configurations.
 182 - ~chronyc sources -v~ : Shows time sources and associated accuracy
 183   information.
 184
 185 - ~chronyc tracking~ : Shows the current time difference between
 186   the reference clock and the system clock. Note: ~chrony~ gradually
 187   attempts to reduce the difference by changing the system clock.
 188
 189 - ~sudo chronyc makestep~ : Force ~chrony~ to set the system clock to
 190   match the reference clock immediately.
 191
 192 - ~sudo systemctl enable chrony~ : Enable automatic startup of
 193   ~chrony~ (Note: This command shouldn't be necessary since the act of
 194   installing ~chrony~ via ~sudo apt install chrony~ should
 195   automatically enable it).
 196
 197 - ~sudo systemctl stop chrony~ : Stop ~chrony~.
 198
 199 - ~sudo systemctl restart chrony~ : Restart ~chrony~.
 200
 201 - ~systemctl status chrony~ : Check status of ~chrony~ service.
 202
 203 - ~sudo ntpshmmon~ : Shows live output of data using the shared memory
 204   driver filled by ~gpsd~. ([[https://gpsd.gitlab.io/gpsd/gpsd-time-service-howto.html][ref]])
 205
 206 - ~sudo ipcs -m~ : Show live segments of the shared memory. ([[https://gpsd.gitlab.io/gpsd/gpsd-time-service-howto.html][ref]])
 207
 208 - ~sudo date -s '2020-07-07T00:00+0000'~ : Manually sets time to a
 209   string.
 210
 211 An example output of ~sudo chronyc sources -v~ will show something
 212 similar to this:
 213
 214 #+BEGIN_EXAMPLE
 215 pi@ninfacyzga-1-x:~ $ sudo chronyc sources -v
 216 210 Number of sources = 6
 217
 218   .-- Source mode  '^' = server, '=' = peer, '#' = local clock.
 219  / .- Source state '*' = current synced, '+' = combined , '-' = not combined,
 220 | /   '?' = unreachable, 'x' = time may be in error, '~' = time too variable.
 221 ||                                                 .- xxxx [ yyyy ] +/- zzzz
 222 ||      Reachability register (octal) -.           |  xxxx = adjusted offset,
 223 ||      Log2(Polling interval) --.      |          |  yyyy = measured offset,
 224 ||                                \     |          |  zzzz = estimated error.
 225 ||                                 |    |           \
 226 MS Name/IP address         Stratum Poll Reach LastRx Last sample
 227 ===============================================================================
 228 #- GPS                           1   4   377    21   +110ms[ +110ms] +/-  200ms
 229 #* PPS                           1   4   377    22  +2496ns[+3045ns] +/- 1000ns
 230 ^- vps-2d3ddab6.vps.ovh.ca       2   6   277    57  +1302us[+1304us] +/-  151ms
 231 ^? time.richiemcintosh.com       2   6     1    59  +2626us[+2628us] +/-   92ms
 232 ^- varuna.ga-group.nl            3   6   377    55  -3962us[-3960us] +/-  151ms
 233 ^- ntp3.junkemailfilter.com      2   6   377    58  -4561us[-4558us] +/-   80ms
 234 #+END_EXAMPLE
 235
 236 General references for the ~chrony.conf~ file are:
 237
 238 - The ~chrony~ ~4.0~ documentation. ([[https://chrony.tuxfamily.org/doc/4.0/chrony.conf.html][ref]])
 239
 240 - The ~gpsd~ documentation for communicating with ~chrony~. ([[https://gpsd.gitlab.io/gpsd/gpsd-time-service-howto.html#_feeding_chrony_from_gpsd][ref]])
 241
 242 - Setup guide for a USB GPS with ~gpsd~ and ~chrony~. ([[https://photobyte.org/raspberry-pi-stretch-gps-dongle-as-a-time-source-with-chrony-timedatectl/][ref]])
 243
 244 ***** Disable CPU power saving
 245 Power saving featurs of the Raspberry Pi Zero W may also be disabled
 246 in order to improve accuracy.
 247
 248 ****** Configure CPU ~scaling_governor~
 249 If additional precision is required, the PPS signal may be made more
 250 reliable at the cost of increasing CPU power by configuring the CPU to
 251 always run at maximum frequency.[fn:se_20180320_raspicpugov] This
 252 change can be performed by modifying the following file as root:
 253
 254 : /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
 255
 256 The file should consist of one line. Change
 257
 258 : ondemand
 259
 260 to
 261
 262 : performance
 263
 264 .
 265
 266 This change can be performed via the ~nano~ text editor by running the
 267 following commands:
 268
 269 : $ sudo su -
 270 : # nano /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
 271
 272 Additionally, in order to prevent the ~raspi-config~ init script from
 273 reverting this text file back to ~ondemand~ after a reboot, this
 274 script must be disabled via:
 275
 276 : $ sudo systemctl disable raspi-config
 277
 278 ****** Configure ~/boot/config.txt~
 279 Modify ~/boot/config.txt~ so that it contains these lines in order to
 280 disable power saving functions:
 281
 282 #+BEGIN_EXAMPLE
 283 # Disable power saving
 284 nohz=off
 285 #+END_EXAMPLE
 286
 287 [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;
 288
 289 ***** Configure another machine to use the time server
 290 A separate Debian machine may be configured to use the ~ninfacyzga-1~
 291 device as a GPS time server. This may be performed by:
 292
 293 1. Installing ~chrony~ onto the separate machine (e.g. hostname
 294    ~somedeb~):
 295
 296 #+begin_example
 297 somedeb:$ sudo apt update && sudo apt upgrade
 298 somedeb:$ sudo apt install chrony
 299 #+end_example
 300
 301 2. Modifying the ~chrony.conf~ file:
 302
 303   : somedeb:$ emacs /etc/chrony/chrony.conf
 304
 305   - Add the following lines to the end of this configuration file,
 306     substituting ~ninfacyzga-1-x~ with the hostname or IP address
 307     chosen for the ~ninfacyzga-1~ device:
 308
 309 #+begin_example
 310 # Use ninfacyzga-1-x if available
 311 server ninfacyzga-1-x iburst prefer minpoll 2 maxpoll 4
 312 #+end_example
 313
 314 3. Restart the ~chrony~ service.
 315
 316   : somedeb:$ sudo systemctl restart chrony
 317
 318 4. Verify that ~ninfacyzga-1-x~ is being used by ~chrony~
 319
 320 #+begin_example
 321 somedeb:$ chronyc sources
 322 MS Name/IP address         Stratum Poll Reach LastRx Last sample
 323 ===============================================================================
 324 ^? pugot.canonical.com           2   6   377    11  -2172us[-2209us] +/-  115ms
 325 ^? prod-ntp-5.ntp4.ps5.cano>     2   6   377     9  -4169us[-4206us] +/-   88ms
 326 ^? prod-ntp-4.ntp1.ps5.cano>     2   6   377    10  -2758us[-2795us] +/-   88ms
 327 ^? prod-ntp-3.ntp1.ps5.cano>     2   6   377     5  -6473us[-6510us] +/-   87ms
 328 ^? mail.novg.net                 2   6   377    11  -6099us[-6136us] +/-  125ms
 329 ^? ntp1a.versadns.com            1   6   377     6  -2006us[-2043us] +/-   40ms
 330 ^? 2602:fde5:2a::12              1   6   377    11  -2200us[-2237us] +/-   49ms
 331 ^? 2001:da8:9000::130            1   6   377    15  -2372us[-2409us] +/-  102ms
 332 ^* ninfacyzga-1-x.lan            2   4   377    14  -1686us[-1724us] +/- 2971us
 333 ^- brazil.time.system76.com      2   6   377    17  -4738us[-4775us] +/-  103ms
 334 ^- ohio.time.system76.com        2   6   377    15   +320us[ +283us] +/-   58ms
 335 ^- oregon.time.system76.com      2   6   377    19  -5845us[-5882us] +/-   30ms
 336 ^- paris.time.system76.com       2   6   377    19  -4531us[-4568us] +/-   92ms
 337 ^- virginia.time.system76.c>     2   6   377    15  -6607us[-6644us] +/-   51ms
 338 #+end_example
 339
 340   The ~*~ in the ~^*~ symbol at the start of the line containing
 341   ~ninfacyzga-1-x~ indicates that ~ninfacyzga-1-x~ is being used to
 342   set the system clock of ~somedeb~.
 343
 344 *** Normal Startup
 345 *** Normal Operation
 346 *** Normal Shutdown
 347 *** Unscheduled Shutdown
 348 ** Appendix A
 349 *** Example ~chrony.conf~ for ~chrony~
 350 For Raspberry Pi OS, the configuration file should be installed at
 351 ~/etc/chrony/chrony.conf~.
 352
 353 #+BEGIN_EXAMPLE
 354 # Welcome to the chrony configuration file. See chrony.conf(5) for more
 355 # information about usuable directives.
 356 pool 2.debian.pool.ntp.org iburst
 357
 358 # This directive specify the location of the file containing ID/key pairs for
 359 # NTP authentication.
 360 keyfile /etc/chrony/chrony.keys
 361
 362 # This directive specify the file into which chronyd will store the rate
 363 # information.
 364 driftfile /var/lib/chrony/chrony.drift
 365
 366 # Uncomment the following line to turn logging on.
 367 #log tracking measurements statistics
 368
 369 # Log files location.
 370 logdir /var/log/chrony
 371
 372 # Stop bad estimates upsetting machine clock.
 373 maxupdateskew 100.0
 374
 375 # This directive enables kernel synchronisation (every 11 minutes) of the
 376 # real-time clock. Note that it can’t be used along with the 'rtcfile' directive.
 377 rtcsync
 378
 379 # Step the system clock instead of slewing it if the adjustment is larger than
 380 # one second, but only in the first three clock updates.
 381 makestep 1 3
 382
 383 # Get time from GPS (/dev/ttyAMA0) and PPS (/dev/pps0)
 384 #refclock SOCK /run/chrony.ttyAMA0.sock refid GPS precision 1e-1 offset 0.0000
 385 #refclock SOCK /run/chrony.pps0.sock refid PP precision 1e-7
 386 refclock SHM 0 refid GPS precision 1e-1 offset 0.0000 delay 0.2 stratum 1
 387 refclock SHM 1 refid PPS precision 1e-7 stratum 1
 388 #+END_EXAMPLE
 389