# 一键网络诊断

***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卡状态、网络参数等，返回的诊断结果可为定位网络故障提供初步排查方向。

- **函数原型**

```cpp
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*](#qappnetworkdiagnosticsconfigt) |

- **返回值说明**  
  详见 [*qapp_nw_diagnostics_result*](#qappnwdiagnostics_result)

```{note}
1. 返回值中每个bit对应一种网络问题，对应位置1即表示该项存在异常。例如：*weak_signal* 事件位置1（值：0x02）代表当前RSRP/RSRQ低于设定阈值，判定为弱信号场景。
2. 此函数仅提供多指标状态筛查，输出异常标记，不提供完整根因定位与深度故障分析。
```

## 结构体定义

### qapp_network_diagnostics_config_t

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

```cpp
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

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

```c
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 | 诊断执行结果<br>*0*：函数执行成功<br>*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 | 预留 |

# 应用逻辑流程图

```{figure} images/board_H0tlwNWsahXrx9bTM6fct1D0nHg.jpg
:align: center
:alt: image
```

# 示例代码

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