m2mb_gnss.h File Reference

m2m base api for gnss functionalities More...

Go to the source code of this file.

Data Structures
struct	M2MB_GNSS_POS_REP_VELOCITY_T
struct	M2MB_GNSS_POS_REP_SPEED_T
struct	M2MB_GNSS_POSITION_REPORT_INFO_T
struct	M2MB_GNSS_GTP_INFO_T

Typedefs
typedef struct M2MB_GNSS_HANDLE_TAG *	M2MB_GNSS_HANDLE
typedef void(*	m2mb_gnss_callback) (M2MB_GNSS_HANDLE handle, M2MB_GNSS_IND_E event, UINT16 resp_size, void *resp, void *userdata)

Enumerations
enum	M2MB_GNSS_IND_E { M2MB_GNSS_INDICATION_POSITION_REPORT, M2MB_GNSS_INDICATION_NMEA_REPORT }
enum	M2MB_GNSS_SERVICE_E { M2MB_GNSS_SERVICE_POSITION_REPORT, M2MB_GNSS_SERVICE_NMEA_REPORT }
enum	M2MB_GNSS_CFG_E { M2MB_GNSS_PRIORITY, M2MB_GNSS_TBF, M2MB_GNSS_CONSTELLATION }
enum	M2MB_GNSS_WWAN_GNSS_PRIORITY_E { GNSS_PRIORITY, WWAN_PRIORITY }
enum	M2MB_AGNSS_PROVIDERS_E { M2MB_AGNSS_XTRA }

Functions
M2MB_RESULT_E	m2mb_gnss_init (M2MB_GNSS_HANDLE *pHandle, m2mb_gnss_callback callback, void *userdata)
	Initializes gnss functionalities. More...
M2MB_RESULT_E	m2mb_gnss_deinit (M2MB_GNSS_HANDLE handle)
	Deinitializes gnss functionalities. More...
M2MB_RESULT_E	m2mb_gnss_enable (M2MB_GNSS_HANDLE handle, M2MB_GNSS_SERVICE_E service)
	Enables a gnss service. More...
M2MB_RESULT_E	m2mb_gnss_disable (M2MB_GNSS_HANDLE handle, M2MB_GNSS_SERVICE_E service)
	Disables a gnss service. More...
M2MB_RESULT_E	m2mb_gnss_start (M2MB_GNSS_HANDLE handle)
	Starts a service. More...
M2MB_RESULT_E	m2mb_gnss_stop (M2MB_GNSS_HANDLE handle)
	Stops a service. More...
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. More...
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. More...
M2MB_RESULT_E	m2mb_gnss_GTP (M2MB_GNSS_HANDLE handle)
	Start a GTP session. More...
M2MB_RESULT_E	m2mb_gnss_EnableGTP (M2MB_GNSS_HANDLE handle, UINT8 enablegtp)
	Enables the GTP feature and reboot the device. More...
M2MB_RESULT_E	m2mb_gnss_GetGTPstatus (M2MB_GNSS_HANDLE h, UINT8 *status)
	Checks if GTP is enabled or disabled. More...
M2MB_RESULT_E	m2mb_gnss_set_prio_runtime (M2MB_GNSS_HANDLE handle, M2MB_GNSS_WWAN_GNSS_PRIORITY_E priority)
	Set WWAN/GNSS priority runtime. More...
M2MB_RESULT_E	m2mb_gnss_get_prio_runtime (M2MB_GNSS_HANDLE handle, M2MB_GNSS_WWAN_GNSS_PRIORITY_E *priority)
	Get WWAN/GNSS priority runtime. More...

Detailed Description

m2m base api for gnss functionalities

m2m/m2m_generic/common/m2mb_inc/m2mb_gnss.h

m2m base gnss api prototype

@notes Dependencies: math.h, m2mb_types.h

Author

Davide Cubeddu

Date

07/03/2017

Function Documentation

m2mb_gnss_deinit()

M2MB_RESULT_E m2mb_gnss_deinit

(

M2MB_GNSS_HANDLE

handle

)

Deinitializes gnss functionalities.

Deinitializes gnss functionalities for current client.

Parameters

[in]

handle

handle for the gnss functionalities (M2MB_GNSS_HANDLE).

Returns

M2MB_RESULT_E: it returns M2MB_RESULT_SUCCESS on success, a different value on error.

m2mb_gnss_deinit( handle );

m2mb_gnss_disable()

