GNSS scan driver definition for LR1110. More...

#include "transceiver/lr1110_gnss_types.h"
#include "common/lr1110_types.h"
#include "common/lr1110_hal.h"

Functions
err_t	lr1110_gnss_get_result_size (lriot_t ctx, uint16_t result_size)
	Get the size of results.

err_t	lr1110_gnss_read_results (lriot_t ctx, uint8_t result_buffer, uint16_t result_buffer_size)
	Read GNSS results.

err_t	lr1110_gnss_get_timings (lriot_t ctx, lr1110_gnss_timings_t timings)
	Get the time spent in signal acquisition and signal analysis.

err_t	lr1110_gnss_almanac_update (lriot_t ctx, uint8_t blocks, uint8_t nb_of_blocks)
	Update almanacs given as parameter.

err_t	lr1110_gnss_read_almanac (lriot_t *ctx, lr1110_gnss_almanac_full_read_bytestream_t almanac_bytestream)
	Read the almanac.

err_t	lr1110_gnss_get_almanac_age_for_satellite (lriot_t ctx, lr1110_gnss_satellite_id_t sv_id, uint16_t almanac_age)
	Get almanac age for a satellite.

err_t	lr1110_gnss_push_solver_msg (lriot_t ctx, uint8_t payload, uint16_t payload_size)
	Push data received from solver to LR1110.

err_t	lr1110_gnss_set_constellations_to_use (lriot_t *ctx, lr1110_gnss_constellation_mask_t constellation_mask)
	Activate the GNSS scan constellation.

err_t	lr1110_gnss_read_used_constellations (lriot_t ctx, lr1110_gnss_constellation_mask_t constellations_used)
	Read constellation used by the GNSS scanner from the almanac update configuration.

err_t	lr1110_gnss_set_almanac_update (lriot_t *ctx, lr1110_gnss_constellation_mask_t constellations_to_update)
	Activate the almanac update.

err_t	lr1110_gnss_read_almanac_update (lriot_t ctx, lr1110_gnss_constellation_mask_t constellations_to_update)
	Function to read the almanac update configuration.

err_t	lr1110_gnss_read_firmware_version (lriot_t ctx, lr1110_gnss_version_t version)
	Function to read the GNSS firmware version.

err_t	lr1110_gnss_read_supported_constellations (lriot_t ctx, lr1110_gnss_constellation_mask_t supported_constellations)
	Function to read the supported constellation, GPS or BEIDOU other constellations.

err_t	lr1110_gnss_set_scan_mode (lriot_t *ctx, lr1110_gnss_scan_mode_t scan_mode)
	Function to set the GNSS scan mode configuration.

err_t	lr1110_gnss_scan_autonomous (lriot_t *ctx, lr1110_gnss_date_t date, lr1110_gnss_search_mode_t effort_mode, uint8_t gnss_input_parameters, uint8_t nb_sat)
	Gnss scan with no assisted parameters needed.

err_t	lr1110_gnss_scan_assisted (lriot_t *ctx, lr1110_gnss_date_t date, lr1110_gnss_search_mode_t effort_mode, uint8_t gnss_input_parameters, uint8_t nb_sat)
	Gnss scan with assisted parameters.

err_t	lr1110_gnss_set_assistance_position (lriot_t ctx, lr1110_gnss_solver_assistance_position_t assistance_position)
	Function to set the assistance position.

err_t	lr1110_gnss_read_assistance_position (lriot_t ctx, lr1110_gnss_solver_assistance_position_t assistance_position)
	Function to read the assistance position.

err_t	lr1110_gnss_push_dmc_msg (lriot_t ctx, uint8_t dmc_msg, uint16_t dmc_msg_len)
	Host receives an update from the network or assembles itself the update message and send it to the LR1110.

err_t	lr1110_gnss_get_context_status (lriot_t *ctx, lr1110_gnss_context_status_bytestream_t context_status_buffer)
	Get the GNSS context status.

err_t	lr1110_gnss_get_nb_detected_satellites (lriot_t ctx, uint8_t nb_detected_satellites)
	Get the number of detected satellites during last scan.

