# 开关机

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

---

# 功能概述

本章全面介绍Quectel OSA电源管理模块的功能特性、API使用方法及典型应用示例，旨在帮助开发者快速掌握电源管理能力的集成与调试，确保设备在各种电源工况下稳定可靠运行。

在蜂窝物联网设备（如Tracker、工业网关、智能表计）的实际部署中，电源相关问题是运维阶段的高发痛点——设备无法正常启动、运行中异常自动关机、电池续航骤降等现象屡见不鲜。这些问题往往源于开机原因不明、低电量处理不当、充电状态监控缺失或复位策略不完善。Quectel OSA电源管理模块正是为解决这些棘手问题而设计，它提供了一套统一且易用的接口，使开发者能够：

- 获取开机原因：区分是按键开机、硬件看门狗复位、深度唤醒、还是异常掉电重上电，帮助快速定位启动阶段故障；

- 控制设备关机与重启：支持软件关机和软复位，并可在重启前保存关键现场日志，便于事后分析；

- 实时查询充电状态与电池电量：包括充电进行中、充电完成、电池电压/百分比等，为低电量预警和充电策略提供依据；

- 监控电源事件：如外部供电插拔、电池过温、欠压等，让应用程序能够提前采取降频、休眠或告警等保护动作。

典型高频应用场景包括：

- 设备无法启动时：通过读取开机原因寄存器，判断是否为异常复位（如看门狗超时），若为异常则上传复位日志至云端，避免反复重启死循环；

- 设备自动关机后：在下次上电时查询上次关机原因（如低电压保护或过热），据此调整下一次运行功耗策略，或向平台上报关机事件；

- 电池供电产品中：结合充电状态和电量值，动态控制网络连接间隔和GPS定位频率，延长有效工作时间。

后续章节将对各API的入参、返回值及错误码进行详细说明，并附带完整的代码示例。同时，我们还将总结常见电源异常现象的诊断思路及应对方案，帮助您提前规避现场故障，提升产品的鲁棒性。

# 开关机API

## 头文件

*qosa_power.h*

## 函数概览

| **函数** | **说明** |
| --- | --- |
| *qosa_power_down()* | 控制模块关机 |
| *qosa_power_reset()* | 控制模块重启 |
| *qosa_power_get_boot_cause()* | 获取开机原因 |
| *qosa_power_get_charger_status()* | 获取充电状态和电量 |
| *qosa_get_pwrkey_level()* | 获取PWRKEY引脚电平 |
| *qosa_pwrkey_callback_register()* | 注册PWRKEY按键关机回调 |
| *qosa_pwrkey_callback()* | PWRKEY按键事件回调函数 |

## 函数详解

### qosa_power_down

- **功能描述**  
  控制模块执行关机操作，支持正常关机和快速关机两种模式。

- **函数原型**

```c
qosa_power_error_e qosa_power_down(qosa_powd_mode_e powd_mode)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *powd_mode* | 输入 | *qosa_powd_mode_e* | 关机模式<br>*QOSA_POWD_NORMAL*：正常关机<br>*QOSA_POWD_IMMDLY*：快速关机 |

- **返回值说明**  
  *QOSA_POWER_SUCCESS*：函数执行成功  
  *QOSA_POWER_GENERAL*：函数执行失败

### qosa_power_reset

- **功能描述**  
  控制模块执行重启操作，支持正常重启、快速重启、FOTA重启、不安全重启四种模式 **。**

- **函数原型**

```c
qosa_power_error_e qosa_power_reset(qosa_reset_mode_e reset_mode)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *reset_mode* | 输入 | *qosa_reset_mode_e* | 重启模式<br>*QOSA_RESET_NORMAL*：正常重启<br>*QOSA_RESET_QUICK*：快速重启<br>*QOSA_RESET_FOTA*：FOTA 升级后重启<br>*QOSA_RESET_UNSAFETY*：不安全强制重启 |

- **返回值说明**  
  *QOSA_POWER_SUCCESS*：函数执行成功  
  *QOSA_POWER_GENERAL*：函数执行失败

