From: Harlan Stenn Date: Wed, 14 May 2003 00:21:21 +0000 (-0400) Subject: Documentation updates from Dave Mills X-Git-Tag: NTP_4_1_80_RC1~25 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=eaf2dd0fa5d227db5ac64fbbd0833e23f77c8abf;p=thirdparty%2Fntp.git Documentation updates from Dave Mills bk: 3ec18c01R6xydihWV1XlBkLfECrZBg --- diff --git a/html/drivers/driver36.html b/html/drivers/driver36.html index b5139016b7..95b94ff38e 100644 --- a/html/drivers/driver36.html +++ b/html/drivers/driver36.html @@ -27,15 +27,15 @@

Program Architecture

As in the original program, the clock discipline is modelled as a Markov process, with probabilistic state transitions corresponding to a conventional clock and the probabilities of received decimal digits. The result is a performance level which results in very high accuracy and reliability, even under conditions when the minute beep of the signal, normally its most prominent feature, can barely be detected by ear with a communications receiver.

The analog audio signal from the shortwave radio is sampled at 8000 Hz and converted to digital representation. The 1000/1200-Hz pulses and 100-Hz subcarrier are first separated using two IIR filters, a 600-Hz bandpass filter centered on 1100 Hz and a 150-Hz lowpass filter. The minute sync pulse is extracted using a 800-ms synchronous matched filter and pulse grooming logic which discriminates between WWV and WWVH signals and noise. The second sync pulse is extracted using a 5-ms FIR matched filter and 8000-stage comb filter.

-

The phase of the 100-Hz subcarrier relative to the second sync pulse is fixed at the transmitter; however, the audio highpass filter in most radios affects the phase response at 100 Hz in unpredictable ways. The driver adjusts for each radio using two 170-ms synchronous matched filters. The I (in-phase) filter is used to demodulate the subcarrier envelope, while the Q (quadrature-phase) filter is used in a tracking loop to discipline the codec sample clock and thus the demodulator phase.

+

The phase of the 100-Hz subcarrier relative to the second sync pulse is fixed at the transmitter; however, the audio stage in many radios affects the phase response at 100 Hz in unpredictable ways. The driver adjusts for each radio using two 170-ms synchronous matched filters. The I (in-phase) filter is used to demodulate the subcarrier envelope, while the Q (quadrature-phase) filter is used in a tracking loop to discipline the codec sample clock and thus the demodulator phase.

The data bit probabilities are determined from the subcarrier envelope using a threshold-corrected slicer. The averaged envelope amplitude 30 ms from the beginning of the second establishes the minimum (noise floor) value, while the amplitude 200 ms from the beginning establishes the maximum (signal peak) value. The slice level is midway between these two values. The negative-going envelope transition at the slice level establishes the length of the data pulse, which in turn establish probabilities for binary zero (P0) and binary one (P1). The data values are established by linear interpolation between the pulse lengths for P0 (-1) and P1 (+1). If the driver has not synchronized to the minute pulse, or if the data bit amplitude, signal/noise ratio (SNR) or length are below thresholds, the bit is considered invalid and the data value is ignored.

-

The difference between the P1 and P0 data values, or likelihood, for each data bit is exponentially averaged in a set of 60 accumulators, one for each second, to determine the semi-static miscellaneous bits, such as DST indicator, leap second warning and DUT1 correction. In this design, a data average value larger than a positive threshold is interpreted as a hit on one and a value smaller than a negative threshold as a hit on zero. Values between the two thresholds, which can occur due to signal fades or loss of signal, are interpreted as a miss, and result in no change of indication.

+

The difference between the P1 and P0 data values, or likelihood, for each data bit is exponentially averaged in a set of 60 accumulators, one for each second, to determine the semi-static miscellaneous bits, such as DST indicator, leap second warning and DUT1 correction. In this design a data average value larger than a positive threshold is interpreted as +1 (hit) and a value smaller than a negative threshold as a -1 (miss). Values between the two thresholds, which can occur due to signal fades or loss of signal, are interpreted as an erasure and result in no change of indication.