err_t	lr1110_gnss_get_detected_satellites (lriot_t ctx, uint8_t nb_detected_satellites, lr1110_gnss_detected_satellite_t detected_satellite_id_snr_doppler)
	Get the satellites detected on last scan with their IDs, C/N (aka CNR) and doppler.

err_t	lr1110_gnss_parse_context_status_buffer (lr1110_gnss_context_status_bytestream_t context_status_bytestream, lr1110_gnss_context_status_t *context_status)
	Parse a raw buffer of context status.

err_t	lr1110_gnss_get_result_destination (uint8_t result_buffer, uint16_t result_buffer_size, uint8_t destination)
	Extract the destination from the result returned by a GNSS scan.

uint16_t	lr1110_gnss_compute_almanac_age (uint16_t almanac_date, uint16_t nb_days_between_epoch_and_corresponding_gps_time_rollover, uint16_t nb_days_since_epoch)
	Helper function that computes the age of an almanac.

Detailed Description

GNSS scan driver definition for LR1110.

Redistribution and use in source and binary forms, with or without modification, are permitted (subject to the limitations in the disclaimer below) provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the Semtech corporation nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SEMTECH CORPORATION BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Function Documentation

◆ lr1110_gnss_almanac_update()

err_t lr1110_gnss_almanac_update	(	lriot_t *	ctx,
		uint8_t *	blocks,
		uint8_t	nb_of_blocks )

Update almanacs given as parameter.

Remarks: Note that information header and almanacs for all 128 SV (i.e. 129 20-byte long blocks) must be updated in a row for the whole operation to be successful. Therefore, this function must be called as many times as needed without any other operations in between.

Parameters

[in]	ctx	Chip implementation context
[in]	blocks	Buffer containing at least (nb_of_blocks * LR1110_GNSS_SINGLE_ALMANAC_WRITE_SIZE) bytes of almanac
[in]	nb_of_blocks	Number of blocks to transfer

Returns: Operation status

◆ lr1110_gnss_compute_almanac_age()

uint16_t lr1110_gnss_compute_almanac_age	(	uint16_t	almanac_date,
		uint16_t	nb_days_between_epoch_and_corresponding_gps_time_rollover,
		uint16_t	nb_days_since_epoch )

Helper function that computes the age of an almanac.

This function does not call the LR1110. The almanac age is computed based on the following elements:

almanac age as obtained from lr1110_gnss_get_almanac_age_for_satellite
the number of days elapsed between Epoch (January 6th 1980) and the GPS rollover reference of the current almanac
the GPS date of today expressed in number of days elapsed since Epoch

Remarks: It is important to use for nb_days_between_epoch_and_corresponding_gps_time_rollover the GPS time rollover corresponding to the reference of the almanac_date. This is especially true when current date is just after a GPS time rollover.

Parameters

[in]	almanac_date	Almanac date as obtained from lr1110_gnss_get_almanac_age_for_satellite
[in]	nb_days_between_epoch_and_corresponding_gps_time_rollover	Number of days elapsed between GPS Epoch and the GPS rollover corresponding to the almanac_date
[in]	nb_days_since_epoch	Number of days elapsed between January 6th 1980 and now

Returns: Age of the almanac expressed in number of days between its start valid instant and now

◆ lr1110_gnss_get_almanac_age_for_satellite()

err_t lr1110_gnss_get_almanac_age_for_satellite	(	lriot_t *	ctx,
		lr1110_gnss_satellite_id_t	sv_id,
		uint16_t *	almanac_age )

Get almanac age for a satellite.

Parameters

[in]	ctx	Chip implementation context
[in]	sv_id	ID of the satellite corresponding the to almanac requested
[out]	almanac_age	Almanac age in days since last GPS time overlap

Returns: Operation status

◆ lr1110_gnss_get_context_status()

err_t lr1110_gnss_get_context_status	(	lriot_t *	ctx,
		lr1110_gnss_context_status_bytestream_t	context_status_buffer )

Get the GNSS context status.

This function returns the GNSS context status as a raw buffer. It is possible to use lr1110_gnss_parse_context_status_buffer to obtain the details of the context status.

Parameters

