mbtk/include/ql_v2/ql_gnss.h

/*-----------------------------------------------------------------------------------------------*/
/**
  @file ql_gnss.h 
  @brief GNSS service API 
*/
/*-----------------------------------------------------------------------------------------------*/

/*-------------------------------------------------------------------------------------------------
  Copyright (c) 2024 mobiletek Wireless Solution, Co., Ltd. All Rights Reserved.
  mobiletek Wireless Solution Proprietary and Confidential.
-------------------------------------------------------------------------------------------------*/

/*-------------------------------------------------------------------------------------------------
  EDIT HISTORY
  This section contains comments describing changes made to the file.
  Notice that changes are listed in reverse chronological order.
  $Header: $
  when       who          what, where, why
  --------   ---------    -----------------------------------------------------------------
  20241022    yq.wang      Created .
-------------------------------------------------------------------------------------------------*/


#ifndef __QL_GNSS_H__
#define __QL_GNSS_H__
#ifdef __cplusplus
extern "C" {
#endif


typedef enum {
    /** Cold Start Gnss*/
    QL_GNSS_COLD_START = 0,
    /** Warm Start Gnss */
    QL_GNSS_WARM_START,
    /** Hot Start Gnss*/
    QL_GNSS_HOT_START,
}QL_GNSS_START_MODE_E;

typedef enum 
{
    /**  gnss engine is off  */
    QL_GNSS_ENGINE_STATE_OFF = 0, 
    /**  gnss engine is on  */
    QL_GNSS_ENGINE_STATE_ON = 1, 
}QL_GNSS_ENGINE_STATE_E;

typedef enum 
{
    QL_GNSS_EPH_DATA_GPS = 0x01, 
    QL_GNSS_EPH_DATA_BDS = 0x02,
    QL_GNSS_EPH_DATA_GLO = 0x04,
    QL_GNSS_EPH_DATA_GAL = 0x08,
    QL_GNSS_EPH_DATA_QZSS = 0x10,
}QL_GNSS_EPH_DATA_E;

typedef enum
{
  GPS_ONLY = 0x01,
  BDS_ONLY = 0x02,
  GPS_BDS = 0x03,
  GLONASS_ONLY = 0x04,
  GPS_GLONASS = 0x05,
  BDS_GLONASS = 0x06,
  GPS_BDS_GLONASS = 0x07,
  GPS_SBAS_QZSS = 0x08,                 /* GPS+SBAS+QZSS           */              
  GPS_BDS_GALILEO_SBAS_QZSS = 0x11,     /* GPS+BDS+GAL+SBAS+QZSS   */
  GPS_GLONASS_GALILEO_SBAS_QZSS = 0x101 /* Not currently supported */
} QL_GNSS_CONSTELLATION_MASK_E;

typedef enum
{
    QL_GNSS_NMEA_VERSION_V30,           /* NMEA 3.0 */
    QL_GNSS_NMEA_VERSION_V41            /* NMEA 4.1 */
}QL_GNSS_NMEA_VERSION_ID_E;

typedef enum
{
    QL_GNSS_MSG_MIN = 0,                  /* GNSS MIN  MSG  */
    QL_GNSS_NMEA_MSG,                     /* GNSS NMEA DATA */
    QL_GNSS_STATUS_MSG,                   /* GNSS NMEA DATA */
    QL_GNSS_MSG_MAX                       /* GNSS MAX  MSG  */
}QL_GNSS_IND_MSG_ID_E;

/**
 *  gnss state definition
 */
typedef enum
{
    QL_GNSS_STATUS_UNDEFINE = 0u,       /* Undefined state  */
    QL_GNSS_STATUS_FOTA_START,          /* Fota init state  */
    QL_GNSS_STATUS_FOTA_REQ,            /* Fota state req   */
    QL_GNSS_STATUS_FOTA_ING,            /* Fota progressing */
    QL_GNSS_STATUS_FOTA_BOOT,           /* Fota bootloader  */
    QL_GNSS_STATUS_FOTA_FIRM,           /* Fota firmware    */
    QL_GNSS_STATUS_FOTA_END,            /* Fota end         */
    QL_GNSS_STATUS_WORKING,             /* GNSS working     */
    QL_GNSS_STATUS_MAX,                 /* Max   state      */
}QL_GNSS_STATUS_E;


typedef struct 
{
    char *ptr;
    size_t len;
} curl_rsp_msg_t;

typedef struct
{
    uint8_t  msg_id;
    uint32_t time;
    char nmea_sentence[128];
} nmea_srv_ind_msg;

typedef struct
{
    uint8_t  msg_id;
    QL_GNSS_STATUS_E g_status;
} gnss_status_ind_msg;

typedef struct
{
    double   latitude;
    double   longitude;
    double   altitude;
} ql_inject_location_t;


typedef struct 
{
    uint8_t mask;     
    struct
    {
        uint8_t gga_nmea_len;    /* GGA */
        char  gga_sent[128];
    }gga_sentences;
    
    struct
    {
        uint8_t rmc_nmea_len;    /* RMC */
        char  rmc_sent[128];
    }rmc_sentences;
    
    uint8_t   gpgsv_lines;
    struct 
    {  
        uint8_t  nmea_sentences_len; /* GPGSV */
        char    gsv_sent[128];        
    }gpgsv_sentences[4];  

    uint8_t   bdgsv_lines;
    struct 
    {
        uint32_t  gsv_lines;
        uint8_t  nmea_sentences_len; /* BD/GBGSV */
        char    gsv_sent[128];        
    }bdgsv_sentences[4];
    
} nmeasrc_sentences;

typedef void (*ql_gnss_ind_cb_f)(void *msg);

typedef void (*ql_gnss_error_cb_f)(int error);


/*-----------------------------------------------------------------------------------------------*/
/**
  @brief Initialize the gnss client
  @return
  QL_ERR_OK - successful
  QL_ERR_INVALID_ARG - as defined
  QL_ERR_SERVICE_NOT_READY - service is not ready, need to retry
  Other - error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_gnss_init(void);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief Deinitialize the  gnss client
  @return
  QL_ERR_OK - successful
  Other - error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_gnss_deinit(void);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief Start gnss
  @return
  QL_ERR_OK - successful
  QL_ERR_NOT_INIT - uninitialized
  QL_ERR_SERVICE_NOT_READY - service is not ready
  QL_ERR_INVALID_ARG - Invalid arguments
  Other - error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_gnss_start(void);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief Stop gnss
  @return
  QL_ERR_OK - successful
  QL_ERR_NOT_INIT - uninitialized
  QL_ERR_SERVICE_NOT_READY - service is not ready
  QL_ERR_INVALID_ARG - Invalid arguments
  Other - error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_gnss_stop(void);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief Set gnss start mode
  @param[in] mask Gnss start mode
  @return
  QL_ERR_OK - successful
  QL_ERR_NOT_INIT - uninitialized
  QL_ERR_SERVICE_NOT_READY - service is not ready
  QL_ERR_INVALID_ARG - Invalid arguments
  Other - error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_gnss_set_start_mode(QL_GNSS_START_MODE_E mask);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief Get gnss nmea
  @param[in] nmea_str
  @return
  QL_ERR_OK - successful
  QL_ERR_NOT_INIT - uninitialized
  QL_ERR_SERVICE_NOT_READY - service is not ready
  QL_ERR_INVALID_ARG - Invalid arguments
  Other - error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_gnss_qgpsgnmea(nmeasrc_sentences *nmea_str);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief Set gnss qgpscfg
  @param[in] enable
  @param[in] str
  @param[in] len
  @return
  QL_ERR_OK - successful
  QL_ERR_NOT_INIT - uninitialized
  QL_ERR_SERVICE_NOT_READY - service is not ready
  QL_ERR_INVALID_ARG - Invalid arguments
  Other - error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_gnss_set_qgpscfg(uint32_t enable, char *str, uint32_t len);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief Get engine state 
  @param[out] state  on/ff
  @return
  QL_ERR_OK - successful
  QL_ERR_NOT_INIT - uninitialized
  QL_ERR_SERVICE_NOT_READY - service is not ready
  QL_ERR_INVALID_ARG - Invalid arguments
  Other - error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_gnss_get_engine_state(QL_GNSS_ENGINE_STATE_E *state);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief Set Constellation .
  @param[in] mask  GPS/GLO/BDS/GAL/QZSS/SBAS
  @return
  QL_ERR_OK - successful
  QL_ERR_NOT_INIT - uninitialized
  QL_ERR_SERVICE_NOT_READY - service is not ready
  QL_ERR_INVALID_ARG - Invalid arguments
  Other - error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_gnss_set_constellation(QL_GNSS_CONSTELLATION_MASK_E mask);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief Get Constellation 
  @param[out] mask   GPS/GLO/BDS/GAL/QZSS/SBAS
  @return
  QL_ERR_OK - successful
  QL_ERR_NOT_INIT - uninitialized
  QL_ERR_SERVICE_NOT_READY - service is not ready
  QL_ERR_INVALID_ARG - Invalid arguments
  Other - error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_gnss_get_constellation(QL_GNSS_CONSTELLATION_MASK_E *mask);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief Set nmea type
  @param[in] mask type
  @return
  QL_ERR_OK - successful
  QL_ERR_NOT_INIT - uninitialized
  QL_ERR_SERVICE_NOT_READY - service is not ready
  QL_ERR_INVALID_ARG - Invalid arguments
  Other - error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_gnss_set_nmea_type(uint32_t mask);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief Get nmea version
  @param[out] version nmea version
  @return
  QL_ERR_OK - successful
  QL_ERR_NOT_INIT - uninitialized
  QL_ERR_SERVICE_NOT_READY - service is not ready
  QL_ERR_INVALID_ARG - Invalid arguments
  Other - error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_gnss_get_nmea_version(QL_GNSS_NMEA_VERSION_ID_E *version);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief Set nmea version
  @param[in] version nmea version
  @return
  QL_ERR_OK - successful
  QL_ERR_NOT_INIT - uninitialized
  QL_ERR_SERVICE_NOT_READY - service is not ready
  QL_ERR_INVALID_ARG - Invalid arguments
  Other - error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_gnss_set_nmea_version(QL_GNSS_NMEA_VERSION_ID_E version);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief Set gnss agnss mode
  @param[in] mask Gnss agnss mode
  @return
  QL_ERR_OK - successful
  QL_ERR_NOT_INIT - uninitialized
  QL_ERR_SERVICE_NOT_READY - service is not ready
  QL_ERR_INVALID_ARG - Invalid arguments
  Other - error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_gnss_set_agnss_mode(uint32_t mask);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief Inject  agnss data
  @param[in] data agnss data
  @return
  QL_ERR_OK - successful
  QL_ERR_NOT_INIT - uninitialized
  QL_ERR_SERVICE_NOT_READY - service is not ready
  QL_ERR_INVALID_ARG - Invalid arguments
  Other - error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_gnss_inject_agnss_data(void);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief Inject UTC time to GNSS Engine.
  @param[in] timestamp ,unit: ms
  @return Whether to successfully Start Gnss 
  @retval QL_ERR_OK successful
  @retval QL_ERR_FAILED  Start Gnss Failed
  @retval Other error code defined by ql_gnss.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_gnss_inject_utc_time(uint64_t timestamp);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief Set gnss suspend
  @return
  QL_ERR_OK - successful
  QL_ERR_NOT_INIT - uninitialized
  QL_ERR_SERVICE_NOT_READY - service is not ready
  QL_ERR_INVALID_ARG - Invalid arguments
  Other - error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_gnss_suspend(void);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief Set gnss resume
  @return
  QL_ERR_OK - successful
  QL_ERR_NOT_INIT - uninitialized
  QL_ERR_SERVICE_NOT_READY - service is not ready
  QL_ERR_INVALID_ARG - Invalid arguments
  Other - error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_gnss_resume(void);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief Register gnss callback
  @param[in] cb
  @return
  QL_ERR_OK - successful
  QL_ERR_NOT_INIT - uninitialized
  QL_ERR_SERVICE_NOT_READY - service is not ready
  QL_ERR_INVALID_ARG - Invalid arguments
  Other - error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_gnss_set_ind_cb(ql_gnss_ind_cb_f cb);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Registration server error callback. Currently, only if the server exits abnormally, 
  the callback function will be executed, and the error code is QL_ERR_ABORTED;
  @param[in] cb  Callback function 
  @return
  QL_ERR_OK - successful
  Other - error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_gnss_set_service_error_cb(ql_gnss_error_cb_f cb);

#ifdef __cplusplus
}
#endif

#endif