2025-11-14

通用 API 开发指南

简介

Quectel FCM242D 和 FGM842D 系列模块支持 QuecOpen® 解决方案。QuecOpen® 是基于 RTOS 系统的嵌入式开发平台。它旨在简化物联网应用的开发和设计。有关 QuecOpen® 的更多信息，请参见 快速入门指南。

本文档适用于基于 SDK 构建环境的 QuecOpen® 解决方案。本文档概述了 Quectel FCM242D 和 FGM842D 系列模块 SDK 中提供的 flash API、SPI flash API、timer API、watchdog API 和低功耗模式 API，以及 QuecOpen® 解决方案中的开发过程。

Flash

Flash API

头文件

ql_flash.h，flash API 的头文件，在 ql_components/api 目录中。除非另有说明，本文档中提到的所有头文件都在此目录中。

API 概述

函数	描述
`ql_flash_security()`	设置 flash 保护类型。
`ql_flash_write_bytes()`	向 flash 写入数据。
`ql_flash_read_bytes()`	从 flash 读取数据。
`ql_flash_erase()`	从 flash 擦除数据。
`ql_flash_partition_erase()`	从 flash 中的指定分区擦除数据。
`ql_flash_partition_write()`	向 flash 中的指定分区写入数据。
`ql_flash_partition_read()`	从 flash 中的指定分区读取数据。
`ql_flash_partition_get_info()`	获取当前 flash 分区的信息。

API 描述

ql_flash_security

此函数设置 flash 保护类型。在写入或删除数据之前需要启用 flash 保护。

原型：

ql_flash_errcode_e ql_flash_security(ql_flash_protect_type_e type)

参数：

type: [入] Flash 保护类型。有关详细信息，请参见 ql_flash_protect_type_e。

返回值：

有关结果代码，请参见 ql_flash_errcode_e。

ql_flash_protect_type_e

flash 保护类型的枚举：

typedef enum {
  QL_FLASH_PROTECT_NONE = 0,
  QL_FLASH_PROTECT_ALL,
  QL_FLASH_PROTECT_HALF,
  QL_FLASH_UNPROTECT_LAST_BLOCK,
} ql_flash_protect_type_e;

成员	描述
QL_FLASH_PROTECT_NONE	无保护
QL_FLASH_PROTECT_ALL	保护整个 flash
QL_FLASH_PROTECT_HALF	保护一半 flash
QL_FLASH_UNPROTECT_LAST_BLOCK	保护 flash 除最后一个块之外的部分

ql_flash_errcode_e

结果代码的枚举：

typedef enum {
  QL_FLASH_SUCCESS = 0,
  QL_FLASH_EXECUTE_ERR,
  QL_FLASH_PARAM_ERROR,
} ql_flash_errcode_e;

成员	描述
QL_FLASH_SUCCESS	执行成功
QL_FLASH_EXECUTE_ERR	执行失败
QL_FLASH_PARAM_ERROR	参数无效

ql_flash_write_bytes

此函数向 flash 写入数据。

原型：

ql_flash_errcode_e ql_flash_write_bytes(const uint8 *data, uint32 addr, uint32 size)

参数：

data: [入] 要写入的数据。
addr: [入] 要写入数据的地址。
size: [入] 要写入数据的长度。单位：字节。

返回值：

有关结果代码，请参见 ql_flash_errcode_e。

ql_flash_read_bytes

此函数从 flash 读取数据。

原型：

ql_flash_errcode_e ql_flash_read_bytes(uint8 *data, uint32 addr, uint32 size)

参数：

data: [出] 用于存储读取数据的缓冲区。
addr: [入] 要读取数据的地址。
size: [入] 要读取数据的长度。单位：字节。

返回值：

有关结果代码，请参见 ql_flash_errcode_e。

ql_flash_erase

此函数从 flash 擦除数据。每次至少擦除一个扇区（4 KB），每次擦除的数据大小是扇区大小的整数倍。

原型：

ql_flash_errcode_e ql_flash_erase(uint32 addr, uint32 size)

参数：

addr: [入] 要擦除数据的地址。该地址长度必须是扇区大小的整数倍。
size: [入] 要擦除数据的长度。是 4096 的整数倍。单位：字节。

返回值：

有关结果代码，请参见 ql_flash_errcode_e。

ql_flash_partition_erase

此函数从 flash 中的指定分区擦除数据。

原型：

ql_flash_errcode_e ql_flash_partition_erase(ql_partition_e inPartition, uint32 off_set, uint32 size)