[in]	ctx	Chip implementation context
[out]	context_status_buffer	Pointer to a buffer to be filled with context status information. Must be at least 7 bytes long. It is up to the caller to ensure there is enough place in this buffer.

Returns: Operation status

See also: lr1110_gnss_parse_context_status_buffer

◆ lr1110_gnss_get_detected_satellites()

err_t lr1110_gnss_get_detected_satellites	(	lriot_t *	ctx,
		uint8_t	nb_detected_satellites,
		lr1110_gnss_detected_satellite_t *	detected_satellite_id_snr_doppler )

Get the satellites detected on last scan with their IDs, C/N (aka CNR) and doppler.

Note: Doppler is returned with 6ppm accuracy.

Parameters

[in]	ctx	Chip implementation context
[in]	nb_detected_satellites	Number of detected satellites on last scan (obtained by calling lr1110_gnss_get_nb_detected_satellites)
[out]	detected_satellite_id_snr_doppler	Pointer to an array of structures of size big enough to contain nb_detected_satellites elements

Returns: Operation status

◆ lr1110_gnss_get_nb_detected_satellites()

err_t lr1110_gnss_get_nb_detected_satellites	(	lriot_t *	ctx,
		uint8_t *	nb_detected_satellites )

Get the number of detected satellites during last scan.

Parameters

[in]	ctx	Chip implementation context
[out]	nb_detected_satellites	Number of satellites detected

Returns: Operation status

◆ lr1110_gnss_get_result_destination()

err_t lr1110_gnss_get_result_destination	(	uint8_t *	result_buffer,
		uint16_t	result_buffer_size,
		uint8_t *	destination )

Extract the destination from the result returned by a GNSS scan.

Parameters

[in]	result_buffer	Pointer to the buffer holding the result
[in]	result_buffer_size	Size of the result in byte
[out]	destination	Destination of the result

Returns: Operation status

◆ lr1110_gnss_get_result_size()

err_t lr1110_gnss_get_result_size	(	lriot_t *	ctx,
		uint16_t *	result_size )

Get the size of results.

This method returns the size in bytes of the results available in LR1110 result buffer.

Parameters

[in]	ctx	Chip implementation context
[out]	result_size	Result size

Returns: Operation status

◆ lr1110_gnss_get_timings()

err_t lr1110_gnss_get_timings	(	lriot_t *	ctx,
		lr1110_gnss_timings_t *	timings )

Get the time spent in signal acquisition and signal analysis.

These timings allow to compute the current consumption of the last GNSS scan.

Parameters

[in]	ctx	Chip implementation context
[out]	timings	GNSS timings of last GNSS scan

Returns: Operation status

◆ lr1110_gnss_parse_context_status_buffer()

err_t lr1110_gnss_parse_context_status_buffer	(	lr1110_gnss_context_status_bytestream_t	context_status_bytestream,
		lr1110_gnss_context_status_t *	context_status )

Parse a raw buffer of context status.

Parameters

[in]	ctx_status_bytestream	The raw buffer of context status to parse. It is up to the caller to ensure the buffer is at least LR1110_GNSS_CONTEXT_STATUS_LENGTH bytes long
[out]	context_status	Pointer to a structure of lr1110_gnss_context_status_t to be filled with information from context_status_bytestream

Returns: Operation status

See also: lr1110_gnss_get_context_status

◆ lr1110_gnss_push_dmc_msg()

err_t lr1110_gnss_push_dmc_msg	(	lriot_t *	ctx,
		uint8_t *	dmc_msg,
		uint16_t	dmc_msg_len )

Host receives an update from the network or assembles itself the update message and send it to the LR1110.

Parameters

[in]	ctx	Chip implementation context
[in]	dmc_msg	buffer containing the update the network
[in]	dmc_msg_len	length of this buffer

Returns: Operation status

◆ lr1110_gnss_push_solver_msg()

err_t lr1110_gnss_push_solver_msg	(	lriot_t *	ctx,
		uint8_t *	payload,
		uint16_t	payload_size )

Push data received from solver to LR1110.

Parameters

[in]	ctx	Chip implementation context
[in]	payload	Payload received from solver
[in]	payload_size	Size of the payload received from solver (in bytes)

