LBS Development Guide_Rev1.1

Revision History

Version	Date	Author	Reviewer	Revision Content
Rev1.0	2023-09-11	lxh	zlc	Initial document creation
Rev1.1	2024-03-25	sxx		Changed document name

1 Introduction

This document introduces the LTE-EC71X LBS interface APIs. The API interfaces are declared in the file components/kernel/lierda_api/liot_lbs/liot_lbs_client.h.

The positioning server used by LBS is Lierda cloud platform, token needs to be applied on the server, server address is: `https://account.xiot.senthink.com`.

2 API Function Overview

Function	Description
`liot_lbs_get_position()`	This function is used to request location information

3 Type Descriptions

3.1 liot_lbs_result_code_e

LBS API execution result error codes.

Declaration

typedef enum
{
    LIOT_LBS_OK                          = 0,
    LIOT_LBS_LOC_FAIL                    = (LIOT_COMPONENT_LWIP_LBS << 16) | 10000,
    LIOT_LBS_IMEI_ILLEGAL                = (LIOT_COMPONENT_LWIP_LBS << 16) | 10001,
    LIOT_LBS_TOKEN_NOT_EXIST             = (LIOT_COMPONENT_LWIP_LBS << 16) | 10002,
    LIOT_LBS_TOKEN_LOC_EXCEED_MAX        = (LIOT_COMPONENT_LWIP_LBS << 16) | 10003,
    LIOT_LBS_IMEI_LOC_EXCEED_DAY_MAX     = (LIOT_COMPONENT_LWIP_LBS << 16) | 10004,
    LIOT_LBS_IMEI_LOC_VISIT_EXCEED_MAX   = (LIOT_COMPONENT_LWIP_LBS << 16) | 10005,
    LIOT_LBS_TOKEN_EXPIRED               = (LIOT_COMPONENT_LWIP_LBS << 16) | 10006,
    LIOT_LBS_IMEI_NO_AUTHORITY           = (LIOT_COMPONENT_LWIP_LBS << 16) | 10007,
    LIOT_LBS_TOKEN_LOC_VISIT_EXCEED_MAX  = (LIOT_COMPONENT_LWIP_LBS << 16) | 10008,
    LIOT_LBS_TOKEN_LOC_EXCEED_PERIOD_MAX = (LIOT_COMPONENT_LWIP_LBS << 16) | 10009,
    LIOT_LBS_DNS_FAIL                    = (LIOT_COMPONENT_LWIP_LBS << 16) | 10101,
    LIOT_LBS_MD5_FAIL                    = (LIOT_COMPONENT_LWIP_LBS << 16) | 10102,
    LIOT_LBS_MEMORY_FAIL                 = (LIOT_COMPONENT_LWIP_LBS << 16) | 10103,
    LIOT_LBS_NET_FAIL                    = (LIOT_COMPONENT_LWIP_LBS << 16) | 10104,
    LIOT_LBS_PARAM_FORMAT_FAIL           = (LIOT_COMPONENT_LWIP_LBS << 16) | 10105,
} liot_lbs_result_code_e;

Parameters

LIOT_LBS_OK: Function executed successfully.
LIOT_LBS_LOC_FAIL: Positioning failed.
LIOT_LBS_IMEI_ILLEGAL: Illegal IMEI.
LIOT_LBS_TOKEN_NOT_EXIS: Token does not exist.
LIOT_LBS_TOKEN_LOC_EXCEED_MAX: Token exceeds maximum value.
LIOT_LBS_IMEI_LOC_EXCEED_DAY_MAX: IMEI exceeds maximum value.
LIOT_LBS_IMEI_LOC_VISIT_EXCEED_MAX: IMEI access exceeds maximum times.
LIOT_LBS_TOKEN_EXPIRED: Token expired.
LIOT_LBS_IMEI_NO_AUTHORITY: IMEI has no authority.
LIOT_LBS_TOKEN_LOC_VISIT_EXCEED_MAX: Token access exceeds maximum times.
LIOT_LBS_TOKEN_LOC_EXCEED_PERIOD_MAX: Token exceeds maximum period.
LIOT_LBS_DNS_FAIL: DNS resolution failed.
LIOT_LBS_MD5_FAIL: MD5 verification failed.
LIOT_LBS_MEMORY_FAIL: Insufficient memory space.
LIOT_LBS_PARAM_FORMAT_FAIL: Parameter error.

3.2 liot_lbs_basic_info_t

LBS basic parameter configuration structure definition is as follows:

Declaration

typedef struct
{
    uint8_t type;
    uint8_t encrypt;
    uint8_t key_index;
    uint8_t pos_format;
    uint8_t loc_method;
} liot_lbs_basic_info_t;

Parameters

