1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
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 <stdint.h> /* C99 types */
#include <time.h> /* time library */
#include <termios.h> /* 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 ------------------------------------------------------------------ */
|
