NW 开发指导_Rev1.3

English

修订记录

版本

日期

作者

修订内容

Rev1.0

2023-09-12

CLY

创建文档

Rev1.1

2024-03-25

sxx

更改文档名称

Rev1.2

2024-10-25

LJZ

修改文档格式

Rev1.3

2025-02-12

ZLC

新增liot_nw_set_ctzu_switch与liot_nw_get_ctzu_switch接口

1 简介

本文档介绍 LTE-EC71X 注网信息接口 API 情况， API 接口位于 components/kernel/lierda_api/liot_nw/liot_nw.h 文件声明。

2 API 函数概览

函数

说明

liot_nw_get_csq()

查询csq信号强度信息

liot_nw_get_operator_name()

获取当前注网的运营商信息

liot_nw_get_reg_status ()

获取当前网络注册信息

liot_nw_set_selection ()

设置运营商

liot_nw_get_selection ()

获取选择的运营商信息

liot_nw_get_signal_strength ()

获取详细信号强度信息

liot_nw_get_nitz_time_info ()

获取当前基站时间

liot_nw_get_cell_info ()

获取当前服务及邻近小区信息

liot_nw_register_cb ()

注册事件回调函数

liot_nw_get_data_count ()

获取上行和下行数据计数

liot_nw_reset_data_count ()

重置上行和下行数据计数

liot_nw_set_ctzu_switch()

设置基站时间同步开关

liot_nw_get_ctzu_switch()

获取基站时间同步开关状态

3 类型说明

3.1 liot_nw_errcode_e

NW API 执行结果错误码。

  • 定义

typedef enum
{
    LIOT_NW_SUCCESS     = 0,
    LIOT_NW_EXECUTE_ERR = 1 | (LIOT_COMPONENT_NETWORK << 16),
    LIOT_NW_MEM_ADDR_NULL_ERR,
    LIOT_NW_INVALID_PARAM_ERR,
    LIOT_NW_CFW_CFUN_GET_ERR,
    LIOT_NW_CFUN_DISABLE_ERR = 5 | (LIOT_COMPONENT_NETWORK << 16),
    LIOT_NW_CFW_NW_STATUS_GET_ERR,
    LIOT_NW_NOT_SEARCHING_ERR,
    LIOT_NW_NOT_REGISTERED_ERR,
    LIOT_NW_CFW_GPRS_STATUS_GET_ERR,
    LIOT_GPRS_NOT_SEARCHING_ERR = 10 | (LIOT_COMPONENT_NETWORK << 16),
    LIOT_GPRS_NOT_REGISTERED_ERR,
    LIOT_NW_CFW_NW_QUAL_GET_ERR,
    LIOT_NW_CFW_OPER_ID_GET_ERR,
    LIOT_NW_CFW_OPER_NAME_GET_ERR,
    LIOT_NW_CFW_OPER_SET_ERR = 15 | (LIOT_COMPONENT_NETWORK << 16),
    LIOT_NW_SIM_ERR,
    LIOT_NW_NO_MEM_ERR,
    LIOT_NW_SEMAPHORE_CREATE_ERR,
    LIOT_NW_SEMAPHORE_TIMEOUT_ERR,
    LIOT_NW_NITZ_NOT_UPDATE_ERR = 20 | (LIOT_COMPONENT_NETWORK << 16),
    LIOT_NW_CFW_EMOD_START_ERR,
    LIOT_NW_OPERATOR_NOT_ALLOWED,
    LIOT_NW_CFW_RRCRel_SET_ERR,
} liot_nw_errcode_e;

  • 参数

  • LIOT_NW_SUCCESS ：函数执行成功。

  • LIOT_NW_EXECUTE_ERR：函数执行错误。

  • LIOT_NW_MEM_ADDR_NULL_ERR：函数的参数地址为空

  • LIOT_NW_INVALID_PARAM_ERR：函数的参数无效

  • LIOT_NW_CFW_CFUN_GET_ERR：功能模式获取失败

  • LIOT_NW_CFUN_DISABLE_ERR：非全功能模式，导致相关信息无法获取

  • LIOT_NW_CFW_NW_STATUS_GET_ERR：获取网络状态失败，导致相关信息无法获取

  • LIOT_NW_NOT_SEARCHING_ERR：未搜索到要注册的运营商，导致相关信息无法获取

  • LIOT_NW_NOT_REGISTERED_ERR：未注册网络，导致相关信息无法获取

  • LIOT_NW_CFW_GPRS_STATUS_GET_ERR：获取 PS 域网络状态失败

  • LIOT_GPRS_NOT_SEARCHING_ERR：未搜索到 PS 域要注册的运营商

  • LIOT_GPRS_NOT_REGISTERED_ERR：未注册到 PS 域网络

  • LIOT_NW_CFW_NW_QUAL_GET_ERR：获取信号质量失败

  • LIOT_NW_CFW_OPER_ID_GET_ERR：获取运营商 ID 信息失败

  • LIOT_NW_CFW_OPER_NAME_GET_ERR：获取运营商名称失败

  • LIOT_NW_CFW_OPER_SET_ERR：设置运营商失败

  • LIOT_NW_SIM_ERR：(U)SIM 卡相关错误，导致信息获取失败

  • LIOT_NW_NO_MEM_ERR：申请内存失败

  • LIOT_NW_SEMAPHORE_CREATE_ERR：创建信号量失败

  • LIOT_NW_SEMAPHORE_TIMEOUT_ERR：等待信号量超时

  • LIOT_NW_NITZ_NOT_UPDATE_ERR：网络时间未同步

  • LIOT_NW_CFW_EMOD_START_ERR：进入工程模式失败，导致小区信息获取失败

  • LIOT_NW_OPERATOR_NOT_ALLOWED：操作不允许

  • LIOT_NW_CFW_RRCRel_SET_ERR：RRCRel设置错误