参数：

inPartition: [入] 要擦除数据的分区。有关详细信息，请参见 *第 2.1.3.5.1* 章。
off_set: [入] 分区中要擦除数据的起始偏移地址。
size: [入] 要擦除数据的长度。单位：字节。

返回值：

有关结果代码，请参见 ql_flash_errcode_e。

ql_partition_e

flash 分区的枚举：

typedef enum {
  QL_PARTITION_BOOTLOADER = 0,
  QL_PARTITION_APPLICATION,
  QL_PARTITION_OTA,
  QL_PARTITION_RF_FIRMWARE,
  QL_PARTITION_NET_PARAM,
  QL_PARTITION_FAST_CONNECT,
  QL_PARTITION_SN_CONFIG,
  #ifdef QL_CSDK_SUPPORT
    #if (QL_CSDK_MODE == 2)
        QL_PARTITION_CUSTOM_APP,
        QL_PARTITION_FS,
    #else
      QL_PARTITION_FS,
      QL_PARTITION_EASY_FLASH,
      QL_PARTITION_BLE_BONDING_FLASH,
    #endif
  #endif
  QL_PARTITION_USR_RESERVE,
  QL_PARTITION_MAX,
} ql_partition_e;

成员	描述
QL_PARTITION_BOOTLOADER	Bootloader 分区
QL_PARTITION_APPLICATION	App 分区
QL_PARTITION_OTA	OTA 分区
QL_PARTITION_RF_FIRMWARE	RF 分区
QL_PARTITION_NET_PARAM	网络分区
QL_PARTITION_FAST_CONNECT	Wi-Fi 快速连接信息分区
QL_PARTITION_SN_CONFIG	SN 存储分区
QL_PARTITION_CUSTOM_APP	用户 App 分区
QL_PARTITION_FS	文件系统分区
QL_PARTITION_EASY_FLASH	Easy Flash 分区
QL_PARTITION_BLE_BONDING_FLASH	BLE 分区
QL_PARTITION_USR_RESERVE	用户配置保留分区
QL_PARTITION_MAX	Flash 分区数量

ql_flash_partition_write

此函数向 flash 中的指定分区写入数据。

原型：

ql_flash_errcode_e ql_flash_partition_write(ql_partition_e inPartition, volatile uint32 off_set, uint8 *inBuffer, uint32 inBufferLength)

参数：

inPartition: [入] 要写入数据的分区。有关详细信息，请参见 操作过程。
off_set: [入] 分区中要写入数据的偏移量。
inBuffer: [入] 存储要写入数据的缓冲区。
inBufferLength: [入] 要写入数据的长度。单位：字节。

返回值：

有关结果代码，请参见 ql_flash_errcode_e。

ql_flash_partition_read

此函数从 flash 中的指定分区读取数据。

原型：

ql_flash_errcode_e ql_flash_partition_read(ql_partition_e inPartition, volatile uint32 off_set, uint8 *outBuffer, uint32 inBufferLength)

参数：

inPartition: [入] 要读取数据的分区。有关详细信息，请参见 ql_partition_e。
off_set: [入] 分区中要读取数据的偏移量。
outBuffer: [出] 存储读取数据的缓冲区。
inBufferLength: [入] 要读取数据的长度。单位：字节。

返回值：

有关结果代码，请参见 ql_flash_errcode_e。

ql_flash_partition_get_info

此函数获取当前 flash 分区的详细信息。

原型：

ql_logic_partition_info_t *ql_flash_partition_get_info(ql_partition_e partition)

参数：

partition: [入] 要获取详细信息的分区。有关详细信息，请参见 ql_partition_e。

返回值：

有关分区信息，请参见 ql_logic_partition_info_t。

ql_logic_partition_info_t

flash 分区信息的结构：

typedef struct {
  ql_flash_type_e partition_owner;
  const char *partition_description;
  uint32_t partition_start_addr;
  uint32_t partition_length;
  uint32_t partition_options;
} ql_logic_partition_info_t;

类型	参数	描述
`ql_flash_type_e`	partition_owner	Flash 类型。有关详细信息，请参见 ql_flash_type_e。
const char	partition_description	Flash 描述
uint32_t	partition_start_addr	分区起始地址
uint32_t	partition_length	分区长度。单位：字节
uint32_t	partition_options	分区选项

ql_flash_type_e

flash 类型的枚举：

