m2mb API docs  25.30.004.0
m2mb API sets documentation
m2mb_gnss.h
Go to the documentation of this file.
1 /* $version: 252203 */
2 /*===============================================================================================*/
3 /* >>> Copyright (C) Telit Communications S.p.A. Italy All Rights Reserved. <<< */
25 #ifndef M2M_M2MB_GNSS_API_H
26 #define M2M_M2MB_GNSS_API_H
27 
28 
29 /* Global declarations ==========================================================================*/
30 
31 
32 /* Global typedefs ==============================================================================*/
33 typedef struct M2MB_GNSS_HANDLE_TAG *M2MB_GNSS_HANDLE;
34 
35 /* Indications */
36 typedef enum
37 {
38  /*
39  Indication M2MB_GNSS_INDICATION_POSITION_REPORT
40  Event related to M2MB_GNSS_SERVICE_POSITION_REPORT service
41  */
42  M2MB_GNSS_INDICATION_POSITION_REPORT,
43  /*
44  Indication M2MB_GNSS_INDICATION_NMEA_REPORT
45  Event related to M2MB_GNSS_SERVICE_NMEA_REPORT service
46  */
47  M2MB_GNSS_INDICATION_NMEA_REPORT
48 } M2MB_GNSS_IND_E;
49 
50 /*
51  Services
52  Not all services are available on all products.
53 */
54 typedef enum
55 {
56  /*
57  Service M2MB_GNSS_SERVICE_POSITION_REPORT
58  Once the receiver acquires the position fix a callback (previously registered
59  in the m2mb_gnss_init) will be called showing the position report
60  */
61  M2MB_GNSS_SERVICE_POSITION_REPORT,
62  /*
63  Service M2MB_GNSS_SERVICE_NMEA_REPORT
64  A callback (previously registered in the m2mb_gnss_init) reporting the NMEA sentences
65  will be called
66  */
67  M2MB_GNSS_SERVICE_NMEA_REPORT
68 } M2MB_GNSS_SERVICE_E;
69 
70 /* Struct for M2MB_GNSS_SERVICE_POSITION_REPORT service */
71 typedef struct
72 {
73  UINT8 codingType; /* Coding of Velocity Type (see 3GPP GAD spec.) */
74 
75  FLOAT64 speed_horizontal;
76  FLOAT64 bearing;
77 } M2MB_GNSS_POS_REP_VELOCITY_T;
78 
79 typedef struct
80 {
81  FLOAT64 speed_horizontal;
82  FLOAT64 speed_vertical;
83 
84  FLOAT64 speed; /* The result */
85 } M2MB_GNSS_POS_REP_SPEED_T;
86 
87 /*
88  M2MB_GNSS_POSITION_REPORT_INFO_T struct
89  Struct containing the position report passed by the callback when the
90  M2MB_GNSS_SERVICE_POSITION_REPORT service has been started
91 */
92 typedef struct
93 {
94  BOOLEAN latitude_valid;
95  FLOAT64 latitude;
96 
97  BOOLEAN longitude_valid;
98  FLOAT64 longitude;
99 
100  BOOLEAN altitude_valid;
101  FLOAT64 altitude;
102 
103  BOOLEAN uncertainty_valid;
104  FLOAT64 uncertainty;
105 
106  BOOLEAN velocity_valid;
107  M2MB_GNSS_POS_REP_VELOCITY_T velocity;
108 
109  BOOLEAN timestamp_valid;
110  UINT64 timestamp; /* UTC timestamp - Units: Milliseconds since Jan. 1, 1970 */
111 
112  BOOLEAN speed_valid;
113  M2MB_GNSS_POS_REP_SPEED_T speed; /* NOT PRESENT! =>
114  I need to calculate it
115  from speed_horizontal and speed_vertical */
116 } M2MB_GNSS_POSITION_REPORT_INFO_T;
117 
118 /* Struct for M2MB_GNSS_SERVICE_GTP service */
119 typedef struct
120 {
121  UINT64 timestamp; /* UTC timestamp for a location fix; milliseconds since Jan. 1, 1970. */
122  FLOAT64 latitude; /* Latitude in degrees. */
123  FLOAT64 longitude; /* Longitude in degrees. */
124  FLOAT64 altitude; /* Altitude in meters above the WGS 84 reference ellipsoid. */
125  FLOAT64 altitudeMeanSeaLevel; /* Altitude in meters with respect to mean sea level. */
126  FLOAT32 speed; /* Speed in meters per second. */
127  FLOAT32 bearing; /* Bearing in degrees; range: 0 to 360. */
128  FLOAT32 accuracy; /* Accuracy in meters. */
129  FLOAT32 verticalAccuracy; /* Vertical accuracy in meters. */
130  FLOAT32 speedAccuracy; /* Speed accuracy in meters/second. */
131  FLOAT32 bearingAccuracy; /* Bearing accuracy in degrees (0 to 359.999). */
132 } M2MB_GNSS_GTP_INFO_T;
133 
134 /*
135  Parameters to set/get by m2mb_gnss_setcfg/m2mb_gnss_getcfg APIs.
136  Please see the description of these APIs for further information.
137 */
138 typedef enum
139 {
140  M2MB_GNSS_PRIORITY, /* GNSS or WWAN as App priority */
141  M2MB_GNSS_TBF, /* Time Between Fix */
142  M2MB_GNSS_CONSTELLATION /* Constellations selection */
143 } M2MB_GNSS_CFG_E;
144 
145 /*
146  WWAN/GNSS priority
147 */
148 typedef enum
149 {
150  GNSS_PRIORITY, /* GNSS as App priority.
151  GNSS fix request succeeds in all WWAN states except when WWAN is loaded
152  due to high priority procedures. */
153  WWAN_PRIORITY, /* WWAN as App priority.
154  GNSS fix request succeeds only in WWAN SLEEP state. */
155  ENUM_TO_INT( M2MB_GNSS_WWAN_GNSS_PRIORITY_E )
156 } M2MB_GNSS_WWAN_GNSS_PRIORITY_E;
157 
158 /*
159  AGNSS providers list to be set/get by m2mb_gnss_set_agnss_enable/m2mb_gnss_get_agnss_enable
160  Please see the description of these APIs for further information.
161 */
162 typedef enum
163 {
164  M2MB_AGNSS_XTRA /* AGNSS provider XTRA */
165 } M2MB_AGNSS_PROVIDERS_E;
166 
167 /*
168  Callback for GNSS m2mb APIs
169  The callback has to be registered in the m2mb_gnss_init.
170 
171  Service M2MB_GNSS_SERVICE_POSITION_REPORT
172  Once the receiver acquires the position fix, the callback will be received, including the
173  GNSS position report in the "resp" field, as a M2MB_GNSS_POSITION_REPORT_INFO_T struct.
174  Please see the following example:
175  void gnssCallback( M2MB_GNSS_HANDLE handle,
176  M2MB_GNSS_IND_E event,
177  UINT16 resp_size,
178  void *resp,
179  void *userdata )
180  {
181  if( event == M2MB_GNSS_INDICATION_POSITION_REPORT )
182  {
183  my_function_to_collect_GNSS_data( ( M2MB_GNSS_POSITION_REPORT_INFO_T * ) resp );
184  }
185  }
186 
187  Service M2MB_GNSS_SERVICE_NMEA_REPORT
188  The callback reporting the NMEA sentences, as a string, will be called.
189  Please see the following example:
190  void gnssCallback( M2MB_GNSS_HANDLE handle,
191  M2MB_GNSS_IND_E event,
192  UINT16 resp_size,
193  void *resp,
194  void *userdata )
195  {
196  if( event == M2MB_GNSS_INDICATION_NMEA_REPORT )
197  {
198  PRINT( "NMEA Sentences: %s", ( CHAR * ) resp );
199  }
200  }
201 */
202 typedef void ( *m2mb_gnss_callback )( M2MB_GNSS_HANDLE handle,
203  M2MB_GNSS_IND_E event,
204  UINT16 resp_size,
205  void *resp,
206  void *userdata );
207 
208 
209 /* Global functions =============================================================================*/
210 /*-----------------------------------------------------------------------------------------------*/
264 /*-----------------------------------------------------------------------------------------------*/
265 M2MB_RESULT_E m2mb_gnss_init( M2MB_GNSS_HANDLE *pHandle,
266  m2mb_gnss_callback callback,
267  void *userdata );
268 
269 
270 /*-----------------------------------------------------------------------------------------------*/
290 /*-----------------------------------------------------------------------------------------------*/
291 M2MB_RESULT_E m2mb_gnss_deinit( M2MB_GNSS_HANDLE handle );
292 
293 
294 /*-----------------------------------------------------------------------------------------------*/
334 /*-----------------------------------------------------------------------------------------------*/
335 M2MB_RESULT_E m2mb_gnss_enable( M2MB_GNSS_HANDLE handle, M2MB_GNSS_SERVICE_E service );
336 
337 
338 /*-----------------------------------------------------------------------------------------------*/
361 /*-----------------------------------------------------------------------------------------------*/
362 M2MB_RESULT_E m2mb_gnss_disable( M2MB_GNSS_HANDLE handle, M2MB_GNSS_SERVICE_E service );
363 
364 
365 /*-----------------------------------------------------------------------------------------------*/
410 /*-----------------------------------------------------------------------------------------------*/
411 M2MB_RESULT_E m2mb_gnss_start( M2MB_GNSS_HANDLE handle );
412 
413 
414 /*-----------------------------------------------------------------------------------------------*/
434 /*-----------------------------------------------------------------------------------------------*/
435 M2MB_RESULT_E m2mb_gnss_stop( M2MB_GNSS_HANDLE handle );
436 
437 
438 /*-----------------------------------------------------------------------------------------------*/
498 /*-----------------------------------------------------------------------------------------------*/
499 M2MB_RESULT_E m2mb_gnss_setcfg( M2MB_GNSS_HANDLE handle, M2MB_GNSS_CFG_E param, void * value );
500 
501 
502 /*-----------------------------------------------------------------------------------------------*/
561 /*-----------------------------------------------------------------------------------------------*/
562 M2MB_RESULT_E m2mb_gnss_getcfg( M2MB_GNSS_HANDLE handle, M2MB_GNSS_CFG_E param, void * value );
563 
564 
565 /*-----------------------------------------------------------------------------------------------*/
640 /*-----------------------------------------------------------------------------------------------*/
641 M2MB_RESULT_E m2mb_gnss_GTP( M2MB_GNSS_HANDLE handle );
642 
643 /*-----------------------------------------------------------------------------------------------*/
703 /*-----------------------------------------------------------------------------------------------*/
704 M2MB_RESULT_E m2mb_gnss_EnableGTP( M2MB_GNSS_HANDLE handle, UINT8 enablegtp );
705 
706 
707 
708 /*-----------------------------------------------------------------------------------------------*/
768 /*-----------------------------------------------------------------------------------------------*/
769 M2MB_RESULT_E m2mb_gnss_GetGTPstatus( M2MB_GNSS_HANDLE h, UINT8* status );
770 
771 
772 /*-----------------------------------------------------------------------------------------------*/
797 /*-----------------------------------------------------------------------------------------------*/
798 M2MB_RESULT_E m2mb_gnss_set_prio_runtime(
799  M2MB_GNSS_HANDLE handle,
800  M2MB_GNSS_WWAN_GNSS_PRIORITY_E priority );
801 
802 
803 /*-----------------------------------------------------------------------------------------------*/
829 /*-----------------------------------------------------------------------------------------------*/
830 M2MB_RESULT_E m2mb_gnss_get_prio_runtime(
831  M2MB_GNSS_HANDLE handle,
832  M2MB_GNSS_WWAN_GNSS_PRIORITY_E * priority );
833 
834 
835 #endif /* M2M_M2MB_GNSS_API_H */
836 
m2mb_gnss_init
M2MB_RESULT_E m2mb_gnss_init(M2MB_GNSS_HANDLE *pHandle, m2mb_gnss_callback callback, void *userdata)
Initializes gnss functionalities.
M2MB_GNSS_POS_REP_VELOCITY_T
Definition: m2mb_gnss.h:71
m2mb_gnss_set_prio_runtime
M2MB_RESULT_E m2mb_gnss_set_prio_runtime(M2MB_GNSS_HANDLE handle, M2MB_GNSS_WWAN_GNSS_PRIORITY_E priority)
Set WWAN/GNSS priority runtime.
m2mb_gnss_GTP
M2MB_RESULT_E m2mb_gnss_GTP(M2MB_GNSS_HANDLE handle)
Start a GTP session.
m2mb_gnss_EnableGTP
M2MB_RESULT_E m2mb_gnss_EnableGTP(M2MB_GNSS_HANDLE handle, UINT8 enablegtp)
Enables the GTP feature and reboot the device.
M2MB_GNSS_POSITION_REPORT_INFO_T
Definition: m2mb_gnss.h:92
m2mb_gnss_disable
M2MB_RESULT_E m2mb_gnss_disable(M2MB_GNSS_HANDLE handle, M2MB_GNSS_SERVICE_E service)
Disables a gnss service.
m2mb_gnss_enable
M2MB_RESULT_E m2mb_gnss_enable(M2MB_GNSS_HANDLE handle, M2MB_GNSS_SERVICE_E service)
Enables a gnss service.
m2mb_gnss_setcfg
M2MB_RESULT_E m2mb_gnss_setcfg(M2MB_GNSS_HANDLE handle, M2MB_GNSS_CFG_E param, void *value)
Set the GNSS configuration (priority, TBF, constellation). This is not supported on all products.
m2mb_gnss_get_prio_runtime
M2MB_RESULT_E m2mb_gnss_get_prio_runtime(M2MB_GNSS_HANDLE handle, M2MB_GNSS_WWAN_GNSS_PRIORITY_E *priority)
Get WWAN/GNSS priority runtime.
m2mb_gnss_getcfg
M2MB_RESULT_E m2mb_gnss_getcfg(M2MB_GNSS_HANDLE handle, M2MB_GNSS_CFG_E param, void *value)
Get the GNSS configuration (priority, TBF, constellation). This is not supported on all products.
M2MB_GNSS_GTP_INFO_T
Definition: m2mb_gnss.h:119
m2mb_gnss_deinit
M2MB_RESULT_E m2mb_gnss_deinit(M2MB_GNSS_HANDLE handle)
Deinitializes gnss functionalities.
m2mb_gnss_stop
M2MB_RESULT_E m2mb_gnss_stop(M2MB_GNSS_HANDLE handle)
Stops a service.
M2MB_GNSS_POS_REP_SPEED_T
Definition: m2mb_gnss.h:79
m2mb_gnss_GetGTPstatus
M2MB_RESULT_E m2mb_gnss_GetGTPstatus(M2MB_GNSS_HANDLE h, UINT8 *status)
Checks if GTP is enabled or disabled.
m2mb_gnss_start
M2MB_RESULT_E m2mb_gnss_start(M2MB_GNSS_HANDLE handle)
Starts a service.