M2MB_RESULT_E m2mb_gnss_disable	(	M2MB_GNSS_HANDLE	handle,
		M2MB_GNSS_SERVICE_E	service
	)

Disables a gnss service.

m2mb_gnss_disable, for each service to deactivate, configures the system in order to don't manage the specified service.

Parameters

[in]	handle	handle for the gnss functionalities (M2MB_GNSS_HANDLE)
[in]	service	service to deactivate (M2MB_GNSS_SERVICE_E)

Returns

M2MB_RESULT_E: it returns M2MB_RESULT_SUCCESS on success, a different value on error.

m2mb_gnss_disable( handle, M2MB_GNSS_SERVICE_POSITION_REPORT );

m2mb_gnss_enable()

M2MB_RESULT_E m2mb_gnss_enable	(	M2MB_GNSS_HANDLE	handle,
		M2MB_GNSS_SERVICE_E	service
	)

Enables a gnss service.

m2mb_gnss_enable, for each service to activate, configures the system in order to manage the specified service. Not all services are available on all products.

Parameters

[in]	handle	handle for the gnss functionalities (M2MB_GNSS_HANDLE)
[in]	service	service to activate (M2MB_GNSS_SERVICE_E)

Returns

M2MB_RESULT_E: it returns M2MB_RESULT_SUCCESS on success, a different value on error.

m2mb_gnss_enable( handle, M2MB_GNSS_SERVICE_POSITION_REPORT );

M2MB_GNSS_HANDLE handle = NULL;
M2MB_RESULT_E res;
 
res = m2mb_gnss_init( &handle, gnssCallback, NULL );
if( M2MB_RESULT_SUCCESS != res )
{
  PRINT("m2mb_gnss_init FAIL");
  return;
}
PRINT("m2mb_gnss_init SUCCESS");
 
if( M2MB_RESULT_SUCCESS != m2mb_gnss_enable( handle, M2MB_GNSS_SERVICE_POSITION_REPORT ) )
{
  PRINT("m2mb_gnss_enable FAIL");
  return;
}
PRINT("m2mb_gnss_enable SUCCESS");

m2mb_gnss_EnableGTP()

M2MB_RESULT_E m2mb_gnss_EnableGTP	(	M2MB_GNSS_HANDLE	handle,
		UINT8	enablegtp
	)

Enables the GTP feature and reboot the device.

Enables the GTP feature and reboot the device

Parameters

[in]	handle	handle for the gnss functionalities (M2MB_GNSS_HANDLE)
[in]	enablegtp	enablegtp it can be either 1(enable) or 0(disable)

Returns

M2MB_RESULT_E: it returns M2MB_RESULT_SUCCESS on success, negative value on error or if platform isn't supported

m2mb_gnss_EnableGTP( handle, enablegtp );

void gnssCallback( M2MB_GNSS_HANDLE handle, M2MB_GNSS_IND_E event, UINT16 resp_size, void *resp, void *userdata )
{
  if(event == M2MB_GNSS_INDICATION_POSITION_REPORT)
  {
    // Success => you can use gnss data arrived.
  }
  else if(event == M2MB_GNSS_INDICATION_NMEA_REPORT)
  {
    // Success => you can use gnss data arrived.
  }
  else
  {
    // Fail
  }
}
void main(void)
{
  M2MB_GNSS_HANDLE gnss_handle;
  M2MB_RESULT_E result = 0;
  UINT8 enablegtp;
 
  result = m2mb_gnss_init( gnss_handle, gnssCallback, NULL );
  if(result != M2MB_RESULT_SUCCESS)
  {
    return;
  }
  else
  {
    printf("m2mb_gnss_init succeeded");
  }
  enablegtp = 1;
  result = m2mb_gnss_EnableGTP( gnss_handle, enablegtp);
  if ( result == M2MB_RESULT_SUCCESS )
  {
    printf( "m2mb_gnss_EnableGTP succeeded");
  }
 
}

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.

If the functionality is not supported the API returns error.

If concurrent WWAN and GNSS operations are not supported an arbitrator is designed to arbitrate concurrencies. GNSS_PRIORITY: GNSS as App priority. GNSS fix request succeeds in all WWAN states except when WWAN is loaded due to high priority procedures. WWAN_PRIORITY: WWAN as App priority. GNSS fix request succeeds only in WWAN SLEEP state. At the startup, runtime priority is equal to "startup" priority (stored in NVM), set by m2mb_gnss_setcfg API.