typedef enum {
  QL_FLASH_EMBEDDED = 0,
  QL_FLASH_SPI,
  QL_FLASH_MAX,
  QL_FLASH_NONE
} ql_flash_type_e;

成员	描述
QL_FLASH_EMBEDDED	嵌入式 flash
QL_FLASH_SPI	SPI 连接的 flash
QL_FLASH_NONE	无 flash
QL_FLASH_MAX	Flash 数量

开发过程

本章描述如何在应用程序中使用 flash API 以及如何调试基本功能。

操作过程

模块 SDK 中提供了操作 flash 的示例。演示在 ql_application/example/flash_demo/ 目录下的 ql_flash_demo.c 中。相关函数的描述如下：

启用 CFG_ENABLE_QUECTEL_FLASH 宏来运行演示，并自动调用 ql_flash_demo_thread_creat() 创建测试任务。

ql_flash_demo_thread_creat()：此函数创建 flash 任务，需要调用以运行演示。
ql_flash_demo_thread()：任务执行函数，向 flash 写入数据，从 flash 读取和擦除数据。

创建 Flash 任务

使用 Flash API（示例 1）

使用 Flash API（示例 2）

函数调试

要调试 flash 函数，使用安装了模块的评估板（例如，FCM242D-TE-B），并按照以下步骤操作：

运行 操作过程 中描述的 flash 演示。
重新编译固件版本，并将其烧录到模块。
重启模块。
将波特率设置为 921600 bps 并打开 UART 2 端口以获取日志信息。

向 flash 写入数据的串口日志示例

从 flash 读取数据的串口日志示例

从 flash 擦除数据的串口日志示例

上述图中的日志数据显示，向 flash 写入数据、从 flash 读取数据以及从 flash 擦除数据都成功。

SPI Flash

SPI Flash API

头文件

ql_spi_flash.h，SPI flash API 的头文件，在 ql_components/api/ 目录中。除非另有说明，本文档中提到的所有头文件都在此目录中。

API 概述

函数	描述
`ql_spi_flash_get_info()`	获取 flash 信息。
`ql_spi_flash_enable()`	启用或禁用 flash。
`ql_spi_flash_read()`	直接从 flash 读取数据而不初始化 SPI。
`ql_spi_flash_write()`	直接向 flash 写入数据而不初始化 SPI。
`ql_spi_flash_erase_chip()`	从 flash 擦除数据。

API 描述

ql_spi_flash_get_info

此函数获取 flash 信息。

原型：

ql_spi_flash_errcode_e ql_spi_flash_get_info(ql_spi_flash_info_t *flash_info)

参数：

flash_info: [出] Flash 信息。有关详细信息，请参见 ql_spi_flash_info_t。

返回值：

有关结果代码，请参见 ql_spi_flash_errcode_e。

ql_spi_flash_info_t

SPI flash 信息的结构：

typedef struct _ql_spi_flash_info_t {
  char *type_name;
  enum_flash_driver_e driver_type;
  uint32_t id;
  uint32_t page_size;
  uint32_t sector_size;
  uint32_t block_size;
  uint32_t capacity;
} ql_spi_flash_info_t;

类型	参数	描述
char	type_name	Flash 类型
`enum_flash_driver_e`	driver_type	Flash 通信方法。有关详细信息，请参见 enum_flash_driver_e
uint32_t	id	Flash ID
uint32_t	page_size	页面大小
uint32_t	sector_size	扇区大小
uint32_t	block_size	块大小
uint32_t	capacity	容量

ql_spi_flash_errcode_e

结果代码的枚举：

typedef enum {
  QL_SPI_FLASH_SUCCESS = 0,
  QL_SPI_FLASH_EXECUTE_ERR,
  QL_SPI_FLASH_PARAM_ERROR,
} ql_spi_flash_errcode_e;

成员	描述
QL_SPI_FLASH_SUCCESS	执行成功
QL_SPI_FLASH_EXECUTE_ERR	执行失败
QL_SPI_FLASH_PARAM_ERROR	参数无效

enum_flash_driver_e

flash 通信方法的枚举：

typedef enum_flash_driver_e {
  DRIVER_SPI = 0,
  DRIVER_QSPI,
} ql_spi_flash_driver_e;

成员	描述
DRIVER_SPI	SPI 通信
DRIVER_QSPI	QSPI 通信

ql_spi_flash_enable

此函数启用或禁用 flash。为了避免误操作，使用此函数在操作 Flash 之前启用 Flash，并在使用后禁用。

