From f9203f1a4a9b635cbe96670ed5a5e5309bb10697 Mon Sep 17 00:00:00 2001 From: Sylvain Miermont Date: Thu, 19 Dec 2013 17:41:02 +0100 Subject: v1.2.0 - Added feature: new GPS module in the library for synchronization - Removed feature: no more missed deadline detection in TX because of incompatibility with GPS - Added documentation for GPS and legal notice - Added flags in Makefiles for easier cross-compilation --- libloragw/inc/loragw_gps.h | 179 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 179 insertions(+) create mode 100644 libloragw/inc/loragw_gps.h (limited to 'libloragw/inc/loragw_gps.h') diff --git a/libloragw/inc/loragw_gps.h b/libloragw/inc/loragw_gps.h new file mode 100644 index 0000000..3884fd5 --- /dev/null +++ b/libloragw/inc/loragw_gps.h @@ -0,0 +1,179 @@ +/* + / _____) _ | | +( (____ _____ ____ _| |_ _____ ____| |__ + \____ \| ___ | (_ _) ___ |/ ___) _ \ + _____) ) ____| | | || |_| ____( (___| | | | +(______/|_____)_|_|_| \__)_____)\____)_| |_| + ©2013 Semtech-Cycleo + +Description: + Library of functions to manage a GNSS module (typically GPS) for accurate + timestamping of packets and synchronisation of gateways. + A limited set of module brands/models are supported. + +License: Revised BSD License, see LICENSE.TXT file include in the project +Maintainer: Sylvain Miermont +*/ + + +#ifndef _LORAGW_GPS_H +#define _LORAGW_GPS_H + +/* -------------------------------------------------------------------------- */ +/* --- DEPENDANCIES --------------------------------------------------------- */ + +/* fix an issue between POSIX and C99 */ +#if __STDC_VERSION__ >= 199901L + #define _XOPEN_SOURCE 600 +#else + #define _XOPEN_SOURCE 500 +#endif + +#include /* C99 types */ +#include /* time library */ +#include /* speed_t */ + +/* -------------------------------------------------------------------------- */ +/* --- PUBLIC TYPES --------------------------------------------------------- */ + +/** +@struct coord_s +@brief Time solution required for timestamp to absolute time conversion +*/ +struct tref { + time_t systime; /*!> system time when solution was calculated */ + uint32_t count_us; /*!> reference concentrator internal timestamp */ + struct timespec utc; /*!> reference UTC time (from GPS) */ + double xtal_err; /*!> clock error estimation (eg. <1 'slow' XTAL) */ +}; + +/** +@struct coord_s +@brief Geodesic coordinates +*/ +struct coord_s { + double lat; /*!> latitude [-90,90] (North +, South -) */ + double lon; /*!> longitude [-180,180] (East +, West -)*/ + short alt; /*!> altitude in meters (WGS 84 geoid ref.) */ +}; + +/** +@enum gps_msg +@brief Type of GPS (and other GNSS) sentences +*/ +enum gps_msg { + UNKNOWN, /*!> neutral value */ + IGNORED, /*!> frame was not parsed by the system */ + INVALID, /*!> system try to parse frame but failed */ + /* NMEA messages of interest */ + NMEA_RMC, /*!> Recommended Minimum data (time + date) */ + NMEA_GGA, /*!> Global positioning system fix data (pos + alt) */ + NMEA_GNS, /*!> GNSS fix data (pos + alt, sat number) */ + NMEA_ZDA, /*!> Time and Date */ + /* NMEA message useful for time reference quality assessment */ + NMEA_GBS, /*!> GNSS Satellite Fault Detection */ + NMEA_GST, /*!> GNSS Pseudo Range Error Statistics */ + NMEA_GSA, /*!> GNSS DOP and Active Satellites (sat number) */ + NMEA_GSV, /*!> GNSS Satellites in View (sat SNR) */ + /* Misc. NMEA messages */ + NMEA_GLL, /*!> Latitude and longitude, with time fix and status */ + NMEA_TXT, /*!> Text Transmission */ + NMEA_VTG, /*!> Course over ground and Ground speed */ + /* uBlox proprietary NMEA messages of interest */ + UBX_POSITION, /*!> */ + UBX_TIME /*!> */ +}; + +/* -------------------------------------------------------------------------- */ +/* --- PUBLIC CONSTANTS ----------------------------------------------------- */ + +#define LGW_GPS_SUCCESS 0 +#define LGW_GPS_ERROR -1 + +/* -------------------------------------------------------------------------- */ +/* --- PUBLIC FUNCTIONS PROTOTYPES ------------------------------------------ */ + +/** +@brief Configure a GPS module + +@param tty_path path to the TTY connected to the GPS +@param gps_familly parameter (eg. ubx6 for uBlox gen.6) +@param target_brate target baudrate for communication (0 keeps default target baudrate) +@param fd_ptr pointer to a variable to receive file descriptor on GPS tty +@return success if the function was able to connect and configure a GPS module +*/ +int lgw_gps_enable(char* tty_path, char* gps_familly, speed_t target_brate, int* fd_ptr); + +/** +@brief Parse messages coming from the GPS system (or other GNSS) + +@param serial_buff pointer to the string to be parsed +@param buff_size maximum string lengths for NMEA parsing (incl. null char) +@return type of frame parsed + +The RAW NMEA sentences are parsed to a global set of variables shared with the +lgw_gps_get function. +If the lgw_parse_nmea and lgw_gps_get are used in different threads, a mutex +lock must be acquired before calling either function. +*/ +enum gps_msg lgw_parse_nmea(char* serial_buff, int buff_size); + +/** +@brief Get the GPS solution (space & time) for the gateway + +@param utc pointer to store UTC time, with ns precision (NULL to ignore) +@param loc pointer to store coordinates (NULL to ignore) +@param err pointer to store coordinates standard deviation (NULL to ignore) +@return success if the chosen elements could be returned + +This function read the global variables generated by the NMEA parsing function +lgw_parse_nmea. It returns time and location data in a format that is +exploitable by other functions in that library sub-module. +If the lgw_parse_nmea and lgw_gps_get are used in different threads, a mutex +lock must be acquired before calling either function. +*/ +int lgw_gps_get(struct timespec* utc, struct coord_s* loc, struct coord_s* err); + +/** +@brief Take a timestamp and UTC time and refresh reference for time conversion + +@param ref pointer to time reference structure +@param old_ref previous time reference (NULL for initial fix) +@param utc UTC time, with ns precision (leap seconds are ignored) +@return success if timestamp was read and time reference could be refreshed + +Set systime to 0 in ref to trigger initial synchronization. +*/ +int lgw_gps_sync(struct tref* ref, uint32_t count_us, struct timespec utc); + +/** +@brief Convert concentrator timestamp counter value to UTC time + +@param ref time reference structure required for time conversion +@param count_us internal timestamp counter of a Lora gateway +@param utc pointer to store UTC time, with ns precision (leap seconds ignored) +@return success if the function was able to convert timestamp to UTC + +This function is typically used when a packet is received to transform the +internal counter-based timestamp in an absolute timestamp with an accuracy in +the order of a couple microseconds (ns resolution). +*/ +int lgw_cnt2utc(struct tref ref, uint32_t count_us, struct timespec* utc); + +/** +@brief Convert UTC time to concentrator timestamp counter value + +@param ref time reference structure required for time conversion +@param utc UTC time, with ns precision (leap seconds are ignored) +@param count_us pointer to store internal timestamp counter of a Lora gateway +@return success if the function was able to convert UTC to timestamp + +This function is typically used when a packet must be sent at an accurate time +(eg. to send a piggy-back response after receiving a packet from a node) to +transform an absolute UTC time into a matching internal concentrator timestamp. +*/ +int lgw_utc2cnt(struct tref ref,struct timespec utc, uint32_t* count_us); + +#endif + +/* --- EOF ------------------------------------------------------------------ */ -- cgit v1.2.3