Parameters

[in]	handle	handle for the gnss functionalities (M2MB_GNSS_HANDLE)
[in]	priority	pointer to priority value to read (M2MB_GNSS_WWAN_GNSS_PRIORITY_E *)

Returns

M2MB_RESULT_E: it returns M2MB_RESULT_SUCCESS on success, a different value on error.

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.

If the functionality is not supported the API returns error.

The GNSS configuration get by this API is the current configuration, read from RAM.

M2MB_GNSS_PRIORITY: If concurrent WWAN and GNSS operations are not supported an arbitrator is designed to arbitrate concurrencies. Priority 0: GNSS as App priority. GNSS fix request succeeds in all WWAN states except when WWAN is loaded due to high priority procedures. Priority 1: WWAN as App priority. GNSS fix request succeeds only in WWAN SLEEP state. M2MB_GNSS_TBF: Time Between Fix: 1÷4294967 [sec] M2MB_GNSS_CONSTELLATION: If feature supported: –All GNSS constellations supported –Two constellations at a time –GPS + any 2nd-constellation 0 - The constellation is selected based on Mobile Country Code (MCC) of camped network 1 - GPS+GLO 2 - GPS+GAL 3 - GPS+BDS 4 - GPS+QZSS

Parameters

[in]	handle	handle for the gnss functionalities (M2MB_GNSS_HANDLE)
[in]	param	CFG parameter to get (M2MB_GNSS_CFG_E)
[in]	value	pointer to the memory to be filled with the value of the specified CFG parameter read (void *)

Returns

M2MB_RESULT_E: it returns M2MB_RESULT_SUCCESS on success, a different value on error.

m2mb_gnss_getcfg( handle, M2MB_GNSS_PRIORITY, &priority );

M2MB_GNSS_HANDLE handle;
UINT8 priority;
UINT32 TBF;
UINT8 constellation;
 
m2mb_gnss_init( &handle, gnssCallback_test, NULL );
 
m2mb_gnss_getcfg( handle, M2MB_GNSS_PRIORITY, &priority );
m2mb_gnss_getcfg( handle, M2MB_GNSS_TBF, &TBF );
m2mb_gnss_getcfg( handle, M2MB_GNSS_CONSTELLATION, &constellation );
 
PRINT("Priority: %d", priority);
PRINT("TBF: %d", TBF);
PRINT("Constellation: %d", constellation);

m2mb_gnss_GetGTPstatus()

M2MB_RESULT_E m2mb_gnss_GetGTPstatus	(	M2MB_GNSS_HANDLE	h,
		UINT8 *	status
	)

Checks if GTP is enabled or disabled.

Checks if GTP feature is enabled or disabled

Parameters

[in]	handle	handle for the gnss functionalities (M2MB_GNSS_HANDLE)
[in]	status	status gets updated with either 1(enabled) or 0(disabled)

Returns

M2MB_RESULT_E: it returns M2MB_RESULT_SUCCESS on success, negative value on error or if platform isn't supported.

m2mb_gnss_GetGTPstatus( handle, &status );

void gnssCallback( M2MB_GNSS_HANDLE handle, M2MB_GNSS_IND_E event, UINT16 resp_size, void *resp, void *userdata )
{
  if(event == M2MB_GNSS_INDICATION_POSITION_REPORT)
  {
    // Success => you can use gnss data arrived.
  }
  else if(event == M2MB_GNSS_INDICATION_NMEA_REPORT)
  {
    // Success => you can use gnss data arrived.
  }
  else
  {
    // Fail
  }
}
void main(void)
{
  M2MB_GNSS_HANDLE gnss_handle;
  M2MB_RESULT_E result = 0;
  UINT8 status;
 
  result = m2mb_gnss_init( gnss_handle, gnssCallback, NULL );
  if(result != M2MB_RESULT_SUCCESS)
  {
    return;
  }
  else
  {
    printf("m2mb_gnss_init succeeded");
  }
 
  result = m2mb_gnss_GetGTPstatus( gnss_handle, &status);
  if ( result == M2MB_RESULT_SUCCESS )
  {
    printf( "m2mb_gnss_GetGTPstatus succeeded");
  }
 
}

m2mb_gnss_GTP()

M2MB_RESULT_E m2mb_gnss_GTP

(

M2MB_GNSS_HANDLE

handle

)

Start a GTP session.