原型：

ql_spi_flash_errcode_e ql_spi_flash_enable(bool status)

参数：

status: [入] 启用或禁用 flash。
1 禁用
2 启用

返回值：

有关结果代码，请参见 ql_spi_flash_errcode_e。

ql_spi_flash_read

此函数直接从 flash 读取数据而不初始化 SPI。

原型：

ql_spi_flash_errcode_e ql_spi_flash_read(uint32_t addr, uint8_t *buf, uint32_t len)

参数：

addr: [入] 要读取数据的地址。
buf: [出] 从 flash 读取数据的缓冲区。
len: [入] 要读取数据的长度。单位：字节。

返回值：

有关结果代码，请参见 ql_spi_flash_errcode_e。

ql_spi_flash_write

此函数直接向 flash 写入数据而不初始化 SPI。

原型：

ql_spi_flash_errcode_e ql_spi_flash_write(uint32_t addr, const uint8_t *buf, uint32_t len)

参数：

addr: [入] 要写入数据的地址。
buf: [入] 要写入数据的缓冲区。
len: [入] 要写入数据的长度。单位：字节。

返回值：

有关结果代码，请参见 ql_spi_flash_errcode_e。

ql_spi_flash_erase_chip

此函数从 flash 擦除数据。

原型：

ql_spi_flash_errcode_e ql_spi_flash_erase(uint32_t addr, ql_spi_flash_erase_e type)

参数：

addr: [入] 要擦除数据的地址。
type: [入] Flash 的擦除类型。有关详细信息，请参见 ql_spi_flash_erase_e。

返回值：

有关结果代码，请参见 ql_spi_flash_errcode_e。

ql_spi_flash_erase_e

flash 擦除类型的枚举：

typedef enum {
  ERASE_ALL = 0,
  ERASE_SECTOR,
  ERASE_BLOCK,
} ql_spi_flash_erase_e;

成员	描述
ERASE_ALL	擦除整个 flash
ERASE_SECTOR	擦除指定的扇区
ERASE_BLOCK	擦除指定的块

开发过程

本章描述如何在应用程序中使用 SPI flash API 以及如何调试基本功能。

操作过程

模块 SDK 中提供了操作 SPI Flash 的示例。演示在 ql_application/example/spi_flash_demo/ 目录下的 ql_spi_flash_demo.c 中。相关函数的描述如下：

启用 CFG_ENABLE_QUECTEL_SPI_FLASH 宏来运行演示，并自动调用 ql_spi_flash_demo_thread_creat() 创建测试任务。

ql_spi_flash_demo_thread_creat()：此函数创建 SPI Flash 任务，需要调用以运行演示。
ql_spi_flash_demo_thread()：任务执行函数，获取 SPI flash 的信息，通过 SPI 向 flash 写入数据、读取和擦除数据。示例程序中使用的 flash 型号是 GD25LQ64C。

创建 SPI Flash 任务

使用 SPI Flash API（示例 1）

使用 SPI Flash API（示例 2）

函数调试

要调试 SPI flash 函数，使用安装了模块的开发板（例如，FCM242D-TE-B），并按照以下步骤操作：

运行 操作过程 中描述的 SPI flash 演示。
重新编译固件版本，并将其烧录到模块。有关详细信息，请参见 快速入门指南。
重启模块。
将波特率设置为 921600 bps 并打开 UART 2 端口以获取日志信息。

上述图中的日志数据显示，通过 SPI 向 flash 写入数据和读取数据成功。

Timer

Timer API

头文件

ql_timer.h，timer API 的头文件，在 ql_components/api 目录中。除非另有说明，本文档中提到的所有头文件都在此目录中。

API 概述

函数	描述
`ql_TimerInit()`	以毫秒为单位初始化定时器。
`ql_TimerInit_us()`	以微秒为单位初始化定时器。
`ql_TimerStart()`	启动定时器。
`ql_TimerStop()`	停止定时器。
`ql_timer_delete()`	删除定时器。
`ql_get_timer_cnt()`	获取定时器计数值。

API 描述

ql_TimerInit

此函数以毫秒为单位初始化定时器。

原型：

ql_timer_errcode_e ql_TimerInit(ql_timer_number_e timer_id, uint32 time_ms, ql_timer_callback timer_cb)

参数：

timer_id: [入] 定时器 ID。有关详细信息，请参见 ql_timer_number_e。
time_ms: [入] 定时器持续时间。单位：毫秒。
timer_cb: [入] 定时器中断的回调函数。有关详细信息，请参见 ql_timer_callback。