The BCD digit in each digit position of the timecode is represented as four data bits, all of which must be valid for the digit itself to be considered valid. If so, the bits are correlated with the bits corresponding to each of the valid decimal digits in this position. If the digit is invalid, the correlated value for all digits in this position is assumed zero. In either case, the values for all digits are exponentially averaged in a likelihood vector associated with this position. The digit associated with the maximum over all averaged values then becomes the maximum likelihood selection for this position and the ratio of the maximum over the next lower value becomes the likelihood ratio.

The decoding matrix contains nine row vectors, one for each digit position. Each row vector includes the maximum likelihood digit, likelihood vector and other related data. The maximum likelihood digit for each of the nine digit positions becomes the maximum likelihood time of the century. A built-in transition function implements a conventional clock with decimal digits that count the minutes, hours, days and years, as corrected for leap seconds and leap years. The counting operation also rotates the likelihood vector corresponding to each digit as it advances. Thus, once the clock is set, each clock digit should correspond to the maximum likelihood digit as transmitted.

Each row of the decoding matrix also includes a compare counter and the difference (modulo the radix) between the current clock digit and most recently determined maximum likelihood digit. If a digit likelihood exceeds the decision level and the difference is constant for a number of successive minutes in any row, the maximum likelihood digit replaces the clock digit in that row. When this condition is true for all rows and the second epoch has been reliably determined, the clock is set (or verified if it has already been set) and delivers correct time to the integral second. The fraction within the second is derived from the logical master clock, which runs at 8000 Hz and drives all system timing functions.

The logical master clock is derived from the audio codec clock. Its frequency is disciplined by a frequency-lock loop (FLL) which operates independently of the data recovery functions. At averaging intervals determined by the measured jitter, the frequency error is calculated as the difference between the most recent and the current second epoch divided by the interval. The sample clock frequency is then corrected by this amount. When first started, the frequency averaging interval is eight seconds, in order to compensate for intrinsic codec clock frequency offsets up to 125 PPM. Under most conditions, the averaging interval doubles in stages from the initial value to over 1000 seconds, which results in an ultimate frequency precision of 0.125 PPM, or about 11 ms/day.

It is important that the logical clock frequency is stable and accurately determined, since in most applications the shortwave radio will be tuned to a fixed frequency where WWV or WWVH signals are not available throughout the day. In addition, in some parts of the US, especially on the west coast, signals from either or both WWV and WWVH may be available at different times or even at the same time. Since the propagation times from either station are almost always different, each station must be reliably identified before attempting to set the clock.

-

Station identification uses the 800-ms minute pulse transmitted by each station. In the acquisition phase the entire minute is searched using both the WWV and WWVH using matched filters and a pulse gate discriminator similar to that found in radar acquisition and tracking receivers. The peak amplitude found determines a range gate and window where the next pulse is expected to be found. The minute is scanned again to verify the peak is indeed in the window and with acceptable amplitude, SNR and jitter. At this point the receiver begins to track the second sync pulse and operate as above until the clock is set. Once the minute is synchronized, the range gate is fixed and only energy within the window is considered for the minute sync pulse.

+

Station identification uses the 800-ms minute pulse transmitted by each station. In the acquisition phase the entire minute is searched using both the WWV and WWVH matched filters and a pulse gate discriminator similar to that found in radar acquisition and tracking receivers. The peak amplitude found determines a range gate and window where the next pulse is expected to be found. The minute is scanned again to verify the peak is indeed in the window and with acceptable amplitude, SNR and jitter. At this point the receiver begins to track the second sync pulse and operate as above until the clock is set. Once the minute is synchronized, the range gate is fixed and only energy within the window is considered for the minute sync pulse.

It is very important to be able to reliably discriminate between very weak signals in noise and noise alone. The driver very aggresively soaks up every scrap of signal information, but has to be careful to avoid making pseudo-sense of noise alone. The signal quality metric depends on the minute pulse amplitude and SNR together with the data subcarrier amplitude and SNR. If all four values are above defined thresholds a hit is declared, otherwise a miss. The number of hits declared in the last six intervals is the high order bits of the metric value, while the current minute sync pulse amplitude is the low order bits. The metric value is represented on a scale from zero to 100. This is used as a quality indicator and reported in the timecode and also for the autotune function described below.

