NW Development Guide_Rev1.3

中文

Revision History

Version	Date	Author	Revision Content
Rev1.0	2023-09-12	CLY	Initial document creation
Rev1.1	2024-03-25	sxx	Changed document name
Rev1.2	2024-10-25	LJZ	Modified document format
Rev1.3	2025-02-12	ZLC	Added liot_nw_set_ctzu_switch and liot_nw_get_ctzu_switch interfaces

1 Introduction

This document introduces the LTE-EC71X network registration information interface APIs. The API interfaces are declared in the file components/kernel/lierda_api/liot_nw/liot_nw.h.

2 API Function Overview

Function	Description
liot_nw_get_csq()	Query CSQ signal strength information
liot_nw_get_operator_name()	Get current registered operator information
liot_nw_get_reg_status()	Get current network registration information
liot_nw_set_selection()	Set operator
liot_nw_get_selection()	Get selected operator information
liot_nw_get_signal_strength()	Get detailed signal strength information
liot_nw_get_nitz_time_info()	Get current base station time
liot_nw_get_cell_info()	Get current serving and neighboring cell information
liot_nw_register_cb()	Register event callback function
liot_nw_get_data_count()	Get uplink and downlink data count
liot_nw_reset_data_count()	Reset uplink and downlink data count
liot_nw_set_ctzu_switch()	Set base station time synchronization switch
liot_nw_get_ctzu_switch()	Get base station time synchronization switch status

3 Type Descriptions

3.1 liot_nw_errcode_e

NW API execution result error codes.

• Definition

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;

• Parameters

• LIOT_NW_SUCCESS: Function executed successfully.

• LIOT_NW_EXECUTE_ERR: Function execution error.

• LIOT_NW_MEM_ADDR_NULL_ERR: Function parameter address is NULL.

• LIOT_NW_INVALID_PARAM_ERR: Function parameter is invalid.

• LIOT_NW_CFW_CFUN_GET_ERR: Failed to get functional mode.

• LIOT_NW_CFUN_DISABLE_ERR: Non-full functional mode, causing related information cannot be obtained.

• LIOT_NW_CFW_NW_STATUS_GET_ERR: Failed to get network status, causing related information cannot be obtained.

• LIOT_NW_NOT_SEARCHING_ERR: Operator to register not found, causing related information cannot be obtained.

• LIOT_NW_NOT_REGISTERED_ERR: Network not registered, causing related information cannot be obtained.

• LIOT_NW_CFW_GPRS_STATUS_GET_ERR: Failed to get PS domain network status.

• LIOT_GPRS_NOT_SEARCHING_ERR: PS domain operator to register not found.

• LIOT_GPRS_NOT_REGISTERED_ERR: Not registered to PS domain network.

• LIOT_NW_CFW_NW_QUAL_GET_ERR: Failed to get signal quality.

• LIOT_NW_CFW_OPER_ID_GET_ERR: Failed to get operator ID information.

• LIOT_NW_CFW_OPER_NAME_GET_ERR: Failed to get operator name.

• LIOT_NW_CFW_OPER_SET_ERR: Failed to set operator.

• LIOT_NW_SIM_ERR: (U)SIM card related error, causing information acquisition failure.

• LIOT_NW_NO_MEM_ERR: Memory allocation failed.

• LIOT_NW_SEMAPHORE_CREATE_ERR: Semaphore creation failed.

• LIOT_NW_SEMAPHORE_TIMEOUT_ERR: Semaphore wait timeout.

• LIOT_NW_NITZ_NOT_UPDATE_ERR: Network time not synchronized.

• LIOT_NW_CFW_EMOD_START_ERR: Failed to enter engineering mode, causing cell information acquisition failure.

• LIOT_NW_OPERATOR_NOT_ALLOWED: Operation not allowed.

• LIOT_NW_CFW_RRCRel_SET_ERR: RRCRel setting error.

3.2 liot_nw_act_type_e

Network registration type.

1. Definition

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;

2. Parameters

• LIOT_NW_ACCESS_TECH_GSM: 2G (GSM, not supported)

• LIOT_NW_ACCESS_TECH_GSM_COMPACT: 2G (GSM COMPACT, not supported)

• LIOT_NW_ACCESS_TECH_UTRAN: 3G (UTRAN, not supported)

