mbg_gps166.h revision 2a25cee78ab1d37e7d2bc40ae675646974d99f56
1/*
2 * /src/NTP/REPOSITORY/ntp4-dev/include/mbg_gps166.h,v 4.7 2006/06/22 18:41:43 kardel RELEASE_20060622_A
3 *
4 * mbg_gps166.h,v 4.7 2006/06/22 18:41:43 kardel RELEASE_20060622_A
5 *
6 * $Created: Sun Jul 20 09:20:50 1997 $
7 *
8 * File GPSSERIO.H Copyright (c) by Meinberg Funkuhren (www.meinberg.de)
9 *
10 * Linkage to PARSE:
11 * Copyright (c) 1997-2005 by Frank Kardel <kardel <AT> ntp.org>
12 *
13 * Redistribution and use in source and binary forms, with or without
14 * modification, are permitted provided that the following conditions
15 * are met:
16 * 1. Redistributions of source code must retain the above copyright
17 *    notice, this list of conditions and the following disclaimer.
18 * 2. Redistributions in binary form must reproduce the above copyright
19 *    notice, this list of conditions and the following disclaimer in the
20 *    documentation and/or other materials provided with the distribution.
21 * 3. Neither the name of the author nor the names of its contributors
22 *    may be used to endorse or promote products derived from this software
23 *    without specific prior written permission.
24 *
25 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
26 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
28 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
29 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
30 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
31 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
32 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
33 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
34 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35 * SUCH DAMAGE.
36 *
37 */
38#ifndef MBG_GPS166_H
39#define MBG_GPS166_H
40
41
42/***************************************************************************
43 *
44 *  Definitions taken from Meinberg's gpsserio.h and gpsdefs.h files.
45 *
46 *  Author:  Martin Burnicki, Meinberg Funkuhren
47 *
48 *  Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
49 *
50 *  Description:
51 *    Structures and codes to be used to access Meinberg GPS clocks via
52 *    their serial interface COM0. COM0 should be set to a high baud rate,
53 *    default is 19200.
54 *
55 *    Standard Meinberg GPS serial operation is to send the Meinberg
56 *    standard time string automatically once per second, once per
57 *    minute, or on request per ASCII '?'.
58 *
59 *    GPS parameter setup or parameter readout uses blocks of binary
60 *    data which have to be isolated from the standard string. A block
61 *    of data starts with a SOH code (ASCII Start Of Header, 0x01)
62 *    followed by a message header with constant length and a block of
63 *    data with variable length.
64 *
65 *    The first field (cmd) of the message header holds the command
66 *    code resp. the type of data to be transmitted. The next field (len)
67 *    gives the number of data bytes that follow the header. This number
68 *    ranges from 0 to sizeof( MSG_DATA ). The third field (data_csum)
69 *    holds a checksum of all data bytes and the last field of the header
70 *    finally holds the checksum of the header itself.
71 *
72 ***************************************************************************/
73
74/**
75 * @brief GPS epoch bias from ordinary time_t epoch
76 *
77 * The Unix time_t epoch is usually 1970-01-01 00:00 whereas
78 * the GPS epoch is 1980-01-06 00:00, so the difference is 10 years,
79 * plus 2 days due to leap years (1972 and 1976), plus the difference
80 * of the day-of-month (6 - 1), so:<br>
81 *
82 * time_t t = ( gps_week * ::SECS_PER_WEEK ) + sec_of_week + ::GPS_SEC_BIAS
83 */
84#define GPS_SEC_BIAS   315964800UL     // ( ( ( 10UL * 365UL ) + 2 + 5 ) * SECS_PER_DAY )
85
86
87#ifndef _COM_HS_DEFINED
88  /**
89   * @brief Enumeration of handshake modes
90   */
91  enum COM_HANSHAKE_MODES { HS_NONE, HS_XONXOFF, HS_RTSCTS, N_COM_HS };
92  #define _COM_HS_DEFINED
93#endif
94
95#ifndef _COM_PARM_DEFINED
96  /**
97   * @brief A data type to configure a serial port's baud rate
98   *
99   * @see ::MBG_BAUD_RATES
100   */
101  typedef int32_t BAUD_RATE;
102
103  /**
104   * @brief Indices used to identify a parameter in the framing string
105   *
106   * @see ::MBG_FRAMING_STRS
107   */
108  enum MBG_FRAMING_STR_IDXS { F_DBITS, F_PRTY, F_STBITS };
109
110  /**
111   * @brief A structure to store the configuration of a serial port
112   */
113  typedef struct
114  {
115    BAUD_RATE baud_rate;  ///< transmission speed, e.g. 19200L, see ::MBG_BAUD_RATES
116    char framing[4];      ///< ASCIIZ framing string, e.g. "8N1" or "7E2", see ::MBG_FRAMING_STRS
117    int16_t handshake;    ///< handshake mode, yet only ::HS_NONE supported
118
119  } COM_PARM;
120
121  #define _COM_PARM_DEFINED
122#endif
123
124
125/**
126 * @brief Enumeration of modes supported for time string transmission
127 *
128 * This determines e.g. at which point in time a string starts
129 * to be transmitted via the serial port.
130 * Used with ::PORT_SETTINGS::mode.
131 *
132 * @see ::STR_MODE_MASKS
133 */
134enum STR_MODES
135{
136  STR_ON_REQ,     ///< transmission on request by received '?' character only
137  STR_PER_SEC,    ///< transmission automatically if second changes
138  STR_PER_MIN,    ///< transmission automatically if minute changes
139  STR_AUTO,       ///< transmission automatically if required, e.g. on capture event
140  STR_ON_REQ_SEC, ///< transmission if second changes and a request has been received before
141  N_STR_MODE      ///< the number of known modes
142};
143
144
145/**
146 * The number of serial ports which are at least available
147 * even with very old GPS receiver models. For devices providing
148 * a ::RECEIVER_INFO structure the number of provided COM ports
149 * is available in ::RECEIVER_INFO::n_com_ports.
150 */
151#define DEFAULT_N_COM   2
152
153
154/**
155 * @brief A The structure used to store the configuration of two serial ports
156 *
157 * @deprecated This structure is deprecated, ::PORT_SETTINGS and related structures
158 * should be used instead, if supported by the device.
159 */
160typedef struct
161{
162  COM_PARM com[DEFAULT_N_COM];    ///< COM0 and COM1 settings
163  uint8_t mode[DEFAULT_N_COM];    ///< COM0 and COM1 output mode
164
165} PORT_PARM;
166
167
168/**
169 * @brief The type of a GPS command code
170 *
171 * @see ::GPS_CMD_CODES
172 */
173typedef uint16_t GPS_CMD;
174
175
176/**
177 * @brief Control codes to be or'ed with a particular command/type code
178 */
179enum GPS_CMD_CTRL_CODES
180{
181  GPS_REQACK = 0x8000,   ///< to device: request acknowledge
182  GPS_ACK    = 0x4000,   ///< from device: acknowledge a command
183  GPS_NACK   = 0x2000,   ///< from device: error evaluating a command
184};
185
186#define GPS_CTRL_MSK  0xF000   ///< bit mask of all ::GPS_CMD_CTRL_CODES
187
188
189/**
190 * @brief Command codes for the binary protocol
191 *
192 * These codes specify commands and associated data types used by Meinberg's
193 * binary protocol to exchange data with a device via serial port, direct USB,
194 * or socket I/O.
195 *
196 * Some commands and associated data structures can be read (r) from a device, others
197 * can be written (w) to the device, and some can also be sent automatically (a) by
198 * a device after a ::GPS_AUTO_ON command has been sent to the device.
199 * The individual command codes are marked with (rwa) accordingly, where '-' is used
200 * to indicate that a particular mode is not supported.
201 *
202 * @note Not all command code are supported by all devices.
203 * See the hints for a particular command.
204 *
205 * @note If ::GPS_ALM, ::GPS_EPH or a code named ..._IDX is sent to retrieve
206 * some data from a device then an uint16_t parameter must be also supplied
207 * in order to specify the index number of the data set to be returned.
208 * The valid index range depends on the command code.
209 * For ::GPS_ALM and ::GPS_EPH the index is the SV number which may be 0 or
210 * ::MIN_SVNO_GPS to ::MAX_SVNO_GPS. If the number is 0 then all ::N_SVNO_GPS
211 * almanacs or ephemeris data structures are returned.
212 *
213 * @see ::GPS_CMD_CODES_TABLE
214 */
215enum GPS_CMD_CODES
216{ /* system data */
217  GPS_AUTO_ON = 0x000,  ///< (-w-) no data, enable auto-msgs from device
218  GPS_AUTO_OFF,         ///< (-w-) no data, disable auto-msgs from device
219  GPS_SW_REV,           ///< (r--) deprecated, ::SW_REV, software revision, use only if ::GPS_RECEIVER_INFO not supp.
220  GPS_BVAR_STAT,        ///< (r--) ::BVAR_STAT, status of buffered variables, only if ::GPS_MODEL_HAS_BVAR_STAT
221  GPS_TIME,             ///< (-wa) ::TTM, current time or capture, or init board time
222  GPS_POS_XYZ,          ///< (rw-) ::XYZ, current position in ECEF coordinates, only if ::GPS_MODEL_HAS_POS_XYZ
223  GPS_POS_LLA,          ///< (rw-) ::LLA, current position in geographic coordinates, only if ::GPS_MODEL_HAS_POS_LLA
224  GPS_TZDL,             ///< (rw-) ::TZDL, time zone / daylight saving, only if ::GPS_MODEL_HAS_TZDL
225  GPS_PORT_PARM,        ///< (rw-) deprecated, ::PORT_PARM, use ::PORT_SETTINGS etc. if ::GPS_RECEIVER_INFO supported
226  GPS_SYNTH,            ///< (rw-) ::SYNTH, synthesizer settings, only if ::GPS_HAS_SYNTH
227  GPS_ANT_INFO,         ///< (r-a) ::ANT_INFO, time diff after antenna disconnect, only if ::GPS_MODEL_HAS_ANT_INFO
228  GPS_UCAP,             ///< (r-a) ::TTM, user capture events, only if ::RECEIVER_INFO::n_ucaps > 0
229
230  /* GPS data */
231  GPS_CFGH = 0x100,     ///< (rw-) ::CFGH, SVs' configuration and health codes
232  GPS_ALM,              ///< (rw-) req: uint16_t SV num, ::SV_ALM, one SV's almanac
233  GPS_EPH,              ///< (rw-) req: uint16_t SV num, ::SV_EPH, one SV's ephemeris
234  GPS_UTC,              ///< (rw-) ::UTC, GPS %UTC correction parameters
235  GPS_IONO,             ///< (rw-) ::IONO, GPS ionospheric correction parameters
236  GPS_ASCII_MSG         ///< (r--) ::ASCII_MSG, the GPS ASCII message
237};
238
239
240#ifndef _CSUM_DEFINED
241  typedef uint16_t CSUM;  /* checksum used by some structures stored in non-volatile memory */
242  #define _CSUM_DEFINED
243#endif
244
245
246/**
247 * @brief The header of a binary message.
248 */
249typedef struct
250{
251  GPS_CMD cmd;      ///< see ::GPS_CMD_CODES
252  uint16_t len;     ///< length of the data portion appended after the header
253  CSUM data_csum;   ///< checksum of the data portion appended after the header
254  CSUM hdr_csum;    ///< checksum of the preceding header bytes
255
256} GPS_MSG_HDR;
257
258
259#define GPS_ID_STR_LEN      16
260#define GPS_ID_STR_SIZE     ( GPS_ID_STR_LEN + 1 )
261
262/**
263 * @brief Software revision information
264 *
265 * Contains a software revision code, plus an optional
266 * identifier for a customized version.
267 */
268typedef struct
269{
270  uint16_t code;               ///< Version number, e.g. 0x0120 means v1.20
271  char name[GPS_ID_STR_SIZE];  ///< Optional string identifying a customized version
272  uint8_t reserved;            ///< Reserved field to yield even structure size
273
274} SW_REV;
275
276
277/**
278 * @brief GNSS satellite numbers
279 *
280 * @todo: Check if MAX_SVNO_GLN is 94 instead of 95, and thus
281 *        N_SVNO_GLN is 30 instead of 31, as reported by Wikipedia.
282 */
283enum GNSS_SVNOS
284{
285  MIN_SVNO_GPS = 1,       ///< min. GPS satellite PRN number
286  MAX_SVNO_GPS = 32,      ///< max. GPS satellite PRN number
287  N_SVNO_GPS = 32,        ///< max. number of active GPS satellites
288
289  MIN_SVNO_WAAS = 33,     ///< min. WAAS satellite number
290  MAX_SVNO_WAAS = 64,     ///< max. WAAS satellite number
291  N_SVNO_WAAS = 32,       ///< max. number of active WAAS satellites
292
293  MIN_SVNO_GLONASS = 65,  ///< min. Glonass satellite number (64 + sat slot ID)
294  MAX_SVNO_GLONASS = 95,  ///< max. Glonass satellite number (64 + sat slot ID)
295  N_SVNO_GLONASS = 31     ///< max. number of active Glonass satellites
296};
297
298
299typedef uint16_t SVNO;    ///< the number of an SV (Space Vehicle, i.e. satellite)
300typedef uint16_t HEALTH;  ///< an SV's 6 bit health code
301typedef uint16_t CFG;     ///< an SV's 4 bit configuration code
302typedef uint16_t IOD;     ///< Issue-Of-Data code
303
304
305/**
306 * @brief Status flags of battery buffered data
307 *
308 * Related to data received from the satellites, or data derived thereof.
309 *
310 * All '0' means OK, single bits set to '1' indicate
311 * the associated type of GPS data is not available.
312 *
313 * @see ::BVAR_FLAGS
314 */
315typedef uint16_t BVAR_STAT;
316
317#define _mbg_swab_bvar_stat( _p )  _mbg_swab16( (_p) )
318
319
320/**
321 * @brief Enumeration of flag bits used to define ::BVAR_FLAGS
322 *
323 * For each bit which is set this means the associated data set in
324 * non-volatile memory is not available, or incomplete.
325 * Most data sets will just be re-collected from the data streams sent
326 * by the satellites. However, the receiver position has usually been
327 * computed earlier during normal operation, and will be re-computed
328 * when a sufficient number of satellites can be received.
329 *
330 * @see ::BVAR_STAT
331 * @see ::BVAR_FLAGS
332 * @see ::BVAR_FLAG_NAMES
333 */
334enum BVAR_FLAG_BITS
335{
336  BVAR_BIT_CFGH_INVALID,      ///< Satellite configuration and health parameters incomplete
337  BVAR_BIT_ALM_NOT_COMPLETE,  ///< Almanac parameters incomplete
338  BVAR_BIT_UTC_INVALID,       ///< %UTC offset parameters incomplete
339  BVAR_BIT_IONO_INVALID,      ///< Ionospheric correction parameters incomplete
340  BVAR_BIT_RCVR_POS_INVALID,  ///< No valid receiver position available
341  N_BVAR_BIT                  ///< number of defined ::BVAR_STAT bits
342};
343
344
345/**
346 * @brief Bit masks associated with ::BVAR_FLAG_BITS
347 *
348 * Used with ::BVAR_STAT.
349 *
350 * @see ::BVAR_STAT
351 * @see ::BVAR_FLAG_BITS
352 * @see ::BVAR_FLAG_NAMES
353 */
354enum BVAR_FLAGS
355{
356  BVAR_CFGH_INVALID     = ( 1UL << BVAR_BIT_CFGH_INVALID ),      ///< see ::BVAR_BIT_CFGH_INVALID
357  BVAR_ALM_NOT_COMPLETE = ( 1UL << BVAR_BIT_ALM_NOT_COMPLETE ),  ///< see ::BVAR_BIT_ALM_NOT_COMPLETE
358  BVAR_UTC_INVALID      = ( 1UL << BVAR_BIT_UTC_INVALID ),       ///< see ::BVAR_BIT_UTC_INVALID
359  BVAR_IONO_INVALID     = ( 1UL << BVAR_BIT_IONO_INVALID ),      ///< see ::BVAR_BIT_IONO_INVALID
360  BVAR_RCVR_POS_INVALID = ( 1UL << BVAR_BIT_RCVR_POS_INVALID ),  ///< see ::BVAR_BIT_RCVR_POS_INVALID
361};
362
363
364/**
365 * @brief A structure used to hold time in GPS format
366 *
367 * Date and time refer to the linear time scale defined by GPS, with
368 * the epoch starting at %UTC midnight at the beginning of January 6, 1980.
369 *
370 * GPS time is counted by the week numbers since the epoch, plus second
371 * of the week, plus fraction of the second. The week number transmitted
372 * by the satellites rolls over from 1023 to 0, but Meinberg devices
373 * just continue to count the weeks beyond the 1024 week limit to keep
374 * the receiver's internal time.
375 *
376 * %UTC time differs from GPS time since a number of leap seconds have
377 * been inserted in the %UTC time scale after the GPS epoche. The number
378 * of leap seconds is disseminated by the satellites using the ::UTC
379 * parameter set, which also provides info on pending leap seconds.
380 */
381typedef struct
382{
383  uint16_t wn;     ///< the week number since GPS has been installed
384  uint32_t sec;    ///< the second of that week
385  uint32_t tick;   ///< fractions of a second, 1/::RECEIVER_INFO::ticks_per_sec units
386
387} T_GPS;
388
389
390/**
391 * @brief Local date and time computed from GPS time
392 *
393 * The current number of leap seconds have to be added to get %UTC
394 * from GPS time. Additional corrections could have been made according
395 * to the time zone/daylight saving parameters ::TZDL defined by the user.
396 * The status field can be checked to see which corrections
397 * have actually been applied.
398 *
399 * @note Conversion from GPS time to %UTC and/or local time can only be
400 * done if some valid ::UTC correction parameters are available in the
401 * receiver's non-volatile memory.
402 */
403typedef struct
404{
405  int16_t year;           ///< year number, 0..9999
406  int8_t month;           ///< month, 1..12
407  int8_t mday;            ///< day of month, 1..31
408  int16_t yday;           ///< day of year, 1..365, or 366 in case of leap year
409  int8_t wday;            ///< day of week, 0..6 == Sun..Sat
410  int8_t hour;            ///< hours, 0..23
411  int8_t min;             ///< minutes, 0..59
412  int8_t sec;             ///< seconds, 0..59, or 60 in case of inserted leap second
413  int32_t frac;           ///< fractions of a second, 1/::RECEIVER_INFO::ticks_per_sec units
414  int32_t offs_from_utc;  ///< local time offset from %UTC [sec]
415  uint16_t status;        ///< status flags, see ::TM_GPS_STATUS_BIT_MASKS
416
417} TM_GPS;
418
419
420
421/**
422 * @brief Status flag bits used to define ::TM_GPS_STATUS_BIT_MASKS
423 *
424 * These bits report info on the time conversion from GPS time to %UTC
425 * and/or local time as well as device status info.
426 *
427 * @see ::TM_GPS_STATUS_BIT_MASKS
428 */
429enum TM_GPS_STATUS_BITS
430{
431  TM_BIT_UTC,          ///< %UTC correction has been made
432  TM_BIT_LOCAL,        ///< %UTC has been converted to local time according to ::TZDL settings
433  TM_BIT_DL_ANN,       ///< state of daylight saving is going to change
434  TM_BIT_DL_ENB,       ///< daylight saving is in effect
435  TM_BIT_LS_ANN,       ///< leap second pending
436  TM_BIT_LS_ENB,       ///< current second is leap second
437  TM_BIT_LS_ANN_NEG,   ///< set in addition to ::TM_BIT_LS_ANN if leap sec is negative
438  TM_BIT_INVT,         ///< invalid time, e.g. if RTC battery bas been empty
439
440  TM_BIT_EXT_SYNC,     ///< synchronized externally
441  TM_BIT_HOLDOVER,     ///< in holdover mode after previous synchronization
442  TM_BIT_ANT_SHORT,    ///< antenna cable short circuited
443  TM_BIT_NO_WARM,      ///< OCXO has not warmed up
444  TM_BIT_ANT_DISCONN,  ///< antenna currently disconnected
445  TM_BIT_SYN_FLAG,     ///< TIME_SYN output is low
446  TM_BIT_NO_SYNC,      ///< time sync actually not verified
447  TM_BIT_NO_POS        ///< position actually not verified, LOCK LED off
448};
449
450
451/**
452 * @brief Status flag masks used with ::TM_GPS::status
453 *
454 * These bits report info on the time conversion from GPS time to %UTC
455 * and/or local time as well as device status info.
456 *
457 * @see ::TM_GPS_STATUS_BITS
458 */
459enum TM_GPS_STATUS_BIT_MASKS
460{
461  TM_UTC         = ( 1UL << TM_BIT_UTC ),          ///< see ::TM_BIT_UTC
462  TM_LOCAL       = ( 1UL << TM_BIT_LOCAL ),        ///< see ::TM_BIT_LOCAL
463  TM_DL_ANN      = ( 1UL << TM_BIT_DL_ANN ),       ///< see ::TM_BIT_DL_ANN
464  TM_DL_ENB      = ( 1UL << TM_BIT_DL_ENB ),       ///< see ::TM_BIT_DL_ENB
465  TM_LS_ANN      = ( 1UL << TM_BIT_LS_ANN ),       ///< see ::TM_BIT_LS_ANN
466  TM_LS_ENB      = ( 1UL << TM_BIT_LS_ENB ),       ///< see ::TM_BIT_LS_ENB
467  TM_LS_ANN_NEG  = ( 1UL << TM_BIT_LS_ANN_NEG ),   ///< see ::TM_BIT_LS_ANN_NEG
468  TM_INVT        = ( 1UL << TM_BIT_INVT ),         ///< see ::TM_BIT_INVT
469
470  TM_EXT_SYNC    = ( 1UL << TM_BIT_EXT_SYNC ),     ///< see ::TM_BIT_EXT_SYNC
471  TM_HOLDOVER    = ( 1UL << TM_BIT_HOLDOVER ),     ///< see ::TM_BIT_HOLDOVER
472  TM_ANT_SHORT   = ( 1UL << TM_BIT_ANT_SHORT ),    ///< see ::TM_BIT_ANT_SHORT
473  TM_NO_WARM     = ( 1UL << TM_BIT_NO_WARM ),      ///< see ::TM_BIT_NO_WARM
474  TM_ANT_DISCONN = ( 1UL << TM_BIT_ANT_DISCONN ),  ///< see ::TM_BIT_ANT_DISCONN
475  TM_SYN_FLAG    = ( 1UL << TM_BIT_SYN_FLAG ),     ///< see ::TM_BIT_SYN_FLAG
476  TM_NO_SYNC     = ( 1UL << TM_BIT_NO_SYNC ),      ///< see ::TM_BIT_NO_SYNC
477  TM_NO_POS      = ( 1UL << TM_BIT_NO_POS )        ///< see ::TM_BIT_NO_POS
478};
479
480
481/**
482 * @brief A structure used to transmit information on date and time
483 *
484 * This structure can be used to transfer the current time, in which
485 * case the channel field has to be set to -1, or an event capture time
486 * retrieved from the on-board FIFO, in which case the channel field
487 * contains the index of the time capture input, e.g. 0 or 1.
488 */
489typedef struct
490{
491  int16_t channel;  ///< -1: the current on-board time; >= 0 the capture channel number
492  T_GPS t;          ///< time in GPS scale and format
493  TM_GPS tm;        ///< time converted to %UTC and/or local time according to ::TZDL settings
494
495} TTM;
496
497
498
499/* Two types of variables used to store a position. Type XYZ is */
500/* used with a position in earth centered, earth fixed (ECEF) */
501/* coordinates whereas type LLA holds such a position converted */
502/* to geographic coordinates as defined by WGS84 (World Geodetic */
503/* System from 1984). */
504
505/**
506 * @brief Sequence and number of components of a cartesian position
507 */
508enum XYZ_FIELDS { XP, YP, ZP, N_XYZ };  // x, y, z
509
510/**
511 * @brief A position in cartesian coordinates
512 *
513 * Usually earth centered, earth fixed (ECEF) coordinates,
514 * in [m].
515 *
516 * @note In the original code this is an array of double.
517 *
518 * @see ::XYZ_FIELDS
519 */
520typedef l_fp XYZ[N_XYZ];
521
522
523/**
524 * @brief Sequence and number of components of a geographic position
525 */
526enum LLA_FIELDS { LAT, LON, ALT, N_LLA };  /* latitude, longitude, altitude */
527
528/**
529 * @brief A geographic position based on latitude, longitude, and altitude
530 *
531 * The geographic position associated to specific cartesian coordinates
532 * depends on the characteristics of the ellipsoid used for the computation,
533 * the so-called geographic datum. GPS uses the WGS84 (World Geodetic System
534 * from 1984) ellipsoid by default.
535 *
536 * lon, lat in [rad], alt in [m]
537 *
538 * @note In the original code this is an array of double.
539 *
540 * @see ::LLA_FIELDS
541 */
542typedef l_fp LLA[N_LLA];
543
544
545/**
546 * @defgroup group_synth Synthesizer parameters
547 *
548 * Synthesizer frequency is expressed as a
549 * four digit decimal number (freq) to be multiplied by 0.1 Hz and an
550 * base 10 exponent (range). If the effective frequency is less than
551 * 10 kHz its phase is synchronized corresponding to the variable phase.
552 * Phase may be in a range from -360 deg to +360 deg with a resolution
553 * of 0.1 deg, so the resulting numbers to be stored are in a range of
554 * -3600 to +3600.
555 *
556 * Example:<br>
557 * Assume the value of freq is 2345 (decimal) and the value of phase is 900.
558 * If range == 0 the effective frequency is 234.5 Hz with a phase of +90 deg.
559 * If range == 1 the synthesizer will generate a 2345 Hz output frequency
560 * and so on.
561 *
562 * Limitations:<br>
563 * If freq == 0 the synthesizer is disabled. If range == 0 the least
564 * significant digit of freq is limited to 0, 3, 5 or 6. The resulting
565 * frequency is shown in the examples below:
566 *    - freq == 1230  -->  123.0 Hz
567 *    - freq == 1233  -->  123 1/3 Hz (real 1/3 Hz, NOT 123.3 Hz)
568 *    - freq == 1235  -->  123.5 Hz
569 *    - freq == 1236  -->  123 2/3 Hz (real 2/3 Hz, NOT 123.6 Hz)
570 *
571 * If range == ::MAX_SYNTH_RANGE the value of freq must not exceed 1000, so
572 * the output frequency is limited to 10 MHz (see ::MAX_SYNTH_FREQ_VAL).
573 *
574 * @{ */
575
576#define N_SYNTH_FREQ_DIGIT  4    ///< number of digits to edit
577#define MAX_SYNTH_FREQ   1000    ///< if range == ::MAX_SYNTH_RANGE
578
579#define MIN_SYNTH_RANGE     0
580#define MAX_SYNTH_RANGE     5
581#define N_SYNTH_RANGE       ( MAX_SYNTH_RANGE - MIN_SYNTH_RANGE + 1 )
582
583#define N_SYNTH_PHASE_DIGIT  4
584#define MAX_SYNTH_PHASE      3600
585
586
587#define MAX_SYNTH_FREQ_EDIT  9999  ///< max sequence of digits when editing
588
589
590/**
591 * @brief The maximum frequency that can be configured for the synthesizer
592 */
593#define MAX_SYNTH_FREQ_VAL   10000000UL     ///< 10 MHz
594/*   == MAX_SYNTH_FREQ * 10^(MAX_SYNTH_RANGE-1) */
595
596/**
597 * @brief The synthesizer's phase is only be synchronized if the frequency is below this limit
598 */
599#define SYNTH_PHASE_SYNC_LIMIT   10000UL    ///< 10 kHz
600
601/**
602 * A Macro used to determine the position of the decimal point
603 * when printing the synthesizer frequency as 4 digit value
604 */
605#define _synth_dp_pos_from_range( _r ) \
606  ( ( ( N_SYNTH_RANGE - (_r) ) % ( N_SYNTH_FREQ_DIGIT - 1 ) ) + 1 )
607
608/**
609 * @brief Synthesizer frequency units
610 *
611 * An initializer for commonly displayed synthesizer frequency units
612 * (::N_SYNTH_RANGE strings)
613 */
614#define DEFAULT_FREQ_RANGES \
615{                           \
616  "Hz",                     \
617  "kHz",                    \
618  "kHz",                    \
619  "kHz",                    \
620  "MHz",                    \
621  "MHz",                    \
622}
623
624
625
626/**
627 * @brief Synthesizer configuration parameters
628 */
629typedef struct
630{
631  int16_t freq;    ///< four digits used; scale: 0.1 Hz; e.g. 1234 -> 123.4 Hz
632  int16_t range;   ///< scale factor for freq; 0..::MAX_SYNTH_RANGE
633  int16_t phase;   ///< -::MAX_SYNTH_PHASE..+::MAX_SYNTH_PHASE; >0 -> pulses later
634
635} SYNTH;
636
637#define _mbg_swab_synth( _p )   \
638{                               \
639  _mbg_swab16( &(_p)->freq );   \
640  _mbg_swab16( &(_p)->range );  \
641  _mbg_swab16( &(_p)->phase );  \
642}
643
644
645/**
646 * @brief Enumeration of synthesizer states
647 */
648enum SYNTH_STATES
649{
650  SYNTH_DISABLED,   ///< disbled by cfg, i.e. freq == 0.0
651  SYNTH_OFF,        ///< not enabled after power-up
652  SYNTH_FREE,       ///< enabled, but not synchronized
653  SYNTH_DRIFTING,   ///< has initially been sync'd, but now running free
654  SYNTH_SYNC,       ///< fully synchronized
655  N_SYNTH_STATE     ///< the number of known states
656};
657
658
659/**
660 * @brief A structure used to report the synthesizer state
661 */
662typedef struct
663{
664  uint8_t state;     ///< state code as enumerated in ::SYNTH_STATES
665  uint8_t flags;     ///< reserved, currently always 0
666
667} SYNTH_STATE;
668
669#define _mbg_swab_synth_state( _p )  _nop_macro_fnc()
670
671#define SYNTH_FLAG_PHASE_IGNORED  0x01
672
673/** @} defgroup group_synth */
674
675
676
677/**
678 * @defgroup group_tzdl Time zone / daylight saving parameters
679 *
680 * Example: <br>
681 * For automatic daylight saving enable/disable in Central Europe,
682 * the variables are to be set as shown below: <br>
683 *   - offs = 3600L           one hour from %UTC
684 *   - offs_dl = 3600L        one additional hour if daylight saving enabled
685 *   - tm_on = first Sunday from March 25, 02:00:00h ( year |= ::DL_AUTO_FLAG )
686 *   - tm_off = first Sunday from October 25, 03:00:00h ( year |= ::DL_AUTO_FLAG )
687 *   - name[0] == "CET  "     name if daylight saving not enabled
688 *   - name[1] == "CEST "     name if daylight saving is enabled
689 *
690 * @{ */
691
692/**
693 * @brief The name of a time zone
694 *
695 * @note Up to 5 printable characters, plus trailing zero
696 */
697typedef char TZ_NAME[6];
698
699/**
700 * @brief Time zone / daylight saving parameters
701 *
702 * This structure is used to specify how a device converts on-board %UTC
703 * to local time, including computation of beginning and end of daylight
704 * saving time (DST), if required.
705 *
706 * @note The ::TZDL structure contains members of type ::TM_GPS to specify
707 * the times for beginning and end of DST. However, the ::TM_GPS::frac,
708 * ::TM_GPS::offs_from_utc, and ::TM_GPS::status fields of these ::TZDL::tm_on
709 * and ::TZDL::tm_off members are ignored for the conversion to local time,
710 * and thus should be 0.
711 */
712typedef struct
713{
714  int32_t offs;      ///< standard offset from %UTC to local time [sec]
715  int32_t offs_dl;   ///< additional offset if daylight saving enabled [sec]
716  TM_GPS tm_on;      ///< date/time when daylight saving starts
717  TM_GPS tm_off;     ///< date/time when daylight saving ends
718  TZ_NAME name[2];   ///< names without and with daylight saving enabled
719
720} TZDL;
721
722/**
723 * @brief A flag indicating automatic computation of DST
724 *
725 * If this flag is or'ed to the year numbers in ::TZDL::tm_on and ::TZDL::tm_off
726 * then daylight saving is computed automatically year by year.
727 */
728#define DL_AUTO_FLAG  0x8000
729
730/** @} defgroup group_tzdl */
731
732
733
734/**
735 * @brief Antenna status and error at reconnect information
736 *
737 * The structure below reflects the status of the antenna,
738 * the times of last disconnect/reconnect, and the board's
739 * clock offset when it has synchronized again after the
740 * disconnection interval.
741 *
742 * @note ::ANT_INFO::status changes back to ::ANT_RECONN only
743 * after the antenna has been reconnected <b>and</b> the
744 * receiver has re-synchronized to the satellite signal.
745 * In this case ::ANT_INFO::delta_t reports the time offset
746 * before resynchronization, i.e. how much the internal
747 * time has drifted while the antenna was disconnected.
748 */
749typedef struct
750{
751  int16_t status;      ///< current status of antenna, see ::ANT_STATUS_CODES
752  TM_GPS tm_disconn;   ///< time of antenna disconnect
753  TM_GPS tm_reconn;    ///< time of antenna reconnect
754  int32_t delta_t;     ///< clock offs at reconn. time in 1/::RECEIVER_INFO::ticks_per_sec units
755
756} ANT_INFO;
757
758
759/**
760 * @brief Status code used with ::ANT_INFO::status
761 */
762enum ANT_STATUS_CODES
763{
764  ANT_INVALID,   ///< No other fields valid since antenna has not yet been disconnected
765  ANT_DISCONN,   ///< Antenna is disconnected, tm_reconn and delta_t not yet set
766  ANT_RECONN,    ///< Antenna has been disconnect, and receiver sync. after reconnect, so all fields valid
767  N_ANT_STATUS_CODES  ///< the number of known status codes
768};
769
770
771
772/**
773 * @brief Summary of configuration and health data of all satellites
774 */
775typedef struct
776{
777  CSUM csum;                  ///< checksum of the remaining bytes
778  int16_t valid;              ///< flag data are valid
779
780  T_GPS tot_51;               ///< time of transmission, page 51
781  T_GPS tot_63;               ///< time of transmission, page 63
782  T_GPS t0a;                  ///< complete reference time almanac
783
784  CFG cfg[N_SVNO_GPS];        ///< 4 bit SV configuration code from page 63
785  HEALTH health[N_SVNO_GPS];  ///< 6 bit SV health codes from pages 51, 63
786
787} CFGH;
788
789
790
791/**
792 * @brief GPS %UTC correction parameters
793 *
794 * %UTC correction parameters basically as sent by the GPS satellites.
795 *
796 * The csum field is only used by the card's firmware to check the
797 * consistency of the structure in non-volatile memory.
798 *
799 * The field labeled valid indicates if the parameter set is valid, i.e.
800 * if it contains data received from the satellites.
801 *
802 * t0t, A0 and A1 contain fractional correction parameters for the current
803 * GPS-%UTC time offset in addition to the whole seconds. This is evaluated
804 * by the receivers' firmware to convert GPS time to %UTC time.
805 *
806 * The delta_tls field contains the current full seconds offset between
807 * GPS time and %UTC, which corresponds to the number of leap seconds inserted
808 * into the %UTC time scale since GPS was put into operation in January 1980.
809 *
810 * delta_tlfs holds the number of "future" leap seconds, i.e. the %UTC offset
811 * after the next leap second event defined by WNlsf and DNt.
812 *
813 * The fields WNlsf and DNt specify the GPS week number and the day number
814 * in that week for the end of which a leap second has been scheduled.
815 *
816 * @note: The satellites transmit WNlsf only as a signed 8 bit value, so it
817 * can only define a point in time which is +/- 127 weeks off the current time.
818 * The firmware tries to expand this based on the current week number, but
819 * the result is ambiguous if the leap second occurs or occurred more
820 * than 127 weeks in the future or past.
821 *
822 * So the leap second date should <b>only</b> be evaluated and displayed
823 * in a user interface if the fields delta_tls and delta_tlsf have
824 * different values, in which case there is indeed a leap second announcement
825 * inside the +/- 127 week range.
826 *
827 * @note In the original code the type of A0 and A1 is double.
828 */
829typedef struct
830{
831  CSUM csum;          ///<  Checksum of the remaining bytes
832  int16_t valid;      ///<  Flag indicating %UTC parameters are valid
833
834  T_GPS t0t;          ///<  Reference Time %UTC Parameters [wn|sec]
835  l_fp A0;            ///<  +- Clock Correction Coefficient 0 [sec]
836  l_fp A1;            ///<  +- Clock Correction Coefficient 1 [sec/sec]
837
838  uint16_t WNlsf;     ///<  Week number of nearest leap second
839  int16_t DNt;        ///<  The day number at the end of which a leap second occurs
840  int8_t delta_tls;   ///<  Current %UTC offset to GPS system time [sec]
841  int8_t delta_tlsf;  ///<  Future %UTC offset to GPS system time after next leap second transition [sec]
842
843} UTC;
844
845
846/**
847 * @brief GPS ASCII message
848 */
849typedef struct
850{
851  CSUM csum;       ///< checksum of the remaining bytes */
852  int16_t valid;   ///< flag data are valid
853  char s[23];      ///< 22 chars GPS ASCII message plus trailing zero
854
855} ASCII_MSG;
856
857
858/**
859 * @brief Ephemeris parameters of one specific satellite
860 *
861 * Needed to compute the position of a satellite at a given time with
862 * high precision. Valid for an interval of 4 to 6 hours from start
863 * of transmission.
864 */
865typedef struct
866{
867  CSUM csum;       ///<    checksum of the remaining bytes
868  int16_t valid;   ///<    flag data are valid
869
870  HEALTH health;   ///<    health indication of transmitting SV      [---]
871  IOD IODC;        ///<    Issue Of Data, Clock
872  IOD IODE2;       ///<    Issue of Data, Ephemeris (Subframe 2)
873  IOD IODE3;       ///<    Issue of Data, Ephemeris (Subframe 3)
874  T_GPS tt;        ///<    time of transmission
875  T_GPS t0c;       ///<    Reference Time Clock                      [---]
876  T_GPS t0e;       ///<    Reference Time Ephemeris                  [---]
877
878  l_fp sqrt_A;     ///<    Square Root of semi-major Axis        [sqrt(m)]
879  l_fp e;          ///<    Eccentricity                              [---]
880  l_fp M0;         ///< +- Mean Anomaly at Ref. Time                 [rad]
881  l_fp omega;      ///< +- Argument of Perigee                       [rad]
882  l_fp OMEGA0;     ///< +- Longit. of Asc. Node of orbit plane       [rad]
883  l_fp OMEGADOT;   ///< +- Rate of Right Ascension               [rad/sec]
884  l_fp deltan;     ///< +- Mean Motion Diff. from computed value [rad/sec]
885  l_fp i0;         ///< +- Inclination Angle                         [rad]
886  l_fp idot;       ///< +- Rate of Inclination Angle             [rad/sec]
887  l_fp crc;        ///< +- Cosine Corr. Term to Orbit Radius           [m]
888  l_fp crs;        ///< +- Sine Corr. Term to Orbit Radius             [m]
889  l_fp cuc;        ///< +- Cosine Corr. Term to Arg. of Latitude     [rad]
890  l_fp cus;        ///< +- Sine Corr. Term to Arg. of Latitude       [rad]
891  l_fp cic;        ///< +- Cosine Corr. Term to Inclination Angle    [rad]
892  l_fp cis;        ///< +- Sine Corr. Term to Inclination Angle      [rad]
893
894  l_fp af0;        ///< +- Clock Correction Coefficient 0            [sec]
895  l_fp af1;        ///< +- Clock Correction Coefficient 1        [sec/sec]
896  l_fp af2;        ///< +- Clock Correction Coefficient 2      [sec/sec^2]
897  l_fp tgd;        ///< +- estimated group delay differential        [sec]
898
899  uint16_t URA;    ///<    predicted User Range Accuracy
900
901  uint8_t L2code;  ///<    code on L2 channel                         [---]
902  uint8_t L2flag;  ///<    L2 P data flag                             [---]
903
904} EPH;
905
906
907
908/**
909 * @brief Almanac parameters of one specific satellite
910 *
911 * A reduced precision set of parameters used to check if a satellite
912 * is in view at a given time. Valid for an interval of more than 7 days
913 * from start of transmission.
914 */
915typedef struct
916{
917  CSUM csum;       ///<    checksum of the remaining bytes
918  int16_t valid;   ///<    flag data are valid
919
920  HEALTH health;   ///<                                               [---]
921  T_GPS t0a;       ///<    Reference Time Almanac                     [sec]
922
923  l_fp sqrt_A;     ///<    Square Root of semi-major Axis         [sqrt(m)]
924  l_fp e;          ///<    Eccentricity                               [---]
925
926  l_fp M0;         ///< +- Mean Anomaly at Ref. Time                  [rad]
927  l_fp omega;      ///< +- Argument of Perigee                        [rad]
928  l_fp OMEGA0;     ///< +- Longit. of Asc. Node of orbit plane        [rad]
929  l_fp OMEGADOT;   ///< +- Rate of Right Ascension                [rad/sec]
930  l_fp deltai;     ///< +-                                            [rad]
931  l_fp af0;        ///< +- Clock Correction Coefficient 0             [sec]
932  l_fp af1;        ///< +- Clock Correction Coefficient 1         [sec/sec]
933
934} ALM;
935
936
937
938/**
939 * @brief Ionospheric correction parameters
940 */
941typedef struct
942{
943  CSUM csum;       ///<    checksum of the remaining bytes
944  int16_t valid;   ///<    flag data are valid
945
946  l_fp alpha_0;    ///<    Ionosph. Corr. Coeff. Alpha 0              [sec]
947  l_fp alpha_1;    ///<    Ionosph. Corr. Coeff. Alpha 1          [sec/deg]
948  l_fp alpha_2;    ///<    Ionosph. Corr. Coeff. Alpha 2        [sec/deg^2]
949  l_fp alpha_3;    ///<    Ionosph. Corr. Coeff. Alpha 3        [sec/deg^3]
950
951  l_fp beta_0;     ///<    Ionosph. Corr. Coeff. Beta 0               [sec]
952  l_fp beta_1;     ///<    Ionosph. Corr. Coeff. Beta 1           [sec/deg]
953  l_fp beta_2;     ///<    Ionosph. Corr. Coeff. Beta 2         [sec/deg^2]
954  l_fp beta_3;     ///<    Ionosph. Corr. Coeff. Beta 3         [sec/deg^3]
955
956} IONO;
957
958
959
960void mbg_tm_str (char **, TM_GPS *, int, int);
961void mbg_tgps_str (char **, T_GPS *, int);
962void get_mbg_header (unsigned char **, GPS_MSG_HDR *);
963void put_mbg_header (unsigned char **, GPS_MSG_HDR *);
964void get_mbg_sw_rev (unsigned char **, SW_REV *);
965void get_mbg_ascii_msg (unsigned char **, ASCII_MSG *);
966void get_mbg_svno (unsigned char **, SVNO *);
967void get_mbg_health (unsigned char **, HEALTH *);
968void get_mbg_cfg (unsigned char **, CFG *);
969void get_mbg_tgps (unsigned char **, T_GPS *);
970void get_mbg_tm (unsigned char **, TM_GPS *);
971void get_mbg_ttm (unsigned char **, TTM *);
972void get_mbg_synth (unsigned char **, SYNTH *);
973void get_mbg_tzdl (unsigned char **, TZDL *);
974void get_mbg_antinfo (unsigned char **, ANT_INFO *);
975void get_mbg_cfgh (unsigned char **, CFGH *);
976void get_mbg_utc (unsigned char **, UTC *);
977void get_mbg_lla (unsigned char **, LLA);
978void get_mbg_xyz (unsigned char **, XYZ);
979void get_mbg_portparam (unsigned char **, PORT_PARM *);
980void get_mbg_eph (unsigned char **, EPH *);
981void get_mbg_alm (unsigned char **, ALM *);
982void get_mbg_iono (unsigned char **, IONO *);
983
984CSUM mbg_csum (unsigned char *, unsigned int);
985
986#endif
987/*
988 * History:
989 *
990 * mbg_gps166.h,v
991 * Revision 4.7  2006/06/22 18:41:43  kardel
992 * clean up signedness (gcc 4)
993 *
994 * Revision 4.6  2005/10/07 22:11:56  kardel
995 * bounded buffer implementation
996 *
997 * Revision 4.5.2.1  2005/09/25 10:23:48  kardel
998 * support bounded buffers
999 *
1000 * Revision 4.5  2005/06/25 10:58:45  kardel
1001 * add missing log keywords
1002 *
1003 * Revision 4.1  1998/06/12 15:07:30  kardel
1004 * fixed prototyping
1005 *
1006 * Revision 4.0  1998/04/10 19:50:42  kardel
1007 * Start 4.0 release version numbering
1008 *
1009 * Revision 1.1  1998/04/10 19:27:34  kardel
1010 * initial NTP VERSION 4 integration of PARSE with GPS166 binary support
1011 *
1012 * Revision 1.1  1997/10/06 20:55:38  kardel
1013 * new parse structure
1014 *
1015 */
1016