Performance

It is the intent of the design that the accuracy and stability of the indicated time be limited only by the characteristics of the ionospheric propagation medium. Conventional wisdom is that synchronization via the HF medium is good only to a millisecond under the best propagation conditions. The performance of the NTP daemon disciplined by the driver is clearly better than this, even under marginal conditions. Ordinarily, with marginal to good signals and a frequency averaging interval of 1024 s, the frequency is stabilized within 0.1 PPM and the time within 125 ms. The frequency stability characteristic is highly important, since the clock may have to free-run for several hours before reacquiring the WWV/H signal.

@@ -49,7 +49,7 @@

It may happen as the hours progress around the clock that WWV and WWVH signals may appear alone, together or not at all. When the driver is first started, the NTP reference identifier appears as NONE. When the driver has mitigated which station and frequency is best, it sets the reference identifier to the string WVf for WWV and WHf for WWVH, where f is the frequency in megahertz. If the propagation delays have been properly set with the fudge time1 (WWV) and fudge time2 (WWVH) commands in the configuration file, handover from one station to the other is seamless.

Once the clock has been set for the first time, it will appear reachable and selectable to discipline the system clock, even if the broadcast signal fades to obscurity. A consequence of this design is that, once the clock is set, the time and frequency are disciplined only by the second sync pulse and the clock digits themselves are driven by the clock state machine. If for some reason the state machine drifts to the wrong second, it would never reresynchronize. To protect against this most unlikely situation, if after two days with no signals, the clock is considered unset and resumes the synchronization procedure from the beginning.

However, as long as the clock has once been set correctly and allowed to converge on the intrinsic codec clock frequency, it will continue to read correctly after a period of signal loss. Assuming the clock frequency can be disciplined within 1 PPM, it can coast without signals for several days without exceeding that NTP step threshold of 128 ms. During such periods the root dispersion increases at 5 ms per second, which makes the driver appears less likely for selection as time goes on. Eventually, when the dispersion due all causes exceeds 1 s, it is no longer suitable for synchronization at all.

-

To work well, the driver needs a communications receiver with good audio response at 100 Hz. Most shortwave and communications receivers roll off the audio response below 250 Hz, so this can be a problem, especially with receivers using DSP technology, since DSP filters can have very fast rolloff outside the passband. Some DSP transceivers, in particular the ICOM 775, have a programmable low frequency cutoff which can be set as low as 80 Hz. However, this particular radio has a strong low frequency buzz at about 10 Hz which appears in the audio output and can affect data recovery under marginal conditions. Although not tested, it would seem very likely that a cheap shortwave receiver could function just as well as an expensive communications receiver.

+

To work well, the driver needs a shortwave receiver with good audio response at 100 Hz. Most shortwave and communications receivers roll off the audio response below 250 Hz, so this can be a problem, especially with receivers using DSP technology, since DSP filters can have very fast rolloff outside the passband. Some DSP transceivers, in particular the ICOM 775, have a programmable low frequency cutoff which can be set as low as 80 Hz. However, this particular radio has a strong low frequency buzz at about 10 Hz which appears in the audio output and can affect data recovery under marginal conditions. Although not tested, it would seem very likely that a cheap shortwave receiver could function just as well as an expensive communications receiver.

Autotune

The driver includes provisions to automatically tune the radio in response to changing radio propagation conditions throughout the day and night. The radio interface is compatible with the ICOM CI-V standard, which is a bidirectional serial bus operating at TTL levels. The bus can be connected to a serial port using a level converter such as the CT-17.

