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.

step 1: Call gnss_init() to initialize the GNSS content and register a callback function.
step 2: Call gnss_power_on() to power on the GNSS chip.
step 3: Call gnss_send_command() to configure GNSS chip settings, such as aiding time.
step 4: Call gnss_read_sentence() to read the incoming NMEA data.
step 5: Call gnss_power_off() to power off the GNSS chip.
Sample code:
int32_t rx_data_ready = 0;
int32_t tx_data_ready = 1;
void my_callback_func(gnss_callback_type_t type, void *param)
{
if (type == GNSS_NOTIFICATION_TYPE_READ) {
// The incoming NMEA sentence is available to read.
// Set a flag, such as send a message to the task and then call #gnss_read_sentence() to read the NMEA sentence.
rx_data_ready = 1;
}
if (type == GNSS_NOTIFICATION_TYPE_WRITE) {
// Set a flag, such as send a message to the task and then call #gnss_send_command() to send a command to GNSS chip.
tx_data_ready = 1;
}
if (type == GNSS_NOTIFICATION_TYPE_POWER_ON_CNF) {
if (*((int32_t*) param) == 1){
// Power on successfully completed.
}
}
if (type == GNSS_NOTIFICATION_TYPE_POWER_OFF_CNF) {
if (*((int32_t*) param) == 1){
// Power off successfully completed.
}
}
}
void app_main(void)
{
int32_t ret;
int8_t buf[256];
int32_t send_len = 0;
uint8_t command[] = "$PMTK353,1,0,0,0,0*2A\r\n";
// Initilize the GNSS content and register a callback function.
gnss_init(my_callback_func);
//Power on the GNSS chip.
gnss_power_on();
do {
// Waiting for the incoming NMEA data.
while (!rx_data_ready);
// Read a complete NMEA sentence, if there is no data, the return value is 0.
ret = gnss_read_sentence(buf, 256);
if (ret > 0) {
// Process the NMEA sentence.
} else {
// Wait
}
do {
// Send
send_len += gnss_send_command(command + send_len, strlen(command) - send_len);
if (send_len == strlen(command)) {
// Data is successfully sent.
break;
} else {
// Set the TX flag.
tx_data_ready = 0;
// Waiting for data send to complete.
while(!tx_data_ready);
}
while (1);
} while (1);
// Power off the GNSS chip.
gnss_power_off();
}

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

enum gnss_notification_type_t

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_function the 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_buffer	a user defined buffer allocated for the NMEA sentence.
[in]	length	is 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]	cmd	The pointer to a buffer of the PMTK command.
[in]	cmd_len	lengh of the PMTK command.

Returns: length of the data sent.

Overview

Terms and Acronyms

Software architecture of GNSS.

How to use GNSS interface.

Data Structures

Typedefs

Enumerations

Functions

Typedef Documentation

Enumeration Type Documentation

Function Documentation