一键网络诊断

Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.

---

功能概述

一键网络诊断功能内部集成多个网络接口，用于快速获取注网状态、SIM卡状态、网络参数等信息。接口返回的结果可为定位网络故障提供初步排查方向。

一键网络诊断API

头文件

easy_network_diagnostics.h

函数概览

函数	说明
qapp_easy_nw_diagnostics()	执行一键网络诊断

函数详解

qapp_easy_nw_diagnostics

• 功能描述
  执行一键网络诊断。此函数内部集成多个网络接口，用于获取注网状态、SIM卡状态、网络参数等，返回的诊断结果可为定位网络故障提供初步排查方向。

• 函数原型

qapp_nw_diagnostics_result qapp_easy_nw_diagnostics(qapp_network_diagnostics_config_t *config);

• 参数说明

参数名	输入/输出	类型	说明
config	输入	qapp_network_diagnostics_config_t	诊断阈值配置；详见 qapp_network_diagnostics_config_t

• 返回值说明
  详见 qapp_nw_diagnostics_result

备注

1. 返回值中每个bit对应一种网络问题，对应位置1即表示该项存在异常。例如：weak_signal 事件位置1（值：0x02）代表当前RSRP/RSRQ低于设定阈值，判定为弱信号场景。

2. 此函数仅提供多指标状态筛查，输出异常标记，不提供完整根因定位与深度故障分析。

结构体定义

qapp_network_diagnostics_config_t

诊断阈值配置结构体定义如下：

typedef struct
{
    qosa_uint8_t rsrp_threshold;                
    qosa_uint8_t rsrq_threshold;               
    qosa_uint8_t snr_threshold;               
    qosa_uint16_t ul_bler_threshold;           
    qosa_uint16_t dl_bler_threshold;         
}qapp_network_diagnostics_config_t;

参数	类型	说明
rsrp_threshold	qosa_uint8_t	RSRP信号强度阈值
rsrq_threshold	qosa_uint8_t	RSRQ信号质量阈值
snr_threshold	qosa_uint8_t	信噪比SNR阈值
ul_bler_threshold	qosa_uint16_t	上行BLER误码率阈值
dl_bler_threshold	qosa_uint16_t	下行BLER误码率阈值

qapp_nw_diagnostics_result

一键诊断结果结构体定义如下：

typedef struct
{
    qosa_uint8_t execute_result : 1;             
    qosa_uint8_t weak_signal : 1;              
    qosa_uint8_t poor_nw_resources : 1;       
    qosa_uint8_t high_bler : 1;              
    qosa_uint8_t cell_change: 1;              
    qosa_uint8_t low_bandwidth : 1;           
    qosa_uint8_t tx_power_abnormal : 1;     
    qosa_uint8_t no_dl_data : 1;              
    qosa_uint8_t simcard_not_ready : 1;         
    qosa_uint8_t rf_close : 1;                 
    qosa_uint8_t lock_oper : 1;               
    qosa_uint8_t lock_band : 1;               
    qosa_uint8_t lock_freq_or_cell : 1;      
    qosa_uint8_t no_available_cell : 1;        
    qosa_uint8_t rach_fail : 1;              
    qosa_uint8_t rrc_establish_fail : 1;      
    qosa_uint8_t dl_loss_sync : 1;            
    qosa_uint8_t esm_cause_event: 1;           
    qosa_uint8_t emm_cause_event: 1;           
    qosa_uint16_t reserve: 13;             
}qapp_nw_diagnostics_result;

参数	类型	说明
execute_result	qosa_uint8_t:1	诊断执行结果 0：函数执行成功 1：函数执行失败
weak_signal	qosa_uint8_t:1	信号弱
poor_nw_resources	qosa_uint8_t:1	网络资源不足
high_bler	qosa_uint8_t:1	上下行误码率偏高
cell_change	qosa_uint8_t:1	小区切换频繁
low_bandwidth	qosa_uint8_t:1	带宽低
tx_power_abnormal	qosa_uint8_t:1	发射功率异常
no_dl_data	qosa_uint8_t:1	无下行数据
simcard_not_ready	qosa_uint8_t:1	SIM卡未就绪
rf_close	qosa_uint8_t:1	射频通道关闭
lock_oper	qosa_uint8_t:1	运营商锁定
lock_band	qosa_uint8_t:1	频段锁定
lock_freq_or_cell	qosa_uint8_t:1	频点/小区锁定
no_available_cell	qosa_uint8_t:1	无可用服务小区
rach_fail	qosa_uint8_t:1	随机接入失败
rrc_establish_fail	qosa_uint8_t:1	RRC连接建立失败
dl_loss_sync	qosa_uint8_t:1	下行同步丢失
esm_cause_event	qosa_uint8_t:1	ESM异常事件
emm_cause_event	qosa_uint8_t:1	EMM异常事件
reserve	qosa_uint16_t:13	预留

应用逻辑流程图

示例代码

完整示例代码请查看 https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/application/one_touch/diagnostics.c