MT2523 API Reference  LinkIt SDK v4
GNSS

This section introduces the GNSS interface APIs including terms and acronyms, supported features, software architecture, details on how to use the GNSS interface, GNSS function groups, enums, structures and functions. More...

Overview

This section introduces the GNSS interface APIs including terms and acronyms, supported features, software architecture, details on how to use the GNSS interface, GNSS function groups, enums, structures and functions.

The GNSS API provides a unified method to control and communicate the data with GNSS chip. For more details on the data format, data flow and other information on GNSS, please refer to MediaTek LinkIt™ Development Platform for RTOS GNSS Developer's Guide.

Terms and Acronyms

Terms Details
GPS Global Positioning System (GPS) satellites broadcast microwave signals to enable GPS receivers on or near the Earth's surface to determine location, velocity and time. For an introduction to GPS, please refer to GPS in Wikipedia..
UTC Coordinated Universal Time is the primary time standard to adjust world clocks and time. For an introduction to UTC, please refer to UTC in Wikipedia..
NMEA National Marine Electronics Association (NMEA 0183) is a combined electrical and data specification for communication between marine electronic devices such as echo sounder, sonar, anemometer, gyrocompass, autopilot, GNSS receivers and many other types of instruments. For an introduction to NMEA, please refer to NMEA in Wikipedia..
UART Universal Asynchronous Receiver/Transmitter is usually an individual (or part of an) integrated circuit (IC) used for serial communications over a micro-controller unit(MCU) or peripheral device serial port. For an introduction to UART, please refer to UART in Wikipedia..
PMTK PMTK command is MediaTek proprietary data transfer protocol for GNSS. It enables configuring the parameters of the GNSS chipset, aiding assistance position information and receive notifications from the GNSS chip..
EINT External Interrupt Controller. Process the interrupt request from external source or peripheral.
GNSS Global navigation satellite system is a satellite navigation system with global coverage, such as GPS.

Software architecture of GNSS.

The GNSS chip is a System-in-Package (SiP) in LinkIt 2523 board by SAC that connects with the host using UART.

How to use GNSS interface.

Data Structures

struct  gnss_debug_data_t
 Data structure to carry the debugging data. More...
 

Typedefs

typedef void(* gnss_callback_t) (gnss_notification_type_t type, void *param)
 GNSS callback typedef, the registered callback is invoked when a UART or EINT interrupt is triggered. More...
 

Enumerations

enum  gnss_notification_type_t {
  GNSS_NOTIFICATION_TYPE_POWER_ON_CNF,
  GNSS_NOTIFICATION_TYPE_POWER_OFF_CNF,
  GNSS_NOTIFICATION_TYPE_READ,
  GNSS_NOTIFICATION_TYPE_WRITE,
  GNSS_NOTIFICATION_TYPE_HOST_WAKEUP,
  GNSS_NOTIFICATION_TYPE_DEBUG_INFO
}
 This enum notifies the user about an incoming event from the GNSS chip. More...
 

Functions

void gnss_init (gnss_callback_t callback_function)
 This function initializes the GNSS content. More...
 
void gnss_power_on (void)
 This function powers on the GNSS chip. More...
 
void gnss_power_off (void)
 This function powers off the GNSS chip. More...
 
int32_t gnss_send_command (int8_t *cmd, int32_t cmd_len)
 This function sends a PMTK command to the GNSS chip. More...
 
int32_t gnss_read_sentence (int8_t *data_buffer, int32_t length)
 This function reads the incoming NMEA sentence. More...
 

Typedef Documentation

typedef void(* gnss_callback_t) (gnss_notification_type_t type, void *param)

GNSS callback typedef, the registered callback is invoked when a UART or EINT interrupt is triggered.

See also
gnss_init

Enumeration Type Documentation

This enum notifies the user about an incoming event from the GNSS chip.

See also
gnss_notification_type_t gnss_init()
Enumerator
GNSS_NOTIFICATION_TYPE_POWER_ON_CNF 

The event notification is sent once the chip is powered on.

GNSS_NOTIFICATION_TYPE_POWER_OFF_CNF 

The event notification is sent once the chip is powered off.

GNSS_NOTIFICATION_TYPE_READ 

The event notification is sent if incoming GNSS data is available.

GNSS_NOTIFICATION_TYPE_WRITE 

Notifies the host to send a command again.

GNSS_NOTIFICATION_TYPE_HOST_WAKEUP 

The GNSS chip is ready to send positioning data to the host.

The host should stay on to receive the data.

GNSS_NOTIFICATION_TYPE_DEBUG_INFO 

Notify the user to save debugging data.

Function Documentation

void gnss_init ( gnss_callback_t  callback_function)

This function initializes the GNSS content.

This function does not support multi-instance. The subsequent call to this function will overwrite the callback function registered by the previous call to this function.

Parameters
[in]callback_functionthe callback function to be registered. The callback is invoked when a UART or EINT interrupt occurs.
See also
gnss_notification_type_t
void gnss_power_off ( void  )

This function powers off the GNSS chip.

Parameters
void
Returns
void gnss_power_on ( void  )

This function powers on the GNSS chip.

Parameters
void
Returns
int32_t gnss_read_sentence ( int8_t *  data_buffer,
int32_t  length 
)

This function reads the incoming NMEA sentence.

It returns a complete NMEA sentence. The NMEA sentence can be processed. The sentence format is aligned with the NMEA0183 protocol. The NMEA sentence: "$GPGGA,030544.713,,,,,0,0,,,M,,M,,*4B", For more details about NMEA, please refer to MediaTek LinkIt™ Development Platform for RTOS GNSS Developer's Guide.

Parameters
[in,out]data_buffera user defined buffer allocated for the NMEA sentence.
[in]lengthis the buffer size. If the buffer size is smaller than the NMEA sentence length, the NMEA sentence will be truncated, up to the size. Usually the size is smaller than 256 bytes. Users can allocate a buffer the size bigger than 256 bytes.
Returns
the read sentence's length.
int32_t gnss_send_command ( int8_t *  cmd,
int32_t  cmd_len 
)

This function sends a PMTK command to the GNSS chip.

"$PMTK225,0,0,0*2B\r\n"

  • Example Commands.

    Packet Type: 225 PMTK_SET_PERIODIC_MODE periodic power saving mode settings.
    Packet Type: 740 PMTK_DT_UTC Time aiding. The packet contains the current UTC time.

    For the details on the command, please refer to MediaTek LinkIt™ Development Platform for RTOS GNSS Developer's Guide. This is an asynchronous API.
Parameters
[in]cmdThe pointer to a buffer of the PMTK command.
[in]cmd_lenlengh of the PMTK command.
Returns
length of the data sent.