3.2 liot_nw_act_type_e

注网类型。

  1. 定义

typedef enum
{
    LIOT_NW_ACCESS_TECH_GSM                = 0,
    LIOT_NW_ACCESS_TECH_GSM_COMPACT        = 1,
    LIOT_NW_ACCESS_TECH_UTRAN              = 2,
    LIOT_NW_ACCESS_TECH_GSM_wEGPRS         = 3,
    LIOT_NW_ACCESS_TECH_UTRAN_wHSDPA       = 4,
    LIOT_NW_ACCESS_TECH_UTRAN_wHSUPA       = 5,
    LIOT_NW_ACCESS_TECH_UTRAN_wHSDPA_HSUPA = 6,
    LIOT_NW_ACCESS_TECH_E_UTRAN            = 7,
} liot_nw_act_type_e;

  1. 参数

  • LIOT_NW_ACCESS_TECH_GSM：2G（GSM，不支持）

  • LIOT_NW_ACCESS_TECH_GSM_COMPACT：2G（GSM COMPACT，不支持）

  • LIOT_NW_ACCESS_TECH_UTRAN：3G（UTRAN，不支持）

  • LIOT_NW_ACCESS_TECH_GSM_wEGPRS：2G（EGPRS，不支持）

  • LIOT_NW_ACCESS_TECH_UTRAN_wHSDPA：3G（HSDPA，不支持）

  • LIOT_NW_ACCESS_TECH_UTRAN_wHSUPA：3G（HSUPA，不支持）

  • LIOT_NW_ACCESS_TECH_UTRAN_wHSDPA_HSUPA：3G（HSDPA 和 HSUPA，不支持）

  • LIOT_NW_ACCESS_TECH_E_UTRAN：4G（E-UTRAN）

3.3 liot_nw_reg_state_e

注网状态。

  1. 定义

