开关机¶

功能概述¶

本章全面介绍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¶

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

qosa_power_error_e qosa_power_down(qosa_powd_mode_e powd_mode)

参数说明

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

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

qosa_power_reset¶

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

qosa_power_error_e qosa_power_reset(qosa_reset_mode_e reset_mode)

参数说明

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

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

qosa_power_get_boot_cause¶

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

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¶

功能描述
获取电池充电状态、剩余电量百分比和电池电压。
函数原型

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 *	充电状态 0：未充电 1：充电中 2 ：充电完成
nBcl	输出	qosa_uint8_t *	剩余电量百分比（0~100）
vol	输出	qosa_uint32_t *	电池电压。单位：mV

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

qosa_get_pwrkey_level¶

功能描述
获取模块PWRKEY按键引脚的当前电平状态。
函数原型

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按键关机回调函数，当按键触发关机时会调用该回调。
函数原型

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按键事件回调函数类型，当按键状态变化时调用，传入当前按键电平。

typedef void (*qosa_pwrkey_callback)(qosa_uint8_t pinlevel)

枚举定义¶

qosa_powd_mode_e¶

关机模式枚举定义如下：

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¶

重启模式枚举定义如下：

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¶

开机原因枚举定义如下：

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¶

充电状态枚举定义如下：

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¶

错误码枚举定义如下：

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	参数无效

应用逻辑流程图¶

关机流程¶

../../_images/board_X6hawsU4ohRDwHba52jc2EvWn4b.jpg

重启流程¶

示例代码¶

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

开关机¶

功能概述¶

开关机API¶

头文件¶

函数概览¶

函数详解¶

qosa_power_down¶

qosa_power_reset¶

qosa_power_get_boot_cause¶

qosa_power_get_charger_status¶

qosa_get_pwrkey_level¶

qosa_pwrkey_callback_register¶

qosa_pwrkey_callback¶

枚举定义¶

qosa_powd_mode_e¶

qosa_reset_mode_e¶

qosa_boot_cause_e¶

qosa_charge_status_e¶

qosa_powd_mode_e¶

应用逻辑流程图¶

关机流程¶

重启流程¶

示例代码¶

目录

本页