LBS 开发指导_Rev1.1

English

修订记录

版本

日期

作者

审核

修订内容

Rev1.0

2023-09-11

lxh

zlc

创建文档

Rev1.1

2024-03-25

sxx

更改文档名称

1 简介

本文档介绍 LTE-EC71X LBS 接口 API 情况， API 接口位于 components/kernel/lierda_api/liot_lbs/liot_lbs_client.h 文件声明。

LBS所使用的定位服务器为lierda云平台，token需自行到服务器去申请，服务器地址为：https://account.xiot.senthink.com 。

2 API 函数概览

函数

说明

liot_lbs_get_position()

该函数用于请求获取定位信息。

3 类型说明

3.1 liot_lbs_result_code_e

LBS API 执行结果错误码。

  1. 声明

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;

  1. 参数

  • LIOT_LBS_OK：函数执行成功。

  • LIOT_LBS_LOC_FAIL ：定位失败。

  • LIOT_LBS_IMEI_ILLEGAL ：非法IMEI。

  • LIOT_LBS_TOKEN_NOT_EXIS ：token不存在。

  • LIOT_LBS_TOKEN_LOC_EXCEED_MAX：token超出最大值。

  • LIOT_LBS_IMEI_LOC_EXCEED_DAY_MAX：IMEI超过最大值。

  • LIOT_LBS_IMEI_LOC_VISIT_EXCEED_MAX：IMEI访问超出最次数。

  • LIOT_LBS_TOKEN_EXPIRED：token过期。

  • LIOT_LBS_IMEI_NO_AUTHORITY：IMEI没有权限。

  • LIOT_LBS_TOKEN_LOC_VISIT_EXCEED_MAX：token访问超出最大次数。

  • LIOT_LBS_TOKEN_LOC_EXCEED_PERIOD_MAX：token超过最大周期

  • LIOT_LBS_DNS_FAIL：DNS解析失败

  • LIOT_LBS_MD5_FAIL：MD5校验失败

  • LIOT_LBS_MEMORY_FAIL：内存空间不足

  • LIOT_LBS_PARAM_FORMAT_FAIL：参数错误

3.2 liot_lbs_basic_info_t

LBS基本参数配置结构体定义如下：

  1. 声明

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;

  1. 参数

类型

参数

描述

uint8_t

type

LBS定位类型

uint8_t

encrypt

数据加密

uint8_t

key_index

关键字索引

uint8_t

pos_format

位置格式

uint8_t

loc_method

定位方式

3.3 liot_lbs_auth_info_t

LBS鉴权信息：

  1. 声明

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

  1. 参数

类型

参数

描述

char

user_name

用户名

char

user_pwd

密码

char

token

定位token，需在利尔达云平台进行申请

char

imei

模组IMEI号

uint16_t

rand

随机数

3.4 liot_lbs_cell_info_t

LBS的网络信息：

  1. 声明

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;

  1. 参数

类型

参数

描述

uint8_t

radio

射频

uint16_t

mcc

移动国家号码

uint16_t

mnc

移动网号

int

lac_id

跟踪区域码

int

cell_id

小区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

预留

3.5 liot_lbs_wifi_mac_info_t

LBS的WIFI信息：

  1. 声明

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

  1. 参数

类型

参数

描述

char

wifi_mac

wifi的mac地址

int

wifi_rssi

信号强度

char

wifi_ssid

Wifi的SSID

3.6 liot_lbs_postion_info_t

LBS定位信息：

  1. 声明

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

  1. 参数

类型

参数

描述

char

longitude

经度信息

char

latitude

纬度信息

uint16_t

accuracy

精度

uint8_t

flag

定位标记位

3.7 liot_lbs_option_t

LBS定位参数信息选项：

  1. 声明

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;

  1. 参数

类型

参数

描述

int

pdp_cid

激活的PDP CID

int

sim_id

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

wifi个数

liot_lbs_wifi_mac_info_t *

wifi_info

wifi信息

3.8 liot_lbs_response_data_t

LBS定位返回的数据信息：

  1. 声明

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;

  1. 参数

类型

参数

描述

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

参数

3.9 liot_lbs_response_callback

LBS定位回调函数：

  1. 声明

void (*liot_lbs_response_callback)(liot_lbs_response_data_t *response_data);

  1. 参数

response_data：[out] 获取到的定位数据信息。由 liot_lbs_get_position()插入链接获取

4 API 函数详解

4.1 liot_lbs_get_position

该函数用于初始化 LBS，发起定位请求。

  1. 声明

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);

  1. 参数

  • lbs_hndl：[In] LBS请求句柄。

  • host：[In] LBS请求服务器地址。

  • user_opts：[In] LBS的配置信息。

  • cb：[In] LBS的回调函数

  • arg: [In]预留参数信息

  1. 返回值

  • liot_lbs_result_code_e ：执行结果码，请参考 3.1。

5 代码示例

  1. 示例代码参考  examples/demo/src/demo_lbs.c 文件。

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);
}

  • 运行结果如下：

_images/lbs-guide/image_1.png