typedef enum
{
    LIOT_NW_REG_STATE_NOT_REGISTERED = 0, // not registered, MT is not currently searching an operator to register to
    LIOT_NW_REG_STATE_HOME_NETWORK   = 1, // registered, home network
    LIOT_NW_REG_STATE_TRYING_ATTACH_OR_SEARCHING = 2, // not registered, but MT is currently trying to attach or
                                                      // searching an operator to register to
    LIOT_NW_REG_STATE_DENIED  = 3,                    // registration denied
    LIOT_NW_REG_STATE_UNKNOWN = 4,                    // unknown
    LIOT_NW_REG_STATE_ROAMING = 5,                    // registered, roaming
} liot_nw_reg_state_e;

  1. 参数

  • LIOT_NW_REG_STATE_NOT_REGISTERED： 未注册，MT 当前未搜索到注册的运营商

  • LIOT_NW_REG_STATE_HOME_NETWORK：已注册，归属地网络

  • LIOT_NW_REG_STATE_TRYING_ATTACH_OR_SEARCHING：未注册，MT当前正在尝试注网或者正在搜索运营商以进行注网

  • LIOT_NW_REG_STATE_DENIED：注册被拒绝

  • LIOT_NW_REG_STATE_UNKNOWN：未知状态

  • LIOT_NW_REG_STATE_ROAMING：已注册，漫游状态

4 API 函数详解

4.1 liot_nw_get_csq

该函数用于获取网络信号质量信息。

  1. 声明

liot_nw_errcode_e liot_nw_get_csq(uint8_t nSim, unsigned char *csq);

  1. 参数

nSim ：

[In] 所使用的(U)SIM 卡。若模块只支持 1 个(U)SIM 接口，此参数可设置为 0。

0  (U)SIM 卡 1

1  (U)SIM 卡 2

csq：

[Out] 返回网络信号质量信息。范围：0 ~ 31。返回 99 为无效值。

  1. 返回值

liot_nw_errcode_e：执行结果码，请参考第 3.1 章 liot_nw_errcode_e。

4.2 liot_nw_get_operator_name

获取运营商名称

  1. 声明

liot_nw_errcode_e liot_nw_get_operator_name(uint8_t nSim, liot_nw_operator_info_s *oper_info);

  1. 参数

nSim ：

[In] 所使用的(U)SIM 卡。若模块只支持 1 个(U)SIM 接口，此参数可设置为 0。

0  (U)SIM 卡 1

1  (U)SIM 卡 2

oper_info：

[Out] 返回运营商信息。详情见第5.2.1章

  1. 返回值

liot_nw_errcode_e：执行结果码，请参考第 3.1 章 liot_nw_errcode_e。

4.2.1 liot_nw_operator_info_s

  1. 运营商信息结构体定义

typedef struct
{
    char long_oper_name[QL_NW_LONG_OPER_MAX_LEN+1];
    char short_oper_name[QL_NW_SHORT_OPER_MAX_LEN+1];
    char mcc[QL_NW_MCC_MAX_LEN+1];
    char mnc[QL_NW_MNC_MAX_LEN+1];
}liot_nw_operator_info_s；

  1. 参数

类型

参数

描述

char

long_oper_name

运营商名称全称，长度不超过32字节

char

short_oper_name

运营商名称简称，长度不超过32字节

char

mcc

移动设备国家代码，长度不超过3字节

char

mnc

移动设备网络代码，长度不超过3字节

4.3 liot_nw_get_reg_status

获取当前网络注册信息。

  1. 声明

liot_nw_errcode_e liot_nw_get_reg_status(uint8_t nSim, liot_nw_reg_status_info_s *reg_info);

  1. 参数

nSim ：

[In] 所使用的(U)SIM 卡。若模块只支持 1 个(U)SIM 接口，此参数可设置为 0。

0  (U)SIM 卡 1

1  (U)SIM 卡 2

reg_info：

[Out] 返回注册信息。详情见第5.3.1章。

  1. 返回值

liot_nw_errcode_e：执行结果码，请参考第 3.1 章 liot_nw_errcode_e。

4.3.1 liot_nw_reg_status_info_s

  1. 网络注册信息结构体定义

typedef struct
{
    liot_nw_common_reg_status_info_s data_reg; // data register info
} liot_nw_reg_status_info_s;

4.3.2 liot_nw_common_reg_status_info_s

  1. 网络注册信息结构体定义

typedef struct
{
    liot_nw_reg_state_e state; // network register state
    int lac;                   // location area code
    int cid;                   // cell ID
    liot_nw_act_type_e act;    // access technology
} liot_nw_common_reg_status_info_s;

  1. 参数

