fix(exec/bklog):Add kill switch if `while read` returns empty buffer

[EVA-2020-02.git] / doc / time / README.org

#+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-18T00:11Z~

** Narrative
The ~ninfacyzga-01~ device is equipped with an Ozzmaker BerryGPS-IMU
module which provides time and location data to ~gpsd~ and ~chrony~. 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
calculates its position in space using a General Relativity
calculation that uses the small variations in the time stamps received
from each satellite. This means that ~gpsd~ may be used to set the
system clock without a need for an internet connection to a default
Debian time server; ~ninfacyzga-01~ can be its own time server.

[fn:nasa_20020408_atomicclock] Title:[[https://science.nasa.gov/science-news/science-at-nasa/2002/08apr_atomicclock/][Tick-Tock Atomic Clock]];
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:
2010-04-29

** Description
*** Hardware
Ozzmaker BerryGPS-IMU, Version 3 (see [[https://ozzmaker.com/berrygps-berrygps-imu-quick-start-guide/][ref]]).
*** Software
- [[https://www.raspberrypi.org/downloads/raspberry-pi-os/][Raspberry Pi OS]] : A GNU/Linux operating system derived from
  Debian 10. This procedure was developed with version ~August 2020~.

- [[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://chrony.tuxfamily.org/][~chrony~]] : A set of programs capable of continuously adjusting the
  system clock until it is synchronized with configurable time sources
  such as GPS and PPS data provided by ~gpsd~. ~chrony~ may be
  configured to act as an NTP time client or server. It uses the same
  protocol as ~ntp~ but is a GPLv2 implementation. This procedure was
  developed with ~chrony~ version ~3.4-4~.

** Operating Procedures
*** Initial Startup
**** 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").

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 ~chrony~.

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. ~chrony~ 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 ~chrony~ via a "shared
memory driver".

***** Install packages via ~apt~
Run the following command to install the required packages.
: $ sudo apt install gpsd gpsd-clients python-gps pps-tools chrony

***** 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]]:

: # Enable PPS on GPIO 18
: 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
$ sudo su -
# ppstest /dev/pps0
trying PPS source "/dev/pps0"
found PPS source "/dev/pps0"
ok, found 1 source(s), now start fetching data...
source 0 - assert 1595708074.003644641, sequence: 219 - clear  0.000000000, sequence: 0
source 0 - assert 1595708075.003709620, sequence: 220 - clear  0.000000000, sequence: 0
source 0 - assert 1595708076.003779580, sequence: 221 - clear  0.000000000, sequence: 0
source 0 - assert 1595708077.003850580, sequence: 222 - clear  0.000000000, sequence: 0
#+END_EXAMPLE

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:../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~.

***** Setup ~gpsd~
See the "[[file:../location/README.org::*Setup%20~gpsd~][Setup ~gpsd~]]" subsection within the "Initial Startup" section
of the Location Logging [[file:../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

Make sure to enable ~gpsd~ to automatically start as a system service.

: $ sudo systemctl enable gpsd
: $ sudo systemctl start gpsd

***** Setup ~chrony~
Modify the configuration file for ~chrony~ at ~/etc/chrony/chrony.conf~.

: $ sudo nano /etc/chrony/chrony.conf

Add the following lines:

#+BEGIN_EXAMPLE
# Get time from GPS (/dev/XXXX) and PPS (/dev/YYYY)
#refclock SOCK /run/chrony.XXXX.sock refid GPS precision 1e-1 offset 0.0000
#refclock SOCK /run/chrony.YYYY.sock refid PP precision 1e-7
refclock SHM 0 refid GPS precision 1e-1 offset 0.0000 delay 0.2 stratum 1
refclock SHM 1 refid PPS precision 1e-7 stratum 1
#+END_EXAMPLE

Where
- ~XXXX~ : the basename of the GPS device's serial port. In this guide
  it should be ~ttyAMA0~; other setups may use ~ttyS0~, ~ttyACM0~, or
  ~serial0~.

- ~YYYY~ : the basename of the PPS device's serial port. In this guide
  it should be ~pps0~.

Note: The ~refclock SOCK~ lines are left as comments in case ~gpsd~
incorrectly maps the GPS and PPS data.

The following commands may be useful for testing ~gpsd~ and ~chrony~
configurations.
- ~chronyc sources -v~ : Shows time sources and associated accuracy
  information.

- ~chronyc tracking~ : Shows the current time difference between
  the reference clock and the system clock. Note: ~chrony~ gradually
  attempts to reduce the difference by changing the system clock.

- ~sudo chronyc makestep~ : Force ~chrony~ to set the system clock to
  match the reference clock immediately.

- ~sudo systemctl enable chrony~ : Enable automatic startup of
  ~chrony~ (Note: This command shouldn't be necessary since the act of
  installing ~chrony~ via ~sudo apt install chrony~ should
  automatically enable it).

- ~sudo systemctl stop chrony~ : Stop ~chrony~.

- ~sudo systemctl restart chrony~ : Restart ~chrony~.

- ~systemctl status chrony~ : Check status of ~chrony~ service.

- ~sudo ntpshmmon~ : Shows live output of data using the shared memory
  driver filled by ~gpsd~. ([[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]])

- ~sudo date -s '2020-07-07T00:00+0000'~ : Manually sets time to a
  string.

An example output of ~sudo chronyc sources -v~ will show something
similar to this:

#+BEGIN_EXAMPLE
pi@ninfacyzga-1-x:~ $ sudo chronyc sources -v
210 Number of sources = 6

  .-- Source mode  '^' = server, '=' = peer, '#' = local clock.
 / .- Source state '*' = current synced, '+' = combined , '-' = not combined,
| /   '?' = unreachable, 'x' = time may be in error, '~' = time too variable.
||                                                 .- xxxx [ yyyy ] +/- zzzz
||      Reachability register (octal) -.           |  xxxx = adjusted offset,
||      Log2(Polling interval) --.      |          |  yyyy = measured offset,
||                                \     |          |  zzzz = estimated error.
||                                 |    |           \
MS Name/IP address         Stratum Poll Reach LastRx Last sample               
===============================================================================
#- GPS                           1   4   377    21   +110ms[ +110ms] +/-  200ms
#* PPS                           1   4   377    22  +2496ns[+3045ns] +/- 1000ns
^- vps-2d3ddab6.vps.ovh.ca       2   6   277    57  +1302us[+1304us] +/-  151ms
^? time.richiemcintosh.com       2   6     1    59  +2626us[+2628us] +/-   92ms
^- varuna.ga-group.nl            3   6   377    55  -3962us[-3960us] +/-  151ms
^- ntp3.junkemailfilter.com      2   6   377    58  -4561us[-4558us] +/-   80ms
#+END_EXAMPLE

General references for the ~chrony.conf~ file are:

- The ~chrony~ ~4.0~ documentation. ([[https://chrony.tuxfamily.org/doc/4.0/chrony.conf.html][ref]])

- The ~gpsd~ documentation for communicating with ~chrony~. ([[https://gpsd.gitlab.io/gpsd/gpsd-time-service-howto.html#_feeding_chrony_from_gpsd][ref]])

- 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]])

***** 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

: ondemand

to

: performance

.

This change can be performed via the ~nano~ text editor by running the
following commands:

: $ sudo su -
: # nano /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor

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:

: $ 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
# 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 ~chrony.conf~ for ~chrony~
For Raspberry Pi OS, the configuration file should be installed at
~/etc/chrony/chrony.conf~.

#+BEGIN_EXAMPLE
# Welcome to the chrony configuration file. See chrony.conf(5) for more
# information about usuable directives.
pool 2.debian.pool.ntp.org iburst

# This directive specify the location of the file containing ID/key pairs for
# NTP authentication.
keyfile /etc/chrony/chrony.keys

# This directive specify the file into which chronyd will store the rate
# information.
driftfile /var/lib/chrony/chrony.drift

# Uncomment the following line to turn logging on.
#log tracking measurements statistics

# Log files location.
logdir /var/log/chrony

# Stop bad estimates upsetting machine clock.
maxupdateskew 100.0

# This directive enables kernel synchronisation (every 11 minutes) of the
# real-time clock. Note that it can’t be used along with the 'rtcfile' directive.
rtcsync

# Step the system clock instead of slewing it if the adjustment is larger than
# one second, but only in the first three clock updates.
makestep 1 3

# Get time from GPS (/dev/ttyAMA0) and PPS (/dev/pps0)
#refclock SOCK /run/chrony.ttyAMA0.sock refid GPS precision 1e-1 offset 0.0000
#refclock SOCK /run/chrony.pps0.sock refid PP precision 1e-7
refclock SHM 0 refid GPS precision 1e-1 offset 0.0000 delay 0.2 stratum 1
refclock SHM 1 refid PPS precision 1e-7 stratum 1
#+END_EXAMPLE