From: Harlan Stenn Date: Mon, 7 Feb 2000 06:36:33 +0000 (-0000) Subject: ChangeLog, driver30.htm, Oncore-SHMEM.htm: X-Git-Tag: NTP_4_0_99_E~6 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1ab84c53a392f1a4b12e0404d4739f5d72dd60c5;p=thirdparty%2Fntp.git ChangeLog, driver30.htm, Oncore-SHMEM.htm: * html/Oncore-SHMEM.htm: New document * html/driver30.htm: Cleanup and improvements From: Reg Clemens bk: 389e67f1Hs2qrFVmeKcZFGHJGEVX0A --- diff --git a/ChangeLog b/ChangeLog index 0fa252d6f..32d68f8f7 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2000-02-07 Harlan Stenn + + * html/Oncore-SHMEM.htm: New document + * html/driver30.htm: Cleanup and improvements + From: Reg Clemens + 2000-01-30 Harlan Stenn * ntpd/refclock_oncore.c: Patches/improvements diff --git a/html/Oncore-SHMEM.htm b/html/Oncore-SHMEM.htm new file mode 100644 index 000000000..d4a65c466 --- /dev/null +++ b/html/Oncore-SHMEM.htm @@ -0,0 +1,228 @@ + + + ONCORE - SHMEM + + +

+Motorola ONCORE - The Shared Memory Interface +

+
+ +

+Introduction +

+ +

+In NMEA mode, the Oncore GPS receiver provides the user with the same information as +other GPS receivers. +In BINARY mode, it can provide a lot of additional information. +When using the Oncore GPS receiver with NTP, this additional information is usually +not available since the receiver is only talking to the oncore driver in NTPD. +

+In particular, you can ask for satellite positions, satellite health, signal levels, +the ephemeris and the almanac, and you can set many operational parameters. +In the case of the VP, +you can get the pseudorange corrections necessary to act as a DGPS base station, and you can see +the raw satellite data messages themselves. +

+To make use of this information you will need an Oncore Reference Manual for the +Oncore GPS receiver that you have. The Manual for the VP only exists as a paper +document, the UT manuals are available as a pdf document online. +

+To make this information available for use in other programs, +(say graphic displays of satellites positions, plots of SA, etc.), a shared memory interface +(SHMEM) has been added to the refclock_oncore driver on those operating systems that support +shared memory. +

+This interface was written by Poul-Henning Kamp (phk@FreeBSD.org), and modified by +Reg Clemens (reg@dwf.com). +The interface is known to work in FreeBSD, Linux, and Solaris. +

+Storage of Messages in Shared Memory +

+With the shared memory interface, the oncore driver (refclock_oncore) allocates space +for all of the messages that it is configured to receive, and then puts each message +in the appropriate slot in shared memory as it arrives from the receiver. +Since there is no easy way for a client program to know when the shared memory has +been updated, +a sequence number is associated with each message, and is incremented when a new message +arrives. +With the sequence number it is easy to check through the shared memory segment for messages that +have changed. +

+The Oncore binary messages are kept in their full length, as described in the Reference +manual, that is everything from the @@ prefix thru the <checksum><CR><LF>. +

+The data starts at location ONE of SHMEM (NOT location ZERO). +

+The messages are stacked in a series of variable length structures, that look like +

+        struct message {
+                u_int   length;
+                u_char  sequence;
+                u_char  message[length];
+        }
+
+

+if something like that were legal. +That is, there are two bytes (caution, these may NOT be aligned with word boundaries, so +the field needs to be treated as a pair of u_char), that contains the length of the next +message. +This is followed by a u_char, a sequence number, that is incremented whenever a new message of +this type is received. +This is followed by 'length' characters of the actual message. +

+The next structure starts immediately following the last char of the previous message (no alignment). +Thus, each structure starts a distance of 'length+3' from the previous structure. +

+Following the last structure, is a u_int containing a zero length to indicate the end +of the data. +

+The messages are recognized by reading the headers in the data itself, viz @@Ea or whatever. +

+There are two special cases. +

+(1) The almanac takes a total of 34 subrecords all starting with @@Cb.
+35 records are allocated. +Each @@Cb message is initially placed in the first of these locations, +and then later it is moved to the appropriate location for that sub-message. +The submessages can be distinguished by the first two characters following the @@Cb header, +and new data is received only when the almanac changes. +

+(2) The @@Ea record contains the satellite position, and are received 1/second. +However, when in timekeeping mode, the receiver is normally put in 0D mode, with the +position fixed to get better accuracy, so the current position is not available. +

+When the SHMEM option is active, one @@Ea record is hijacked each 15s, and the receiver +is put back in 3D mode so the the current location can be determined (for position determination, or for +tracking SA). +The timekeeping code is careful NOT to use the time associated with this (less accurate) 3D tick +in its timekeeping functions. +

+Following the initial @@Ea record are 3 subrecords for a total of four. +As with the almanac, the first gets filled each time a new record becomes available, +Later in the code, it is distributed to the appropriate subrecord. +These records can be distinguished by different bit patterns in the last byte of the record. +Currently there +are subrecords for 0D, 2D, 3D, but the code only fills in the 0D and 3D positions at +present. +

+Opening the Shared Memory File +

+The shared memory segment is accessed through a file name given on a ACCESS card in the +/etc/ntp.oncore input file. +The following code could be used to open the Shared Memory Segment: + +
+        char *Buf, *file;
+        int size, fd;
+        struct stat statbuf;
+
+        file = "/var/adm/ntpstats/ONCORE";  /* the file name on my ACCESS card */
+        if ((fd=open(file, O_RDONLY)) < 0) {
+                fprintf(stderr, "Cant open %s\n", file);
+                exit(1);
+        }
+
+        if (stat(file, &statbuf) < 0) {
+                fprintf(stderr, "Cant stat %s\n", file);
+                exit(1);
+        }
+
+        size = statbuf.st_size;
+        if ((Buf=mmap(0, size, PROT_READ, MAP_SHARED, fd, (off_t) 0)) < 0) {
+                fprintf(stderr, "MMAP failed\n");
+                exit(1);
+        }
+
+ +

+Accessing the data +

+The following code shows how to get to the individual records. + +
+        void    oncore_msg_Ea(), oncore_msg_As(), oncore_msg_Bb();
+
+        struct Msg {
+            char         c[5];
+            unsigned int seq;
+            void         (*go_to)(uchar *);
+        };
+
+        struct Msg Hdr[] = { {"@@Bb", 0, &oncore_msg_Bb},
+                             {"@@Ea", 0, &oncore_msg_Ea},
+                             {"@@As", 0, &oncore_msg_As}};
+
+        void
+        read_data()
+        {
+            int     i, j, k, n, iseq, jseq;
+            uchar   *cp, *cp1;
+
+
+            for(cp=Buf+1; (n = 256*(*cp) + *(cp+1)) != 0;  cp+=(n+3)) {
+                for (k=0; k < sizeof(Hdr)/sizeof(Hdr[0]);  k++) {
+                    if (!strncmp(cp+3, Hdr[k].c, 4)) {      /* am I interested? */
+                        iseq = *(cp+2);
+                        jseq = Hdr[k].seq;
+                        Hdr[k].seq = iseq;
+                        if (iseq > jseq) {              /* has it changed? */
+                            /* verify checksum */
+                            j = 0;
+                            cp1 = cp+3;             /* points to start of oncore response */
+                            for (i=2; i < n-3; i++)
+                                j ^= cp1[i];
+                            if (j == cp1[n-3]) {    /* good checksum */
+                                    Hdr[k].go_to(cp1);
+                            } else {
+                                fprintf(stderr, "Bad Checksum for %s\n", Hdr[k].c);
+                                break;
+                            }
+                        }
+                    }
+                }
+                if (!strncmp(cp+3, "@@Ea", 4))
+                    cp += 3*(n+3);
+                if (!strncmp(cp+3, "@@Cb", 4))
+                    cp += 34*(n+3);
+            }
+        }
+
+        oncore_msg_Bb(uchar *buf)
+        {
+                /* process Bb messages */
+        }
+
+        oncore_msg_Ea(uchar *buf)
+        {
+                /* process Ea messages */
+        }
+
+        oncore_msg_As(uchar *buf)
+        {
+                /* process As messages */
+        }
+
+ +

+The structure Hdr contains the Identifying string for each of the messages that +we want to examine, and the name of a program to call when a new message of that +type is arrives. +

+The loop can be run every few seconds to check for new data. +

+There are two more complete examples +(one that that show satellite positions and the station position as affected by SA, and +another that computes the effective horizon by watching satellite tracks) that +will be found in the GNU-zipped tar file + +ftp://ftp.udel.edu/pub/ntp/software/OncorePlot.tar.gz. +

+Try it, have fun. +

+
+ reg@dwf.com +
+ + diff --git a/html/driver30.htm b/html/driver30.htm index fab604b8a..c32cc52af 100644 --- a/html/driver30.htm +++ b/html/driver30.htm @@ -35,8 +35,7 @@ Protocol. the "UT+",  and the "Remote" which is a prepackaged "UT+".  The "VP" is no longer available. - -

The evaluation kit +The evaluation kit can also be recommended, it interfaces to a PC straightaway, using the serial (DCD) or parallel port for PPS input and packs the receiver in a nice and sturdy box. @@ -78,13 +77,18 @@ for the VP/UT models.

The driver will use the "position hold" mode with user provided coordinates, the receivers built-in site-survey, -or a similar algorithm implemented in this driver. +or a similar algorithm implemented in this driver to determine the antenna position.

Monitor Data

-The driver is quite chatty on stdout if ntpd is run with -debugging.  -A manual will be required though. -Additional information is written to the clockstats file, if configured. +The driver is quite chatty on stdout if ntpd is run with debugging. +

+In addition, on platforms supporting Shared Memory, all of the messages +received from the Oncore receiver are made available in shared memory for +use by other programs. +See the Oncore-SHMEM manual page for +information on how to use this option. +For either debugging or using the SHMEM option, an Oncore Reference Manual +for the specific receiver in use will be required.

Fudge Factors

@@ -141,7 +145,7 @@ Not used by this driver. Not used by this driver. Additional Information -

The driver has been tested on FreeBSD, Linux and SunOS. +

The driver was initially developed on FreeBSD, and has since been tested on Linux SunOS and Solaris.

There is a driver specific configuration file /etc/ntp.oncore that contains information on the startup mode, the location of the GPS