返回值：

有关结果代码，请参见 ql_timer_errcode_e。

ql_timer_number_e

定时器 ID 的枚举：

typedef enum {
  QL_TIMER_0 = 0,
  QL_TIMER_1,
  QL_TIMER_2,
  QL_TIMER_3,
  QL_TIMER_4,
  QL_TIMER_5,
} ql_timer_number_e;

成员	描述
QL_TIMER_0	定时器 0
QL_TIMER_1	定时器 1
QL_TIMER_2	定时器 2
QL_TIMER_3	定时器 3（由系统使用，不能再次使用）
QL_TIMER_4	定时器 4
QL_TIMER_5	定时器 5

ql_timer_callback

此函数是定时器中断的回调函数。

typedef void (*ql_timer_callback)(uint8 arg)

arg: [入] 输入的参数。

ql_timer_errcode_e

结果代码的枚举：

typedef enum {
  QL_TIMER_SUCCESS = 0,
  QL_TIMER_EXECUTE_ERR,
  QL_TIMER_INVALID_PARAM_ERR,
  QL_TIMER_NOT_OPEN_ERR,
  QL_TIMER_NOT_SUPPORT_ERR
} ql_timer_errcode_e;

成员	描述
QL_TIMER_SUCCESS	执行成功
QL_TIMER_EXECUTE_ERR	执行失败
QL_TIMER_INVALID_PARAM_ERR	参数无效
QL_TIMER_NOT_OPEN_ERR	定时器未启用
QL_TIMER_NOT_SUPPORT_ERR	不支持定时器

ql_TimerInit_us

此函数以微秒为单位初始化定时器。

原型：

ql_timer_errcode_e ql_TimerInit_us(ql_timer_number_e timer_id, uint32 time_us, ql_timer_callback timer_cb)

参数：

timer_id: [入] 定时器 ID。有关详细信息，请参见 ql_timer_number_e。
time_us: [入] 定时器持续时间。单位：微秒。
timer_cb: [入] 定时器中断的回调函数。有关详细信息，请参见 ql_timer_callback。

返回值：

有关结果代码，请参见 ql_timer_errcode_e。

ql_TimerStart

此函数启动定时器。

原型：

ql_timer_errcode_e ql_TimerStart(ql_timer_number_e timer_id)

参数：

timer_id: [入] 定时器 ID。有关详细信息，请参见 ql_timer_number_e。

返回值：

有关结果代码，请参见 ql_timer_errcode_e。

ql_TimerStop

此函数停止定时器。

原型：

ql_timer_errcode_e ql_TimerStop(ql_timer_number_e timer_id)

参数：

timer_id: [入] 定时器 ID。有关详细信息，请参见 ql_timer_number_e。

返回值：

有关结果代码，请参见 ql_timer_errcode_e。

ql_timer_delete

此函数删除定时器。

原型：

ql_timer_errcode_e ql_timer_delete(ql_timer_number_e timer_id)

参数：

timer_id: [入] 定时器 ID。有关详细信息，请参见 ql_timer_number_e。

返回值：

有关结果代码，请参见 ql_timer_errcode_e。

ql_get_timer_cnt

此函数获取定时器计数值。

原型：

ql_timer_errcode_e ql_get_timer_cnt(ql_timer_number_e timer_id, uint32 *cont)

参数：

timer_id: [入] 定时器 ID。有关详细信息，请参见 ql_timer_number_e。
cont: [出] 计数值的指针。

返回值：

有关结果代码，请参见 ql_timer_errcode_e。

开发过程

本章描述如何在应用程序中使用 timer API 以及如何调试基本功能。在此示例中，默认测试定时器 0。

操作过程

模块 SDK 中提供了操作定时器的示例。演示在 ql_application/example/timer_demo/ 目录下的 ql_timer_demo.c 中。相关函数的描述如下：

启用 CFG_ENABLE_QUECTEL_TIMER 宏来运行演示，并自动调用 ql_timer_demo_thread_creat() 创建测试任务。

ql_timer_demo_thread_creat()：此函数创建定时器任务，需要调用以运行演示。
- ql_timer_demo_thread()：任务执行函数，初始化定时器，执行中断函数并停止定时器。

创建定时器任务

使用定时器 API 的示例

函数调试

要调试定时器函数，使用安装了模块的开发板（例如 FCM242D-TE-B），并按照以下步骤操作：