类型

参数

描述

liot_nw_reg_state_e

state

注网状态；详见 第 4.3章

int

lac

位置区码

int

cid

小区全球识别码

liot_nw_act_type_e

act

注网制式；详见 第 4.2章

4.4 liot_nw_set_selection

该函数用于选择运营商。

  1. 声明

liot_nw_errcode_e liot_nw_set_selection(uint8_t nSim, liot_nw_seclection_info_s *select_info);

  1. 参数

nSim ：

[In] 所使用的(U)SIM 卡。若模块只支持 1 个(U)SIM 接口，此参数可设置为 0。

0  (U)SIM 卡 1

1  (U)SIM 卡 2

select_info：

[Out] 选择的运营商信息。详情见第5.4.1章 liot_nw_seclection_info_s。

  1. 返回值

liot_nw_errcode_e：执行结果码，请参考第 3.1 章 liot_nw_errcode_e。

4.4.1 liot_nw_seclection_info_s

  1. 选择的运营商信息结构体定义

typedef struct
{
    unsigned char nw_selection_mode;   // 0 auto select operator    1 manual select operator
    char mcc[LIOT_NW_MCC_MAX_LEN + 1]; // String format
    char mnc[LIOT_NW_MNC_MAX_LEN + 1]; // String format    eg:China Mobile -----> mcc="460"   mnc="00"
    liot_nw_act_type_e act;            // access technology
} liot_nw_seclection_info_s;

  1. 参数

类型

参数

描述

unsigned char

nw_selection_mode

运营商选择方式。
0  Modem 自动选择，MCC 和 MNC 无效
1  手动选择

char

mcc

移动设备国家代码

char

mnc

移动设备网络代码

liot_nw_act_type_e

act

注网制式；详见 第 4.2 章

4.5 liot_nw_get_selection

获取选择的运营商信息，需要等待注网成功。

  1. 声明

liot_nw_errcode_e liot_nw_get_selection(uint8_t nSim, liot_nw_seclection_info_s *select_info);

  1. 参数

nSim ：

[In] 所使用的(U)SIM 卡。若模块只支持 1 个(U)SIM 接口，此参数可设置为 0。

0  (U)SIM 卡 1

1  (U)SIM 卡 2

select_info：

[Out] 选择的运营商信息。请参考第 3.1 章 liot_nw_errcode_e。

4.6 liot_nw_get_signal_strength

获取的详细信号强度信息。

  1. 声明

liot_nw_errcode_e liot_nw_get_signal_strength(uint8_t nSim, liot_nw_signal_strength_info_s *pt_info);

  1. 参数

nSim ：

[In] 所使用的(U)SIM 卡。若模块只支持 1 个(U)SIM 接口，此参数可设置为 0。

0  (U)SIM 卡 1

1  (U)SIM 卡 2

pt_info：

[Out] 获取的详细信号强度信息。详情见第5.6.1章。

4.6.1 liot_nw_signal_strength_info_s

  1. 详细信号强度信息结构体定义

typedef struct
{
    int rssi;         // received signal strength level, range 0-31, 99=unknown. Convert to dBm: rssi_dBm = 2 * rssi - 113
    int bitErrorRate; // channel bit error rate (return 99 indicates that not known or not detectable)
    int rsrq;         // reference signal received quality, range 0-34, 255=unknown. Step 0.5dB, lower bound: rsrq_dB = rsrq * 0.5 - 20 (0: <-19.5dB, 34: >=-3dB)
    int rsrp;         // reference signal received power, range 0-97, 255=unknown. Step 1dBm, lower bound: rsrp_dBm = rsrp - 141 (0: <-140dBm, 97: >=-44dBm)
    int snr;          // SNR Signal-to-Noise Ratio value in dB, value range: -20 ~ 40
} liot_nw_signal_strength_info_s;

  1. 参数

类型

参数

描述

int

rssi

接收信号强度指示，范围 0-31，99 表示无效值。转换公式：rssi_dBm = 2 × rssi - 113

int

bitErrorRate

信道误码率，只在通话过程中有效，99 表示无效值

int

rsrq

参考信号接收质量，范围 0-34，255 表示无效值。步进 0.5dB，转换公式：rsrq_dB = rsrq × 0.5 - 20（0 表示 <-19.5dB，34 表示 >=-3dB）

int

rsrp

参考信号接收功率，范围 0-97，255 表示无效值。步进 1dBm，转换公式：rsrp_dBm = rsrp - 141（0 表示 <-140dBm，97 表示 >=-44dBm）

int

snr

信噪比，值范围：-20 ~ 40 dB

4.7 liot_nw_get_nitz_time_info

获取当前基站时间，此时间只在注网成功的那一刻更新，需要当地网络支持。

  1. 声明

liot_nw_errcode_e liot_nw_get_nitz_time_info(liot_nw_nitz_time_info_s *nitz_info);

  1. 参数

nitz_info：

[Out] 从基站获取的时间信息。详情见第5.7.1章 liot_nw_nitz_time_info_s 。

4.7.1 liot_nw_nitz_time_info_s

  1. 基站时间信息结构体定义

typedef struct
{
    char nitz_time[32]; // string format: YY/MM/DD HH:MM:SS '+/-'TZ daylight,   20/09/25 07:40:18 +32 00.
    long abs_time;      // Numeric format of NITZ time    0 is unavailable
} liot_nw_nitz_time_info_s;

  1. 参数

类型

参数

描述

char

nitz_time

本地时间。格式为：YY/MM/DD HH:MM:SS '+/-'TZ DST
TZ：本地时区（以15 分钟为单位显示本地时间和GMT时间的差异）
DST：夏令时调整时间
例如：20/10/21 09:17:43 +32 00

long

abs_time

从 1970-1-1，00:00:00（UTC 时间）到现在的总秒数。0 表示不可用

4.8 liot_nw_get_cell_info

获取当前服务及邻近小区信息。

  1. 声明

liot_nw_errcode_e liot_nw_get_cell_info(uint8_t nSim, liot_nw_cell_info_s *cell_info);

  1. 参数

nSim ：

[In] 所使用的(U)SIM 卡。若模块只支持 1 个(U)SIM 接口，此参数可设置为 0。

0  (U)SIM 卡 1

1  (U)SIM 卡 2

cell_info：

[Out] 返回当前服务及邻近小区信息。请参考 liot_nw_cell_info_s 。

  1. 返回值

liot_nw_errcode_e：执行结果码，请参考第 3.1 章 liot_nw_errcode_e。

4.8.1 liot_nw_cell_info_s

  1. 返回当前服务及邻近小区信息结构体定义

typedef struct
{
    int lte_info_valid; // 0: LTE cell information is invalid   1: LTE cell information is valid
    int lte_info_num;   // LTE cell number
    liot_nw_lte_cell_info_s lte_info[LIOT_NW_CELL_MAX_NUM]; // LTE cell information (Serving and neighbor)
} liot_nw_cell_info_s;

  1. 参数

类型

参数

描述

int

lte_info_valid

LTE 制式下小区信息是否可用。
0  不可用
1  可用

int

lte_info_num

LTE 制式下获取到的小区个数

liot_nw_lte_cell_info_s

lte_info

LTE 制式下获取到的小区信息列表

4.8.2 liot_nw_lte_cell_info_s

  1. LTE 制式下获取到的小区信息列表结构体定义

typedef struct
{
    int flag; // Cell type, 0:serving, 1:neighbor
    int cid;  // Cell ID, (0 indicates that the cellid is not received)
    int mcc;
    int mnc;
    int tac;    // Tracing area code
    int pci;    // Physical cell ID
    int earfcn; // E-UTRA absolute radio frequency channel number of the cell. RANGE: 0 TO 65535
    int rssi;   // Receive signal strength, Value range: rsrp-140 for dbm format
    char mnc_len;
    char RX_dBm; // Received power
} liot_nw_lte_cell_info_s;

  1. 参数

类型

参数

描述

int

flag

小区类别。
0  主小区
1  频间相邻小区

int

cid

小区全球识别码；0 表示未接收到小区全球识别码

int

mcc

移动设备国家代码

int

mnc

移动设备网络代码

int

tac

跟踪区域码

int

pci

物理小区识别码

int

earfcn

E-UTRA 绝对射频信道号；范围：0 ~ 65535

int

rssi

接收信号强度指示；单位：dBm

char

mnc_len

移动设备网络代码长度

char

RX_dBm

接收功率；单位：dBm

4.9 liot_nw_register_cb

该函数用于网络注册过程中相关回调处理。

  1. 声明

liot_nw_errcode_e liot_nw_register_cb(liot_nw_callback nw_cb);

  1. 参数

nw_cb：

[In] 注网信息事件回调函数；若此参数为 NULL,则表示该线程取消注册注网信息类的回调函数。

  1. 返回值

liot_nw_errcode_e：执行结果码，请参考第 3.1 章 liot_nw_errcode_e。

4.9.1 liot_nw_callback

该函数为移动网络事件回调函数。

  1. 声明

typedef void (*liot_nw_callback)(uint8_t nSim, unsigned int ind_type, void *ctx);

  1. 参数

nSim ：

[In] 所使用的(U)SIM 卡。若模块只支持 1 个(U)SIM 接口，此参数可设置为 0。

0  (U)SIM 卡 1

1  (U)SIM 卡 2

ind_type：

[In] 移动网络事件类型。

LIOT_NW_SIGNAL_QUALITY_IND  信号强度事件

LIOT_NW_DATA_REG_STATUS_IND 数据拨号事件

LIOT_NW_NITZ_TIME_UPDATE_IND 网络时间更新事件

ctx：

[In] 事件对应的信息数据。

  1. 返回值

无。

4.10 liot_nw_get_data_count

该函数用于查询上行和下行链路所消耗的流量。

  1. 声明

liot_nw_errcode_e liot_nw_get_data_count(uint8_t nSim, liot_nw_data_count_info_s *data_info);

  1. 参数

nSim ：

[In] 所使用的(U)SIM 卡。若模块只支持 1 个(U)SIM 接口，此参数可设置为 0。

0  (U)SIM 卡 1

1  (U)SIM 卡 2

data_info：

[Out] 流量统计信息。详情见  liot_nw_data_count_info_s。

  1. 返回值

liot_nw_errcode_e：执行结果码，请参考第 3.1 章 liot_nw_errcode_e。

4.10.1 liot_nw_data_count_info_s

  1. 选择的运营商信息结构体定义

typedef struct
{
    UINT64 uplink_data_count;
    UINT64 downlink_data_count;
} liot_nw_data_count_info_s;

  1. 参数

类型

参数

描述

UINT64

uplink_data_count

上行链路所消耗的流量；单位：字节

UINT64

downlink_data_count

下行链路所消耗的流量；单位：字节

4.11 liot_nw_reset_data_count

该函数用于清零已统计的流量。

  1. 声明

liot_nw_errcode_e liot_nw_reset_data_count(uint8_t nSim);

  1. 参数

nSim ：

[In] 所使用的(U)SIM 卡。若模块只支持 1 个(U)SIM 接口，此参数可设置为 0。

0  (U)SIM 卡 1

1  (U)SIM 卡 2

  1. 返回值

liot_nw_errcode_e：执行结果码，请参考第 3.1 章。

4.12 liot_nw_set_ctzu_switch

该函数用于设置基站时间同步开关，(保存并立即生效)。

  1. 声明

liot_nw_errcode_e liot_nw_set_ctzu_switch(bool onoff);

  1. 参数

[In] 开关时间同步。

[In]     0: 禁止， 1：使能

  1. 返回值

liot_nw_errcode_e：执行结果码，请参考第 3.1 章。

4.13 liot_nw_get_ctzu_switch

该函数用于获取基站时间同步开关状态。

  1. 声明

bool  liot_nw_get_ctzu_switch(void);

  1. 参数

[In] void

  1. 返回值

false    关闭。

true     打开。

5 代码示例

示例代码参考  examples/demo/src/demo_nw.c 文件。如下运行结果则说明获取所有信息正常：

_images/nw-guide/image_1.png