Returns: Operation status

◆ lr1110_gnss_read_almanac()

err_t lr1110_gnss_read_almanac	(	lriot_t *	ctx,
		lr1110_gnss_almanac_full_read_bytestream_t	almanac_bytestream )

Read the almanac.

Parameters

[in]	ctx	Chip implementation context
[out]	almanac_bytestream	The bytestream of the almanac

Returns: Operation status

◆ lr1110_gnss_read_almanac_update()

err_t lr1110_gnss_read_almanac_update	(	lriot_t *	ctx,
		lr1110_gnss_constellation_mask_t *	constellations_to_update )

Function to read the almanac update configuration.

Parameters

[in]	ctx	Chip implementation context
[out]	constellations_to_update	Bit mask of the constellations to mark to update. See lr1110_gnss_constellation_t for the possible values

Returns: Operation status

◆ lr1110_gnss_read_assistance_position()

err_t lr1110_gnss_read_assistance_position	(	lriot_t *	ctx,
		lr1110_gnss_solver_assistance_position_t *	assistance_position )

Function to read the assistance position.

The assistance position read may be different from the one set beforehand with lr1110_gnss_set_assistance_position due to a scaling computation.

Parameters

[in]	ctx	Chip implementation context
[in]	assistance_position,latitude	12 bits and longitude 12 bits

See lr1110_gnss_solver_assistance_position_t

Returns: Operation status

◆ lr1110_gnss_read_firmware_version()

err_t lr1110_gnss_read_firmware_version	(	lriot_t *	ctx,
		lr1110_gnss_version_t *	version )

Function to read the GNSS firmware version.

Parameters

[in]	ctx	Chip implementation context
[in]	version	GNSS Firmware version currently running on the chip

Returns: Operation status

◆ lr1110_gnss_read_results()

err_t lr1110_gnss_read_results	(	lriot_t *	ctx,
		uint8_t *	result_buffer,
		uint16_t	result_buffer_size )

Read GNSS results.

The GNSS results are pushed into a buffer directly. This buffer is provided by the application using the driver. It MUST be long enough to contains at least result_buffer_size bytes.

Warning: No check is done on result_buffer size. If this application provided buffer is too small, there will be a buffer overflow bug!

Parameters

[in]	ctx	Chip implementation context
[out]	result_buffer	Application provided buffer to be filled with result
[in]	result_buffer_size	The number of bytes to read from the LR1110

Returns: Operation status

◆ lr1110_gnss_read_supported_constellations()

err_t lr1110_gnss_read_supported_constellations	(	lriot_t *	ctx,
		lr1110_gnss_constellation_mask_t *	supported_constellations )

Function to read the supported constellation, GPS or BEIDOU other constellations.

Parameters

[in]	ctx	Chip implementation context
[out]	supported_constellations	Bit mask of the constellations used. See lr1110_gnss_constellation_t for the possible values

Returns: Operation status

◆ lr1110_gnss_read_used_constellations()

err_t lr1110_gnss_read_used_constellations	(	lriot_t *	ctx,
		lr1110_gnss_constellation_mask_t *	constellations_used )

Read constellation used by the GNSS scanner from the almanac update configuration.

Parameters

[in]	ctx	Chip implementation context
[out]	constellations_used	Bit mask of the constellations used. See lr1110_gnss_constellation_t for the possible values

Returns: Operation status

See also: lr1110_gnss_set_constellations_to_use

◆ lr1110_gnss_scan_assisted()

err_t lr1110_gnss_scan_assisted	(	lriot_t *	ctx,
		lr1110_gnss_date_t	date,
		lr1110_gnss_search_mode_t	effort_mode,
		uint8_t	gnss_input_parameters,
		uint8_t	nb_sat )

Gnss scan with assisted parameters.

Parameters

[in]	ctx	Chip implementation context
[in]	date	The actual date of scan. Its format is the number of seconds elapsed since January the 6th 1980 00:00:00 with leap seconds included.
[in]	effort_mode	Effort mode lr1110_gnss_search_mode_t
[in]	gnss_input_parameters	Bit mask indicating which information is added in the output payload lr1110_gnss_input_parameters_e
[in]	nb_sat	The expected number of satellite to provide. This value must be in the range [0:128]