运行 *操作过程 中描述的定时器演示。
重新编译固件版本，并将其烧录到模块。
重启模块。
将波特率设置为 921600 bps 并打开 UART 2 端口以获取日志信息。

通过串口工具获取的定时器日志

上述图中的日志数据显示，定时器已启动，定时器中断回调函数已成功调用。

Watchdog

Watchdog API

头文件

ql_watchdog.h，watchdog API 的头文件，在 ql_components/api 目录中。除非另有说明，本文档中提到的所有头文件都在此目录中。

API 概述

函数	描述
`ql_wdg_init()`	初始化 watchdog。
`ql_wdg_reload()`	喂狗。
`ql_wdg_finalize()`	关闭 watchdog。

API 描述

ql_wdg_init

此函数初始化 watchdog。

原型：

ql_wdg_errcode_e ql_wdg_init(uint32 timeout)

参数：

timeout: [入] Watchdog 重置周期。单位：毫秒。最大值：0xFFF（约 65 s）。

返回值：

有关结果代码，请参见 ql_wdg_errcode_e。

ql_wdg_errcode_e

结果代码的枚举：

typedef enum {
  QL_WDG_SUCCESS = 0,
  QL_WDG_EXECUTE_ERR,
  QL_WDG_INVALID_PARAM_ERR,
} ql_wdg_errcode_e;

成员	描述
QL_WDG_SUCCESS	执行成功
QL_WDG_EXECUTE_ERR	执行失败
QL_WDG_INVALID_PARAM_ERR	参数无效

ql_wdg_reload

此函数喂狗。

原型：

ql_wdg_errcode_e ql_wdg_reload(void)

参数：

无

返回值：

有关结果代码，请参见 ql_wdg_errcode_e。

ql_wdg_finalize

此函数关闭 watchdog。

原型：

ql_wdg_errcode_e ql_wdg_finalize(void)

参数：

无

返回值：

有关结果代码，请参见 ql_wdg_errcode_e。

开发过程

本章描述如何在应用程序中使用 watchdog API 以及如何调试基本功能。

操作过程

模块 SDK 中提供了操作 watchdog API 的示例。演示在 ql_application/example/watchdog_demo/ 目录下的 ql_watchdog_demo.c 文件中。相关函数的描述如下：

启用 CFG_NABLE_QUECTEL_WATCHDOG 宏来运行演示，并自动调用 ql_wdg_demo_thread_creat() 创建测试任务。

ql_wdg_demo_thread_creat()：此函数创建 watchdog 任务，需要调用以运行演示。
ql_wdg_demo_thread()：这是任务的执行函数，初始化并喂狗。

创建 Watchdog 任务

使用 Watchdog API 的示例

函数调试

要调试 watchdog 函数，使用安装了模块的开发板（例如，FCM242D-TE-B），并按照以下步骤操作：

运行 操作过程 中描述的 watchdog 演示。
重新编译固件版本，并将其烧录到模块。
重启模块。
将波特率设置为 921600 bps 并打开 UART 2 端口以获取日志信息。

通过串口工具获取的 Watchdog 日志

日志表明演示程序成功重置了 watchdog。

低功耗模式

低功耗模式 API

头文件

ql_lowpower.h，低功耗模式 API 的头文件，在 ql_components/api 目录中。除非另有说明，本文档中提到的所有头文件都在此目录中。

API 概述

函数	描述
`ql_deep_sleep_enter()`	将 MCU 设置为深度睡眠模式。
`ql_lowvol_sleep_enter()`	将 MCU 设置为低电压待机模式。
`ql_deep_mcudtim_enter()`	启用或禁用 MCU 正常待机模式。
`ql_deep_rfdtim_enter()`	启用或禁用 RF 睡眠模式。
`ql_lv_ps_mode_set_en()`	启用或禁用低电压 Wi-Fi 保持活动模式。
`ql_set_gpio_wakeup_index()`	设置 Wi-Fi 保持活动模式下唤醒 MCU 的 GPIO 引脚。

API 描述

ql_deep_sleep_enter

此函数将 MCU 设置为深度睡眠模式。

原型：

ql_lowpower_errcode_e ql_deep_sleep_enter(ql_sleep_ctrl_parm_s deep_sleep_param)

参数：

deep_sleep_param: [入] 深度睡眠模式的配置。有关详细信息，请参见 ql_sleep_ctrl_parm_s。

返回值：