Type	Parameter	Description
uint8_t	type	LBS positioning type
uint8_t	encrypt	Data encryption
uint8_t	key_index	Key index
uint8_t	pos_format	Position format
uint8_t	loc_method	Positioning method

3.3 liot_lbs_auth_info_t

LBS authentication information:

Declaration

typedef struct
{
    char user_name[64];
    char user_pwd[64];
    char token[128];
    char imei[64];
    uint16_t rand;
} liot_lbs_auth_info_t;

Parameters

Type	Parameter	Description
char	user_name	Username
char	user_pwd	Password
char	token	Positioning token, needs to be applied on Lierda Cloud Platform
char	imei	Module IMEI number
uint16_t	rand	Random number

3.4 liot_lbs_cell_info_t

LBS network information:

Declaration

typedef struct
{
    uint8_t radio;
    uint16_t mcc;
    uint16_t mnc;
    int lac_id;
    int cell_id;
    int16_t signal;
    uint16_t tac;
    uint16_t bcch;
    uint8_t bsic;
    uint16_t uarfcndl;
    uint16_t psc;
    uint16_t rsrq;
    uint16_t pci;
    uint16_t earfcn;
    uint16_t reserve;
} liot_lbs_cell_info_t;

Parameters

Type	Parameter	Description
uint8_t	radio	Radio
uint16_t	mcc	Mobile Country Code
uint16_t	mnc	Mobile Network Code
int	lac_id	Tracking Area Code
int	cell_id	Cell ID
int16_t	signal	Signal strength
uint16_t	tac	Tracking Area Code
uint16_t	bcch	Broadcast Channel
uint8_t	bsic	Base Station Identity Code
uint16_t	uarfcndl	Carrier Frequency Number
uint16_t	psc	Personal Security Code
uint16_t	rsrq	Signal Quality
uint16_t	pci	Physical Cell Identifier
uint16_t	earfcn	Carrier Frequency Point Number
uint16_t	reserve	Reserved

3.5 liot_lbs_wifi_mac_info_t

LBS WIFI information:

Declaration

typedef struct
{
    char wifi_mac[18];
    int wifi_rssi;
    char wifi_ssid[32];
} liot_lbs_wifi_mac_info_t;

Parameters

Type	Parameter	Description
char	wifi_mac	WIFI MAC address
int	wifi_rssi	Signal strength
char	wifi_ssid	WIFI SSID

3.6 liot_lbs_postion_info_t

LBS positioning information:

Declaration

typedef struct
{
    char longitude[32];
    char latitude[32];
    uint16_t accuracy;
    uint8_t flag;
} liot_lbs_postion_info_t;

Parameters

Type	Parameter	Description
char	longitude	Longitude information
char	latitude	Latitude information
uint16_t	accuracy	Accuracy
uint8_t	flag	Positioning flag bit

3.7 liot_lbs_option_t

LBS positioning parameter options:

Declaration

typedef struct
{
    int pdp_cid;
    int sim_id;
    int req_timeout;
    liot_lbs_basic_info_t *basic_info;
    liot_lbs_auth_info_t *auth_info;
    int cell_num;
    liot_lbs_cell_info_t *cell_info;
    int wifi_num;
    liot_lbs_wifi_mac_info_t *wifi_info;
} liot_lbs_option_t;

Parameters

Type	Parameter	Description
int	pdp_cid	Activated PDP CID
int	sim_id	SIM card ID
int	req_timeout	Request timeout
liot_lbs_basic_info_t *	basic_info	Basic positioning information
liot_lbs_auth_info_t *	auth_info	Authentication information
int	cell_num	Number of base stations
liot_lbs_cell_info_t*	cell_info	Base station information
int	wifi_num	Number of WIFI
liot_lbs_wifi_mac_info_t *	wifi_info	WIFI information

3.8 liot_lbs_response_data_t

LBS positioning response data information:

Declaration

typedef struct
{
    liot_lbs_client_hndl hndl;
    liot_lbs_result_code_e result;
    int pos_num;
    liot_lbs_postion_info_t *pos_info;
    char *date;
    void *arg;
} liot_lbs_response_data_t;

Parameters

Type	Parameter	Description
liot_lbs_client_hndl	hndl	Positioning request handle
liot_lbs_result_code_e	result	Positioning request result
int	pos_num	Request count
liot_lbs_postion_info_t *	pos_info	Requested positioning information
char *	date	Date
void *	arg	Parameter

3.9 liot_lbs_response_callback

LBS positioning callback function:

Declaration

void (*liot_lbs_response_callback)(liot_lbs_response_data_t *response_data);

Parameters

response_data: [out] Obtained positioning data information. Obtained through liot_lbs_get_position()

4 API Function Details

4.1 liot_lbs_get_position

This function is used to initialize LBS and initiate positioning request.

Declaration

liot_lbs_result_code_e liot_lbs_get_position(
    liot_lbs_client_hndl *lbs_hndl, char *host, liot_lbs_option_t *user_opts, liot_lbs_response_callback cb, void *arg);

