doc(time):Create README for time server setup

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

* Time 
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-07-25T19:34Z~
** Development Task list
*** Set up prototype unit
**** Solder wire for PPS signal
**** 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~.
*** Document prototype unit
** Narrative
The ~ninfacyzga-01~ device is equipped with an Ozzmaker BerryGPS-IMU
module which provides time and location data to ~gpsd~. The time is
provided by GPS satellites which themselves are [[https://science.nasa.gov/science-news/science-at-nasa/2002/08apr_atomicclock/][equipped]] 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.
** 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
in order to enable ~gpsd~ to read the PPS signal for forwarding to
~ntp~.

**** Install Software
Run the following command to install the required packages.
: $ sudo apt install usbmount eject gpsd gpsd-clients python-gps pps-tools ntp

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/tty???~ will
provide the raw GPS module data.

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