有关结果代码，请参见 ql_lowpower_errcode_e。

ql_sleep_ctrl_parm_s

深度睡眠模式或低电压待机模式的配置结构：

typedef struct ql_ps_sleep_ctrl {
  ql_deep_wakeup_way wake_up_way;
  UINT32 gpio_index_map;
  UINT32 gpio_edge_map;
  UINT32 gpio_stay_lo_map;
  UINT32 gpio_last_index_map;
  UINT32 gpio_last_edge_map;
  UINT32 gpio_stay_hi_map;
  UINT32 sleep_time;
  UINT32 lpo_32k_src;
  UINT32 sleep_mode;
} ql_sleep_ctrl_parm_s;

类型	参数	描述
`ql_deep_wakeup_way`	wake_up_way	唤醒 MCU 的方法。有关详细信息，请参见 ql_deep_wakeup_way。
UINT32	gpio_index_map	唤醒 MCU 的引脚。GPIO 0--GPIO 31。
UINT32	gpio_edge_map	唤醒 MCU 的边沿。0：上升，1：下降
UINT32	gpio_stay_lo_map	GPIO 引脚在深度睡眠中保持低状态
UINT32	gpio_last_index_map	无需配置
UINT32	gpio_last_edge_map	无需配置
UINT32	gpio_stay_hi_map	GPIO 引脚在深度睡眠中保持高状态
UINT32	sleep_time	睡眠时间（RTC 定时唤醒）。单位：秒
UINT32	lpo_32k_src	RTC 时钟源
UINT32	sleep_mode	睡眠模式：0 普通，1 低电压

ql_lowpower_errcode_e

结果代码的枚举：

typedef enum {
  QL_LOWPOWER_SUCCESS = 0,
  QL_LOWPOWER_EXECUTE_ERR,
  QL_LOWPOWER_INVALID_PARAM_ERR,
} ql_lowpower_errcode_e;

成员	描述
QL_LOWPOWER_SUCCESS	执行成功
QL_LOWPOWER_EXECUTE_ERR	执行失败
QL_LOWPOWER_INVALID_PARAM_ERR	参数无效

ql_deep_wakeup_way

从深度睡眠模式或低电压待机模式唤醒 MCU 的方法的枚举：

typedef enum {
  QL_DEEP_WAKEUP_GPIO = 1,
  QL_DEEP_WAKEUP_RTC = 2,
} ql_deep_wakeup_way;

成员	描述
QL_DEEP_WAKEUP_GPIO	GPIO 中断唤醒
QL_DEEP_WAKEUP_RTC	RTC 定时唤醒

ql_lowvol_sleep_enter

此函数将 MCU 设置为低电压待机模式。

原型：

ql_lowpower_errcode_e ql_lowvol_sleep_enter(ql_sleep_ctrl_parm_s lowvol_sleep_param)

参数：

lowvol_sleep_param: [入] 低电压待机模式的配置。有关详细信息，请参见 ql_sleep_ctrl_parm_s。

返回值：

有关结果代码，请参见 ql_lowpower_errcode_e。

ql_deep_mcudtim_enter

此函数启用或禁用 MCU 正常待机模式。

原型：

ql_lowpower_errcode_e ql_deep_mcudtim_enter(UINT32 enable)

参数：

enable: [入] 启用或禁用 MCU 正常待机模式。
0: 禁用
1: 启用

返回值：

有关结果代码，请参见 ql_lowpower_errcode_e。

ql_deep_rfdtim_enter

此函数启用或禁用 RF 睡眠模式。

原型：

ql_lowpower_errcode_e ql_deep_rfdtim_enter(UINT32 enable, UINT32 dtimnum)

参数：

enable: [入] 启用或禁用 RF 睡眠模式。
0: 禁用
1: 启用
dtimnum: [入] 正常待机期间 MCU 是否进入 Wi-Fi 保持活动模式。
0: 否
其他值: Wi-Fi 保持活动模式下唤醒 MCU 的时间间隔。单位：100 ms（推荐：30，即 3000 ms）

返回值：

有关结果代码，请参见 ql_lowpower_errcode_e。

ql_lv_ps_mode_set_en

此函数启用或禁用低电压 Wi-Fi 保持活动模式。

原型：

ql_lowpower_errcode_e ql_lv_ps_mode_set_en(bool enable)

参数：

enable: [入] 启用或禁用低电压保持活动模式。

0: 禁用

1: 启用

返回值：

