Merge branch 'develop' into feature/time-server/EVA-2020-02

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

* Time Tracking
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: <http://www.pool.ntp.org/join.html>
#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 <http://support.ntp.org/bin/view/Support/AccessRestrictions>
# 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]]

** Narrative
The ~ninfacyzga-01~ device is equipped with an Ozzmaker BerryGPS-IMU
module which provides time and location data to ~gpsd~ and ~ntp~. 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
*** Software
This guide describes steps that may be used to convert a Raspberry Pi
into a time server using ~gpsd~.
** Operating Procedures
*** Initial Startup
**** Install Raspbian 10 (Buster) onto a Raspberry Pi Zero W.


**** Install Hardware
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.

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.

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

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

: dtoverlay=pps-gpio,gpiopin=18

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

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

: /etc/udev/rules.d/09-pps.rules

with the contents:

#+BEGIN_EXAMPLE
KERNEL=="ttyAMA0", SUBSYSTEM=="tty", DRIVER=="", OWNER=="root", GROUP=="tty", MODE=="0777", SYMLINK+="gps0"
#+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:

: pps-gpio

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,

#+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

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

As of 2020-07-25, using Raspbian Buster 10 with a BerryGPS-IMU v3,
~/etc/modules~ did not need to be modified.

***** 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)".

This can be performed by running the following command (shown in
script form for readability):

#+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;
#+END_EXAMPLE

*** Normal Startup
*** Normal Operation
*** Normal Shutdown
*** Unscheduled Shutdown