Each ICOM radio is assigned a unique 8-bit ID select code, usually expressed in hex format. To activate the CI-V interface, the mode keyword of the server configuration command specifies a nonzero select code in decimal format. A table of ID select codes for the known ICOM radios is given below. Since all ICOM select codes are less than 128, the high order bit of the code is used by the driver to specify the baud rate. If this bit is not set, the rate is 9600 bps for the newer radios; if set, the rate is 1200 bps for the older radios. A missing mode keyword or a zero argument leaves the interface disabled.

@@ -85,8 +85,7 @@
0x0002
Second sync. Set when the decoder has acquired the second sync pulse and within 125 ms of the correct phase.
0x0004 -
Minute unit sync. Set when the decoder has reliably determined the unit digit of the minute. -
0x0008 +
digit sync. Set when the decoder has reliably determined at least one digit of the minute.
0x0008
Clock set. Set when the decoder has reliably determined all nine digits of the timecode and is selectable to discipline the system clock.

With debugging enabled the driver produces messages in the following formats:

@@ -107,9 +106,9 @@

wwv4 8 010f 5772 10 9 9 0 6 4615 6.1

Here the driver has previousl set or verified the clock. It has just decoded the digit preceding second 8 of the minute. The digit radix is 10, the current clock and maximum likelihood digits are both 9, the likelihood is well above the threshold (1000) and the likelihood function well above threshold (3.0 dB). Short of a hugely unlikely probability conspiracy, the clock digit is most certainly a 9.

Format wwv2 messages are produced at each master oscillator frequency update, which starts at 8 s, but eventually climbs to 1024 s. They show the progress of the algorithm as it refines the frequency measurement to a precision of 0.1 PPM.

-

wwv2 ss stat sigl epoch jitr avinc avint wiggle freq

-

where ss, stat and sigl are as above, epoch the codec clock at the seconds epoch, jitr the jitter counter, avinc the increment counter, avint the averaging interval, phase the phase correction and freq the current frequency (PPM). An example is:

-

wwv2 22 030f 5795 7433 0 3 256 0 49.0

+

wwv2 ss stat sigl epoch maxrun jitr avinc avint wiggle freq

+

where ss, stat and sigl are as above, epoch the codec clock at the seconds epoch, maxrun the maximum run length, jitr the jitter counter, avinc the increment counter, avint the averaging interval, phase the phase correction and freq the current frequency (PPM). An example is:

+

wwv2 22 030f 5795 7433 223 0 3 256 0 49.0

Here the driver has acquired minute and second sync and set the clock. The averaging interval has increased to 256 s on the way to 1024 s, has stayed at that interval for 3 averaging intervals and the current frequency is 49.0 PPM.

If the CI-V interface for ICOM radios is active, a debug level greater than 1 will produce a trace of the CI-V command and response messages. Interpretation of these messages requires knowledge of the CI-V protocol, which is beyond the scope of this document.

Monitor Data