有关结果代码，请参见 ql_lowpower_errcode_e。

ql_set_gpio_wakeup_index

此函数设置 Wi-Fi 保持活动模式下唤醒 MCU 的 GPIO 引脚。

原型：

ql_lowpower_errcode_e ql_set_gpio_wakeup_index(UINT8 gpio, int wakeup_level)

参数：

gpio: [入] 唤醒 MCU 的 GPIO 引脚。
wakeup_level: [入] 唤醒电平。

0: 低电平

1: 高电平

返回值：

有关结果代码，请参见 ql_lowpower_errcode_e。

开发过程

本章描述如何在应用程序中使用低功耗模式 API 以及如何调试基本功能。

操作过程

模块 SDK 中提供了操作低功耗模式 API 的示例。演示在 ql_application/example/lowpower_demo/ 目录下的 ql_lowpower_demo.c 文件中。相关函数的描述如下：

要运行演示，启用 CFG_ENABLE_QUECTEL_LOWPOWER 宏。这将自动调用 ql_lowpower_demo_thread_creat() 创建测试任务。

ql_lowpower_demo_thread_creat()：此函数创建低功耗任务，需要调用以运行演示。
ql_lowpower_demo_thread()：任务执行函数，初始化低功耗模式。

创建低功耗任务

使用低功耗模式 API 的示例

函数调试

要调试低功耗模式，使用安装了模块的开发板（例如，FCM242D-TE-B），并按照以下步骤操作：

运行 操作过程 中描述的低功耗演示。
重新编译固件版本，并将其烧录到模块。
将波特率设置为 921600 bps 并打开 UART 2 端口以获取日志信息。
发送 STA 命令（STA SSID Key）连接 Wi-Fi，否则 MCU 无法进入低功耗保持活动模式。

通过串口工具获取的日志

连接 Wi-Fi 后，您需要等待 MCU 进入低功耗模式。

MCU 成功进入低功耗保持活动模式

MCU 进入低功耗保持活动模式后，Wi-Fi 仍保持连接。上拉 GPIO22 以唤醒模块，模块退出低功耗保持活动模式。串口工具每 1 秒打印一次 "wake up"。

附录参考

缩略语	描述
API	应用程序编程接口
App	应用程序
BLE	低功耗蓝牙
GPIO	通用输入/输出
ID	标识符
IoT	物联网
MCU	微程序控制单元
NET	网络
OTA	空中技术
QSPI	队列串行外围接口
RF	射频
RTC	实时时钟
RTOS	实时操作系统
SDK	软件开发工具包
SN	序列号
SPI	串行外围接口
SSID	服务集标识符
STA	站点
UART	通用异步接收器/发射器
Wi-Fi	无线保真

BLE 开发指南

RTOS 开发指南

ShortRange

通用 API 开发指南

简介

Flash

Flash API

头文件

API 概述

API 描述

ql_flash_security

ql_flash_protect_type_e

ql_flash_errcode_e

ql_flash_write_bytes

ql_flash_read_bytes

ql_flash_erase

ql_flash_partition_erase

ql_partition_e

ql_flash_partition_write

ql_flash_partition_read

ql_flash_partition_get_info

ql_logic_partition_info_t

ql_flash_type_e

开发过程

操作过程

函数调试

SPI Flash

SPI Flash API

头文件

API 概述

API 描述

ql_spi_flash_get_info

ql_spi_flash_info_t

ql_spi_flash_errcode_e

enum_flash_driver_e

ql_spi_flash_enable

ql_spi_flash_read

ql_spi_flash_write

ql_spi_flash_erase_chip

ql_spi_flash_erase_e

开发过程

操作过程

函数调试

Timer

Timer API

头文件

API 概述

API 描述

ql_TimerInit

ql_timer_number_e

ql_timer_callback

ql_timer_errcode_e

ql_TimerInit_us

ql_TimerStart

ql_TimerStop

ql_timer_delete

ql_get_timer_cnt

开发过程

操作过程

函数调试

Watchdog

Watchdog API

头文件

API 概述

API 描述

ql_wdg_init

ql_wdg_errcode_e

ql_wdg_reload

ql_wdg_finalize

开发过程

操作过程

函数调试

低功耗模式

低功耗模式 API

头文件

API 概述

API 描述

ql_deep_sleep_enter

ql_sleep_ctrl_parm_s

ql_lowpower_errcode_e

ql_deep_wakeup_way

ql_lowvol_sleep_enter