Returns: Operation status

◆ lr1110_gnss_scan_autonomous()

err_t lr1110_gnss_scan_autonomous	(	lriot_t *	ctx,
		lr1110_gnss_date_t	date,
		lr1110_gnss_search_mode_t	effort_mode,
		uint8_t	gnss_input_parameters,
		uint8_t	nb_sat )

Gnss scan with no assisted parameters needed.

Parameters

[in]	ctx	Chip implementation context
[in]	date	The actual date of scan. Its format is the number of seconds elapsed since January the 6th 1980 00:00:00 with leap seconds included.
[in]	effort_mode	Effort mode lr1110_gnss_search_mode_t
[in]	gnss_input_parameters	Bit mask indicating which information is added in the output payload lr1110_gnss_input_parameters_e
[in]	nb_sat	The expected number of satellite to provide. This value must be in the range [0:128]

Returns: Operation status

◆ lr1110_gnss_set_almanac_update()

err_t lr1110_gnss_set_almanac_update	(	lriot_t *	ctx,
		lr1110_gnss_constellation_mask_t	constellations_to_update )

Activate the almanac update.

Parameters

[in]	ctx	Chip implementation context
[in]	constellations_to_update	Bit mask of the constellations to mark to update. See lr1110_gnss_constellation_t for the possible values

Returns: Operation status

◆ lr1110_gnss_set_assistance_position()

err_t lr1110_gnss_set_assistance_position	(	lriot_t *	ctx,
		lr1110_gnss_solver_assistance_position_t *	assistance_position )

Function to set the assistance position.

Parameters

[in]	ctx	Chip implementation context
[in]	assistance_position,latitude	12 bits and longitude 12 bits

See lr1110_gnss_solver_assistance_position_t

Returns: Operation status

◆ lr1110_gnss_set_constellations_to_use()

err_t lr1110_gnss_set_constellations_to_use	(	lriot_t *	ctx,
		lr1110_gnss_constellation_mask_t	constellation_mask )

Activate the GNSS scan constellation.

Parameters

[in]	ctx	Chip implementation context
[in]	constellation_mask	Bit mask of the constellations to use. See lr1110_gnss_constellation_t for the possible values

Returns: Operation status

See also: lr1110_gnss_read_used_constellations

◆ lr1110_gnss_set_scan_mode()

err_t lr1110_gnss_set_scan_mode	(	lriot_t *	ctx,
		lr1110_gnss_scan_mode_t	scan_mode )

Function to set the GNSS scan mode configuration.

Parameters

[in]	ctx	Chip implementation context
[in]	scan_mode	GNSS scan mode

Returns: Operation status

lr1110_gnss_scan_mode_t

Functions

Detailed Description

Function Documentation

◆ lr1110_gnss_almanac_update()

◆ lr1110_gnss_compute_almanac_age()

◆ lr1110_gnss_get_almanac_age_for_satellite()

◆ lr1110_gnss_get_context_status()

◆ lr1110_gnss_get_detected_satellites()

◆ lr1110_gnss_get_nb_detected_satellites()

◆ lr1110_gnss_get_result_destination()

◆ lr1110_gnss_get_result_size()

◆ lr1110_gnss_get_timings()

◆ lr1110_gnss_parse_context_status_buffer()

◆ lr1110_gnss_push_dmc_msg()

◆ lr1110_gnss_push_solver_msg()

◆ lr1110_gnss_read_almanac()

◆ lr1110_gnss_read_almanac_update()

◆ lr1110_gnss_read_assistance_position()

◆ lr1110_gnss_read_firmware_version()

◆ lr1110_gnss_read_results()

◆ lr1110_gnss_read_supported_constellations()

◆ lr1110_gnss_read_used_constellations()

◆ lr1110_gnss_scan_assisted()

◆ lr1110_gnss_scan_autonomous()

◆ lr1110_gnss_set_almanac_update()

◆ lr1110_gnss_set_assistance_position()

◆ lr1110_gnss_set_constellations_to_use()

◆ lr1110_gnss_set_scan_mode()