Starts the GTP session and when the call is completed, user callback is triggered for M2MB_GNSS_INDICATION_POSITION_REPORT event Prerequisites for running GTP

• GTP needs to be enabled before running it.
• m2mb_gnss_EnableGTP() enables the GTP and reboots the device.

Parameters

[in]

handle

handle for the gnss functionalities (M2MB_GNSS_HANDLE)

Returns

M2MB_RESULT_E: it returns M2MB_RESULT_SUCCESS on success, a different value on error.

m2mb_gnss_GTP( handle );

void gnssCallback( M2MB_GNSS_HANDLE handle, M2MB_GNSS_IND_E event, UINT16 resp_size, void *resp, void *userdata )
{
  if(event == M2MB_GNSS_INDICATION_POSITION_REPORT)
  {
    // Success => you can use gnss data arrived.
  }
  else if(event == M2MB_GNSS_INDICATION_NMEA_REPORT)
  {
    // Success => you can use gnss data arrived.
  }
  else
  {
    // Fail
  }
}
void main(void)
{
  M2MB_GNSS_HANDLE gnss_handle;
  M2MB_RESULT_E result = 0;
 
  result = m2mb_gnss_init( gnss_handle, gnssCallback, NULL );
  if(result != M2MB_RESULT_SUCCESS)
  {
    return;
  }
  else
  {
    printf("m2mb_gnss_init succeeded");
  }
 
  result = m2mb_gnss_GetGTPstatus( gnss_handle, &status);
  if ( result == M2MB_RESULT_SUCCESS )
  {
    printf( "m2mb_gnss_GetGTPstatus succeeded");
  }
 
  if(status == 0)
  {
    result = m2mb_gnss_EnableGTP( gnss_handle, enablegtp);
    if ( result == M2MB_RESULT_SUCCESS )
    {
      printf( "m2mb_gnss_EnableGTP succeeded");
    }
  }
 
  result = m2mb_gnss_GTP( gnss_handle );
  if ( result == M2MB_RESULT_SUCCESS )
  {
    printf( "m2mb_gnss_GTP succeeded");
  }
 
}

m2mb_gnss_init()

M2MB_RESULT_E m2mb_gnss_init	(	M2MB_GNSS_HANDLE *	pHandle,
		m2mb_gnss_callback	callback,
		void *	userdata
	)

Initializes gnss functionalities.

m2mb_gnss_init initializes gnss service for current client, returning the handle that must be passed as first parameter for all gnss actions. Calling the m2mb_gnss_init is mandatory before using the gnss service.

Parameters

[in]	pHandle	pointer to the handle for the gnss functionalities (M2MB_GNSS_HANDLE *). Memory pointed by the pointer must be allocated by the user.
[in]	callback	callback for the gnss indications (m2mb_gnss_callback)
[in]	userdata	user data to be returned by callback function (void *)

Returns

M2MB_RESULT_E: it returns M2MB_RESULT_SUCCESS on success, a different value on error.

m2mb_gnss_init( &handle, callback, userdata );

void gnssCallback( M2MB_GNSS_HANDLE handle, M2MB_GNSS_IND_E event, UINT16 resp_size, void *resp, void *userdata )
{
  if(event == M2MB_GNSS_INDICATION_POSITION_REPORT)
  {
    // Success => you can use GNSS data arrived:
    my_function_to_collect_GNSS_data( ( M2MB_GNSS_POSITION_REPORT_INFO_T * ) resp );
  }
  else
  {
    // Fail
  }
}
 
void M2MB_main( int argc, char **argv )
{
  M2MB_GNSS_HANDLE handle;
  void *userdata;
 
  userdata = ( void * )m2mb_os_malloc( sizeof( UINT8 ) );
  memset( userdata, 12, sizeof( UINT8 ) );  // Test value: 12
 
  if( M2MB_RESULT_SUCCESS != m2mb_gnss_init( &handle, gnssCallback, userdata ) )
  {
    PRINT("m2mb_gnss_init Fail");
    return;
  }
  PRINT("m2mb_gnss_init Success");
}

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.

If the functionality is not supported the API returns error.

If concurrent WWAN and GNSS operations are not supported an arbitrator is designed to arbitrate concurrencies. GNSS_PRIORITY: GNSS as App priority. GNSS fix request succeeds in all WWAN states except when WWAN is loaded due to high priority procedures. WWAN_PRIORITY: WWAN as App priority. GNSS fix request succeeds only in WWAN SLEEP state. This API allows to change the priority runtime.