• LIOT_NW_ACCESS_TECH_GSM_wEGPRS: 2G (EGPRS, not supported)

• LIOT_NW_ACCESS_TECH_UTRAN_wHSDPA: 3G (HSDPA, not supported)

• LIOT_NW_ACCESS_TECH_UTRAN_wHSUPA: 3G (HSUPA, not supported)

• LIOT_NW_ACCESS_TECH_UTRAN_wHSDPA_HSUPA: 3G (HSDPA and HSUPA, not supported)

• LIOT_NW_ACCESS_TECH_E_UTRAN: 4G (E-UTRAN)

3.3 liot_nw_reg_state_e

Network registration state.

1. Definition

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;

2. Parameters

• LIOT_NW_REG_STATE_NOT_REGISTERED: Not registered, MT currently not searching for operator to register to.

• LIOT_NW_REG_STATE_HOME_NETWORK: Registered, home network.

• LIOT_NW_REG_STATE_TRYING_ATTACH_OR_SEARCHING: Not registered, MT currently trying to register or searching for operator to register.

• LIOT_NW_REG_STATE_DENIED: Registration denied.

• LIOT_NW_REG_STATE_UNKNOWN: Unknown state.

• LIOT_NW_REG_STATE_ROAMING: Registered, roaming state.

4 API Function Details

4.1 liot_nw_get_csq

This function is used to get network signal quality information.

1. Declaration

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

2. Parameters

nSim:

[In] (U)SIM card used. If module only supports 1 (U)SIM interface, this parameter can be set to 0.

0 (U)SIM card 1

1 (U)SIM card 2

csq:

[Out] Return network signal quality information. Range: 0 ~ 31. Return 99 indicates invalid value.

3. Return Value

liot_nw_errcode_e: Execution result code, please refer to section 3.1 liot_nw_errcode_e.

4.2 liot_nw_get_operator_name

Get operator name.

1. Declaration

liot_nw_errcode_e liot_nw_get_operator_name(uint8_t nSim, liot_nw_operator_info_s *oper_info);

2. Parameters

nSim:

[In] (U)SIM card used. If module only supports 1 (U)SIM interface, this parameter can be set to 0.

0 (U)SIM card 1

1 (U)SIM card 2

oper_info:

[Out] Return operator information. See section 5.2.1 for details.

3. Return Value

liot_nw_errcode_e: Execution result code, please refer to section 3.1 liot_nw_errcode_e.

4.2.1 liot_nw_operator_info_s

1. Operator information structure definition

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;

2. Parameters

Type	Parameter	Description
char	long_oper_name	Full operator name, length不超过32 bytes
char	short_oper_name	Short operator name, length不超过32 bytes
char	mcc	Mobile Country Code, length不超过3 bytes
char	mnc	Mobile Network Code, length不超过3 bytes

4.3 liot_nw_get_reg_status

Get current network registration information.

1. Declaration

liot_nw_errcode_e liot_nw_get_reg_status(uint8_t nSim, liot_nw_reg_status_info_s *reg_info);

2. Parameters

nSim:

[In] (U)SIM card used. If module only supports 1 (U)SIM interface, this parameter can be set to 0.

0 (U)SIM card 1

1 (U)SIM card 2

reg_info:

[Out] Return registration information. See section 5.3.1 for details.

3. Return Value

liot_nw_errcode_e: Execution result code, please refer to section 3.1 liot_nw_errcode_e.

4.3.1 liot_nw_reg_status_info_s

1. Network registration information structure definition

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. Network registration information structure definition

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;

2. Parameters

Type	Parameter	Description
liot_nw_reg_state_e	state	Network registration state; see section 4.3
int	lac	Location Area Code
int	cid	Cell Global Identity
liot_nw_act_type_e	act	Network registration standard; see section 4.2

4.4 liot_nw_set_selection

This function is used to select operator.

1. Declaration

liot_nw_errcode_e liot_nw_set_selection(uint8_t nSim, liot_nw_seclection_info_s *select_info);

2. Parameters

nSim:

[In] (U)SIM card used. If module only supports 1 (U)SIM interface, this parameter can be set to 0.

0 (U)SIM card 1

1 (U)SIM card 2

select_info:

[Out] Selected operator information. See section 5.4.1 liot_nw_seclection_info_s for details.

3. Return Value

liot_nw_errcode_e: Execution result code, please refer to section 3.1 liot_nw_errcode_e.

4.4.1 liot_nw_seclection_info_s

1. Selected operator information structure definition

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;

2. Parameters

Type	Parameter	Description
unsigned char	nw_selection_mode	Operator selection method. 0 Modem auto select, MCC and MNC invalid 1 Manual select
char	mcc	Mobile Country Code
char	mnc	Mobile Network Code
liot_nw_act_type_e	act	Network registration standard; see section 4.2

4.5 liot_nw_get_selection

Get selected operator information, need to wait for successful network registration.

1. Declaration

liot_nw_errcode_e liot_nw_get_selection(uint8_t nSim, liot_nw_seclection_info_s *select_info);

2. Parameters

nSim:

[In] (U)SIM card used. If module only supports 1 (U)SIM interface, this parameter can be set to 0.

0 (U)SIM card 1

1 (U)SIM card 2

select_info:

[Out] Selected operator information. Please refer to section 3.1 liot_nw_errcode_e.

4.6 liot_nw_get_signal_strength

Get detailed signal strength information.

1. Declaration

liot_nw_errcode_e liot_nw_get_signal_strength(uint8_t nSim, liot_nw_signal_strength_info_s *pt_info);

2. Parameters

nSim:

[In] (U)SIM card used. If module only supports 1 (U)SIM interface, this parameter can be set to 0.

0 (U)SIM card 1

1 (U)SIM card 2

pt_info:

[Out] Get detailed signal strength information. See section 5.6.1 for details.

4.6.1 liot_nw_signal_strength_info_s

1. Detailed signal strength information structure definition

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;

2. Parameters

Type	Parameter	Description
int	rssi	Received Signal Strength Indicator, range 0-31, 99 indicates invalid value. Formula: rssi_dBm = 2 × rssi - 113
int	bitErrorRate	Channel Bit Error Rate, only valid during call, 99 indicates invalid value
int	rsrq	Reference Signal Received Quality, range 0-34, 255 indicates invalid value. Step 0.5dB, formula: rsrq_dB = rsrq × 0.5 - 20 (0: <-19.5dB, 34: >=-3dB)
int	rsrp	Reference Signal Received Power, range 0-97, 255 indicates invalid value. Step 1dBm, formula: rsrp_dBm = rsrp - 141 (0: <-140dBm, 97: >=-44dBm)
int	snr	Signal-to-Noise Ratio, value range: -20 ~ 40 dB

4.7 liot_nw_get_nitz_time_info

Get current base station time, this time is only updated at the moment of successful network registration, requires local network support.

1. Declaration

liot_nw_errcode_e liot_nw_get_nitz_time_info(liot_nw_nitz_time_info_s *nitz_info);

2. Parameters

nitz_info:

[Out] Time information obtained from base station. See section 5.7.1 liot_nw_nitz_time_info_s for details.

4.7.1 liot_nw_nitz_time_info_s

1. Base station time information structure definition

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;

2. Parameters

Type	Parameter	Description
char	nitz_time	Local time. Format: YY/MM/DD HH:MM:SS '+/-'TZ DST TZ: Local timezone (displays difference between local time and GMT time in 15-minute units) DST: Daylight Saving Time adjustment Example: 20/10/21 09:17:43 +32 00
long	abs_time	Total seconds from 1970-1-1, 00:00:00 (UTC time) to now. 0 indicates unavailable

4.8 liot_nw_get_cell_info

Get current serving and neighboring cell information.

1. Declaration

liot_nw_errcode_e liot_nw_get_cell_info(uint8_t nSim, liot_nw_cell_info_s *cell_info);

2. Parameters

nSim:

[In] (U)SIM card used. If module only supports 1 (U)SIM interface, this parameter can be set to 0.

0 (U)SIM card 1

1 (U)SIM card 2

cell_info:

[Out] Return current serving and neighboring cell information. Please refer to liot_nw_cell_info_s.

3. Return Value

liot_nw_errcode_e: Execution result code, please refer to section 3.1 liot_nw_errcode_e.

4.8.1 liot_nw_cell_info_s

1. Return current serving and neighboring cell information structure definition

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;