### qosa_power_get_boot_cause

- **功能描述**  
  获取模块本次的开机原因（如按键开机、RTC闹钟开机、充电开机等）。

- **函数原型**

```c
qosa_power_error_e qosa_power_get_boot_cause(qosa_boot_cause_e *boot_cause)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *boot_cause* | 输出 | qosa_boot_cause_e* | 输出参数，指向开机原因枚举的指针 |

- **返回值说明**  
  始终返回 *QOSA_POWER_SUCCESS*：函数执行成功

### qosa_power_get_charger_status

- **功能描述**  
  获取电池充电状态、剩余电量百分比和电池电压。

- **函数原型**

```c
qosa_power_error_e qosa_power_get_charger_status(qosa_charge_status_e *nBcs, qosa_uint8_t *nBcl, qosa_uint32_t *vol)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *nBcs* | 输出 | qosa_charge_status_e * | 充电状态<br>*0*：未充电<br>*1*：充电中<br>2 *：* 充电完成 |
| *nBcl* | 输出 | qosa_uint8_t * | 剩余电量百分比（0~100） |
| *vol* | 输出 | qosa_uint32_t * | 电池电压。单位：mV |

- **返回值说明**  
  始终返回 *QOSA_POWER_SUCCESS*：函数执行成功

### qosa_get_pwrkey_level

- **功能描述**  
  获取模块PWRKEY按键引脚的当前电平状态。

- **函数原型**

```c
qosa_power_error_e qosa_get_pwrkey_level(qosa_uint8_t *pwrkey_level)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *pwrkey_level* | 输出 | qosa_uint8_t* | PWRKEY引脚电平值 |

- **返回值说明**  
  *QOSA_POWER_SUCCESS：函数执行成功*  
  *QOSA_POWER_INVALID_PARAM*：参数为NULL

### qosa_pwrkey_callback_register

- **功能描述**  
  注册PWRKEY按键关机回调函数，当按键触发关机时会调用该回调。

- **函数原型**

```c
qosa_power_error_e qosa_pwrkey_callback_register(qosa_pwrkey_callback pwrkey_cb)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *pwrkey_cb* | 输入 | qosa_pwrkey_callback | 回调函数指针，无参数无返回值 |

- **返回值说明**  
  *QOSA_POWER_SUCCESS*：函数执行成功  
  *QOSA_POWER_INVALID_PARAM*：回调函数指针为NULL

### qosa_pwrkey_callback

回调函数类型定义如下：

- **功能描述**  
  PWRKEY按键事件回调函数类型，当按键状态变化时调用，传入当前按键电平。

```c
typedef void (*qosa_pwrkey_callback)(qosa_uint8_t pinlevel)
```

## 枚举定义

### qosa_powd_mode_e

关机模式枚举定义如下：

```c
typedef enum{    
    QOSA_POWD_IMMDLY = 0,   
    QOSA_POWD_NORMAL,     
    QOSA_POWD_INVALID     
} qosa_powd_mode_e;
```

| **成员** | **说明** |
| --- | --- |
| *QOSA_POWD_IMMDLY* | 快速关机模式：不注销网络，直接关机 |
| *QOSA_POWD_NORMAL* | 正常关机模式：先注销网络，再关机 |
| *QOSA_POWD_INVALID* | 无效关机模式 |

### qosa_reset_mode_e

重启模式枚举定义如下：

```c
typedef enum{    
    QOSA_RESET_QUICK = 0,     /*!< 快速重启：不注销网络，不等待 FLASH 操作完成 */             
    QOSA_RESET_NORMAL,        /*!< 正常重启：注销网络并等待 FLASH 操作完成 */                 
    QOSA_RESET_FOTA,          /*!< FOTA 重启：固件升级后重启 */    
    QOSA_RESET_UNSAFETY,      /*!< 不安全重启：立即复位，不保证数据完整性 */    
    QOSA_RESET_INVALID        /*!< 无效重启模式 */
} qosa_reset_mode_e;
```

