dfc(1)

NAME
dfc - keep machine exactly on time by receiving radio signals from an atom-clock broadcast

VERSION
1.1 (19/10/1995)

SYNOPSIS
dfc [-h] [-l device] [-t type] [-s speed] [-d] [-v] [-n path] [-a]

DESCRIPTION
Around the world there are several transmitters that are linked to an atom clock and are intended to keep clocks synchronised across the continent. For some of these transmitters small receivers can be bought that will feed the timing information into the computer. dfc is a utility to decode this information and thus keep the machine always on time, including winter- and summertime, leap seconds, etc. This way you will _never_ have to set the time of your machine again. The program will read the data through a serial line (see DEVICES below), decode it, and if it is a valid time, synchronize the kernel time at regular intervals. Synchronization should keep the PC clock within one second of the exact time (probably less).

OPTIONS

-h  show help.

-l device
    Name the serial device; default is /dev/dfc77 (which may be a symlink to the real device).

-n path
    The Unix socket at which dfc will communicate with others, to receive or send the exact time and statistics. Default is /tmp/.dfc.

-s speed
    The speed at which to communicate with the receiver. Default is 50 baud.

-t type
    A number that indicates the type of receiver installed. At the moment only 1 type is supported, numbered: 1 (this is here for upward compatibility)

-d  Increase debug level. Every -d will increase the debug level, and thus produce more junk on your screen.

-v  Print the version number and creator.

-a  Print all; when calling the running daemon, also print statistics after the time. It prints this information on a single line: - the last time the kernel time was synchronised (in time_t format, e.g. seconds since 1 Jan 1970); - the very first time the daemon synchronised with the atom-clock (also in time_t); - the number of received minutes; - the number of good minutes; - the number of times the daemon lost sync; - two characters, the first one showing either a 'W', 'S' or '-' for resp. wintertime, summertime or none. The second character announces the change of Winter and Summer time (one of the features of the DFC-77); - Finally a character that indicates if the primary or secondary transmitter is in use.

INSTALLATION
This program requires a patch in the kernel. First it creates an extra ioctl() call in the serial driver, to switch on the power to the device and time the intervals between pulses. The latter is necassary beacuse the select() call cannot return the time between pulses acurately, especially on heavily loaded machines. The serial interrupt routine is modified to count the jiffies between interrupts, thus getting a precise measurement. Also, the outgoing data stream is modified to reflect timeouts in the received bytes. To install the patch, go into your linux-kernel sources-directory, then apply this command:

patch -p1 -s < {path-of-dfc-source}/dfc77.patch

Recompile, install the kernel, reboot and you're ready to go. It does not affect normal operation of the serial devices. The program itself, dfc can be placed in /usr/bin, /sbin, /usr/local/bin or any other convenient place. It can be run by root or other any user; the latter has the disadvantage it cannot set the time in the kernel (but still produce accurate results anytime; see below). It is probably handiest to start it from rc.local at bootup.

RUNNING
When the program is run, it first tries to find out if there already is a dfc running by looking at the socket; if it's there and a daemon is listening to it, it will ask the exact time and print that immediately. If not, it will try to open the serial device and setup the socket for communication later, but then there are two possibilies:

  Run as root
When run as root, it will fork, put itself in the background and detach itself from the controling tty, i.e. become a real daemon. Every hour it will set the time in the kernel, assuming the PC clock-crystal is accurate enough in the mean time. Warning: do not run this program suid!

  Run as user
When a user starts the program for the first time, and can get the serial line and socket, it'll run, but print a warning and not fork. Instead it prints a timestamp every whole hour. It still opens the socket so others can request the exact time. Since a user can't set the time in the kernel, it requires a little arithmetic to print the right time. The difference between real and kernel time is calculated every hour, so deviation should be minimal.

NETWORK
There are several programs available on the Net to synchronise other computer clocks through a LAN; this way only one receiver has to be bought in order to keep a whole building on time. At the moment, 'nist' comes to mind. Also, telnetting to port 13 of the machine dfc is running on will dump the current time. In theory, you could attach multiple devices to one computer that are tuned to different time-stations (for example, Radio France at 163.840 KHz) by supplying different paths for the serial device and the socket. Just don't ask me if it's any use...

HOW DOES IT WORK
Note: because I live in Europe and only have one device to use, this tells about Europe and this deivce only; but you'll get the picture. The DFC-77 transmitter is located in Mainflingen, Germany and is linked to an atomic clock with a precision of 1 second in 300,000 years. It operates on a frequency of 77.5 KHz in the long wave band, and can be received by a simple device. It sends out timing information through pulses at the incredible rate of 1 bit/s. Every second (except the 59th) it broadcasts a pulse of 100 or 200 milliseconds wide for resp. a 0 or a 1. In the 59 pulses that are broadcasted the current time (hours & minutes) and date (day of month, month, day of week & year) are encoded, plus a few parity bits and miscellanceous information like winter- and summer time. The 59th pulse is missing, so the start of a minute can be easily detected. The details of which bits are what can be found in the source code. But some of them are worth explaining. There are two separate bits for winter and summertime; when they're both off no such rule is in place. Another bit is there to warn you there's a change in winter- and summer time coming; I don't know how much time in advance this bit is turned on. A week seems reasonable. Since the time of the transmitter is adjusted accordingly, there's no need for you to take action. Another interesting bit is the leap-second-bit. Since the rotation of the Earth is slowing down, sometimes an extra second is added to a year (the last minute of the year is then 61 seconds long). This bit is there to announce that. I admit: astronomers are nit-picks :-).

DEVICES
The device I have is appearantly from a German compagny. It's just a small box with a flashing LED that show the pulses that are received. It feeds the received bits into the computer through a serial line (which is also where it gets its power from). After some debugging I found out how to power the thing and the baudrate at which it works (50 baud... *ahum*) There is also a version of this device available that works through the joystick-port, but I have no idea how. Ask around in your local computer store and try to find something similar. If you find something else, you may need to write your own driver for it (in which case I'd be happy to help, and get some feedback on it).

BUGS
Well, bugs... the checking of the time-bits could be more rigid, for example checking if the time isn't running back or we're leaping a few years ahead (theoretically, a wrong time with valid parity might be received and put us at Warp 13).

AUTHOR
Nemosoft Unv. E-mail: nemosoft@void.tdcnet.nl (soon: nemosoft@void.tdc.globalxs.nl)

COPYING, POLICY, ETC
Well, feel free to do with this whatever you like; on these conditions: my original authorship must be maintained in the documentation and the program somewhere. I would like to hear from any extra support for other receivers, so I can build that into the program. I just hope it's useful for someone out there.

TODO
- Supporting the joy-stick-port version of this device - Get other timezones than CET working (anyone have some _good_ ideas?) - More devices