2. Parameters

Type	Parameter	Description
int	lte_info_valid	Whether LTE standard cell information is available. 0 Unavailable 1 Available
int	lte_info_num	Number of cells obtained in LTE standard
liot_nw_lte_cell_info_s	lte_info	List of cell information obtained in LTE standard

4.8.2 liot_nw_lte_cell_info_s

1. LTE standard cell information list structure definition

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;

2. Parameters

Type	Parameter	Description
int	flag	Cell category. 0 Serving cell 1 Inter-frequency neighboring cell
int	cid	Cell Global Identity; 0 indicates Cell Global Identity not received
int	mcc	Mobile Country Code
int	mnc	Mobile Network Code
int	tac	Tracking Area Code
int	pci	Physical Cell Identity
int	earfcn	E-UTRA Absolute Radio Frequency Channel Number; range: 0 ~ 65535
int	rssi	Received Signal Strength Indicator; unit: dBm
char	mnc_len	Mobile Network Code length
char	RX_dBm	Received power; unit: dBm

4.9 liot_nw_register_cb

This function is used for related callback handling during network registration process.

1. Declaration

liot_nw_errcode_e liot_nw_register_cb(liot_nw_callback nw_cb);

2. Parameters

nw_cb:

[In] Network registration information event callback function; if this parameter is NULL, it means this thread cancels registration of network registration information callback function.

3. Return Value

liot_nw_errcode_e: Execution result code, please refer to section 3.1 liot_nw_errcode_e.

4.9.1 liot_nw_callback

This function is mobile network event callback function.

1. Declaration

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

2. Parameters

nSim:

[In] (U)SIM card used. If module only supports 1 (U)SIM interface, this parameter can be set to 0.

0 (U)SIM card 1

1 (U)SIM card 2

ind_type:

[In] Mobile network event type.

LIOT_NW_SIGNAL_QUALITY_IND Signal strength event

LIOT_NW_DATA_REG_STATUS_IND Data dial-up event

LIOT_NW_NITZ_TIME_UPDATE_IND Network time update event

ctx:

[In] Information data corresponding to the event.

3. Return Value

None.

4.10 liot_nw_get_data_count

This function is used to query traffic consumed by uplink and downlink.

1. Declaration

liot_nw_errcode_e liot_nw_get_data_count(uint8_t nSim, liot_nw_data_count_info_s *data_info);

2. Parameters

nSim:

[In] (U)SIM card used. If module only supports 1 (U)SIM interface, this parameter can be set to 0.

0 (U)SIM card 1

1 (U)SIM card 2

data_info:

[Out] Traffic statistics information. See liot_nw_data_count_info_s for details.

3. Return Value

liot_nw_errcode_e: Execution result code, please refer to section 3.1 liot_nw_errcode_e.

4.10.1 liot_nw_data_count_info_s

1. Selected operator information structure definition

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

2. Parameters

Type	Parameter	Description
UINT64	uplink_data_count	Traffic consumed by uplink; unit: bytes
UINT64	downlink_data_count	Traffic consumed by downlink; unit: bytes

4.11 liot_nw_reset_data_count

This function is used to clear counted traffic.

1. Declaration

liot_nw_errcode_e liot_nw_reset_data_count(uint8_t nSim);

2. Parameters

nSim:

[In] (U)SIM card used. If module only supports 1 (U)SIM interface, this parameter can be set to 0.

0 (U)SIM card 1

1 (U)SIM card 2

3. Return Value

4.12 liot_nw_set_ctzu_switch

This function is used to set the base station time synchronization switch (save and take effect immediately).

1. Declaration

liot_nw_errcode_e liot_nw_set_ctzu_switch(bool onoff);

2. Parameters

[In] Switch time synchronization.

[In] 0: Disable, 1: Enable

3. Return Value

liot_nw_errcode_e: Execution result code, please refer to section 3.1.

4.13 liot_nw_get_ctzu_switch

This function is used to get the base station time synchronization switch status.

1. Declaration

bool  liot_nw_get_ctzu_switch(void);

2. Parameters

[In] void

3. Return Value

    false    Closed.
   

true Opened.

5 Code Example

Sample code reference: examples/demo/src/demo_nw.c file. The following running result indicates that all information has been obtained normally: