NTP timing details

The Raspberry Shake’s timestamping is based on NTP, where the NTP daemon program governs the local Raspberry Pi computer clock on a permanent basis, assuming a connection to the Internet.

Case 0 (normal mode of operation): When the Raspberry Shake does have a connection to an NTP server at boot-up

The computer clock will be properly set and the NTP daemon started. The NTP daemon keeps the computer clock in sync with real time over all time, constantly making tiny adjustments that are hardly noticable. It does not do something like wake up every so often to check the clock and reset it if necessary. All you really need to know is that if the unit is connected to the internet, and the NTP daemon has a connection to an NTP server, the clock will remain in sync within a few milliseconds of accuracy at all times. But here are some more details:

Once the system is started, the program responsible for timestamping the actual data packets reads the local Raspberry Pi clock, using this time to stamp the actual data packets delivered by the micro-chip for onward forwarding.

During ongoing data processing, constant adjustments between the data packet processing program and the local clock are maintained, guaranteeing that any data sample will be within one sample interval of time.

For the different types of Raspberry Shakes, this means the timestamps will be within a margin of error based on the instrument’s sample rate, defined for each as:

  • The original Raspberry Shake (1D) - (data delivered @ 50Hz) - 20 Msecs
  • Raspberry Shake 3D, 4D and Raspberry Jam - (data delivered @ 100Hz) - 10 Msecs

Some things to keep in mind:

  • This accuracy very much depends on NTP maintaining access to the Internet to keep the local Raspberry Pi clock as close to real-time as possible. That is to say that timing is only good as NTP’s ability to govern the local clock itself.
  • After the NTP daemon has been running for a week, it has “learned” how the local Raspberry Pi clock drifts and becomes very good at maintaining good time even when not connected to the Internet for long periods of time. (of course, this assumes conditions affecting clock drift remain mostly constant when not connected to an NTP server).

Case 1: No Internet connection at startup

When the Raspberry Shake starts, the computer clock will be set to the same time as when it was last powered down, either one minute ago (in case of a simple reboot command), or many months ago (in case of receiving the Raspberry Shake for the first time, for example).

If an NTP server is not available, the timing will start incorrect and will remain incorrect until an internet connection is found and the Raspberry Shake rebooted. When the computer time is very much different from real time, the computer must be rebooted in order for NTP to reset the clock successfully, i.e., resetting the clock can only happen during the computer’s boot-up sequence. Please note: this is a Raspberry Pi feature, not a Shake feature.

Data will still flow locally and use the system time for time stamping (It always uses the computer clock, whether NTP is running or not. The difference is if the clock disciplined by NTP). If there is no NTP, however, Raspberry Shake will recognize that the timing quality has been compromised and will not stream the data to the community server.

If at some later time an internet connection is detected, the unit will reboot. After reboot, NTP timing will behave as described above in Case 0. Note: internet detection and system reboot is automatic, i.e., it is not necessary for the end-user to manage this state change themselves.

Note

This also applies to: stand-alone mode of operation (see I have no Internet Connection. Will my Shake work?) where the unit is installed in the field with no GPS antenna and no Internet

Case 2: Connection to NTP lost for some time

If connection to an NTP server is lost for some time, timestamping will drift exactly in step with the drift of the local Raspberry Pi clock itself and the NTP client will continue to govern the local Raspberry Pi clock according to what it has learned over time in terms of its specific drift rate, keeping relatively good time

When an Internet connection is restored, and NTP makes a large adjustment to the local Raspberry Pi clock (large defined as >= one sample interval of time), the data processing program will do a hard reset of the data packet timestamp, thus forcing a timestamp re-sync with the local clock. This will necessarily result in a time-tear, either a gap or an overlap, depending on the direction of drift, which will be reported at /opt/log/odf_SL_plugin.info.

We commonly are asked, how much drift can one expect when there is no external clock that can be referenced to govern the shake computer’s clock? Unknown. The Raspberry Pi clock is governed by a 20 ppm crystal, so ~2 seconds/ day.

Case 3: Connecting a GPS module to the computer via USB

This is done also in conjunction with NTP, where:

  • the GPS module sends a PPS to the computer across some hardware channel
  • a GPS daemon, gpsd, receives the PPS command, processes it and sets a time inside of shared memory (RAM)
  • the NTP daemon, in the meantime, has been configured to query the same location in shared memory to retrieve the time and set the clock and to keep it in sync, just as it does when querying an NTP server

So, to the end-user, there is no difference in terms of using the NTP daemon whether connecting to an NTP server, or to shared memory (which is being updated by a PPS generated by an attached GPS module). The only difference is the NTP configuration file.

If either or both situations can happen, (that an NTP server might be available, and / or that a GPS module is attached), it is also standard to configure NTP to retrieve its time from both the GPS PPS and an NTP server as a fallback. This is desirable in the case when the GPS module may lose contact with the satellite for a time, where NTP can then fall back to using an NTP server.

ver.9 added the functionality needed to use the PPS from an attached GPS module (where the user will only be required to do the physical attachment of the module).