@@ -137,39 +136,31 @@ The fields beginning with year and extending through dut are decoded from the received data and are in fixed-length format. The agc and lset fields, as well as the following driver-dependent fields, are in variable-length format.
s -
The sync indicator is initially ? before the clock is set, but turns to space when all nine digits of the timecode are correctly set. -
q -
The quality character is a four-bit hexadecimal code showing which alarms have been raised. Each bit is associated with a specific alarm condition according to the following: -
+
The sync indicator is initially ? before the clock is set, but turns to space when all nine digits of the timecode are correctly set and the decoder is synchronized to the station within 125 ms.
q +
The quality character is a four-bit hexadecimal code showing which alarms have been raised. Each bit is associated with a specific alarm condition according to the following:
0x8 -
Sync alarm. The decoder may not be in correct second or minute phase relative to the transmitter. -
0x4 +
Sync alarm. The decoder is not synchronized to the station within 125 ms.
0x4
Error alarm. More than 30 data bit errors occurred in the last minute.
0x2
Symbol alarm. The probability of correct decoding for a digit or miscellaneous bit has fallen below the threshold.
0x1
Decoding alarm. A maximum likelihood digit fails to agree with the current associated clock digit. -
- It is important to note that one or more of the above alarms does not necessarily indicate a clock error, but only that the decoder has detected a condition that may in future result in an error. -
yyyy ddd hh:mm:ss -
The timecode format itself is self explanatory. Since the driver latches the on-time epoch directly from the second sync pulse, the fraction is always zero. Although the transmitted timecode includes only the year of century, the Gregorian year is augmented by 2000. -
l +
It is important to note that one or more of the above alarms does not necessarily indicate a clock error, but only that the decoder has detected a condition that may eventually result in an error.
yyyy ddd hh:mm:ss +
The timecode format itself is self explanatory. Since the driver latches the on-time epoch directly from the second sync pulse, the seconds fraction is always zero. Although the transmitted timecode includes only the year of century, the Gregorian year is augmented by 2000.
l
The leap second warning is normally space, but changes to L if a leap second is to occur at the end of the month of June or December.
d
The DST state is S or D when standard time or daylight time is in effect, respectively. The state is I or O when daylight time is about to go into effect or out of effect, respectively.
dut
The DUT sign and magnitude shows the current UT1 offset relative to the displayed UTC time, in deciseconds.
lset -
Before the clock is set, the interval since last set is the number of minutes since the driver was started; after the clock is set, this is number of minutes since the time was last verified relative to the broadcast signal. -
agc +
Before the clock is set, the interval since last set is the number of minutes since the driver was started; after the clock is set, this is number of minutes since the decoder was last synchronized to the station within 125 ms.
agc
The audio gain shows the current codec gain setting in the range 0 to 255. Ordinarily, the receiver audio gain control or IRIG level control should be set for a value midway in this range.
ident -
The station identifier shows the station, C for WWV or H for WWVH, and frequency being tracked. If neither station is heard on any frequency, the station identifier shows X. +
The station identifier shows the station, C for WWV or H for WWVH, and frequency being tracked. If neither station is heard on any frequency, the reference identifier shows NONE.
metric
The signal metric described above from 0 (no signal) to 100 (best).
errs -
The bit error counter is useful to determine the quality of the data signal received in the most recent minute. It is normal to drop a couple of data bits under good signal conditions and increasing numbers as conditions worsen. While the decoder performs moderately well even with half the bits are in error in any minute, usually by that point the metric drops below threshold and signals from that station are ignored. -
freq +
The bit error counter is useful to determine the quality of the data signal received in the most recent minute. It is normal to drop a couple of data bits under good signal conditions and increasing numbers as conditions worsen. While the decoder performs moderately well even with half the bits are in error in any minute, usually by that point the metric drops below threshold and the decoder switches to a different frequency.
freq
The frequency offset is the current estimate of the codec frequency offset to within 0.1 PPM. This may wander a bit over the day due to local temperature fluctuations and propagation conditions.
avgt
The averaging time is the interval between frequency updates in powers of two to a maximum of 1024 s. Attainment of the maximum indicates the driver is operating at the best possible resolution in time and frequency. diff --git a/html/miscopt.html b/html/miscopt.html index 76db9fc8b9..13f8981c2e 100644 --- a/html/miscopt.html +++ b/html/miscopt.html @@ -12,7 +12,7 @@

Miscellaneous Options

giffrom Pogo, Walt Kelly

We have three, now looking for more.

-

Last update: 00:50 UTC Sunday, February 09, 2003

+

Last update: 01:50 UTC Friday, May 02, 2003


Related Links

@@ -23,11 +23,11 @@
calldelay delay
This option controls the delay in seconds between the first and second packets sent in burst or iburst mode to allow additional time for a modem or ISDN call to complete.
driftfile driftfile -
This command specifies the complete path and name of the file used to record the frequency of the local clock oscillator. This is the same operation as the -f command linke option. If the file exists, it is read at startup in order to set the initial frequency and then updated once per hour with the current frequency computed by the daemon. If the file name is specified, but the file itself does not exist, the starts with an initial frequency of zero and creates the file when writing it for the first time. If this command is not given, the daemon will always start with an initial frequency of zero.

