mbg_gps166.h revision ef64b99e8412f2273dd2e8b3291c2f78ffc4667f
1/*
2 * /src/NTP/ntp-4/include/mbg_gps166.h,v 4.1 1998/06/12 15:07:30 kardel RELEASE_19990228_A
3 *
4 * $Created: Sun Jul 20 09:20:50 1997 $
5 *
6 * Copyright (C) 1997, 1998 by Frank Kardel
7 */
8#ifndef MBG_GPS166_H
9#define MBG_GPS166_H
10
11
12/***************************************************************************/
13/*                                                                         */
14/*   File:         GPSSERIO.H                    4.1          */
15/*                                                                         */
16/*   Project:      Common C Library                                        */
17/*                                                                         */
18/*   Compiler:     Borland C++                                             */
19/*                                                                         */
20/*   Author:       M. Burnicki,  Meinberg Funkuhren                        */
21/*                                                                         */
22/*                                                                         */
23/*   Description:                                                          */
24/*     This file defines structures and codes to be used to access GPS166  */
25/*     via its serial interface COM0. COM0 should be set to a high baud    */
26/*     rate, default is 19200.                                             */
27/*                                                                         */
28/*     Standard GPS166 serial operation is to send a time string that is   */
29/*     compatible with Meinberg UA31 or PZF535 DCF77 radio remote clocks.  */
30/*     That string can be transmitted automatically once per second, once  */
31/*     per minute or on request per ASCII '?'.                             */
32/*                                                                         */
33/*     Parameter setup or parameter readout works using blocks of binary   */
34/*     data which have to be isolated from the standard string. A block of */
35/*     data starts with a SOH code (ASCII Start Of Header, 0x01) followed  */
36/*     by a message header with constant length and a data portion with    */
37/*     variable length. The first field (cmd) of the message header holds  */
38/*     the command code rsp. the type of data to be transmitted. The next  */
39/*     field (len) gives the number of data bytes that are transmitted     */
40/*     after the header. This number ranges from 0 to sizeof( MSG_DATA ).  */
41/*     The third field (data_csum) holds a checksum of all data bytes and  */
42/*     the last field of the header finally holds the checksum of the.     */
43/*     header.                                                             */
44/*                                                                         */
45/***************************************************************************/
46
47/* the control codes defined below are to be or'ed with a command/type code */
48
49#define GPS_REQACK    0x8000   /* to GPS166: request acknowledge */
50#define GPS_ACK       0x4000   /* from GPS166: acknowledge a command */
51#define GPS_NACK      0x2000   /* from GPS166: error receiving command */
52
53#define GPS_CTRL_MSK  0xF000   /* masks control code from command */
54
55
56/* The codes below specify commands/types of data to be supplied to GPS166: */
57
58/*                            GPS166 auto-message to host            */
59/*                            �   host request, GPS166 response      */
60/*                            �   �   host download to GPS166        */
61/*                            �   �   �                              */
62enum {  /*                    �   �   �                              */
63  /* system data */
64  GPS_AUTO_ON = 0x000,   /* �   �   � X � enable auto-messages from GPS166 */
65  GPS_AUTO_OFF,          /* �   �   � X � disable auto-messages from GPS166 */
66  GPS_SW_REV,            /* �   � X �   � request software revision */
67  GPS_STAT,              /* �   � X �   � request status of buffered variables */
68  GPS_TIME,              /* � X �   � X � current time or capture or init board time */
69  GPS_POS_XYZ,           /* �   � X � X � current position in ECEF coords */
70  GPS_POS_LLA,           /* �   � X � X � current position in geographic coords */
71  GPS_TZDL,              /* �   � X � X � time zone / daylight saving */
72  GPS_PORT_PARM,         /* �   � X � X � parameters of the serial ports */
73  GPS_SYNTH,             /* �   � X � X � synthesizer's frequency and phase */
74  GPS_ANT_INFO,          /* � X � X �   � time diff after antenna disconnect */
75  GPS_UCAP,              /* � X � X �   � user capture */
76
77  /* GPS data */
78  GPS_CFGH = 0x100,      /* �   � X � X � SVs' configuration and health codes */
79  GPS_ALM,               /* �   � X � X � one SV's almanac */
80  GPS_EPH,               /* �   � X � X � one SV's ephemeris */
81  GPS_UTC,               /* �   � X � X � UTC correction parameters */
82  GPS_IONO,              /* �   � X � X � ionospheric correction parameters */
83  GPS_ASCII_MSG          /* �   � X �   � the GPS ASCII message */
84};
85
86/*
87 * modelled after GPSDEFS.H Revision 1.5
88 */
89/***************************************************************************/
90/*                                                                         */
91/*   File:         GPSDEFS.H                     4.1          */
92/*                                                                         */
93/*   Project:      Common C Library                                        */
94/*                                                                         */
95/*   Compiler:     Borland C++                                             */
96/*                                                                         */
97/*   Author:       M. Burnicki,  Meinberg Funkuhren                        */
98/*                                                                         */
99/*                                                                         */
100/*   Description:                                                          */
101/*     General definitions to be used with GPS166                          */
102/*     GPS166 Rev. 1.23 or above                                           */
103/*                                                                         */
104/*   Modifications: see file GPSLIB.TXT                                    */
105/*                                                                         */
106/***************************************************************************/
107#define _GPSDEFS_H
108/* the type of various checksums */
109
110#ifndef _CSUM_DEFINED
111  typedef unsigned short CSUM;
112#  define _CSUM_DEFINED
113#endif
114
115/* the message header */
116
117typedef struct {
118  unsigned short gps_cmd;
119  unsigned short gps_len;
120  unsigned short gps_data_csum;
121  unsigned short gps_hdr_csum;
122} GPS_MSG_HDR;
123
124/* a struct used to hold the software revision information */
125
126typedef struct {
127  unsigned short code;       /* e.g. 0x0120 means rev. 1.20 */
128  unsigned char name[17];     /* used to identify customized versions */
129} SW_REV;
130
131/* GPS ASCII message */
132
133typedef struct {
134  CSUM csum;       /* checksum of the remaining bytes */
135  short valid;     /* flag data are valid */
136  char s[23];      /* 22 chars GPS ASCII message plus trailing zero */
137} ASCII_MSG;
138
139#define MIN_SVNO         1                  /* min. SV number */
140#define MAX_SVNO        32                  /* max. SV number */
141#define N_SVNO ( MAX_SVNO - MIN_SVNO + 1)   /* number of possibly active SVs */
142
143
144typedef short          SVNO;     /* the number of a SV */
145typedef unsigned short HEALTH;  /* a SV's health code */
146typedef unsigned short CFG;     /* a SV's configuration code */
147typedef unsigned short IOD;     /* Issue-Of-Data code */
148
149/* Date and time referred to the linear time scale defined by GPS. */
150/* GPS time is defined by the number of weeks since midnight from */
151/* January 5, 1980 to January 6, 1980 plus the number of seconds of */
152/* the current week plus fractions of a second. GPS time differs from */
153/* UTC because UTC is corrected with leap seconds while GPS time scale */
154/* is continuous. */
155
156typedef struct {
157  unsigned short wn;     /* the week number since GPS has been installed */
158  unsigned long sec;     /* the second of that week */
159  unsigned long tick;    /* fractions of a second; scale: 1E-7 */
160} T_GPS;
161
162
163/* Local date and time computed from GPS time. The current number */
164/* of leap seconds have to be added to get UTC from GPS time. */
165/* Additional corrections could have been made according to the */
166/* time zone/daylight saving parameters (TZDL, see below) defined */
167/* by the user. The status field can be checked to see which corrections */
168/* have been applied. */
169
170#ifndef _TM_DEFINED
171  typedef struct {
172    short year;          /* 0..9999 */
173    char month;          /* 1..12 */
174    char mday;           /* 1..31 */
175    short yday;          /* 1..366 */
176    char wday;           /* 0..6 == Sun..Sat */
177    char hour;           /* 0..23 */
178    char minute;         /* 0..59 */
179    char second;         /* 0..59 */
180    long frac;           /* fractions of a second, scale 1E-7 */
181    long offs_from_utc;  /* local time's offset from UTC */
182    unsigned short status;       /* flags */
183  } TM;
184
185  /* status flags used with conversion from GPS time to local time */
186
187#  define TM_UTC        0x01   /* UTC correction has been made */
188#  define TM_LOCAL      0x02   /* UTC has been converted to local time */
189#  define TM_DL_ANN     0x04   /* state of daylight saving is going to change */
190#  define TM_DL_ENB     0x08   /* daylight saving is enabled */
191#  define TM_LS_ANN     0x10   /* leap second will be inserted */
192#  define TM_LS_ENB     0x20   /* current second is leap second */
193
194#  define _TM_DEFINED
195#endif
196
197
198/* the status flags below are defined starting with rev. 1.32 */
199
200#define TM_ANT_DISCONN  0x1000  /* antenna currently disconnected */
201#define TM_SYN_FLAG     0x2000  /* TIME_SYN output is low */
202#define TM_NO_SYNC      0x4000  /* not sync'ed after reset */
203#define TM_NO_POS       0x8000  /* position not computed after reset, */
204                                /*   LOCK LED off */
205
206/* a struct used to transmit information on date and time */
207
208typedef struct {
209  short channel;        /* -1: the current time; 0, 1: capture 0, 1 */
210  T_GPS t;              /* time in GPS format */
211  TM tm;                /* that time converted to local time */
212} TTM;
213
214
215
216/* Two types of variables used to store a position. Type XYZ is */
217/* used with a position in earth centered, earth fixed (ECEF) */
218/* coordinates whereas type LLA holds such a position converted */
219/* to geographic coordinates as defined by WGS84 (World Geodetic */
220/* System from 1984). */
221
222#ifndef _XYZ_DEFINED
223  /* sequence and number of components of a cartesian position */
224  enum { XP, YP, ZP, N_XYZ };
225
226  /* a type of array holding a cartesian position */
227  typedef l_fp XYZ[N_XYZ];      /* values are in [m] */
228
229#  define _XYZ_DEFINED
230#endif
231
232
233#ifndef _LLA_DEFINED
234  /* sequence and number of components of a geographic position */
235  enum { LAT, LON, ALT, N_LLA };  /* latitude, longitude, altitude */
236
237  /* a type of array holding a geographic position */
238  typedef l_fp LLA[N_LLA];      /* lon, lat in [rad], alt in [m] */
239
240#  define _LLA_DEFINED
241#endif
242
243/* Synthesizer parameters. Synthesizer frequency is expressed as a */
244/* four digit decimal number (freq) to be multiplied by 0.1 Hz and an */
245/* base 10 exponent (range). If the effective frequency is less than */
246/* 10 kHz its phase is synchronized corresponding to the variable phase. */
247/* Phase may be in a range from -360� to +360� with a resolution of 0.1�, */
248/* so the resulting numbers to be stored are in a range of -3600 to +3600. */
249
250/* Example: */
251/* Assume the value of freq is 2345 (decimal) and the value of phase is 900. */
252/* If range == 0 the effective frequency is 234.5 Hz with a phase of +90�. */
253/* If range == 1 the synthesizer will generate a 2345 Hz output frequency */
254/* and so on. */
255
256/* Limitations: */
257/* If freq == 0 the synthesizer is disabled. If range == 0 the least */
258/* significant digit of freq is limited to 0, 3, 5 or 6. The resulting */
259/* frequency is shown in the examples below: */
260/*     freq == 1230  -->  123.0 Hz */
261/*     freq == 1233  -->  123 1/3 Hz (real 1/3 Hz, NOT 123.3 Hz) */
262/*     freq == 1235  -->  123.5 Hz */
263/*     freq == 1236  -->  123 2/3 Hz (real 2/3 Hz, NOT 123.6 Hz) */
264
265/* If range == MAX_RANGE the value of freq must not exceed 1200, so the */
266/* output frequency is limited to 12 MHz. */
267
268/* Phase will be ignored if the resulting frequency is greater or equal */
269/* to 10 kHz. */
270
271#define MAX_SYNTH_FREQ   1200    /* if range == MAX_SYNTH_RANGE */
272#define MIN_SYNTH_RANGE     0
273#define MAX_SYNTH_RANGE     5
274#define MAX_SYNTH_PHASE  3600
275
276typedef struct {
277  short freq;      /* four digits used; scale: 0.1; e.g. 1234 -> 123.4 Hz */
278  short range;     /* scale factor for freq; 0..MAX_SYNTH_RANGE */
279  short phase;     /* -MAX_SYNTH_PHASE..+MAX_SYNTH_PHASE; >0 -> pulses later */
280} SYNTH;
281
282
283
284/* Time zone/daylight saving parameters. */
285
286/* the name of a time zone, 5 characters plus trailing zero */
287typedef char TZ_NAME[6];
288
289typedef struct {
290  long offs;         /* offset from UTC to local time [sec] */
291  long offs_dl;      /* additional offset if daylight saving enabled [sec] */
292  TM tm_on;          /* date/time when daylight saving starts */
293  TM tm_off;         /* date/time when daylight saving ends */
294  TZ_NAME name[2];   /* names without and with daylight saving enabled */
295} TZDL;
296
297/* The constant below is defined beginning with software rev. 1.29. */
298/* If the year in tzdl.tmon and tzdl.tm_off is or'ed with that constant, */
299/* the receiver automatically generates daylight saving year by year. */
300/* See GPSLIB.TXT for more information. */
301
302#define DL_AUTO_FLAG  0x8000
303
304/* Example: */
305/* for automatic daylight saving enable/disable in Central Europe, */
306/* the variables are to be set as shown below: */
307/*   offs = 3600L           one hour from UTC */
308/*   offs_dl = 3600L        one additional hour if daylight saving enabled */
309/*   tm_on = first Sunday from March 25, 02:00:00h ( year |= DL_AUTO_FLAG ) */
310/*   tm_off = first Sunday from Sept 24, 03:00:00h ( year |= DL_AUTO_FLAG ) */
311/*   name[0] == "MEZ  "     name if daylight saving not enabled */
312/*   name[1] == "MESZ "     name if daylight saving is enabled */
313
314
315
316
317/* the structure below was defined in rev. 1.31. It reflects the status */
318/* of the antenna, the times of last disconnect/reconnect and the boards */
319/* clock offset after the phase of disconnection. */
320
321typedef struct {
322  short status;    /* current status of antenna */
323  TM tm_disconn;   /* time of antenna disconnect */
324  TM tm_reconn;    /* time of antenna reconnect */
325  long delta_t;    /* clock offset at reconnect time, units: TICKS_PER_SEC */
326} ANT_INFO;
327
328
329/* the status field may be set to one of the values below: */
330
331enum {
332  ANT_INVALID,   /* struct not set yet because ant. has not been disconn. */
333  ANT_DISCONN,   /* ant. now disconn., tm_reconn and delta_t not set */
334  ANT_RECONN     /* ant. has been disconn. and reconn., all fields valid */
335};
336
337
338/* Summary of configuration and health data of all SVs. */
339
340typedef struct {
341  CSUM csum;               /* checksum of the remaining bytes */
342  short valid;             /* flag data are valid */
343
344  T_GPS tot_51;            /* time of transmission, page 51 */
345  T_GPS tot_63;            /* time of transmission, page 63 */
346  T_GPS t0a;               /* complete reference time almanac */
347
348  CFG cfg[N_SVNO];         /* SV configuration from page 63 */
349  HEALTH health[N_SVNO];   /* SV health from pages 51, 63 */
350} CFGH;
351
352
353
354/* UTC correction parameters */
355
356typedef struct {
357  CSUM csum;       /*    checksum of the remaining bytes                  */
358  short valid;     /*    flag data are valid                              */
359
360  T_GPS t0t;       /*    Reference Time UTC Parameters              [sec] */
361  l_fp A0;         /*  � Clock Correction Coefficient 0             [sec] */
362  l_fp A1;         /*  � Clock Correction Coefficient 1         [sec/sec] */
363
364  ushort WNlsf;    /*  week number of nearest leap second                 */
365  short DNt;       /*  the day number at the end of which LS is inserted  */
366  char delta_tls;  /*                                                     */
367  char delta_tlsf; /*                                                     */
368
369} UTC;
370
371/* a struct used to hold the settings of a serial port */
372
373#ifndef _COM_PARM_DEFINED
374  typedef long BAUD_RATE;
375
376  /* indices used to identify a parameter in the framing string */
377  enum { F_DBITS, F_PRTY, F_STBITS };
378
379  /* types of handshake */
380  enum { HS_NONE, HS_XONXOFF, HS_RTSCTS };
381
382  typedef struct {
383    BAUD_RATE baud_rate;    /* e.g. 19200L */
384    char framing[4];        /* e.g. "8N1" */
385    short handshake;        /* a numeric value, only HS_NONE supported yet */
386  } COM_PARM;
387
388#define _COM_PARM_DEFINED
389#endif
390
391
392
393/* the codes below define what has to comes out of the serial ports */
394
395enum { STR_ON_REQ, STR_PER_SEC,
396       STR_PER_MIN, N_STR_MODE_0,      /* COM0 and COM1 */
397       STR_UCAP = N_STR_MODE_0,
398       STR_UCAP_REQ, N_STR_MODE_1      /* COM1 only */
399     };
400
401
402#define N_COM   2  /* the number of serial ports */
403
404/* the structure used to store the modes of both serial ports */
405
406typedef struct {
407  COM_PARM com[N_COM];    /* COM0 and COM1 settings */
408  u_char mode[N_COM];      /* COM0 and COM1 output mode */
409} PORT_PARM;
410
411/* Ephemeris parameters of one specific SV. Needed to compute the position */
412/* of a satellite at a given time with high precision. Valid for an */
413/* interval of 4 to 6 hours from start of transmission. */
414
415typedef struct {
416  CSUM csum;       /*    checksum of the remaining bytes                  */
417  short valid;     /*    flag data are valid                              */
418
419  HEALTH health;   /*    health indication of transmitting SV      [---]  */
420  IOD IODC;        /*    Issue Of Data, Clock                             */
421  IOD IODE2;       /*    Issue of Data, Ephemeris (Subframe 2)            */
422  IOD IODE3;       /*    Issue of Data, Ephemeris (Subframe 3)            */
423  T_GPS tt;        /*    time of transmission                             */
424  T_GPS t0c;       /*    Reference Time Clock                      [---]  */
425  T_GPS t0e;       /*    Reference Time Ephemeris                  [---]  */
426
427  l_fp   sqrt_A;   /*    Square Root of semi-major Axis        [sqrt(m)]  */
428  l_fp   e;        /*    Eccentricity                              [---]  */
429  l_fp   M0;       /*  � Mean Anomaly at Ref. Time                 [rad]  */
430  l_fp   omega;    /*  � Argument of Perigee                       [rad]  */
431  l_fp   OMEGA0;   /*  � Longit. of Asc. Node of orbit plane       [rad]  */
432  l_fp   OMEGADOT; /*  � Rate of Right Ascension               [rad/sec]  */
433  l_fp   deltan;   /*  � Mean Motion Diff. from computed value [rad/sec]  */
434  l_fp   i0;       /*  � Inclination Angle                         [rad]  */
435  l_fp   idot;     /*  � Rate of Inclination Angle             [rad/sec]  */
436  l_fp   crc;      /*  � Cosine Corr. Term to Orbit Radius           [m]  */
437  l_fp   crs;      /*  � Sine Corr. Term to Orbit Radius             [m]  */
438  l_fp   cuc;      /*  � Cosine Corr. Term to Arg. of Latitude     [rad]  */
439  l_fp   cus;      /*  � Sine Corr. Term to Arg. of Latitude       [rad]  */
440  l_fp   cic;      /*  � Cosine Corr. Term to Inclination Angle    [rad]  */
441  l_fp   cis;      /*  � Sine Corr. Term to Inclination Angle      [rad]  */
442
443  l_fp   af0;      /*  � Clock Correction Coefficient 0            [sec]  */
444  l_fp   af1;      /*  � Clock Correction Coefficient 1        [sec/sec]  */
445  l_fp   af2;      /*  � Clock Correction Coefficient 2       [sec/sec�]  */
446  l_fp   tgd;      /*  � estimated group delay differential        [sec]  */
447
448  u_short URA;      /*    predicted User Range Accuracy                    */
449
450  u_char L2code;    /*    code on L2 channel                         [---] */
451  u_char L2flag;    /*    L2 P data flag                             [---] */
452
453} EPH;
454
455/* Almanac parameters of one specific SV. A reduced precision set of */
456/* parameters used to check if a satellite is in view at a given time. */
457/* Valid for an interval of more than 7 days from start of transmission. */
458
459typedef struct {
460  CSUM csum;       /*    checksum of the remaining bytes                  */
461  short valid;     /*    flag data are valid                              */
462
463  HEALTH health;   /*                                               [---] */
464  T_GPS t0a;       /*    Reference Time Almanac                     [sec] */
465
466  l_fp   sqrt_A;   /*    Square Root of semi-major Axis         [sqrt(m)] */
467  l_fp   e;        /*    Eccentricity                               [---] */
468
469  l_fp   M0;       /*  � Mean Anomaly at Ref. Time                  [rad] */
470  l_fp   omega;    /*  � Argument of Perigee                        [rad] */
471  l_fp   OMEGA0;   /*  � Longit. of Asc. Node of orbit plane        [rad] */
472  l_fp   OMEGADOT; /*  � Rate of Right Ascension                [rad/sec] */
473  l_fp   deltai;   /*  �                                            [rad] */
474  l_fp   af0;      /*  � Clock Correction Coefficient 0             [sec] */
475  l_fp   af1;      /*  � Clock Correction Coefficient 1         [sec/sec] */
476} ALM;
477
478
479/* ionospheric correction parameters */
480
481typedef struct {
482  CSUM csum;       /*    checksum of the remaining bytes                  */
483  short valid;     /*    flag data are valid                              */
484
485  l_fp   alpha_0;  /*    Ionosph. Corr. Coeff. Alpha 0              [sec] */
486  l_fp   alpha_1;  /*    Ionosph. Corr. Coeff. Alpha 1          [sec/deg] */
487  l_fp   alpha_2;  /*    Ionosph. Corr. Coeff. Alpha 2        [sec/deg^2] */
488  l_fp   alpha_3;  /*    Ionosph. Corr. Coeff. Alpha 3        [sec/deg^3] */
489
490  l_fp   beta_0;   /*    Ionosph. Corr. Coeff. Beta 0               [sec] */
491  l_fp   beta_1;   /*    Ionosph. Corr. Coeff. Beta 1           [sec/deg] */
492  l_fp   beta_2;   /*    Ionosph. Corr. Coeff. Beta 2         [sec/deg^2] */
493  l_fp   beta_3;   /*    Ionosph. Corr. Coeff. Beta 3         [sec/deg^3] */
494
495} IONO;
496
497void mbg_tm_str P((unsigned char **, TM *));
498void mbg_tgps_str P((unsigned char **, T_GPS *));
499void get_mbg_header P((unsigned char **, GPS_MSG_HDR *));
500void put_mbg_header P((unsigned char **, GPS_MSG_HDR *));
501void get_mbg_sw_rev P((unsigned char **, SW_REV *));
502void get_mbg_ascii_msg P((unsigned char **, ASCII_MSG *));
503void get_mbg_svno P((unsigned char **, SVNO *));
504void get_mbg_health P((unsigned char **, HEALTH *));
505void get_mbg_cfg P((unsigned char **, CFG *));
506void get_mbg_tgps P((unsigned char **, T_GPS *));
507void get_mbg_tm P((unsigned char **, TM *));
508void get_mbg_ttm P((unsigned char **, TTM *));
509void get_mbg_synth P((unsigned char **, SYNTH *));
510void get_mbg_tzdl P((unsigned char **, TZDL *));
511void get_mbg_antinfo P((unsigned char **, ANT_INFO *));
512void get_mbg_cfgh P((unsigned char **, CFGH *));
513void get_mbg_utc P((unsigned char **, UTC *));
514void get_mbg_lla P((unsigned char **, LLA));
515void get_mbg_xyz P((unsigned char **, XYZ));
516void get_mbg_portparam P((unsigned char **, PORT_PARM *));
517void get_mbg_eph P((unsigned char **, EPH *));
518void get_mbg_alm P((unsigned char **, ALM *));
519void get_mbg_iono P((unsigned char **, IONO *));
520
521unsigned long mbg_csum P((unsigned char *, unsigned int));
522
523#endif
524/*
525 * mbg_gps166.h,v
526 * Revision 4.1  1998/06/12 15:07:30  kardel
527 * fixed prototyping
528 *
529 * Revision 4.0  1998/04/10 19:50:42  kardel
530 * Start 4.0 release version numbering
531 *
532 * Revision 1.1  1998/04/10 19:27:34  kardel
533 * initial NTP VERSION 4 integration of PARSE with GPS166 binary support
534 *
535 * Revision 1.1  1997/10/06 20:55:38  kardel
536 * new parse structure
537 *
538 */
539