| **成员** | **说明** |
| --- | --- |
| *QOSA_RESET_QUICK* | 快速重启：不注销网络，不等待FLASH操作完成 |
| *QOSA_RESET_NORMAL* | 正常重启：注销网络并等待FLASH操作完成 |
| *QOSA_RESET_FOTA* | FOTA重启：固件升级后重启 |
| *QOSA_RESET_UNSAFETY* | 不安全重启：立即复位，不保证数据完整性 |
| *QOSA_RESET_INVALID* | 无效重启模式 |

### qosa_boot_cause_e

开机原因枚举定义如下：

```c
typedef enum{    
    QOSA_BOOT_CAUSE_UNKNOWN = 0,   /*!< 未知原因开机 */    
    QOSA_BOOT_CAUSE_PSM_WAKE,      /*!< 深睡眠/PSM 睡眠唤醒开机 */    
    QOSA_BOOT_CAUSE_PWRKEY,        /*!< PWRKEY 按键开机 */    
    QOSA_BOOT_CAUSE_RESET,         /*!< RESET 按键复位开机 */    
    QOSA_BOOT_CAUSE_WDG,           /*!< 看门狗复位开机 */    
    QOSA_BOOT_CAUSE_PANIC,         /*!< 系统异常崩溃复位开机 */    
    QOSA_BOOT_CAUSE_SWRESET,       /*!< 软件主动复位开机 */    
    QOSA_BOOT_CAUSE_FOTA,          /*!< FOTA 流程复位开机 */    
    QOSA_BOOT_CAUSE_INVALID        /*!< 无效开机原因 */
} qosa_boot_cause_e;
```

| **成员** | **说明** |
| --- | --- |
| *QOSA_BOOT_CAUSE_UNKNOWN* | 未知原因开机 |
| *QOSA_BOOT_CAUSE_PSM_WAKE* | 深睡眠/PSM睡眠唤醒开机 |
| *QOSA_BOOT_CAUSE_PWRKEY* | PWRKEY按键开机 |
| *QOSA_BOOT_CAUSE_RESET* | RESET按键复位开机 |
| *QOSA_BOOT_CAUSE_WDG* | 看门狗复位开机 |
| *QOSA_BOOT_CAUSE_PANIC* | 系统异常崩溃复位开机 |
| *QOSA_BOOT_CAUSE_SWRESET* | 软件主动复位开机 |
| *QOSA_BOOT_CAUSE_FOTA* | FOTA流程复位开机 |
| *QOSA_BOOT_CAUSE_INVALID* | 无效开机原因 |

### qosa_charge_status_e

充电状态枚举定义如下：

```c
typedef enum{    
    QOSA_CHARGE_IDEL = 0,   /*!< 未充电状态 */    
    QOSA_CHARGE_ING,        /*!< 正在充电 */    
    QOSA_CHARGE_STOP        /*!< 充电完成 */
} qosa_charge_status_e;
```

| **成员** | **说明** |
| --- | --- |
| *QOSA_CHARGE_IDEL* | 未充电状态 |
| *QOSA_CHARGE_ING* | 正在充电 |
| *QOSA_CHARGE_STOP* | 充电完成 |

### qosa_powd_mode_e

错误码枚举定义如下：

```c
typedef enum{    
    QOSA_POWER_SUCCESS = 0,                                   
    QOSA_POWER_GENERAL = 1 | (QOSA_COMPONENT_POWER << 16),    
    QOSA_POWER_INVALID_PARAM,                               
} qosa_power_error_e;
```

| **成员** | **说明** |
| --- | --- |
| *QOSA_POWER_SUCCESS* | 操作成功 |
| *QOSA_POWER_GENERAL* | 通用错误 |
| *QOSA_POWER_INVALID_PARAM* | 参数无效 |

# 应用逻辑流程图

## 关机流程

```{image} images/board_X6hawsU4ohRDwHba52jc2EvWn4b.jpg
:width: 691px
:height: 950px
:align: center
```

## 重启流程

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

# 示例代码

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