The file format consists of a single line containing a single floating point number, which records the frequency offset measured in parts-per-million (PPM). The file is updated by first writing the current drift value into a temporary file and then renaming this file to replace the old version. This implies that ntpd must have write permission for the directory the drift file is located in, and that file system links, symbolic or otherwise, should be avoided.

+
This command specifies the complete path and name of the file used to record the frequency of the local clock oscillator. This is the same operation as the -f command linke option. If the file exists, it is read at startup in order to set the initial frequency and then updated once per hour with the current frequency computed by the daemon. If the file name is specified, but the file itself does not exist, the starts with an initial frequency of zero and creates the file when writing it for the first time. If this command is not given, the daemon will always start with an initial frequency of zero. +

The file format consists of a single line containing a single floating point number, which records the frequency offset measured in parts-per-million (PPM). The file is updated by first writing the current drift value into a temporary file and then renaming this file to replace the old version. This implies that ntpd must have write permission for the directory the drift file is located in, and that file system links, symbolic or otherwise, should be avoided.

enable [ auth | bclient | calibrate | kernel | monitor | ntp | pps | stats]
disable [ auth | bclient | calibrate | kernel | monitor | ntp | pps | stats ]
Provides a way to enable or disable various system options. Flags not mentioned are unaffected. Note that all of these flags can be controlled remotely using the ntpdc utility program. -
auth
Enables the server to synchronize with unconfigured peers only if the peer has been correctly authenticated using either public key or private key cryptography. The default for this flag is enable. @@ -59,7 +59,7 @@

This command specifies the location of an alternate log file to be used instead of the default system syslog facility. This is the same operation as the -l command line option.

setvar variable [default]
This command adds an additional system variable. These variables can be used to distribute additional information such as the access policy. If the variable of the form name = value is followed by the default keyword, the variable will be listed as part of the default system variables (ntpq rv command). These additional variables serve informational purposes only. They are not related to the protocol other that they can be listed. The known protocol variables will always override any variables defined via the setvar mechanism. There are three special variables that contain the names of all variable of the same group. The sys_var_list holds the names of all system variables. The peer_var_list holds the names of all peer variables and the clock_var_list holds the names of the reference clock variables. -
tinker [ allan allan | dispersion dispersion | huffpuff | huffpuff | panic panic | step step | stepout stepout ] +
tinker [ allan allan | dispersion dispersion | freq freq | huffpuff | huffpuff | panic panic | step step | stepout stepout ]
This command can be used to alter several system variables in very exceptional circumstances. It should occur in the configuration file before any other configuration options. The default values of these variables have been carefully optimized for a wide range of network speeds and reliability expectations. In general, they interact in intricate ways that are hard to predict and some combinations can result in some very nasty behavior. Very rarely is it necessary to change the default values; but, some folks can't resist twisting the knobs anyway and this command is for them. Emphasis added: twisters are on their own and can expect no help from the support group.

The variables operate as follows:

@@ -67,6 +67,8 @@
The argument becomes the new value for the minimum Allan intercept, which is a parameter of the PLL/FLL clock discipline algorithm. The value in log2 seconds defaults to 7 (1024 s), which is also the lower limit.
dispersion dispersion
The argument becomes the new value for the dispersion increase rate, normally .000015 s/s. +
freq freq +
The argument becomes the initial value of the frequency offset in parts-per-million. This overrides the value in the frequency file, if present, and avoids the initial training state if it is not.
huffpuff huffpuff
The argument becomes the new value for the experimental huff-n'-puff filter span, which determines the most recent interval the algorithm will search for a minimum delay. The lower limit is 900 s (15 m), but a more reasonable value is 7200 (2 hours). There is no default, since the filter is not enabled unless this command is given.
panic panic diff --git a/html/scripts/footer.txt b/html/scripts/footer.txt index b8726dc2eb..7fc6dd87a9 100644 --- a/html/scripts/footer.txt +++ b/html/scripts/footer.txt @@ -3,6 +3,5 @@ document.write("\ gif\ Home Page\ gif\ -\ -David L. Mills <mills@udel.edu>\ +Contacts\ ") \ No newline at end of file