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