diff options
Diffstat (limited to 'mbglib/common/gpsserio.h')
| -rw-r--r-- | mbglib/common/gpsserio.h | 1225 |
1 files changed, 918 insertions, 307 deletions
diff --git a/mbglib/common/gpsserio.h b/mbglib/common/gpsserio.h index 494f125..a3d5c3a 100644 --- a/mbglib/common/gpsserio.h +++ b/mbglib/common/gpsserio.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: gpsserio.h 1.34 2011/04/15 13:12:02 martin REL_M $ + * $Id: gpsserio.h 1.48.1.1 2015/07/24 11:07:39 martin TEST $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -31,6 +31,62 @@ * * ----------------------------------------------------------------------- * $Log: gpsserio.h $ + * Revision 1.48.1.1 2015/07/24 11:07:39 martin + * Revision 1.48 2015/07/06 15:23:51 martin + * Updated function prototypes. + * Revision 1.47 2015/05/13 13:52:57 martin + * Support XBP addressing. + * Fixed misspelled MBG_XFER_MODE_ENCRYPTED. + * Renamed some GPS cmd codes to more intuitive names. + * Added GPS cmd CMD codes for FDM. + * New cmd code GPS_XMR_EXT_SRC_INFO_IDX. + * Removed trailing whitespace. + * Updated doxygen-style comments. + * Updated function prototypes. + * Revision 1.46 2014/07/17 09:47:21 martin + * New command codes GPS_GPIO_STATUS_IDX + * and GPS_XMR_HOLDOVER_STATUS. + * Updated doxygen comments. + * Revision 1.45 2014/05/27 08:58:47 martin + * Defined a some new command codes and added + * associated fields to MSG_DATA union. + * Introduced MBG_SOCK_FD type. + * Use new preprocessor symbol MBG_TGT_POSIX. + * Support new libusb. + * Conditional FTDI serial interface support. + * Account for definitions renamed elsewhere. + * Simplified declaration of code/name tables. + * Conditionally use new CHK_TSTR_FNC type. + * Huge rework of comments in doxygen format. + * Revision 1.44 2013/04/04 09:03:29Z martin + * Support HaveQuick configuration. + * Revision 1.43 2013/01/30 16:07:49 martin + * Changed definition of transfer status codes to an enum + * with appropriate comments. + * Added union TZCODE_UNION. + * Fixed some doxygen comments. + * Revision 1.42 2013/01/16 11:48:36Z martin + * Support IMS and XMR_HOLDOVER_INTV. + * Revision 1.41 2012/10/30 16:25:15 martin + * Added GPS_WILDCARD cmd code. + * Account for changed chk_tstr_func return code. + * Added completion codes TR_COMPLETE_TSTR and TR_RCVD_NACK. + * Revision 1.40 2012/04/11 16:03:29 martin + * Fixed some doxygen stuff. + * Revision 1.39 2012/03/08 15:34:18Z martin + * Added default setting for _USE_USB_IO. + * Revision 1.38 2012/03/06 15:33:43 martin + * Added support for SCU and LNO. + * Account for modified chk_tstr() parameters. + * Revision 1.37 2011/11/25 14:59:17Z martin + * Account for some renamed evt_log library symbols. + * Revision 1.36 2011/11/25 10:37:10 martin + * Added commands and data structures to support log events. + * Revision 1.35 2011/07/29 09:46:54 daniel + * Use native alignment only. + * Added command code GPS_XMR_INSTANCES. + * Support GPIO configuration. + * Support for USB. * Revision 1.34 2011/04/15 13:12:02 martin * Added initializer for command name table. * Unified mutex stuff using macros from mbgmutex.h. @@ -61,7 +117,7 @@ * Now _USE_PCPSDEFS by default for non-firmware apps. * Fixed comments on GPS_OPT_SETTINGS and GPS_OPT_INFO. * Revision 1.25 2007/02/06 16:31:04Z martin - * Modified comment for PZF_PCPS_TIME which can now also + * Modified comment for PZF_PCPS_TIME which can now also * be sent to a device. * Added mutex support. * Added SVNO to the buffer union. @@ -91,7 +147,7 @@ * Revision 1.19 2006/06/15 10:39:49Z martin * Added some special types to the MSG_DATA union which have * previously been defined as generic uint16_t types. - * Removed MBG_OPT_SETTINGS and MBG_OPT_INFO from + * Removed MBG_OPT_SETTINGS and MBG_OPT_INFO from * the MSG_DATA union since those types are not used with * the binary protocol. * Revision 1.18 2006/05/18 09:43:35Z martin @@ -100,7 +156,7 @@ * Renamed IRIG_... symbols to IRIG_TX_... in order to distinguish * from IRIG input configuration which might be available in the future. * Added some fields to the MSG_DATA union. - * Renamed MSG_BUFF field "data" to "msg_data" in order to avoid + * Renamed MSG_BUFF field "data" to "msg_data" in order to avoid * conflict with reserved word in some environments. * Rewrote inclusion control macros. * Replace control of inclusion of function prototypes by new symbol @@ -124,7 +180,7 @@ * Don't include function prototypes by default if compiling firmware. * Conditionally support private data structures, automatically include * those definitions if compiling firmware. - * The data portion of MSG_BUFF is now a union whose maximum size + * The data portion of MSG_BUFF is now a union whose maximum size * can be overridden by a preprocessor value. * Added MBG_OPT_SETTINGS and MBG_OPT_INFO to the buffer union. * Updated function prototypes. @@ -186,7 +242,7 @@ #ifndef _USE_MUTEX #if defined( MBG_TGT_WIN32 ) #define _USE_MUTEX 1 - #elif defined( MBG_TGT_UNIX ) + #elif defined( MBG_TGT_POSIX ) #define _USE_MUTEX 1 #endif #endif @@ -204,24 +260,52 @@ /* Control whether serial port communication shall be supported */ #ifndef _USE_SERIAL_IO #if _IS_MBG_FIRMWARE - #define _USE_SERIAL_IO 0 // Firmware provides its own serial I/O functions + #define _USE_SERIAL_IO 0 // firmware provides its own serial I/O functions #else - #define _USE_SERIAL_IO 1 // supported by default + #define _USE_SERIAL_IO 1 // supported by default + #endif +#endif + +#ifndef _USE_SERIAL_IO_FTDI + // FTDI D2xx USB-To-Serial converters accessed via a proprietary DLL + #define _USE_SERIAL_IO_FTDI 0 // not supported by default +#endif + +/* Control whether USB communication shall be supported */ +#if defined( MBG_TGT_LINUX ) + #ifndef _USE_USB_IO // may be overridden by project settings + #define _USE_USB_IO 0 // not supported by default #endif +#else + // USB I/O requires libusb and is currently only supported under Linux. + // So for non-Linux targets force _USE_USB_IO to 0. + #define _USE_USB_IO 0 // not supported by default +#endif + +/* + * Control whether direct USB I/O communication is supported + * for example via "/dev/mbgims" in case there is an appropriate + * channel to do so. + */ +#if defined( MBG_TGT_LINUX ) + #ifndef _USE_USB_DIRECT_IO + #define _USE_USB_DIRECT_IO 0 // Not supported by default + #endif +#else + // Not supported by other platforms + #define _USE_USB_DIRECT_IO 0 // Not supported by default #endif /* Control inclusion of secudefs.h */ #if _USE_SOCKET_IO // Network socket I/O always requires secudefs, so make sure // this is defined correctly. - #ifdef _USE_ENCRYPTION - #undef _USE_ENCRYPTION - #endif - #define _USE_ENCRYPTION 1 + #undef _USE_ENCRYPTION + #define _USE_ENCRYPTION 1 #else // If no socket I/O is used then secudefs aren't required, either. #ifndef _USE_ENCRYPTION - #define _USE_ENCRYPTION 0 + #define _USE_ENCRYPTION 0 #endif #endif @@ -265,8 +349,19 @@ #include <mbgserio.h> #endif +#if _USE_SERIAL_IO_FTDI + #include <ftd2xx.h> // interface for ftd2xx.dll +#else + // just to avoid build errors if FTDI API is not supported + #define FT_STATUS int +#endif + +#if _USE_USB_IO + #include <mbgusbio.h> +#endif + #if _USE_SOCKET_IO - #if defined( MBG_TGT_UNIX ) + #if defined( MBG_TGT_POSIX ) #include <netdb.h> #endif #endif @@ -289,246 +384,387 @@ #endif - -#ifdef __cplusplus -extern "C" { -#endif - #ifdef _GPSSERIO #define _ext #else #define _ext extern #endif -#if defined( _USE_PACK ) // set byte alignment - #pragma pack( 1 ) -#endif +/* Start of header body */ +// We don't use pragma pack() here but native alignment. -/* Start of header body */ +#ifdef __cplusplus +extern "C" { +#endif -/* Status codes of check_transfer() function. */ +/** + * @brief Status codes returned by the check_transfer() function. + */ +enum TR_STATUS_CODES +{ + TR_COMPLETE_TSTR = 3, ///< The optional time string check has detected a valid time string + TR_COMPLETE = 2, ///< A binary message has been received successfully + TR_RECEIVING = 1, ///< Binary reception in progress, i.e. after START_OF_HEADER received + TR_WAITING = 0, ///< Waiting for a binary message, i.e. no START_OF_HEADER received, yet + TR_TIMEOUT = -1, ///< No data received during the timeout interval + TR_CSUM_HDR = -2, ///< The header checksum of a received message is invalid + TR_CSUM_DATA = -3, ///< The data checksum of a received message is invalid + TR_DECRYPTION = -4, ///< A binary message received over LAN could not be decrypted. + TR_OPEN_ERR = -5, ///< Failed to open connection. + TR_IO_ERR = -6, ///< I/O error for the specified connection + TR_AUTH_ERR = -7, ///< Authentication error for the specified LAN connection + TR_RCVD_NACK = -8 ///< Received Negative Acknowledge from a device (prev. msg not accepted or not supported) +}; -#define TR_COMPLETE 2 -#define TR_RECEIVING 1 -#define TR_WAITING 0 -#define TR_TIMEOUT -1 -#define TR_CSUM_HDR -2 -#define TR_CSUM_DATA -3 -#define TR_DECRYPTION -4 -#define TR_OPEN_ERR -5 -#define TR_IO_ERR -6 -#define TR_AUTH_ERR -7 -/* The code below is sent before a message header. */ +/** + * @brief The start of header code sent before a binary message header + */ +#define START_OF_HEADER 0x01 ///< ASCII SOH -#define START_OF_HEADER 0x01 /* ASCII SOH */ +/** + * @brief Control codes to be or'ed with a particular command/type code + */ +enum GPS_CMD_CTRL_CODES +{ + GPS_REQACK = 0x8000, ///< to device: request acknowledge + GPS_ACK = 0x4000, ///< from device: acknowledge a command + GPS_NACK = 0x2000, ///< from device: error evaluating a command +}; -/* The control codes defined below are to be or'ed with a command/type code. */ +#define GPS_CTRL_MSK 0xF000 ///< bit mask of all ::GPS_CMD_CTRL_CODES -#define GPS_REQACK 0x8000 /* to GPS rcvr: request acknowledge */ -#define GPS_ACK 0x4000 /* from GPS rcvr: acknowledge a command */ -#define GPS_NACK 0x2000 /* from GPS rcvr: error receiving command */ -#define GPS_CTRL_MSK 0xF000 /* masks control code from command */ +/** + * @brief A wildcard command code + * + * This code can be passed to a receive routine to wait for any type + * of binary packet rather than for a specific packet. + */ +#define GPS_WILDCARD ( (GPS_CMD) -1 ) -/**< @defgroup gps_cmds_serial GPS commands passed via serial port +/** + * @brief Command codes for the binary protocol + * + * These codes specify commands and associated data types used by Meinberg's + * binary protocol to exchange data with a device via serial port, direct USB, + * or socket I/O. + * + * Some commands and associated data structures can be read (r) from a device, others + * can be written (w) to the device, and some can also be sent automatically (a) by + * a device after a ::GPS_AUTO_ON command has been sent to the device. + * The individual command codes are marked with (rwa) accordingly, where '-' is used + * to indicate that a particular mode is not supported. * - * These codes specify commands/types of data to be supplied to - * the GPS receiver: + * @note Not all command code are supported by all devices. + * See the hints for a particular command. + * + * @note If ::GPS_ALM, ::GPS_EPH or a code named ..._IDX is sent to retrieve + * some data from a device then an uint16_t parameter must be also supplied + * in order to specify the index number of the data set to be returned. + * The valid index range depends on the command code. + * For ::GPS_ALM and ::GPS_EPH the index is the SV number which may be 0 or + * ::MIN_SVNO_GPS to ::MAX_SVNO_GPS. If the number is 0 then all ::N_SVNO_GPS + * almanacs or ephemeris data structures are returned. + * + * @see ::GPS_CMD_CODES_TABLE */ -/* clock auto-message to host */ -/* | host request, clock response */ -/* | | host download to clock */ -/* | | | */ -enum /* | | | */ +enum GPS_CMD_CODES { /* system data */ - GPS_AUTO_ON = 0x000, /* | | | X | no param, enable auto-msgs from GPS rcvr */ - GPS_AUTO_OFF, /* | | | X | no param, disable auto-msgs from GPS rcvr */ - GPS_SW_REV, /* | | X | | SW_REV, software revision */ - GPS_BVAR_STAT, /* | | X | | BVAR_STAT, status of buffered variables */ - GPS_TIME, /* | X | | X | TTM, current time or capture, or init board time */ - GPS_POS_XYZ, /* | | X | X | XYZ, current position in ECEF coords */ - GPS_POS_LLA, /* | | X | X | LLA, current position in geographic coords */ - GPS_TZDL, /* | | X | X | TZDL, time zone / daylight saving */ - GPS_PORT_PARM, /* | | X | X | PORT_PARM, (obsolete, use PORT_SETTINGS etc. ) */ - GPS_SYNTH, /* | | X | X | SYNTH synthesizer's frequency and phase */ - GPS_ANT_INFO, /* | X | X | | ANT_INFO, time diff after antenna disconnect */ - GPS_UCAP, /* | X | X | | TTM, user capture events */ - GPS_ENABLE_FLAGS, /* | | X | X | ENABLE_FLAGS, when to enable serial, pulses, and synth */ - GPS_STAT_INFO, /* | | X | | STAT_INFO, request SV, mode and DAC info */ - GPS_SWITCH_PARMS, /* | | X | X | (obsolete, use GPS_POUT_PROG_IDX) */ - GPS_STRING_PARMS, /* | | X | X | (obsolete, use GPS_PORT_INFO/GPS_PORT_SETTINGS */ - GPS_ANT_CABLE_LENGTH, /* | | X | X | ANT_CABLE_LEN, length of antenna cable */ - GPS_SYNC_OUTAGE_DELAY, /* | | X | X | (customized firmware only) */ - GPS_PULSE_INFO, /* | | X | X | (customized firmware only) */ - GPS_OPT_FEATURES, /* | | X | | (obsolete, use GPS_RECEIVER_INFO) */ - GPS_IRIG_TX_SETTINGS, /* | | X | X | IRIG_SETTINGS, (only if GPS_HAS_IRIG_TX) */ - GPS_RECEIVER_INFO, /* | | X | | RECEIVER_INFO, model specific info */ - GPS_STR_TYPE_INFO_IDX, /* | | X | | STR_TYPE_INFO_IDX, names and modes of supp. string types */ - GPS_PORT_INFO_IDX, /* | | X | | PORT_INFO_IDX, port settings + additional info */ - GPS_PORT_SETTINGS_IDX, /* | | X | X | PORT_SETTINGS_IDX, settings for specified port */ - GPS_POUT_INFO_IDX, /* | | X | | POUT_INFO_IDX, pout settings + additional info */ - GPS_POUT_SETTINGS_IDX, /* | | X | X | POUT_SETTINGS_IDX, programmable pulse output cfg */ - GPS_IRIG_TX_INFO, /* | | X | | IRIG_INFO, (only if GPS_HAS_IRIG_TX) */ - GPS_MULTI_REF_SETTINGS,/* | | X | X | MULTI_REF_SETTINGS, (only if HAS_MULTI_REF) */ - GPS_MULTI_REF_INFO, /* | | X | | MULTI_REF_INFO, (only if HAS_MULTI_REF) */ - GPS_ROM_CSUM, /* | | X | | ROM_CSUM, (not supported by all devices) */ - GPS_MULTI_REF_STATUS, /* | | X | | MULTI_REF_STATUS, (only if HAS_MULTI_REF) */ - GPS_RCV_TIMEOUT, /* | | X | X | RCV_TIMEOUT, [min] (only if HAS_RCV_TIMEOUT) */ - GPS_IGNORE_LOCK, /* | | X | X | IGNORE_LOCK, if != 0 always claim to be sync */ - GPS_IRIG_RX_SETTINGS, /* | | X | X | IRIG_SETTINGS, (only if GPS_HAS_IRIG_RX) */ - GPS_IRIG_RX_INFO, /* | | X | | IRIG_INFO, (only if GPS_HAS_IRIG_RX) */ - GPS_REF_OFFS, /* | | X | X | MBG_REF_OFFS, (only if GPS_HAS_REF_OFFS) */ - GPS_DEBUG_STATUS, /* | | X | | MBG_DEBUG_STATUS, (only if GPS_HAS_DEBUG_STATUS) */ - GPS_XMR_SETTINGS_IDX, /* | | X | X | XMULTI_REF_SETTINGS_IDX, (only if GPS_HAS_XMULTI_REF) */ - GPS_XMR_INFO_IDX, /* | | X | | XMULTI_REF_INFO_IDX, (only if GPS_HAS_XMULTI_REF) */ - GPS_XMR_STATUS_IDX, /* | | X | | XMULTI_REF_STATUS_IDX, (only if GPS_HAS_XMULTI_REF) */ - GPS_OPT_SETTINGS, /* | | X | X | MBG_OPT_SETTINGS, (only if GPS_HAS_OPT_SETTINGS) */ - GPS_OPT_INFO, /* | | X | | MBG_OPT_INFO, (only if GPS_HAS_OPT_SETTINGS) */ - GPS_CLR_UCAP_BUFF, /* | | X | | command only, no data */ - GPS_TIME_SCALE, /* | | X | X | MBG_TIME_SCALE_{SETTINGS|INFO}, (only if GPS_HAS_TIME_SCALE) */ - GPS_NAV_ENG_SETTINGS, /* | | X | X | NAV_ENGINE_SETTINGS, (only if GPS_HAS_NAV_ENGINE_SETTINGS) */ - GPS_RAW_IRIG_DATA, /* | | X | | MBG_RAW_IRIG_DATA, (only if GPS_HAS_RAW_IRIG_DATA) */ + GPS_AUTO_ON = 0x000, ///< (-w-) no data, enable auto-msgs from device + GPS_AUTO_OFF, ///< (-w-) no data, disable auto-msgs from device + GPS_SW_REV, ///< (r--) deprecated, ::SW_REV, software revision, use only if ::GPS_RECEIVER_INFO not supp. + GPS_BVAR_STAT, ///< (r--) ::BVAR_STAT, status of buffered variables, only if ::GPS_MODEL_HAS_BVAR_STAT + GPS_TIME, ///< (-wa) ::TTM, current time or capture, or init board time + GPS_POS_XYZ, ///< (rw-) ::XYZ, current position in ECEF coordinates, only if ::GPS_MODEL_HAS_POS_XYZ + GPS_POS_LLA, ///< (rw-) ::LLA, current position in geographic coordinates, only if ::GPS_MODEL_HAS_POS_LLA + GPS_TZDL, ///< (rw-) ::TZDL, time zone / daylight saving, only if ::GPS_MODEL_HAS_TZDL + GPS_PORT_PARM, ///< (rw-) deprecated, ::PORT_PARM, use ::PORT_SETTINGS etc. if ::GPS_RECEIVER_INFO supported + GPS_SYNTH, ///< (rw-) ::SYNTH, synthesizer settings, only if ::GPS_HAS_SYNTH + GPS_ANT_INFO, ///< (r-a) ::ANT_INFO, time diff after antenna disconnect, only if ::GPS_MODEL_HAS_ANT_INFO + GPS_UCAP, ///< (r-a) ::TTM, user capture events, only if ::RECEIVER_INFO::n_ucaps > 0 + GPS_ENABLE_FLAGS, ///< (rw-) ::ENABLE_FLAGS, when to enable serial, pulses, and synth, only if ::GPS_MODEL_HAS_ENABLE_FLAGS + GPS_STAT_INFO, ///< (r--) ::STAT_INFO, satellite info, mode of operation, and DAC info, only if ::GPS_MODEL_HAS_STAT_INFO + GPS_SWITCH_PARMS, ///< (rw-) deprecated, use ::GPS_POUT_INFO_IDX/::GPS_POUT_SETTINGS_IDX + GPS_STRING_PARMS, ///< (rw-) deprecated, use ::GPS_PORT_INFO_IDX/::GPS_PORT_SETTINGS_IDX + GPS_ANT_CABLE_LENGTH, ///< (rw-) ::ANT_CABLE_LEN, length of antenna cable, only if ::GPS_MODEL_HAS_ANT_CABLE_LENGTH + GPS_SYNC_OUTAGE_DELAY, ///< (rw-) (customized firmware only) + GPS_PULSE_INFO, ///< (rw-) (customized firmware only) + GPS_OPT_FEATURES, ///< (r--) deprecated, use ::GPS_RECEIVER_INFO + GPS_IRIG_TX_SETTINGS, ///< (rw-) ::IRIG_SETTINGS, only if ::GPS_HAS_IRIG_TX + GPS_RECEIVER_INFO, ///< (r--) ::RECEIVER_INFO, model specific info, not supported by *very* old devices + GPS_STR_TYPE_INFO_IDX, ///< (r--) ::STR_TYPE_INFO_IDX, names and capabilities of supp. string types, only if ::RECEIVER_INFO::n_str_type > 0 + GPS_PORT_INFO_IDX, ///< (r--) ::PORT_INFO_IDX, serial port settings and capabilities, only if ::RECEIVER_INFO::n_com_ports > 0 + GPS_PORT_SETTINGS_IDX, ///< (rw-) ::PORT_SETTINGS_IDX, settings for specified serial port, only if ::RECEIVER_INFO::n_com_ports > 0 + GPS_POUT_INFO_IDX, ///< (r--) ::POUT_INFO_IDX, programmable pulse output settings and capabilities, only if ::RECEIVER_INFO::n_prg_out > 0 + GPS_POUT_SETTINGS_IDX, ///< (rw-) ::POUT_SETTINGS_IDX, programmable pulse output settings, only if ::RECEIVER_INFO::n_prg_out > 0 + GPS_IRIG_TX_INFO, ///< (r--) ::IRIG_INFO, only if ::GPS_HAS_IRIG_TX + GPS_MULTI_REF_SETTINGS, ///< (rw-) ::MULTI_REF_SETTINGS, only if ::GPS_HAS_MULTI_REF + GPS_MULTI_REF_INFO, ///< (r--) ::MULTI_REF_INFO, only if ::GPS_HAS_MULTI_REF + GPS_ROM_CSUM, ///< (r--) ::ROM_CSUM, not supported by all devices + GPS_MULTI_REF_STATUS, ///< (r--) ::MULTI_REF_STATUS, only if ::GPS_HAS_MULTI_REF + GPS_RCV_TIMEOUT, ///< (rw-) ::RCV_TIMEOUT, [min], only if ::GPS_HAS_RCV_TIMEOUT + GPS_IGNORE_LOCK, ///< (rw-) ::IGNORE_LOCK, if != 0 always claim to be sync, only if ::GPS_MODEL_HAS_GPS_IGNORE_LOCK + GPS_IRIG_RX_SETTINGS, ///< (rw-) ::IRIG_SETTINGS, only if ::GPS_HAS_IRIG_RX + GPS_IRIG_RX_INFO, ///< (r--) ::IRIG_INFO, only if ::GPS_HAS_IRIG_RX + GPS_REF_OFFS, ///< (rw-) ::MBG_REF_OFFS, only if ::GPS_HAS_REF_OFFS + GPS_DEBUG_STATUS, ///< (r--) ::MBG_DEBUG_STATUS, only if ::GPS_HAS_DEBUG_STATUS + GPS_XMR_SETTINGS_IDX, ///< (rw-) ::XMULTI_REF_SETTINGS_IDX, idx 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1, only if ::GPS_HAS_XMULTI_REF + GPS_XMR_INFO_IDX, ///< (r--) ::XMULTI_REF_INFO_IDX, idx 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1, only if ::GPS_HAS_XMULTI_REF + GPS_XMR_STATUS_IDX, ///< (r--) ::XMULTI_REF_STATUS_IDX, idx 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1, only if ::GPS_HAS_XMULTI_REF + GPS_OPT_SETTINGS, ///< (rw-) ::MBG_OPT_SETTINGS, only if ::GPS_HAS_OPT_SETTINGS + GPS_OPT_INFO, ///< (r--) ::MBG_OPT_INFO, only if ::GPS_HAS_OPT_SETTINGS + GPS_CLR_UCAP_BUFF, ///< (-w-) no data, only if ::RECEIVER_INFO::n_ucaps > 0 + GPS_TIME_SCALE, ///< (rw-) ::MBG_TIME_SCALE_SETTINGS/::MBG_TIME_SCALE_INFO, only if ::GPS_HAS_TIME_SCALE + GPS_NAV_ENG_SETTINGS, ///< (rw-) ::NAV_ENGINE_SETTINGS, only if ::GPS_HAS_NAV_ENGINE_SETTINGS + GPS_RAW_IRIG_DATA, ///< (r--) ::MBG_RAW_IRIG_DATA, only if ::GPS_HAS_RAW_IRIG_DATA + GPS_GPIO_CFG_LIMITS, ///< (r--) ::MBG_GPIO_CFG_LIMITS, only if ::GPS_HAS_GPIO + GPS_GPIO_INFO_IDX, ///< (r--) ::MBG_GPIO_INFO_IDX, settings and capabilities, only if ::GPS_HAS_GPIO + GPS_GPIO_SETTINGS_IDX, ///< (rw-) ::MBG_GPIO_SETTINGS_IDX, settings of a specific port, only if ::GPS_HAS_GPIO + GPS_XMR_INSTANCES, ///< (r--) ::XMULTI_REF_INSTANCES, only if ::GPS_HAS_XMRS_MULT_INSTC + GPS_CLR_EVT_LOG, ///< (-w-) no data, clear event log command, only if ::GPS_HAS_EVT_LOG + GPS_NUM_EVT_LOG_ENTRIES, ///< (r--) ::MBG_NUM_EVT_LOG_ENTRIES, num. of log entries, only if ::GPS_HAS_EVT_LOG + GPS_FIRST_EVT_LOG_ENTRY, ///< (r--) first/oldest ::MBG_EVT_LOG_ENTRY, only if ::GPS_HAS_EVT_LOG + GPS_NEXT_EVT_LOG_ENTRY, ///< (r--) next ::MBG_EVT_LOG_ENTRY, only if ::GPS_HAS_EVT_LOG + GPS_LNO_STATUS, ///< (r--) ::LNO_STATE, only if ::GPS_MODEL_IS_LNO + GPS_IMS_STATE, ///< (r--) ::MBG_IMS_STATE, only if ::GPS_HAS_IMS + GPS_IMS_SENSOR_STATE_IDX, ///< (r--) ::MBG_IMS_SENSOR_STATE_IDX, only if ::GPS_HAS_IMS + GPS_XMR_HOLDOVER_INTV, ///< (rw-) ::XMR_HOLDOVER_INTV, only if ::GPS_MODEL_HAS_XMR_HOLDOVER_INTV, see also ::GPS_XMR_HOLDOVER_STATUS + GPS_HAVEQUICK_RX_SETTINGS, ///< (rw-) ::HAVEQUICK_SETTINGS for input, only if ::GPS_HAS_HAVEQUICK + GPS_HAVEQUICK_RX_INFO, ///< (r--) ::HAVEQUICK_INFO for input, only if ::GPS_HAS_HAVEQUICK + GPS_HAVEQUICK_TX_SETTINGS, ///< (rw-) ::HAVEQUICK_SETTINGS for output, only if ::GPS_HAS_HAVEQUICK + GPS_HAVEQUICK_TX_INFO, ///< (r--) ::HAVEQUICK_INFO for output, only if ::GPS_HAS_HAVEQUICK + GPS_PTP_CFG, ///< (rw-) ::PTP_CFG_INFO/::PTP_CFG_SETTINGS, only if ::GPS_HAS_PTP + GPS_PTP_STATE, ///< (r--) ::PTP_STATE, current PTP status, only if ::GPS_HAS_PTP + GPS_PTP_UC_MASTER_CFG_LIMITS, ///< (r--) ::PTP_UC_MASTER_CFG_LIMITS, only if ::PTP_CFG_CAN_BE_UNICAST_SLAVE + GPS_PTP_UC_MASTER_CFG, ///< (rw-) ::PTP_UC_MASTER_INFO_IDX/::PTP_UC_MASTER_SETTINGS_IDX, only if ::PTP_CFG_CAN_BE_UNICAST_SLAVE + GPS_NTP_GLB_CFG, ///< (rw-) ::NTP_GLB_INFO/::NTP_GLB_SETTINGS, only if ::GPS_HAS_NTP + GPS_NTP_CLNT_MODE_CFG, ///< (rw-) ::NTP_CLNT_MODE_INFO/::NTP_CLNT_MODE_SETTINGS, only if ::NTP_MSK_ROLE_CLIENT + GPS_NTP_SRV_MODE_CFG, ///< (rw-) ::NTP_SRV_MODE_INFO/::NTP_SRV_MODE_SETTINGS, only if ::NTP_MSK_ROLE_SERVER + GPS_NTP_PEER_SETTINGS_IDX, ///< (rw-) ::NTP_PEER_SETTINGS_IDX, only if ??? + GPS_NTP_SYS_STATE, ///< (r--) ::NTP_SYS_STATE, only if ??? + GPS_NTP_PEER_STATE_IDX, ///< (r--) ::NTP_PEER_STATE_IDX, only if ??? + GPS_SHS, ///< (rw-) ::SHS_INFO/::SHS_SETTINGS, only if ::GPS_HAS_SHS + GPS_SHS_STATUS, ///< (r--) ::SHS_STATUS, only if ::GPS_HAS_SHS + GPS_NET_GLB_CFG, ///< (rw-) ::MBG_NET_GLB_CFG_INFO/::MBG_NET_GLB_CFG_SETTINGS, only if ::GPS_HAS_NET_CFG + GPS_NET_DNS_SRVR, ///< (rw-) ::MBG_IP_ADDR_IDX, DNS cfg., only if ::MBG_NET_GLB_CFG_INFO::num_dns_srvr > 0 + GPS_NET_DNS_SRCH_DOM, ///< (rw-) ::MBG_NET_NAME_IDX, DNS cfg., only if ::MBG_NET_GLB_CFG_INFO::num_dns_srch_dom > 0 + GPS_NET_STAT_DNS_SRVR, ///< (r--) ::MBG_IP_ADDR_IDX, DNS status, only if ::MBG_NET_GLB_CFG_INFO::num_dns_srvr > 0 + GPS_NET_STAT_DNS_SRCH_DOM, ///< (r--) ::MBG_NET_NAME_IDX, DNS status, only if ::MBG_NET_GLB_CFG_INFO::num_dns_srch_dom > 0 + GPS_GNSS_SAT_INFO_IDX, ///< (r--) ::GNSS_SAT_INFO_IDX, only if ::MBG_GNSS_FLAG_SAT_INFO_IDX_SUPP_SER, deprecates ::GPS_GNSS_SAT_INFO + GPS_XMR_HOLDOVER_ELAPSED, ///< (r--) ::XMR_HOLDOVER_INTV, elapsed time in holdover mode, only if ::GPS_MODEL_HAS_XMR_HOLDOVER_INTV, deprecated by ::GPS_XMR_HOLDOVER_STATUS + GPS_GPIO_STATUS_IDX, ///< (r--) ::MBG_GPIO_STATUS_IDX, only if ::MBG_GPIO_CFG_LIMIT_FLAG_MASK_STATUS_SUPP + GPS_XMR_HOLDOVER_STATUS, ///< (r--) ::XMR_HOLDOVER_STATUS, only if ::XMRIF_MSK_HOLDOVER_STATUS_SUPP, deprecates ::GPS_XMR_HOLDOVER_ELAPSED and partially ::GPS_XMR_HOLDOVER_INTV + GPS_XBP_LIMITS, ///< (r--) ::XBP_LIMITS, only if ::GPS_HAS_XBP + GPS_XBP_NODE_LIMITS, ///< (r--) ::XBP_NODE_LIMITS, only if ::XBP_FEAT_MASK_NODES is set in ::XBP_LIMITS::features + GPS_XBP_NODE_INFO_IDX, ///< (r--) ::XBP_NODE_INFO_IDX, 0..::XBP_NODE_LIMITS::node_count-1 instances can be retrieved + GPS_FDM_OUTPUT_STATE_IDX, ///< (r--) ::MBG_IMS_FDM_OUTPUT_STATE_IDX, only if ::MBG_IMS_STATE_FLAG_MSK_HAS_FDM is set in ::MBG_IMS_STATE::flags + GPS_FDM_OUTPUT_SETTINGS_IDX, ///< (rw-) ::MBG_IMS_FDM_OUTPUT_SETTINGS_IDX, only if ::MBG_IMS_STATE_FLAG_MSK_HAS_FDM is set in ::MBG_IMS_STATE::flags + GPS_FDM_OUTPUT_INFO_IDX, ///< (r--) ::MBG_IMS_FDM_OUTPUT_INFO, only if ::MBG_IMS_STATE_FLAG_MSK_HAS_FDM is set in ::MBG_IMS_STATE::flags + GPS_FDM_LIMITS, ///< (r--) ::MBG_IMS_FDM_LIMITS, only if ::MBG_IMS_STATE_FLAG_MSK_HAS_FDM is set in ::MBG_IMS_STATE::flags + GPS_FDM_STATE, ///< (r--) ::MBG_IMS_FDM_STATE, only if ::MBG_IMS_STATE_FLAG_MSK_HAS_FDM is set in ::MBG_IMS_STATE::flags + GPS_FDM_SETTINGS, ///< (rw-) ::MBG_IMS_FDM_SETTINGS, only if ::MBG_IMS_STATE_FLAG_MSK_HAS_FDM is set in ::MBG_IMS_STATE::flags + GPS_FDM_INFO, ///< (r--) ::MBG_IMS_FDM_INFO, only if ::MBG_IMS_STATE_FLAG_MSK_HAS_FDM is set in ::MBG_IMS_STATE::flags + GPS_XMR_EXT_SRC_INFO_IDX, ///< (r--) ::XMR_EXT_SRC_INFO_IDX, only if ::XMRIF_MSK_EXT_SRC_INFO_SUPP /* GPS data */ - GPS_CFGH = 0x100, /* | | X | X | CFGH, SVs' configuration and health codes */ - GPS_ALM, /* | | X | X | req: uint16_t SV num, SV_ALM, one SV's almanac */ - GPS_EPH, /* | | X | X | req: uint16_t SV num, SV_EPH, one SV's ephemeris */ - GPS_UTC, /* | | X | X | UTC, GPS UTC correction parameters */ - GPS_IONO, /* | | X | X | IONO, GPS ionospheric correction parameters */ - GPS_ASCII_MSG, /* | | X | | ASCII_MSG, the GPS ASCII message */ + GPS_CFGH = 0x100, ///< (rw-) ::CFGH, SVs' configuration and health codes + GPS_ALM, ///< (rw-) req: uint16_t SV num, ::SV_ALM, one SV's almanac + GPS_EPH, ///< (rw-) req: uint16_t SV num, ::SV_EPH, one SV's ephemeris + GPS_UTC, ///< (rw-) ::UTC, GPS %UTC correction parameters + GPS_IONO, ///< (rw-) ::IONO, GPS ionospheric correction parameters + GPS_ASCII_MSG, ///< (r--) ::ASCII_MSG, the GPS ASCII message /* Glonass data */ - GPS_GLNS_ALM = 0x200, /* | | X | X | ** preliminary ** */ //##++ - GPS_GNSS_SAT_INFO, /* | | X | | GNSS_SAT_INFO, request SVs */ - GPS_GNSS_MODE, /* | | X | X | MBG_GNSS_MODE_{SETTINGS|INFO}, GNSS operation mode */ + GPS_GLNS_ALM = 0x200, ///< (rw-) ** preliminary ** //##++ + GPS_GNSS_SAT_INFO, ///< (r--) ::GNSS_SAT_INFO, Glonass-only sat. info (deprecated by ::GPS_GNSS_SAT_INFO_IDX) + GPS_GNSS_MODE, ///< (rw-) ::MBG_GNSS_MODE_SETTINGS/::MBG_GNSS_MODE_INFO}, GNSS operation mode + // Warning: + // The next numbers in range 0x200 are reserved /* Misc data */ - GPS_IP4_SETTINGS = 0x800, /* | X | X | IP4_SETTINGS, cfg of optional LAN interface */ - GPS_LAN_IF_INFO, /* | X | | LAN_IF_INFO, LAN interface info */ + GPS_IP4_SETTINGS = 0x800, ///< (rw-) ::IP4_SETTINGS, only if ::GPS_HAS_LAN_IP4 + GPS_LAN_IF_INFO, ///< (r--) ::LAN_IF_INFO, only if ::GPS_HAS_LAN_IP4 + GPS_IP4_STATE, ///< (r--) ::IP4_SETTINGS, only if ::GPS_HAS_LAN_IP4 + + /* misc data (SCU) */ + GPS_SCU_STAT = 0x820, ///< (rwa) ::SCU_STAT_SETTINGS/::SCU_STAT_INFO, SCU board control, only if ::GPS_MODEL_IS_SCU - GPS_CRYPTED_PACKET = 0x880, /* | X | X | X | encrypted binary packet */ - GPS_CRYPTED_RAW_PACKET, /* | X | X | X | encrypted binary raw packet */ + GPS_CRYPTED_PACKET = 0x880, ///< (rwa) encrypted binary packet + GPS_CRYPTED_RAW_PACKET, ///< (rwa) encrypted binary raw packet + GPS_XBP_PACKET, ///< (rwa) eXtended Binary Packet, only if ::GPS_HAS_XBP, see @ref group_xbp - GPS_SECU_INFO = 0x900, /* | | X | | encryption method for LAN interface */ - GPS_SECU_SETTINGS, /* | | X | X | reserved for public key LAN interface */ - GPS_SECU_PUBLIC_KEY, /* | | | | settings and password for LAN interface */ + GPS_SECU_INFO = 0x900, ///< (r--) encryption method for LAN interface + GPS_SECU_SETTINGS, ///< (rw-) reserved for public key LAN interface + GPS_SECU_PUBLIC_KEY, ///< (---) settings and password for LAN interface /* PZF data */ - PZF_PCPS_TIME = 0xA00, /* | | X | X | PCPS_TIME, date/time/status */ - PZF_TR_DISTANCE, /* | | X | X | TR_DISTANCE, dist. from transmitter [km] */ - PZF_TZCODE, /* | | X | X | TZCODE, time zone code */ - PZF_CORR_INFO /* | | X | | CORR_INFO, correlation info */ + PZF_PCPS_TIME = 0xA00, ///< (rw-) ::PCPS_TIME, date/time/status, only if ::GPS_MODEL_IS_DCF_PZF + PZF_TR_DISTANCE, ///< (rw-) ::TR_DISTANCE, dist. from transmitter [km], only if ::GPS_MODEL_IS_DCF_PZF + PZF_TZCODE, ///< (rw-) ::TZCODE, time zone code, only if ::GPS_MODEL_IS_DCF_PZF + PZF_CORR_INFO ///< (r--) ::CORR_INFO, correlation info, only if ::GPS_MODEL_IS_DCF_PZF }; -/* - * Caution: If GPS_ALM, GPS_EPH or a code named ..._IDX is sent to retrieve - * some data from a device then an uint16_t parameter must be also supplied - * in order to specify the index number of the data set to be returned. - * The valid index range depends on the command code. - * - * For GPS_ALM and GPS_EPH the index is the SV number which may be 0 or - * MIN_SVNO to MAX_SVNO. If the number is 0, ALL almanacs (32) are returned. - */ -typedef struct -{ - GPS_CMD cmd_code; - const char *cmd_name; -} GPS_CMD_NAME_TABLE_ENTRY; - -#define GPS_CMD_NAME_TABLE_ENTRIES \ -{ \ - { GPS_AUTO_ON, "GPS_AUTO_ON" }, \ - { GPS_AUTO_OFF, "GPS_AUTO_OFF" }, \ - { GPS_SW_REV, "GPS_SW_REV" }, \ - { GPS_BVAR_STAT, "GPS_BVAR_STAT" }, \ - { GPS_TIME, "GPS_TIME" }, \ - { GPS_POS_XYZ, "GPS_POS_XYZ" }, \ - { GPS_POS_LLA, "GPS_POS_LLA" }, \ - { GPS_TZDL, "GPS_TZDL" }, \ - { GPS_PORT_PARM, "GPS_PORT_PARM" }, \ - { GPS_SYNTH, "GPS_SYNTH" }, \ - { GPS_ANT_INFO, "GPS_ANT_INFO" }, \ - { GPS_UCAP, "GPS_UCAP" }, \ - { GPS_ENABLE_FLAGS, "GPS_ENABLE_FLAGS" }, \ - { GPS_STAT_INFO, "GPS_STAT_INFO" }, \ - { GPS_SWITCH_PARMS, "GPS_SWITCH_PARMS" }, \ - { GPS_STRING_PARMS, "GPS_STRING_PARMS" }, \ - { GPS_ANT_CABLE_LENGTH, "GPS_ANT_CABLE_LENGTH" }, \ - { GPS_SYNC_OUTAGE_DELAY, "GPS_SYNC_OUTAGE_DELAY" }, \ - { GPS_PULSE_INFO, "GPS_PULSE_INFO" }, \ - { GPS_OPT_FEATURES, "GPS_OPT_FEATURES" }, \ - { GPS_IRIG_TX_SETTINGS, "GPS_IRIG_TX_SETTINGS" }, \ - { GPS_RECEIVER_INFO, "GPS_RECEIVER_INFO" }, \ - { GPS_STR_TYPE_INFO_IDX, "GPS_STR_TYPE_INFO_IDX" }, \ - { GPS_PORT_INFO_IDX, "GPS_PORT_INFO_IDX" }, \ - { GPS_PORT_SETTINGS_IDX, "GPS_PORT_SETTINGS_IDX" }, \ - { GPS_POUT_INFO_IDX, "GPS_POUT_INFO_IDX" }, \ - { GPS_POUT_SETTINGS_IDX, "GPS_POUT_SETTINGS_IDX" }, \ - { GPS_IRIG_TX_INFO, "GPS_IRIG_TX_INFO" }, \ - { GPS_MULTI_REF_SETTINGS, "GPS_MULTI_REF_SETTINGS" }, \ - { GPS_MULTI_REF_INFO, "GPS_MULTI_REF_INFO" }, \ - { GPS_ROM_CSUM, "GPS_ROM_CSUM" }, \ - { GPS_MULTI_REF_STATUS, "GPS_MULTI_REF_STATUS" }, \ - { GPS_RCV_TIMEOUT, "GPS_RCV_TIMEOUT" }, \ - { GPS_IGNORE_LOCK, "GPS_IGNORE_LOCK" }, \ - { GPS_IRIG_RX_SETTINGS, "GPS_IRIG_RX_SETTINGS" }, \ - { GPS_IRIG_RX_INFO, "GPS_IRIG_RX_INFO" }, \ - { GPS_REF_OFFS, "GPS_REF_OFFS" }, \ - { GPS_DEBUG_STATUS, "GPS_DEBUG_STATUS" }, \ - { GPS_XMR_SETTINGS_IDX, "GPS_XMR_SETTINGS_IDX" }, \ - { GPS_XMR_INFO_IDX, "GPS_XMR_INFO_IDX" }, \ - { GPS_XMR_STATUS_IDX, "GPS_XMR_STATUS_IDX" }, \ - { GPS_OPT_SETTINGS, "GPS_OPT_SETTINGS" }, \ - { GPS_OPT_INFO, "GPS_OPT_INFO" }, \ - { GPS_CLR_UCAP_BUFF, "GPS_CLR_UCAP_BUFF" }, \ - { GPS_TIME_SCALE, "GPS_TIME_SCALE" }, \ - { GPS_NAV_ENG_SETTINGS, "GPS_NAV_ENG_SETTINGS" }, \ - { GPS_RAW_IRIG_DATA, "GPS_RAW_IRIG_DATA" }, \ - \ - /* GPS data */ \ - { GPS_CFGH, "GPS_CFGH" }, \ - { GPS_ALM, "GPS_ALM" }, \ - { GPS_EPH, "GPS_EPH" }, \ - { GPS_UTC, "GPS_UTC" }, \ - { GPS_IONO, "GPS_IONO" }, \ - { GPS_ASCII_MSG, "GPS_ASCII_MSG" }, \ - \ - /* Glonass data */ \ - { GPS_GLNS_ALM, "GPS_GLNS_ALM" }, \ - { GPS_GNSS_SAT_INFO, "GPS_GNSS_SAT_INFO" }, \ - { GPS_GNSS_MODE, "GPS_GNSS_MODE" }, \ - \ - /* Misc data */ \ - { GPS_IP4_SETTINGS, "GPS_IP4_SETTINGS" }, \ - { GPS_LAN_IF_INFO, "GPS_LAN_IF_INFO" }, \ - \ - { GPS_CRYPTED_PACKET, "GPS_CRYPTED_PACKET" }, \ - { GPS_CRYPTED_RAW_PACKET, "GPS_CRYPTED_RAW_PACKET" }, \ - \ - { GPS_SECU_INFO, "GPS_SECU_INFO" }, \ - { GPS_SECU_SETTINGS, "GPS_SECU_SETTINGS" }, \ - { GPS_SECU_PUBLIC_KEY, "GPS_SECU_PUBLIC_KEY" }, \ - \ - /* PZF data */ \ - { PZF_PCPS_TIME, "PZF_PCPS_TIME" }, \ - { PZF_TR_DISTANCE, "PZF_TR_DISTANCE" }, \ - { PZF_TZCODE, "PZF_TZCODE" }, \ - { PZF_CORR_INFO, "PZF_CORR_INFO" }, \ - { 0, NULL } \ +#if !defined( MBG_TGT_DOS ) + +/** + * @brief An initializer for a table of code/name entries of ::GPS_CMD_CODES + * + * This can e.g. be assigned to an array of ::MBG_CODE_NAME_TABLE_ENTRY elements + * and may be helpful when debugging. + * + * @see ::GPS_CMD_CODES + */ +#define GPS_CMD_CODES_TABLE \ +{ \ + _mbg_cn_table_entry( GPS_WILDCARD ), \ + _mbg_cn_table_entry( GPS_AUTO_ON ), \ + _mbg_cn_table_entry( GPS_AUTO_OFF ), \ + _mbg_cn_table_entry( GPS_SW_REV ), \ + _mbg_cn_table_entry( GPS_BVAR_STAT ), \ + _mbg_cn_table_entry( GPS_TIME ), \ + _mbg_cn_table_entry( GPS_POS_XYZ ), \ + _mbg_cn_table_entry( GPS_POS_LLA ), \ + _mbg_cn_table_entry( GPS_TZDL ), \ + _mbg_cn_table_entry( GPS_PORT_PARM ), \ + _mbg_cn_table_entry( GPS_SYNTH ), \ + _mbg_cn_table_entry( GPS_ANT_INFO ), \ + _mbg_cn_table_entry( GPS_UCAP ), \ + _mbg_cn_table_entry( GPS_ENABLE_FLAGS ), \ + _mbg_cn_table_entry( GPS_STAT_INFO ), \ + _mbg_cn_table_entry( GPS_SWITCH_PARMS ), \ + _mbg_cn_table_entry( GPS_STRING_PARMS ), \ + _mbg_cn_table_entry( GPS_ANT_CABLE_LENGTH ), \ + _mbg_cn_table_entry( GPS_SYNC_OUTAGE_DELAY ), \ + _mbg_cn_table_entry( GPS_PULSE_INFO ), \ + _mbg_cn_table_entry( GPS_OPT_FEATURES ), \ + _mbg_cn_table_entry( GPS_IRIG_TX_SETTINGS ), \ + _mbg_cn_table_entry( GPS_RECEIVER_INFO ), \ + _mbg_cn_table_entry( GPS_STR_TYPE_INFO_IDX ), \ + _mbg_cn_table_entry( GPS_PORT_INFO_IDX ), \ + _mbg_cn_table_entry( GPS_PORT_SETTINGS_IDX ), \ + _mbg_cn_table_entry( GPS_POUT_INFO_IDX ), \ + _mbg_cn_table_entry( GPS_POUT_SETTINGS_IDX ), \ + _mbg_cn_table_entry( GPS_IRIG_TX_INFO ), \ + _mbg_cn_table_entry( GPS_MULTI_REF_SETTINGS ), \ + _mbg_cn_table_entry( GPS_MULTI_REF_INFO ), \ + _mbg_cn_table_entry( GPS_ROM_CSUM ), \ + _mbg_cn_table_entry( GPS_MULTI_REF_STATUS ), \ + _mbg_cn_table_entry( GPS_RCV_TIMEOUT ), \ + _mbg_cn_table_entry( GPS_IGNORE_LOCK ), \ + _mbg_cn_table_entry( GPS_IRIG_RX_SETTINGS ), \ + _mbg_cn_table_entry( GPS_IRIG_RX_INFO ), \ + _mbg_cn_table_entry( GPS_REF_OFFS ), \ + _mbg_cn_table_entry( GPS_DEBUG_STATUS ), \ + _mbg_cn_table_entry( GPS_XMR_SETTINGS_IDX ), \ + _mbg_cn_table_entry( GPS_XMR_INFO_IDX ), \ + _mbg_cn_table_entry( GPS_XMR_STATUS_IDX ), \ + _mbg_cn_table_entry( GPS_OPT_SETTINGS ), \ + _mbg_cn_table_entry( GPS_OPT_INFO ), \ + _mbg_cn_table_entry( GPS_CLR_UCAP_BUFF ), \ + _mbg_cn_table_entry( GPS_TIME_SCALE ), \ + _mbg_cn_table_entry( GPS_NAV_ENG_SETTINGS ), \ + _mbg_cn_table_entry( GPS_RAW_IRIG_DATA ), \ + _mbg_cn_table_entry( GPS_GPIO_CFG_LIMITS ), \ + _mbg_cn_table_entry( GPS_GPIO_INFO_IDX ), \ + _mbg_cn_table_entry( GPS_GPIO_SETTINGS_IDX ), \ + _mbg_cn_table_entry( GPS_XMR_INSTANCES ), \ + _mbg_cn_table_entry( GPS_CLR_EVT_LOG ), \ + _mbg_cn_table_entry( GPS_NUM_EVT_LOG_ENTRIES ), \ + _mbg_cn_table_entry( GPS_FIRST_EVT_LOG_ENTRY ), \ + _mbg_cn_table_entry( GPS_NEXT_EVT_LOG_ENTRY ), \ + _mbg_cn_table_entry( GPS_LNO_STATUS ), \ + _mbg_cn_table_entry( GPS_IMS_STATE ), \ + _mbg_cn_table_entry( GPS_IMS_SENSOR_STATE_IDX ), \ + _mbg_cn_table_entry( GPS_XMR_HOLDOVER_INTV ), \ + _mbg_cn_table_entry( GPS_HAVEQUICK_RX_SETTINGS ), \ + _mbg_cn_table_entry( GPS_HAVEQUICK_RX_INFO ), \ + _mbg_cn_table_entry( GPS_HAVEQUICK_TX_SETTINGS ), \ + _mbg_cn_table_entry( GPS_HAVEQUICK_TX_INFO ), \ + _mbg_cn_table_entry( GPS_PTP_CFG ), \ + _mbg_cn_table_entry( GPS_PTP_STATE ), \ + _mbg_cn_table_entry( GPS_PTP_UC_MASTER_CFG_LIMITS ), \ + _mbg_cn_table_entry( GPS_PTP_UC_MASTER_CFG ), \ + _mbg_cn_table_entry( GPS_NTP_GLB_CFG ), \ + _mbg_cn_table_entry( GPS_NTP_CLNT_MODE_CFG ), \ + _mbg_cn_table_entry( GPS_NTP_SRV_MODE_CFG ), \ + _mbg_cn_table_entry( GPS_NTP_PEER_SETTINGS_IDX ), \ + _mbg_cn_table_entry( GPS_NTP_SYS_STATE ), \ + _mbg_cn_table_entry( GPS_NTP_PEER_STATE_IDX ), \ + _mbg_cn_table_entry( GPS_SHS ), \ + _mbg_cn_table_entry( GPS_SHS_STATUS ), \ + _mbg_cn_table_entry( GPS_NET_GLB_CFG ), \ + _mbg_cn_table_entry( GPS_NET_DNS_SRVR ), \ + _mbg_cn_table_entry( GPS_NET_DNS_SRCH_DOM ), \ + _mbg_cn_table_entry( GPS_NET_STAT_DNS_SRVR ), \ + _mbg_cn_table_entry( GPS_NET_STAT_DNS_SRCH_DOM ), \ + _mbg_cn_table_entry( GPS_GNSS_SAT_INFO_IDX ), \ + _mbg_cn_table_entry( GPS_XMR_HOLDOVER_ELAPSED ), \ + _mbg_cn_table_entry( GPS_GPIO_STATUS_IDX ), \ + _mbg_cn_table_entry( GPS_XMR_HOLDOVER_STATUS ), \ + _mbg_cn_table_entry( GPS_XBP_LIMITS ), \ + _mbg_cn_table_entry( GPS_XBP_NODE_LIMITS ), \ + _mbg_cn_table_entry( GPS_XBP_NODE_INFO_IDX ), \ + _mbg_cn_table_entry( GPS_FDM_OUTPUT_STATE_IDX ), \ + _mbg_cn_table_entry( GPS_FDM_OUTPUT_SETTINGS_IDX ), \ + _mbg_cn_table_entry( GPS_FDM_OUTPUT_INFO_IDX ), \ + _mbg_cn_table_entry( GPS_FDM_LIMITS ), \ + _mbg_cn_table_entry( GPS_FDM_STATE ), \ + _mbg_cn_table_entry( GPS_FDM_SETTINGS ), \ + _mbg_cn_table_entry( GPS_FDM_INFO ), \ + _mbg_cn_table_entry( GPS_XMR_EXT_SRC_INFO_IDX ), \ + \ + /* GPS data */ \ + _mbg_cn_table_entry( GPS_CFGH ), \ + _mbg_cn_table_entry( GPS_ALM ), \ + _mbg_cn_table_entry( GPS_EPH ), \ + _mbg_cn_table_entry( GPS_UTC ), \ + _mbg_cn_table_entry( GPS_IONO ), \ + _mbg_cn_table_entry( GPS_ASCII_MSG ), \ + \ + /* Glonass data */ \ + _mbg_cn_table_entry( GPS_GLNS_ALM ), \ + _mbg_cn_table_entry( GPS_GNSS_SAT_INFO ), \ + _mbg_cn_table_entry( GPS_GNSS_MODE ), \ + \ + /* Misc data */ \ + _mbg_cn_table_entry( GPS_IP4_SETTINGS ), \ + _mbg_cn_table_entry( GPS_LAN_IF_INFO ), \ + _mbg_cn_table_entry( GPS_IP4_STATE ), \ + \ + /* misc data (SCU) */ \ + _mbg_cn_table_entry( GPS_SCU_STAT ), \ + \ + _mbg_cn_table_entry( GPS_CRYPTED_PACKET ), \ + _mbg_cn_table_entry( GPS_CRYPTED_RAW_PACKET ), \ + _mbg_cn_table_entry( GPS_XBP_PACKET ), \ + \ + _mbg_cn_table_entry( GPS_SECU_INFO ), \ + _mbg_cn_table_entry( GPS_SECU_SETTINGS ), \ + _mbg_cn_table_entry( GPS_SECU_PUBLIC_KEY ), \ + \ + /* PZF data */ \ + _mbg_cn_table_entry( PZF_PCPS_TIME ), \ + _mbg_cn_table_entry( PZF_TR_DISTANCE ), \ + _mbg_cn_table_entry( PZF_TZCODE ), \ + _mbg_cn_table_entry( PZF_CORR_INFO ), \ + _mbg_cn_table_end() \ } +#endif // !defined( MBG_TGT_DOS ) -/* A structure holding the number of a SV and the SV's almanac. */ +/** + * @brief An SV number plus the SV's almanac data + */ typedef struct { SVNO svno; @@ -536,9 +772,9 @@ typedef struct } SV_ALM; - -/* A structure holding the number of a SV and the SV's ephemeris. */ - +/** + * @brief An SV number plus the SV's ephemeris data + */ typedef struct { SVNO svno; @@ -549,37 +785,63 @@ typedef struct #if _USE_PCPSDEFS -/* Attention: this differs from PCPS_TZCODE defined in pcpsdefs.h */ +/** + * @brief Type of variable to hold a TZ code + * + * This is used with the binary protocol but differs from ::PCPS_TZCODE + * which is used with the PCI interface. + * + * @see ::PCPS_TZCODE + * @see ::TZCODE_UNION + */ typedef uint16_t TZCODE; -#endif +#define _mbg_swab_tzcode( _p ) \ + _mbg_swab16( _p ); + + +/** + * @brief A union holding different types of a TZ code + * + * This is used with the binary protocol but differs from ::PCPS_TZCODE + * which is used with the PCI interface. + * + * @see ::TZCODE + * @see ::PCPS_TZCODE + */ +typedef union +{ + TZCODE ser; ///< code retrieved via serial binary protocol + PCPS_TZCODE pci; ///< code retrieved via PCI bus + +} TZCODE_UNION; +#endif -/* The message header */ +/** + * @brief The header of a binary message. + */ typedef struct { - GPS_CMD cmd; - uint16_t len; - CSUM data_csum; - CSUM hdr_csum; -} MSG_HDR; + GPS_CMD cmd; ///< see ::GPS_CMD_CODES and ::GPS_CMD_CTRL_CODES + uint16_t len; ///< length of the data portion appended after the header + CSUM data_csum; ///< checksum of the data portion appended after the header + CSUM hdr_csum; ///< checksum of the preceding header bytes +} MSG_HDR; -/* A union combining all kinds of parameters to be read from or written */ -/* to the GPS receiver. The size of the union corresponds to the maximum */ -/* size of the data part of a message. */ +/** + * @brief A union of all data types used with the binary protocol. + */ typedef union { - /* common types */ uint16_t us; double d; SVNO svno; - - /* user data */ SW_REV sw_rev; BVAR_STAT bvar_stat; TTM ttm; @@ -623,8 +885,59 @@ typedef union GNSS_SAT_INFO gnss_sat_info; //##++++++ MBG_GNSS_MODE_INFO gnss_mode_info; //##++++++ MBG_GNSS_MODE_SETTINGS gnss_mode_settings; //##++++++ + MBG_GPIO_CFG_LIMITS gpio_cfg_limits; + MBG_GPIO_INFO_IDX gpio_info_idx; + MBG_GPIO_SETTINGS_IDX gpio_settings_idx; + XMULTI_REF_INSTANCES xmulti_ref_instances; + MBG_NUM_EVT_LOG_ENTRIES num_evt_log_entries; + MBG_EVT_LOG_ENTRY evt_log_entry; + LNO_STATE lno_state; + MBG_IMS_STATE ims_state; + MBG_IMS_SENSOR_STATE_IDX ims_sensor_state_idx; + XMR_HOLDOVER_INTV xmr_holdover_intv; + HAVEQUICK_SETTINGS havequick_settings; + HAVEQUICK_INFO havequick_info; + PTP_CFG_INFO ptp_cfg_info; + PTP_CFG_SETTINGS ptp_cfg_settings; + PTP_STATE ptp_state; + PTP_UC_MASTER_CFG_LIMITS ptp_uc_master_cfg_limits; + PTP_UC_MASTER_INFO_IDX ptp_uc_master_info_idx; + PTP_UC_MASTER_SETTINGS_IDX ptp_uc_master_settings_idx; + NTP_GLB_INFO ntp_glb_info; + NTP_GLB_SETTINGS ntp_glb_settings; + NTP_CLNT_MODE_INFO ntp_clnt_mode_info; + NTP_CLNT_MODE_SETTINGS ntp_clnt_mode_settings; + #if defined( DEBUG ) + NTP_SRV_MODE_INFO ntp_srv_mode_info; + NTP_SRV_MODE_INFO ntp_srv_mode_settings; + #endif + NTP_PEER_SETTINGS_IDX ntp_peer_settings_idx; + NTP_SYS_STATE ntp_sys_state; + NTP_PEER_STATE_IDX ntp_peer_state_idx; + SHS_INFO shs_info; + SHS_SETTINGS shs_settings; + SHS_STATUS shs_status; + MBG_NET_GLB_CFG_INFO net_glb_cfg_info; + MBG_NET_GLB_CFG_SETTINGS net_glb_cfg_settings; + MBG_IP_ADDR_IDX ip_addr_idx; + MBG_NET_NAME_IDX net_name_idx; + GNSS_SAT_INFO_IDX gnss_sat_info_idx; + MBG_GPIO_STATUS_IDX gpio_status_idx; + XMR_HOLDOVER_STATUS xmr_holdover_status; + XBP_LIMITS xbp_limits; + XBP_NODE_LIMITS xbp_node_limits; + XBP_NODE_INFO_IDX xbp_node_info_idx; + MBG_IMS_FDM_OUTPUT_STATE_IDX fdm_output_state_idx; + MBG_IMS_FDM_OUTPUT_SETTINGS_IDX fdm_output_settings_idx; + MBG_IMS_FDM_OUTPUT_INFO_IDX fdm_output_info_idx; + MBG_IMS_FDM_LIMITS fdm_limits; + MBG_IMS_FDM_STATE fdm_state; + MBG_IMS_FDM_SETTINGS fdm_settings; + MBG_IMS_FDM_INFO fdm_info; + XMR_EXT_SRC_INFO_IDX xmr_ext_src_info_idx; + + //##++ PTP_POWER_PROFILE_CFG ptp_power_profile_cfg; // no cmd code, yet. - /* GPS system data */ CFGH cfgh; SV_ALM sv_alm; SV_EPH sv_eph; @@ -632,10 +945,12 @@ typedef union IONO iono; ASCII_MSG ascii_msg; - /* Misc data */ IP4_SETTINGS ip4_settings; LAN_IF_INFO lan_if_info; + SCU_STAT_INFO scu_stat_info; + SCU_STAT_SETTINGS scu_stat_settings; + #if _USE_PCPSDEFS PCPS_TIME pcps_time; TR_DISTANCE tr_distance; @@ -654,6 +969,7 @@ typedef union } MSG_DATA; +/// The maximum number of bytes required for a ::MSG_DATA buffer #ifndef MAX_MSG_DATA_SIZE #ifndef ADD_MSG_DATA_SIZE #if _USE_ENCRYPTION @@ -667,10 +983,66 @@ typedef union #endif +/** + * @brief A union of all data types used with the binary protocol, or array of bytes. + * + * This union can be used to implement a buffer which can hold either a known data structure + * or an array of bytes which can be read from or written to a device. + */ +typedef union +{ + MSG_DATA msg_data; ///< union of known structures + uint8_t bytes[MAX_MSG_DATA_SIZE]; + +} STD_MSG_DATA_BUFF; + -/* The structures below define parts of a binary message packet which */ -/* are used with encrypted messages, */ +/** + * @brief The format of a standard binary message. + */ +typedef struct +{ + MSG_HDR hdr; ///< Message header containing the command code and length of the data portion + STD_MSG_DATA_BUFF data_buf; ///< Data portion using the number of bytes specified in the header + +} MBG_STD_MSG; + + + +/** + * @brief The data portion of an XBP message. + */ +typedef struct +{ + XBP_ADDR xbp_addr; ///< XBP address of the transmitter or receiver + MBG_STD_MSG std_msg; ///< Encapsulated standard binary message + +} XBP_MSG_DATA; + + + +/** + * @brief A message header for the eXtended Binary Protocol (XBP) + * + * The data portion of such message is a standard binary message. + * The ::MSG_HDR::len field in ::XBP_MSG_HDR::xbp_hdr must contain + * the number of bytes following the xbp_hdr field, i.e. the length + * of the whole encapsulated binary message plus the size of the + * xbp_addr field. + */ +typedef struct +{ + MSG_HDR xbp_hdr; + XBP_ADDR xpb_addr; + +} XBP_MSG_HDR; + + + +/** + * @brief A message prefix used for encrypted messages + */ typedef struct { MSG_HDR hdr; @@ -678,7 +1050,7 @@ typedef struct #if _USE_ENCRYPTION uint8_t aes_initvect[AES_BLOCK_SIZE]; #else - // In this case this structure is just a dummy to avoid + // In this case this structure is just a dummy to avoid // a compiler error with the function prototypes. #endif @@ -688,21 +1060,13 @@ typedef struct #if _USE_ENCRYPTION +/** + * @brief A message data block used for encrypted messages + */ typedef struct { uint8_t aes_initvect[AES_BLOCK_SIZE]; - - struct - { - MSG_HDR enc_hdr; - - union - { - uint8_t bytes[MAX_MSG_DATA_SIZE]; - MSG_DATA msg_data; - } enc_msg; - - } enc_msg; + MBG_STD_MSG std_msg; } CRYPT_MSG_DATA; @@ -710,21 +1074,25 @@ typedef struct -/* A buffer holding a message header plus data part of a message */ -/* For portability reasons the CMSG_BUFF structure defined below */ -/* should be preferred for coding. */ - +/** + * @brief A buffer for a message header plus data part + * + * The data part has to be interpreted depending on the command code + * in the message header field, hdr. + */ typedef struct { - MSG_HDR hdr; + MSG_HDR hdr; ///< The message header union { - uint8_t bytes[MAX_MSG_DATA_SIZE]; - MSG_DATA msg_data; + uint8_t bytes[MAX_MSG_DATA_SIZE]; ///< Data part as a number of bytes + MSG_DATA msg_data; ///< Standard message data structures + MBG_STD_MSG std_msg; ///< Encapsulated standard message + XBP_MSG_DATA xbp_msg_data; ///< XBP address field plus encapsulated standard message #if _USE_ENCRYPTION - CRYPT_MSG_DATA crypt_msg_data; + CRYPT_MSG_DATA crypt_msg_data; ///< Encryption data plus encrypted standard message #endif } u; @@ -733,30 +1101,34 @@ typedef struct -/* The structure below is used to control the reception of messages */ - +/** + * @brief A structure used to control the reception of binary messages + */ typedef struct { - MBG_MSG_BUFF *pmb; /* points to unencrypted message buffer */ - int buf_size; /* size of buffer, including header */ - uint8_t *cur; /* points to current pos inside receive buffer */ - int cnt; /* the number of bytes to receive */ - ulong flags; /* flags if header already completed */ + MBG_MSG_BUFF *pmb; ///< points to unencrypted message buffer + int buf_size; ///< size of buffer, including header + uint8_t *cur; ///< points to current pos inside receive buffer + int cnt; ///< the number of bytes to be received + ulong flags; ///< flags if header already completed, etc., see ::MBG_MSG_RCV_CTL_MASKS #if _USE_RCV_TSTAMP - MBG_TMO_TIME tstamp; + MBG_TMO_TIME tstamp; ///< time when the first byte of the packet was received #endif #if _USE_CHK_TSTR - void (*chk_tstr_fnc)( char c, TIMESTR_CHECK *arg ); /* optional handler for normal, non-protocol data */ - TIMESTR_CHECK *chk_tstr_arg; + CHK_TSTR_FNC chk_tstr_fnc; ///< optional handler for normal, non-protocol data + CHK_TSTR_ARG *chk_tstr_arg; ///< arguments for the non-protocol data handler #endif } MBG_MSG_RCV_CTL; -/* The flag bits below and the corresponding bit masks are used - for MBG_MSG_RCV_CTL::flags: */ -enum +/** + * @brief Receive control bits used to define ::MBG_MSG_RCV_CTL_MASKS + * + * @see ::MBG_MSG_RCV_CTL_MASKS + */ +enum MBG_MSG_RCV_CTL_BITS { MBG_MSG_RCV_CTL_BIT_RCVD_HDR, MBG_MSG_RCV_CTL_BIT_MSG_TOO_LONG, @@ -766,32 +1138,50 @@ enum N_MBG_MSG_RCV_CTL_BIT }; -#define MBG_MSG_RCV_CTL_RCVD_HDR ( 1UL << MBG_MSG_RCV_CTL_BIT_RCVD_HDR ) -#define MBG_MSG_RCV_CTL_MSG_TOO_LONG ( 1UL << MBG_MSG_RCV_CTL_BIT_MSG_TOO_LONG ) -#define MBG_MSG_RCV_CTL_OVERFLOW ( 1UL << MBG_MSG_RCV_CTL_BIT_OVERFLOW ) -#define MBG_MSG_RCV_CTL_DECRYPT_ERR ( 1UL << MBG_MSG_RCV_CTL_BIT_DECRYPT_ERR ) -#define MBG_MSG_RCV_CTL_DECRYPTED ( 1UL << MBG_MSG_RCV_CTL_BIT_DECRYPTED ) +/** + * @brief Receive control bit masks + * + * Used with ::MBG_MSG_RCV_CTL::flags + * + * @see ::MBG_MSG_RCV_CTL_BITS + */ +enum MBG_MSG_RCV_CTL_MASKS +{ + MBG_MSG_RCV_CTL_RCVD_HDR = ( 1UL << MBG_MSG_RCV_CTL_BIT_RCVD_HDR ), ///< see ::MBG_MSG_RCV_CTL_BIT_RCVD_HDR + MBG_MSG_RCV_CTL_MSG_TOO_LONG = ( 1UL << MBG_MSG_RCV_CTL_BIT_MSG_TOO_LONG ), ///< see ::MBG_MSG_RCV_CTL_BIT_MSG_TOO_LONG + MBG_MSG_RCV_CTL_OVERFLOW = ( 1UL << MBG_MSG_RCV_CTL_BIT_OVERFLOW ), ///< see ::MBG_MSG_RCV_CTL_BIT_OVERFLOW + MBG_MSG_RCV_CTL_DECRYPT_ERR = ( 1UL << MBG_MSG_RCV_CTL_BIT_DECRYPT_ERR ), ///< see ::MBG_MSG_RCV_CTL_BIT_DECRYPT_ERR + MBG_MSG_RCV_CTL_DECRYPTED = ( 1UL << MBG_MSG_RCV_CTL_BIT_DECRYPTED ) ///< see ::MBG_MSG_RCV_CTL_BIT_DECRYPTED +}; + -typedef struct +/** + * @brief A structure used to control the transmission of binary messages + */ +typedef struct { - MBG_MSG_BUFF *pmb; - int buf_size; - int xfer_mode; + MBG_MSG_BUFF *pmb; ///< points to unencrypted message buffer + int buf_size; ///< size of buffer, including header + int xfer_mode; ///< transfer mode, see ::MBG_XFER_MODES #if _USE_MUTEX - MBG_MUTEX xmt_mutex; + MBG_MUTEX xmt_mutex; ///< mutex to serialize transmission #endif } MBG_MSG_XMT_CTL; -// codes used with MBG_MSG_CTL::xfer_mode: -enum +/** + * @brief Binary message transfer modes + * + * Used with ::MBG_MSG_XMT_CTL::xfer_mode + */ +enum MBG_XFER_MODES { - MBG_XFER_MODE_NORMAL, - MBG_XFER_MODE_ENCRYTED, + MBG_XFER_MODE_NORMAL, ///< normal, unencrypted transmission + MBG_XFER_MODE_ENCRYPTED, ///< encrypted transmission, usually over network N_MBG_XFER_MODE }; @@ -805,13 +1195,47 @@ enum #define LAN_XPT_PORT 10001 -#ifndef INVALID_SOCKET - #define INVALID_SOCKET -1 + +/** + * @brief A socket file descriptor type + */ +#if defined( MBG_TGT_WIN32 ) + typedef SOCKET MBG_SOCK_FD; // usually evaluates to (unsigned int), or (unsigned __int64) +#elif defined( MBG_TGT_POSIX ) + typedef int MBG_SOCK_FD; #endif + +/** + * @brief A value to mark an ::MBG_SOCK_FD as invalid + */ +#if defined( MBG_TGT_WIN32 ) + #define MBG_INVALID_SOCK_FD INVALID_SOCKET // usually evaluates to (SOCKET)(~0) since SOCKET is unsigned +#elif defined( MBG_TGT_POSIX ) + #define MBG_INVALID_SOCK_FD -1 +#endif + +#if defined( MBG_TGT_WIN32 ) + #define socklen_t int +#elif defined( MBG_TGT_POSIX ) + #define socklen_t socklen_t +#endif + + +/** + * @brief The return code of socket functions in case of error + */ +#if defined( MBG_TGT_WIN32 ) + #define MBG_SOCKET_ERR_RETVAL SOCKET_ERROR // usually evaluates to -1 +#elif defined( MBG_TGT_POSIX ) + #define MBG_SOCKET_ERR_RETVAL -1 +#endif + + + typedef struct { - int sockfd; + MBG_SOCK_FD sockfd; struct sockaddr_in addr; } SOCKET_IO_STATUS; @@ -819,27 +1243,50 @@ typedef struct #endif // _USE_SOCKET_IO -#if _USE_SERIAL_IO +#if _USE_SERIAL_IO_FTDI + +typedef struct +{ + FT_HANDLE port_handle; + +} FTDI_IO_STATUS; -#endif // _USE_SERIAL_IO +#endif // _USE_SERIAL_IO_FTDI -#if defined( _USE_PACK ) // set default alignment - #pragma pack() + +#if _USE_USB_DIRECT_IO + +typedef int MBG_USB_DIRECT_IO_FD; + +#if !defined (MBG_USB_DIRECT_IO_INVALID_FD) + #define MBG_USB_DIRECT_IO_INVALID_FD -1 #endif +#if !defined ( MBGEXTIO_RCV_TIMEOUT_USB_DIRECT_IO ) + #define MBGEXTIO_RCV_TIMEOUT_USB_DIRECT_IO 1000 // [ms] +#endif + +typedef struct +{ + MBG_USB_DIRECT_IO_FD usbdiofd; +}USB_DIRECT_IO_STATUS; -// For the next structure we can and should use native alignment: +#endif // _USE_USB_DIRECT_IO -typedef struct + + +/** + * @brief A generic message send and receive control structure + */ +typedef struct { MBG_MSG_RCV_CTL rcv; MBG_MSG_XMT_CTL xmt; int conn_type; - int io_error; - ulong msg_rcv_timeout; // binary message receive timeout [ms] - ulong char_rcv_timeout; // serial character receive timeout [ms] + ulong msg_rcv_timeout; ///< binary message receive timeout [ms] + ulong char_rcv_timeout; ///< serial character receive timeout [ms] #if _USE_ENCRYPTION uint8_t aes_initvect[AES_BLOCK_SIZE]; @@ -850,7 +1297,11 @@ typedef struct SECU_SETTINGS secu_settings; #endif - #if _USE_SERIAL_IO || _USE_SOCKET_IO + #if _USE_SERIAL_IO || \ + _USE_SERIAL_IO_FTDI || \ + _USE_SOCKET_IO || \ + _USE_USB_IO || \ + _USE_USB_DIRECT_IO union { #if _USE_SOCKET_IO @@ -860,18 +1311,36 @@ typedef struct #if _USE_SERIAL_IO SERIAL_IO_STATUS serio; #endif + + #if _USE_SERIAL_IO_FTDI + FTDI_IO_STATUS ftdiio; + #endif + + #if _USE_USB_IO + USB_IO_STATUS usbio; + #endif + + #if _USE_USB_DIRECT_IO + USB_DIRECT_IO_STATUS usbdio; + #endif } st; #endif } MBG_MSG_CTL; -// codes used with MBG_MSG_CTL::conn_type: - -enum +/** + * @brief Binary message connection types + * + * Used with ::MBG_MSG_CTL::conn_type + */ +enum MBG_CONN_TYPES { - MBG_CONN_TYPE_SERIAL, - MBG_CONN_TYPE_SOCKET, + MBG_CONN_TYPE_SERIAL, ///< connection via serial port + MBG_CONN_TYPE_SOCKET, ///< connection via network socket + MBG_CONN_TYPE_USB, ///< connection via direct USB + MBG_CONN_TYPE_SERIAL_FTDI, ///< connection via FTDI D2xx USB-To-Serial converter + MBG_CONN_TYPE_USB_DIRECT_IO, ///< connection via direct USB I/O operation N_MBG_CONN_TYPE }; @@ -886,19 +1355,160 @@ enum /* This section was generated automatically */ /* by MAKEHDR, do not remove the comments. */ - CSUM msg_csum_update( CSUM csum, uint8_t *p, int n ) ; - CSUM msg_csum( uint8_t *p, int n ) ; - CSUM msg_hdr_csum( MSG_HDR *pmh ) ; - int chk_hdr_csum( MSG_HDR *pmh ) ; - int chk_data_csum( MBG_MSG_BUFF *pmb ) ; + /** + * @brief Translate a FTDI API status code to one of the @ref MBG_ERROR_CODES + * + * @param[in] status A status code defined by the FTDI API interface + * + * @return One of the @ref MBG_RETURN_CODES + */ + int mbg_ftdi_ft_status_to_mbg( FT_STATUS status ) ; + + /** + * @brief Compute a simple binary checksum + * + * Compute a checksum about a number of bytes starting + * with a given initial value. + * + * @param[in] csum the initial value + * @param[in] p pointer to a buffer of data bytes + * @param[in] n the number of bytes in the buffer + * + * @return the computed checksum + */ + CSUM msg_csum_update( CSUM csum, const uint8_t *p, int n ) ; + + /** + * @brief Compute a checksum for a binary message + * + * @note This function differs from the checksum() function + * used to compute the checksum of battery-buffered variables. + * + * @param[in] p pointer to a buffer of data bytes + * @param[in] n the number of bytes in the buffer + * + * @return the computed checksum + */ + CSUM msg_csum( const uint8_t *p, int n ) ; + + /** + * @brief Compute the checksum of a binary message header + * + * @param[in] pmh pointer to a binary message header + * + * @return the computed checksum + */ + CSUM msg_hdr_csum( const MSG_HDR *pmh ) ; + + /** + * @brief Check if the header checksum of a binary message is valid + * + * @param[in] pmh pointer to a binary message header + * + * @return ::MBG_SUCCESS or ::MBG_ERR_HDR_CSUM + */ + int chk_hdr_csum( const MSG_HDR *pmh ) ; + + /** + * @brief Check if the data checksum of a binary message is valid + * + * @param[in] pmb pointer to a binary message buffer + * + * @return ::MBG_SUCCESS or ::MBG_ERR_DATA_CSUM + */ + int chk_data_csum( const MBG_MSG_BUFF *pmb ) ; + + /** + * @brief Encrypt a binary message + * + * In encryption mode the original packet is encrypted and put + * as data portion into an envelope package. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in,out] pcmp Pointer to encryption settings + * @param[in,out] pmb Pointer to a binary message buffer + * + * @return the number of bytes of the encrypted message, or one of the @ref MBG_ERROR_CODES + */ int encrypt_message( MBG_MSG_CTL *pmctl, CRYPT_MSG_PREFIX *pcmp, MBG_MSG_BUFF *pmb ) ; + + /** + * @brief Decrypt an encrypted binary message + * + * @param[in,out] pmctl Pointer to a valid message control structure + * + * @return One of the @ref MBG_RETURN_CODES + */ int decrypt_message( MBG_MSG_CTL *pmctl ) ; + + /** + * @brief Set communication channel to specified encryption mode + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] mode Encryption mode, usually ::MBG_XFER_MODE_ENCRYPTED + * @param[in] key The crypto key (password) to be used + */ void set_encryption_mode( MBG_MSG_CTL *pmctl, int mode, const char *key ) ; - int xmt_tbuff( MBG_MSG_CTL *pmctl ) ; - int xmt_cmd( MBG_MSG_CTL *pmctl, GPS_CMD cmd ) ; - int xmt_cmd_us( MBG_MSG_CTL *pmctl, GPS_CMD cmd, uint16_t us ) ; + + /** + * @brief Complete message header and transmit message + * + * Compute checksums and complete the message header, + * then transmit both header and data. The caller must + * have copied the data to be sent to the data field + * of the transmit buffer and have set up the cmd and + * len fields of the message header. + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to XBP address specifier + * + * @return one of the @ref MBG_RETURN_CODES + */ + int xmt_tbuff( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr ) ; + + /** + * @brief Send a binary command message without parameters + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to XBP address specifier + * @param[in] cmd One of the command codes enumerated in ::GPS_CMD_CODES + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::xmt_cmd_us + */ + int xmt_cmd( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, GPS_CMD cmd ) ; + + /** + * @brief Send a binary command message with ushort ( 16 bit) parameter + * + * @param[in,out] pmctl Pointer to a valid message control structure + * @param[in] p_addr Pointer to XBP address specifier + * @param[in] cmd One of the command codes enumerated in ::GPS_CMD_CODES + * @param[in] us The 16 bit message parameter (data) + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::xmt_cmd + */ + int xmt_cmd_us( MBG_MSG_CTL *pmctl, const XBP_ADDR *p_addr, GPS_CMD cmd, uint16_t us ) ; + + /** + * @brief Check an incoming data stream for a binary message + * + * Check the sequence of incoming characters for blocks of + * binary message data. Binary messages are saved in a buffer + * which is part of the ::MBG_MSG_RCV_CTL structure and the + * caller checks the return value to get the receive status. + * + * @param[in,out] prctl Pointer to a valid receive control structure + * @param[in] c A byte from the incoming data stream + * + * @return One of the ::TR_STATUS_CODES + */ int check_transfer( MBG_MSG_RCV_CTL *prctl, uint8_t c ) ; + /* ----- function prototypes end ----- */ #endif // _USE_GPSSERIO_FNC @@ -914,3 +1524,4 @@ enum #endif /* _GPSSERIO_H */ + |