Parameters

lbs_hndl: [In] LBS request handle.
host: [In] LBS request server address.
user_opts: [In] LBS configuration information.
cb: [In] LBS callback function.
arg: [In] Reserved parameter information.

Return Value

liot_lbs_result_code_e: Execution result code, please refer to 3.1.

5 Code Example

Sample code reference: examples/demo/src/demo_lbs.c file.

static void lbs_result_cb(liot_lbs_response_data_t *response_data)
{
    char latitude_str[30]  = {0};
    char longitude_str[30] = {0};
    if (response_data == NULL || response_data->hndl == 0)
    {
        return;
    }

    liot_trace(
        "==lbs_result_cb  lbs result: %d, response_data->pos_num:%d", response_data->result, response_data->pos_num);
    if (response_data->result == LIOT_LBS_OK)
    {
        memcpy(latitude_str, response_data->pos_info->latitude, strlen(response_data->pos_info->latitude));
        memcpy(longitude_str, response_data->pos_info->longitude, strlen(response_data->pos_info->longitude));
        liot_trace("lbs_result_cb  Location: longitude:%s, latitude:%s", latitude_str, longitude_str);
    }
    liot_rtos_semaphore_release(lbs_semp);
}

extern void liot_lbs_demo_thread(void *arg)
{
    liot_lbs_client_hndl lbs_client = 0;
    int ret                         = 0;
    int cid                         = 1;
    int i                           = 0;
    liot_data_call_info_t info;
    uint8_t nSim = 0;
    liot_nw_cell_info_s cell_info;
    liot_nw_seclection_info_s select_info;
    liot_lbs_option_t lbs_option;
    liot_lbs_cell_info_t lbs_cell_info[LBS_MAX_CELL_NUM] = {0};
    char imei_str[64]                                    = {0};

    liot_dev_get_imei(imei_str, 64, nSim);

    liot_lbs_basic_info_t basic_info = {
        .type       = 1,
        .encrypt    = 1,
        .key_index  = 1,
        .pos_format = 1,
        .loc_method = 4,
    };

    liot_lbs_auth_info_t auth_info = {
        .user_name = "lierda",
        .user_pwd  = "123456",
        .token     = "B84E427D95B1DF4A3F49B18DDF714C72",
        .rand      = liot_rtos_rand(),
    };
    strcpy(auth_info.imei, imei_str);
    memset(&imei_str, 0x00, sizeof(imei_str));

    liot_rtos_semaphore_create(&lbs_semp, 0);

    liot_trace("==========lbs demo start ==========");

    liot_trace("===start data call====");
    ret = liot_start_data_call(nSim, cid, LIOT_DATA_TYPE_IP, "APNTEST", "", "", LIOT_DATA_AUTH_TYPE_NONE);
    liot_trace("===data call result:%d", ret);
    if (ret != 0)
    {
        liot_trace("====data call failure!!!!!=====");
    }

    liot_rtos_task_sleep_ms(2000);

    liot_set_data_call_asyn_mode(nSim, cid, 1);

    ret = liot_get_data_call_info(nSim, cid, &info);
    if (ret != 0)
    {
        liot_trace("liot_get_data_call_info ret: %d", ret);
        liot_stop_data_call(nSim, cid);
        goto exit;
    }

    liot_trace("info->profile_idx: %d", info.cid);
    liot_trace("info->ip_version: %d", info.ip_version);

    liot_trace("info->v4.state: %d", info.v4.state);

    liot_ip4addr_ntoa(&info.v4.addr.ip);
    liot_trace("info.v4.addr.ip: %s\r\n", liot_ip4addr_ntoa(&info.v4.addr.ip));

    liot_ip4addr_ntoa(&info.v4.addr.pri_dns);
    liot_trace("info.v4.addr.pri_dns: %s\r\n", liot_ip4addr_ntoa(&info.v4.addr.pri_dns));

    liot_ip4addr_ntoa(&info.v4.addr.sec_dns);
    liot_trace("info.v4.addr.sec_dns: %s\r\n", liot_ip4addr_ntoa(&info.v4.addr.sec_dns));
start:
    if (liot_nw_get_cell_info(nSim, &cell_info) != LIOT_NW_SUCCESS)
    {
        liot_trace("===============lbs get cell info fail===============\n");
        goto exit;
    }
    ret = liot_nw_get_selection(nSim, &select_info);
    if (ret != 0)
    {
        liot_trace("liot_nw_get_selection ret: %d", ret);
        goto exit;
    }
    liot_trace(
        "%s:%d  info_num:%d  valid:%d", __FUNCTION__, __LINE__, cell_info.lte_info_num, cell_info.lte_info_valid);
    liot_trace("nw_act_type=%d", select_info.act);

    if (select_info.act == LIOT_NW_ACCESS_TECH_E_UTRAN)
    {
        /*
            liot_trace("mcc=%d,mnc=%d,cell_id=%d,signal=%d,tac=%d,bcch=%d,bsic=%d,rsrq=%d,pci=%d,earfcn=%d,lac_id:%d",
            lbs_cell_info.mcc,lbs_cell_info.mnc,lbs_cell_info.cell_id,lbs_cell_info.signal,lbs_cell_info.tac,
            lbs_cell_info.bcch,lbs_cell_info.bsic,lbs_cell_info.rsrq,lbs_cell_info.pci,lbs_cell_info.earfcn,lbs_cell_info.lac_id);
            */
        char mcc_str[5] = {0};
        char mnc_str[5] = {0};

        lbs_cell_info[0].radio = 3;

        snprintf(mcc_str, 5, "%03X", cell_info.lte_info[0].mcc);
        lbs_cell_info[0].mcc = atoi(mcc_str);
        memset(mcc_str, 0x0, 5);

        snprintf(mnc_str, 5, "%02X", cell_info.lte_info[0].mnc & 0XFFF);
        lbs_cell_info[0].mnc = atoi(mnc_str);
        memset(mnc_str, 0x0, 5);

        lbs_cell_info[0].cell_id = cell_info.lte_info[0].cid;
        lbs_cell_info[0].lac_id  = cell_info.lte_info[0].tac;
        lbs_cell_info[0].pci     = cell_info.lte_info[0].pci;
        lbs_cell_info[0].earfcn  = cell_info.lte_info[0].earfcn;
        lbs_cell_info[0].bcch    = cell_info.lte_info[0].earfcn;
        lbs_cell_info[0].signal  = cell_info.lte_info[0].rssi;

        for (i = 0; i < cell_info.lte_info_num; i++)
        {
            lbs_cell_info[i + 1].radio = 3;

            snprintf(mcc_str, 5, "%03X", cell_info.lte_info[i + 1].mcc);
            lbs_cell_info[i + 1].mcc = atoi(mcc_str);
            memset(mcc_str, 0x0, 5);

            snprintf(mnc_str, 5, "%02X", cell_info.lte_info[i + 1].mnc & 0XFFF);
            lbs_cell_info[i + 1].mnc = atoi(mnc_str);
            memset(mnc_str, 0x0, 5);

            lbs_cell_info[i + 1].cell_id = cell_info.lte_info[i + 1].cid;
            lbs_cell_info[i + 1].lac_id  = cell_info.lte_info[i + 1].tac;
            lbs_cell_info[i + 1].pci     = cell_info.lte_info[i + 1].pci;
            lbs_cell_info[i + 1].earfcn  = cell_info.lte_info[i + 1].earfcn;
            lbs_cell_info[i + 1].bcch    = cell_info.lte_info[i + 1].earfcn;
            lbs_cell_info[i + 1].signal  = cell_info.lte_info[i + 1].rssi;
        }

        liot_trace("mcc=%d,mnc=%d,cell_id=%d,signal=%d,bcch=%d,pci=%d,earfcn=%d,lac_id:%d",
                   lbs_cell_info[0].mcc,
                   lbs_cell_info[0].mnc,
                   lbs_cell_info[0].cell_id,
                   lbs_cell_info[0].signal,
                   lbs_cell_info[0].bcch,
                   lbs_cell_info[0].pci,
                   lbs_cell_info[0].earfcn,
                   lbs_cell_info[0].lac_id);
    }
    else
    {
        liot_trace("network access technology type error");
        goto exit;
    }

    memset(&lbs_option, 0x00, sizeof(liot_lbs_option_t));
    lbs_option.pdp_cid     = cid;
    lbs_option.sim_id      = nSim;
    lbs_option.req_timeout = 60;
    lbs_option.basic_info  = &basic_info;
    lbs_option.auth_info   = &auth_info;
    lbs_option.cell_num    = cell_info.lte_info_num;
    lbs_option.cell_info   = lbs_cell_info;

    if (LIOT_LBS_OK == liot_lbs_get_position(&lbs_client,
                                             "http://locator-aep.xiot.senthink.com:80/locator/v0.1/locate",
                                             &lbs_option,
                                             lbs_result_cb,
                                             NULL))
    {
        liot_rtos_semaphore_wait(lbs_semp, LIOT_WAIT_FOREVER);

        liot_trace("lbs success");
        liot_rtos_task_sleep_ms(500);
        goto start;
    }
    else
    {
        liot_trace("lbs failed");
    }

exit:

    liot_rtos_semaphore_delete(lbs_semp);
    liot_trace("===liot_lbs_thread exit===");
    liot_rtos_task_delete(NULL);
}

Running Result:

As shown in the figure above, it indicates that all information has been obtained normally.