location.h

Go to the documentation of this file.

/*
 * Copyright (c) 2021 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
 */
 
#ifndef LOCATION_H_
#define LOCATION_H_
 
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#if (defined(CONFIG_LOCATION_SERVICE_EXTERNAL) && defined(CONFIG_NRF_CLOUD_AGNSS)) ||\
        defined(CONFIG_LOCATION_DATA_DETAILS)
#include <nrf_modem_gnss.h>
#endif
#if defined(CONFIG_LOCATION_SERVICE_EXTERNAL) && defined(CONFIG_NRF_CLOUD_PGPS)
#include <net/nrf_cloud_pgps.h>
#endif
#if defined(CONFIG_LOCATION_SERVICE_EXTERNAL) && defined(CONFIG_LOCATION_METHOD_CELLULAR)
#include <modem/lte_lc.h>
#endif
#if defined(CONFIG_LOCATION_SERVICE_EXTERNAL) && defined(CONFIG_LOCATION_METHOD_WIFI)
#include <net/wifi_location_common.h>
#endif
 
#ifdef __cplusplus
extern "C" {
#endif
 
enum location_method {
        LOCATION_METHOD_CELLULAR = 1,
        LOCATION_METHOD_GNSS,
        LOCATION_METHOD_WIFI,
        LOCATION_METHOD_WIFI_CELLULAR,
};
 
enum location_req_mode {
        LOCATION_REQ_MODE_FALLBACK = 0,
        LOCATION_REQ_MODE_ALL,
};
 
enum location_event_id {
        LOCATION_EVT_LOCATION = 1,
        LOCATION_EVT_TIMEOUT,
        LOCATION_EVT_ERROR,
        LOCATION_EVT_RESULT_UNKNOWN,
        LOCATION_EVT_GNSS_ASSISTANCE_REQUEST,
        LOCATION_EVT_GNSS_PREDICTION_REQUEST,
        LOCATION_EVT_CLOUD_LOCATION_EXT_REQUEST,
        LOCATION_EVT_STARTED,
        LOCATION_EVT_FALLBACK,
        LOCATION_EVT_CANCELLED,
};
 
enum location_ext_result {
        LOCATION_EXT_RESULT_SUCCESS,
        LOCATION_EXT_RESULT_UNKNOWN,
        LOCATION_EXT_RESULT_ERROR
};
 
enum location_accuracy {
        LOCATION_ACCURACY_LOW,
        LOCATION_ACCURACY_NORMAL,
        LOCATION_ACCURACY_HIGH,
};
 
struct location_datetime {
        bool valid;
        uint16_t year;
        uint8_t month;
        uint8_t day;
        uint8_t hour;
        uint8_t minute;
        uint8_t second;
        uint16_t ms;
};
 
#if defined(CONFIG_LOCATION_DATA_DETAILS)
struct location_data_details_gnss {
        uint8_t satellites_tracked;
        uint8_t satellites_used;
        struct nrf_modem_gnss_pvt_data_frame pvt_data;
        uint32_t elapsed_time_gnss;
};
 
struct location_data_details_cellular {
        uint8_t ncells_count;
        uint8_t gci_cells_count;
};
 
struct location_data_details_wifi {
        uint16_t ap_count;
};
 
struct location_data_details {
        uint32_t elapsed_time_method;
 
#if defined(CONFIG_LOCATION_METHOD_GNSS)
        struct location_data_details_gnss gnss;
#endif
#if defined(CONFIG_LOCATION_METHOD_CELLULAR)
        struct location_data_details_cellular cellular;
#endif
#if defined(CONFIG_LOCATION_METHOD_WIFI)
        struct location_data_details_wifi wifi;
#endif
};
#endif
 
struct location_data {
        double latitude;
        double longitude;
        float accuracy;
        struct location_datetime datetime;
 
#if defined(CONFIG_LOCATION_DATA_DETAILS)
        struct location_data_details details;
#endif
};
 
#if defined(CONFIG_LOCATION_DATA_DETAILS)
struct location_data_error {
        struct location_data_details details;
};
 
struct location_data_unknown {
        struct location_data_details details;
};
 
struct location_data_fallback {
        enum location_method next_method;
        enum location_event_id cause;
        struct location_data_details details;
};
#endif
 
struct location_data_cloud {
#if defined(CONFIG_LOCATION_SERVICE_EXTERNAL) && defined(CONFIG_LOCATION_METHOD_CELLULAR)
        const struct lte_lc_cells_info *cell_data;
#endif
#if defined(CONFIG_LOCATION_SERVICE_EXTERNAL) && defined(CONFIG_LOCATION_METHOD_WIFI)
        const struct wifi_scan_info *wifi_data;
#endif
};
 
struct location_event_data {
        enum location_event_id id;
        enum location_method method;
 
        union {
                struct location_data location;
 
#if defined(CONFIG_LOCATION_DATA_DETAILS)
                struct location_data_error error;
 
                struct location_data_unknown unknown;
 
                struct location_data_fallback fallback;
#endif
 
#if defined(CONFIG_LOCATION_SERVICE_EXTERNAL) && defined(CONFIG_NRF_CLOUD_AGNSS)
                struct nrf_modem_gnss_agnss_data_frame agnss_request;
#endif
#if defined(CONFIG_LOCATION_SERVICE_EXTERNAL) && defined(CONFIG_NRF_CLOUD_PGPS)
                struct gps_pgps_request pgps_request;
#endif
#if defined(CONFIG_LOCATION_SERVICE_EXTERNAL) &&\
        (defined(CONFIG_LOCATION_METHOD_CELLULAR) || defined(CONFIG_LOCATION_METHOD_WIFI))
                struct location_data_cloud cloud_location_request;
#endif
        };
};
 
struct location_gnss_config {
        int32_t timeout;
 
        enum location_accuracy accuracy;
 
        uint8_t num_consecutive_fixes;
 
        bool visibility_detection;
 
        bool priority_mode;
};
 
struct location_cellular_config {
        int32_t timeout;
 
        uint8_t cell_count;
};
 
struct location_wifi_config {
        int32_t timeout;
};
 
struct location_method_config {
        enum location_method method;
        union {
                struct location_cellular_config cellular;
                struct location_gnss_config gnss;
                struct location_wifi_config wifi;
        };
};
 
struct location_config {
        uint8_t methods_count;
 
        struct location_method_config methods[CONFIG_LOCATION_METHODS_LIST_SIZE];
 
        uint16_t interval;
 
        int32_t timeout;
 
        enum location_req_mode mode;
};
 
typedef void (*location_event_handler_t)(const struct location_event_data *event_data);
 
int location_handler_register(location_event_handler_t handler);
 
int location_handler_deregister(location_event_handler_t handler);
 
int location_init(location_event_handler_t handler);
 
int location_request(const struct location_config *config);
 
int location_request_cancel(void);
 
void location_config_defaults_set(
        struct location_config *config,
        uint8_t methods_count,
        enum location_method *method_types);
 
const char *location_method_str(enum location_method method);
 
const struct location_data_details *location_details_get(
        const struct location_event_data *event_data);
 
int location_agnss_data_process(const char *buf, size_t buf_len);
 
int location_pgps_data_process(const char *buf, size_t buf_len);
 
void location_cloud_location_ext_result_set(
        enum location_ext_result result,
        struct location_data *location);
 
#ifdef __cplusplus
}
#endif
 
#endif /* LOCATION_H_ */