Parameters

[in]	handle	handle for the gnss functionalities (M2MB_GNSS_HANDLE)
[in]	priority	priority value to set (M2MB_GNSS_WWAN_GNSS_PRIORITY_E)

Returns

M2MB_RESULT_E: it returns M2MB_RESULT_SUCCESS on success, a different value on error.

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.

If the functionality is not supported the API returns error.

The new GNSS configuration will be set in NVM. A reboot is required, after the m2mb_gnss_setcfg calls, to load the new values in RAM and make them effective.

M2MB_GNSS_PRIORITY: If concurrent WWAN and GNSS operations are not supported an arbitrator is designed to arbitrate concurrencies. Priority 0: GNSS as App priority. GNSS fix request succeeds in all WWAN states except when WWAN is loaded due to high priority procedures. Priority 1: WWAN as App priority. GNSS fix request succeeds only in WWAN SLEEP state. M2MB_GNSS_TBF: Time Between Fix: 1÷4294967 [sec] M2MB_GNSS_CONSTELLATION: If feature supported: –All GNSS constellations supported –Two constellations at a time –GPS + any 2nd-constellation 0 - The constellation is selected based on Mobile Country Code (MCC) of camped network 1 - GPS+GLO 2 - GPS+GAL 3 - GPS+BDS 4 - GPS+QZSS

Parameters

[in]	handle	handle for the gnss functionalities (M2MB_GNSS_HANDLE)
[in]	param	CFG parameter to set (M2MB_GNSS_CFG_E)
[in]	value	pointer to the value to set for the specified CFG parameter (void *)

Returns

M2MB_RESULT_E: it returns M2MB_RESULT_SUCCESS on success, a different value on error.

m2mb_gnss_setcfg( handle, M2MB_GNSS_PRIORITY, &priority );

M2MB_GNSS_HANDLE handle;
UINT8 priority;
UINT32 TBF;
UINT8 constellation;
 
m2mb_gnss_init( &handle, gnssCallback_test, NULL );
 
priority=1;
TBF=4321;
constellation=4;
m2mb_gnss_setcfg( handle, M2MB_GNSS_PRIORITY, &priority );
m2mb_gnss_setcfg( handle, M2MB_GNSS_TBF, &TBF );
m2mb_gnss_setcfg( handle, M2MB_GNSS_CONSTELLATION, &constellation );

m2mb_gnss_start()

M2MB_RESULT_E m2mb_gnss_start

(

M2MB_GNSS_HANDLE

handle

)

Starts a service.

m2mb_gnss_start starts all the services, previously enabled through the m2mb_gnss_enable function, with the proper configuration.

Parameters

[in]

handle

handle for the gnss functionalities (M2MB_GNSS_HANDLE)

Returns

M2MB_RESULT_E: it returns M2MB_RESULT_SUCCESS on success, a different value on error.

m2mb_gnss_start( handle );

M2MB_GNSS_HANDLE handle = NULL;
M2MB_GNSS_POSITION_REPORT_INFO_T *testDataStructure;
M2MB_RESULT_E res;
 
res = m2mb_gnss_init( &handle, gnssCallback, NULL );
if( M2MB_RESULT_SUCCESS != res )
{
  PRINT("m2mb_gnss_init FAIL");
  return;
}
PRINT("m2mb_gnss_init SUCCESS");
 
if( M2MB_RESULT_SUCCESS != m2mb_gnss_enable( handle, M2MB_GNSS_SERVICE_POSITION_REPORT ) )
{
  PRINT("m2mb_gnss_enable FAIL");
  return;
}
PRINT("m2mb_gnss_enable SUCCESS");
 
if( M2MB_RESULT_SUCCESS != m2mb_gnss_start( handle ) )
{
  PRINT("m2mb_gnss_start FAIL");
  return;
}
PRINT("m2mb_gnss_start SUCCESS");

m2mb_gnss_stop()

M2MB_RESULT_E m2mb_gnss_stop

(

M2MB_GNSS_HANDLE

handle

)

Stops a service.

m2mb_gnss_stop stops all the services previously enabled through the m2mb_gnss_enable function.

Parameters

[in]

handle

handle for the gnss functionalities (M2MB_GNSS_HANDLE)

Returns

M2MB_RESULT_E: it returns M2MB_RESULT_SUCCESS on success, a different value on error.

m2mb_gnss_stop( handle );