[LinuxPPS] Oncore section of the LinuxPPS NTPD support web page. Improve docmumentation.
Hal V. Engel
hvengel at astound.net
Wed Feb 18 00:32:22 CET 2009
Udo,
I was looking at the LinuxPPS web pages today and noticed that the Oncore
installation documentation is very basic. Since I had documented this in some
detail for someone I assisted with installing LinuxPPS I though that perhaps
the documentation I put together can be used to improve what is on the web
site. Here it is:
Motorola Oncore GPS receiver (refclock_oncore - driver 30)
This driver implements reference clock support for the NTPD package that reads
time data and PPS signals from a Motorola Oncore GPS receiver.
Installation
Run the configure command with the following parameters:
./configure --disable-all-clocks --disable-parse-clocks --enable-ONCORE \
--enable-LOCAL-CLOCK –enable-SHM
Review the configure output to confirm that it found timepps.h and that it is
configured for ONCORE (should say yes for both).
Then compile and install with make and make install.
Symlinks (Udo - perhaps this section could be generalized for more refclocks
since many of them need device symlinks to be setup?)
There has to be a /dev/oncore.pps or /dev/oncore.pps.<X> device file which is
a symlink to /dev/pps<X> where in most cases <X> will be 0 unless you have
more than one PPS device. In addition, there needs to be a sym link from
/dev/oncore.serial or /dev/oncore.serial.<X> (if you use *.<X> for the pps sym
link these must match) to the serial device that is attached to the GPS.
Typically ln -s /dev/ttyS0 oncore.serial.0 (or whatever serial interface you
use). If you only have one Oncore GPS then you do not need to use
/dev/oncore.<X> because the use of .<X> is intended to allow the installation
of more than one Oncore refclock. When finalizing the installation the
creation of these symlinks should be implemented with udev rules like the
following:
KERNEL=="ttyS0", SYMLINK+="oncore.serial.0"
KERNEL=="pps0", OWNER="root", GROUP="uucp", MODE="0660",
SYMLINK+="oncore.pps.0", OPTIONS+="last_rule"
Storing GPS Initialization Data for Faster Startup
The –enable-SHM setting has two functions. The first is to allow the driver
to create a file that contains GPS data for initializing the GPS. This makes
cold starts of the GPS much faster since a true cold start without this
initialization would take about 470 seconds. With this data the GPS will
start locking onto satellites in less than one minute. The second function is
to allow external software to get a read only interface to the GPS data
stream. Please see the on-line ntp Oncore docs for a link to an example
program which will allow you to monitor the reception of the GPS while ntp is
running.
The SHM file created is fairly small (<4K). The name and location of this
file is set in the Oncore configuration file (see the section below for
details). To avoid confusion the SHM file should use a naming convention
that is similar to the other configuration related files and device symlinks
used by the Oncore driver.
NTP Configuration Files
The main ntp configuration file is typically named /etc/ntp.conf but it can
also be located in the /etc/ntp/ directory. This file should contain the
following lines:
# set up logging and statistics capture - useful for trouble shooting
statsdir </some/location>
# where you want ntp to put statistics files
# typially /var/log or /var/log/ntp
# this is where the clockstats file (see below) will go
Logconfig +clockall
logfile /var/log/ntp/ntp.log # create log file
# create a clockstats file comment the following
# two lines once things are working
statistics clockstats
filegen clockstats file clockstats type none enable
server 127.127.30.<X> prefer # <X> matches the convention used elsewhere
The Oncore configuration file is named /etc/ntp.oncore.<X> or
/etc/ntp/ntp.oncore.<X> where <X> matches the naming conversions documented in
the symlinks section above. There needs to be one of these for each installed
Oncore. These files should have the following:
#
# Oncore UT+ configuration file
#
# —– mandatory lines —————-
MODE 1 # put GPS into position hold mode. Uses
# the position data in the next section.
# In position hold mode only one satellite is
# needed to get accurate time data and timing
# information is more accurate.
# for the next config items see the winoncore section below
LON 5 11.4548 #insert your own longitude here
# this will be negative if you are in the
# western hemisphere.
LAT 52 14.2342 #insert your own latitude here
HT 11.0 M #insert your own GPS height here
# —– optional lines ——————
DELAY 50 NS #delay is approx 5 ns/m cable (I have 10m antenna cable)
ASSERT #positive edge is synced to UTC epochs,
# will need to be changed to CLEAR if the pps
# signal is inverted. ASSERT is the default.
SHMEM <directory location>/oncore.<X>
# again match .<X> to naming used for other files and device symlinks
# where <directory location> is something
# like /var/log or /var/log/ntp or /var/log/ntpstats but
# make sure this directory exists
MASK 0 # optional I use 10 which masks satellites close to the horizon
For further info on this reference clock, please, refer to the file
driver30.html in the NTP source tree. There is also additional information
about how the various configuration settings are used in the driver source
code - ntpd/refclock_oncore.c.
WinOncore
Motorola has made available a software package named WinOncore12 that has a
number of useful features for Oncore users. There are no longer any links to
this software on the Motorola web site. But you can get a copy of it here:
http://www.macropol.com.pl/FTP_WWW/MOTOROLA/GPS_ONCORE/M12/
This software is licensed and the EULA requires you to use it only for
testing, configuration or integration of your Oncore GPS and does not allow
you to reverse engineer the code or make modifications to the software.
Redistribution is allowed as long as the software is not altered and the
license is included. That is it is proprietary closed source freeware for
Oncore users. This is a windows application but it runs very well with recent
versions of wine so Linux users can use all of it's features. It supports all
versions of the Oncore including the newer 12 channel models at least up to
the M12 and M12T and it works well with 6 and 8 channel models such as the VP,
UT and UT+.
One important use of this software for those using a timing specific Oncore
(VP, UT, UT+ and M12T) is that it can be used to do a site survey for using
position hold mode. A site survey will take a large number of GPS position
readings (8,000 to 10,000) and averages these to produce a very precise
location for the GPS antenna (with in a few inches). The more accurate this
position the better the accuracy of the timing pulses from the GPS since a
position error of 1 meter results in about a 3 nanosecond error in the time
data from the GPS. Run a site survey with WinOncore12 and use these results
in the /etc/ntp.oncore.<X> config file for the LON, LAT and HT settings
(please see the Oncore configuration file section above).
In addition, if your GPS should ever need to be initialized WinOncore12 can be
used to do that as well as to confirm that the GPS is functioning and
correctly hooked up to the computer. In some cases you may need to initialize
the GPS when it is first hooked up to the computer. You can also run a GPS
diagnostic with WinOncore12.
You can also use WinOncore12 to help find a good location for your antenna
using it's signal quality indicators and sky view display to find a location
with the best reception. You should do this before running a site survey and
the antenna should not be moved after the site survey is complete.
Trouble Shooting
One of the most useful tools for getting this driver working and confirming
it's correct functioning is the clockstats file. If you don't get a
clockstats file (assuming this is correctly configured in the ntp
configuration file) when ntp is started then there is a basic issue with ntp
like perhaps the Oncore driver was not correctly built into the ntp daemon.
If you are only seeing part of this output (IE. It stops before the satellite
messages) then there is likely an issue with the serial connection to the GPS.
When the driver is working correctly the clockstats file should look like this
(the lines after LEAP_NOWARNING are the satellite messages):
54878 74202.922 127.127.30.0 ONCORE DRIVER -- CONFIGURING
54878 74202.922 127.127.30.0 state = ONCORE_NO_IDEA
54878 74202.922 127.127.30.0 Input mode = 1
54878 74202.922 127.127.30.0 Initializing timeing to Assert..
54878 74202.922 127.127.30.0 SHMEM (size = 3584) is CONFIGURED and available
as /var/log/ntp/oncore.0
54878 74202.922 127.127.30.0 state = ONCORE_CHECK_ID
54878 74203.597 127.127.30.0 @@Cj
54878 74203.597 127.127.30.0 COPYRIGHT 1991-1997 MOTOROLA INC.
54878 74203.597 127.127.30.0 SFTW P/N # 98-P36848P
54878 74203.597 127.127.30.0 SOFTWARE VER # 3
54878 74203.597 127.127.30.0 SOFTWARE REV # 1
54878 74203.597 127.127.30.0 SOFTWARE DATE May 28 1999
54878 74203.597 127.127.30.0 MODEL # R5122U1154
54878 74203.597 127.127.30.0 HWDR P/N # 5
54878 74203.597 127.127.30.0 SERIAL # R0ANHC
54878 74203.597 127.127.30.0 MANUFACTUR DATE 0M19
54878 74203.597 127.127.30.0
54878 74203.597 127.127.30.0 This looks like an Oncore UT with version 3.1
firmware.
54878 74203.597 127.127.30.0 Channels = 8, TRAIM = ON
54878 74203.597 127.127.30.0 state = ONCORE_CHECK_CHAN
54878 74208.145 127.127.30.0 Input says chan = -1
54878 74208.145 127.127.30.0 Model # says chan = 8
54878 74208.145 127.127.30.0 Testing says chan = 8
54878 74208.145 127.127.30.0 Using chan = 8
54878 74208.145 127.127.30.0 state = ONCORE_HAVE_CHAN
54878 74209.595 127.127.30.0 state = ONCORE_TEST_SENT
54878 74217.230 127.127.30.0 GPS antenna: OK
54878 74217.230 127.127.30.0 state = ONCORE_INIT
54878 74218.920 127.127.30.0 Oncore: Resend @@Cj
54878 74220.342 127.127.30.0 Setting Posn from input data
54878 74220.342 127.127.30.0 state = ONCORE_ALMANAC
54878 74220.929 127.127.30.0 See Cb [5,1]
54878 74220.971 127.127.30.0 See Cb [5,2]
54878 74221.005 127.127.30.0 See Cb [5,3]
54878 74221.038 127.127.30.0 See Cb [5,4]
54878 74221.072 127.127.30.0 See Cb [5,5]
54878 74221.105 127.127.30.0 See Cb [5,6]
54878 74221.139 127.127.30.0 See Cb [5,7]
54878 74221.173 127.127.30.0 See Cb [5,8]
54878 74221.206 127.127.30.0 See Cb [5,9]
54878 74221.248 127.127.30.0 See Cb [5,10]
54878 74221.282 127.127.30.0 See Cb [5,11]
54878 74221.315 127.127.30.0 See Cb [5,12]
54878 74221.349 127.127.30.0 See Cb [5,13]
54878 74221.382 127.127.30.0 See Cb [5,14]
54878 74221.416 127.127.30.0 See Cb [5,15]
54878 74221.450 127.127.30.0 See Cb [5,16]
54878 74221.483 127.127.30.0 See Cb [5,17]
54878 74221.525 127.127.30.0 See Cb [5,18]
54878 74221.559 127.127.30.0 See Cb [5,19]
54878 74221.592 127.127.30.0 See Cb [5,20]
54878 74221.626 127.127.30.0 See Cb [5,21]
54878 74221.660 127.127.30.0 See Cb [5,22]
54878 74221.693 127.127.30.0 See Cb [5,23]
54878 74221.730 127.127.30.0 See Cb [5,24]
54878 74228.286 127.127.30.0 See Cb [4,2]
54878 74228.319 127.127.30.0 See Cb [4,3]
54878 74228.353 127.127.30.0 See Cb [4,4]
54878 74228.386 127.127.30.0 See Cb [4,5]
54878 74228.420 127.127.30.0 See Cb [4,7]
54878 74228.454 127.127.30.0 See Cb [4,8]
54878 74228.487 127.127.30.0 See Cb [4,9]
54878 74228.529 127.127.30.0 See Cb [4,10]
54878 74228.563 127.127.30.0 See Cb [5,25]
54878 74228.596 127.127.30.0 See Cb [4,25]
54878 74228.630 127.127.30.0 Posn:
54878 74228.630 127.127.30.0 Lat = N 37.9630917deg, Long = W
122.0137383deg, Alt = 11.61m (38.09ft) GPS
54878 74228.630 127.127.30.0 Lat = N 37deg 57.7855m, Long = W 122deg
0.82430m, Alt = 11.61m (38.09ft) GPS
54878 74228.630 127.127.30.0 Lat = N 37deg 57m 47.13s, Long = W 122deg 0m
49.46s, Alt = 11.61m (38.09ft) GPS
54878 74228.689 127.127.30.0 Cable delay is set to 50 ns
54878 74228.700 127.127.30.0 Satellite mask angle set to 10 degrees
54878 74231.117 127.127.30.0 Have now loaded an ALMANAC
54878 74231.117 127.127.30.0 state = ONCORE_RUN
54878 74231.117 127.127.30.0 SSstate = ONCORE_SS_DONE
54878 74231.189 127.127.30.0 ONCORE: Detected TRAIM, TRAIM = ON
54878 74231.189 127.127.30.0 Input says TRAIM = -1
54878 74231.189 127.127.30.0 Model # says TRAIM = 1
54878 74231.189 127.127.30.0 Testing says TRAIM = 1
54878 74231.189 127.127.30.0 Using TRAIM = 1
54878 74232.217 127.127.30.0 PPS Offset is set to 0 ns
54878 74232.241 127.127.30.0 Satellite mask angle is 10 degrees
54878 74233.228 127.127.30.0 ONCORE[0]: Leap Sec Msg: 15 15 2009 1 1 15 0 0 0
0
54878 74233.228 127.127.30.0 Set pp.leap to LEAP_NOWARNING
54878 74246.299 127.127.30.0 3443805446.000238977 2009 47 20 37 26 26 rstat
08 dop 0.0 nsat 11,5 traim 1,0,0 sigma 63 neg-sawtooth 43 sat 08585830
54878 74248.217 127.127.30.0 3443805447.000226386 2009 47 20 37 28 27 rstat
08 dop 0.0 nsat 11,6 traim 1,0,0 sigma 63 neg-sawtooth -14 sat 08585850
54878 74249.217 127.127.30.0 3443805449.000201707 2009 47 20 37 29 29 rstat
08 dop 0.0 nsat 11,7 traim 1,0,0 sigma 63 neg-sawtooth -46 sat 58585850
More information about the LinuxPPS
mailing list