1.\" $OpenBSD: udcf.4,v 1.27 2015/06/07 20:13:13 claudio Exp $ 2.\" 3.\" Copyright (c) 2006 - 2008 Marc Balmer <mbalmer@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: June 7 2015 $ 18.Dt UDCF 4 19.Os 20.Sh NAME 21.Nm udcf 22.Nd Gude ADS Expert mouseCLOCK USB timedelta sensor 23.Sh SYNOPSIS 24.Cd "udcf* at uhub?" 25.Sh DESCRIPTION 26The 27.Nm 28driver provides support for the Gude ADS Expert mouseCLOCK USB and 29the Expert mouseCLOCK USB II, receivers for the German DCF77. 30While receivers for the British MSF time signal station are also 31being made, 32.Nm 33lacks support for them. 34.Pp 35.Nm 36implements a timedelta sensor and the delta (in nanoseconds) between the 37received time information and the local time can be accessed through the 38.Xr sysctl 8 39interface. 40The clock type is indicated in the sensor description: 41.Bl -tag -width "CRITICALXX" -offset indent 42.It DCF77 43German DCF77 time signal station 44(77.5 kHz longwave transmitter located in Mainflingen near Frankfurt). 45.El 46.Pp 47The quality of the timedelta is reported as the sensor status: 48.Bl -tag -width "CRITICALXX" -offset indent 49.It UNKNOWN 50No valid time information has been received yet. 51.It OK 52The time information is valid and the timedelta is safe to use for 53applications like 54.Xr ntpd 8 . 55.It WARN 56The time information is still valid, but no new time information has been 57decoded for at least 5 minutes due to a reception or parity error. 58The timedelta should be used with care. 59.It CRITICAL 60No valid time information has been received for more than 15 minutes since 61the sensor state degraded from OK to WARN. 62This is an indication that hardware should be checked 63to see if it is still functional. 64The timedelta will eventually degrade to a lie 65as all computer internal clocks have a drift. 66.El 67.Sh SEE ALSO 68.Xr intro 4 , 69.Xr uhub 4 , 70.Xr usb 4 , 71.Xr ntpd 8 , 72.Xr sysctl 8 73.Sh HISTORY 74The 75.Nm 76driver first appeared in 77.Ox 4.0 . 78.Sh AUTHORS 79.An -nosplit 80The 81.Nm 82driver was written by 83.An Marc Balmer Aq Mt mbalmer@openbsd.org . 84.Sh CAVEATS 85DCF77 uses a 77.5 kHz long wave radio signal transmitted from near Frankfurt, 86Germany. 87Up to about 900 km, the radio signal can travel directly to the receiver, 88providing a linearly increasing time offset based on distance. 89Due to the curvature of the Earth, beyond this distance the signal must 90bounce off the lower ionosphere (residing at approximately 70 km elevation 91during the day, and 90 km at night), thus causing a non-linearly increasing 92time offset which can only be roughly calculated using trigonometry. 93Since the distance and transmission geometry is not known, 94the clock receivers and 95.Nm 96driver currently make no effort to calculate this offset. 97We simply assume that the offset is small. 98.Pp 99In Germany, the train system uses DCF77 clocks. 100As the distance from Frankfurt increases, 101trains can be expected to run later. 102