2025-11-14

外设接口开发指南

简介

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

本文档适用于基于 SDK 构建环境的 QuecOpen® 解决方案。它概述了模块支持的 GPIO、UART、SPI、ADC、PWM 和 I2C API 的使用方式。

GPIO API

头文件

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

API 描述

ql_gpio_init

此函数初始化 GPIO 引脚。

原型

ql_gpio_errcode_e ql_gpio_init(ql_gpio_num_e gpio_num, ql_gpio_mode_e mode, ql_gpio_level_e level);

参数
- gpio_num: [入] GPIO 引脚号。有关详细信息，请参见 ql_gpio_num_e。
- mode: [入] GPIO 模式。有关详细信息，请参见 ql_gpio_mode_e。
- level: [入] GPIO 输出电平。仅当 mode 为 QL_GMODE_OUTPUT 时有效。有关详细信息，请参见 ql_gpio_level_e。
返回值
结果代码。有关详细信息，请参见 ql_gpio_errcode_e。

ql_gpio_num_e

GPIO 引脚号的枚举：

typedef enum {
    QL_GPIO0 = 0,
    QL_GPIO1,
    QL_GPIO6 = 6,
    QL_GPIO7,
    QL_GPIO8,
    QL_GPIO9,
    QL_GPIO10,
    QL_GPIO11,
    QL_GPIO14 = 14,
    QL_GPIO15,
    QL_GPIO16,
    QL_GPIO17,
    QL_GPIO20 = 20,
    QL_GPIO21,
    QL_GPIO22,
    QL_GPIO23,
    QL_GPIO24,
    QL_GPIO26 = 26,
    QL_GPIO28 = 28,   
} ql_gpio_num_e

成员	描述
QL_GPIO0	GPIO0
QL_GPIO1	GPIO1
QL_GPIO6	GPIO6
QL_GPIO7	GPIO7
QL_GPIO8	GPIO8
QL_GPIO9	GPIO9
QL_GPIO10	GPIO10
QL_GPIO11	GPIO11
QL_GPIO14	GPIO14
QL_GPIO15	GPIO15
QL_GPIO16	GPIO16
QL_GPIO17	GPIO17
QL_GPIO20	GPIO20
QL_GPIO21	GPIO21
QL_GPIO22	GPIO22
QL_GPIO23	GPIO23
QL_GPIO24	GPIO24
QL_GPIO26	GPIO26
QL_GPIO28	GPIO28

ql_gpio_mode_e

GPIO 模式的枚举：

成员	描述
QL_GMODE_HIGH_IMPEDANCE	高阻抗
QL_GMODE_INPUT	输入配置为浮动
QL_GMODE_IN_PD	输入配置为下拉
QL_GMODE_IN_PU	输入配置为上拉
QL_GMODE_OUTPUT	输出

ql_gpio_errcode_e

GPIO API 结果代码的枚举：

typedef enum {
    QL_GPIO_SUCCESS = 0,
    QL_GPIO_EXECUTE_ERR,
    QL_GPIO_INVALID_PARAM_ERR,
} ql_gpio_errcode_e;

成员

成员	描述
QL_GPIO_SUCCESS	执行成功
QL_GPIO_EXECUTE_ERR	执行失败
QL_GPIO_INVALID_PARAM_ERR	参数无效

ql_gpio_deinit

此函数取消初始化 GPIO。

原型

ql_gpio_errcode_e ql_gpio_deinit(ql_gpio_num_e gpio_num);

参数
- gpio_num: [入] GPIO 引脚号。有关详细信息，请参见 ql_gpio_num_e。
返回值
结果代码。有关详细信息，请参见 ql_gpio_errcode_e。

ql_gpio_set_level

此函数设置指定 GPIO 引脚的电平。仅对输出引脚有效。

原型

ql_gpio_errcode_e ql_gpio_set_level(ql_gpio_num_e gpio_num, ql_gpio_level_e level);

参数
- gpio_num: [入] GPIO 引脚号。有关详细信息，请参见 ql_gpio_num_e。
- level: [入] GPIO 输出电平。有关详细信息，请参见 ql_gpio_level_e。
返回值
结果代码。有关详细信息，请参见 ql_gpio_errcode_e。

ql_gpio_level_e

GPIO 输出电平的枚举：

typedef enum {
    QL_GPIO_LEVEL_LOW = 0,
    QL_GPIO_LEVEL_HIGH,
} ql_gpio_level_e;

成员

成员	描述
QL_GPIO_LEVEL_LOW	低电平
QL_GPIO_LEVEL_HIGH	高电平

ql_gpio_set_level_reverse

此函数反转 GPIO 输出电平。仅对输出引脚有效。

原型

ql_gpio_errcode_e ql_gpio_set_level_reverse(ql_gpio_num_e gpio_num);

参数
- gpio_num: [入] GPIO 引脚号。有关详细信息，请参见 ql_gpio_num_e。
返回值
结果代码。有关详细信息，请参见 ql_gpio_errcode_e。

ql_gpio_get_level

此函数获取指定 GPIO 引脚的电平。仅对输入引脚有效。

原型

ql_gpio_errcode_e ql_gpio_get_level(ql_gpio_num_e gpio_num, uint32 *input_level);

参数
- gpio_num: [入] GPIO 引脚号。有关详细信息，请参见 ql_gpio_num_e。
- input_level: [出] GPIO 引脚电平。
返回值
结果代码。有关详细信息，请参见 ql_gpio_errcode_e。

ql_gpio_int_init

此函数初始化并启用 GPIO 中断。

原型

ql_gpio_errcode_e ql_gpio_int_init(ql_gpio_num_e gpio_num, ql_gpio_irq_trigger_e irq_trigger, ql_gpio_irq_callback cb);

参数
- gpio_num: [入] GPIO 引脚号。有关详细信息，请参见 ql_gpio_num_e。
- irq_trigger: [入] GPIO 中断触发模式。有关详细信息，请参见 ql_gpio_irq_trigger_e。
- cb: [入] GPIO 中断回调函数。有关详细信息，请参见 ql_gpio_irq_callback。
返回值
结果代码。有关详细信息，请参见 ql_gpio_errcode_e。

ql_gpio_irq_trigger_e

GPIO 中断触发模式的枚举：

typedef enum {
    QL_IRQ_TRIGGER_LOW_LEVEL,
    QL_IRQ_TRIGGER_HIGH_LEVEL,
    QL_IRQ_TRIGGER_RISING_EDGE,
    QL_IRQ_TRIGGER_FALLING_EDGE,
} ql_gpio_irq_trigger_e;

成员

成员	描述
QL_IRQ_TRIGGER_LOW_LEVEL	GPIO 中断在低电平触发
QL_IRQ_TRIGGER_HIGH_LEVEL	GPIO 中断在高电平触发
QL_IRQ_TRIGGER_RISING_EDGE	GPIO 中断在上升沿触发
QL_IRQ_TRIGGER_FALLING_EDGE	GPIO 中断在下降沿触发

ql_gpio_irq_callback

GPIO 中断的回调函数。

原型

typedef void (*ql_gpio_irq_callback)(void *arg);

参数
- arg: [入] 触发 GPIO 中断的引脚。
返回值
无。

ql_gpio_int_disable

此函数禁用配置的 GPIO 中断。

原型

ql_gpio_errcode_e ql_gpio_int_disable(ql_gpio_num_e gpio_num);

参数
- gpio_num: [入] GPIO 引脚号。有关详细信息，请参见 ql_gpio_num_e。
返回值
结果代码。有关详细信息，请参见 ql_gpio_errcode_e。

GPIO 开发过程

本章解释如何使用上述 GPIO API 来配置 GPIO 并执行基本调试。

GPIO 操作

模块 SDK 中提供了使用 GPIO API 的示例。在 ql_application/example/gpio_demo/ql_gpio_demo.c 文件中。相关函数的描述如下：

ql_gpio_demo_thread_creat()：此函数创建 GPIO 任务。调用此函数以运行演示。
ql_gpio_demo_thread()：此函数执行 GPIO 任务。它初始化 GPIO 引脚，配置输出电平，并启动、启用和禁用 GPIO 中断。

要运行演示，请在 ql_application/ql_app_main.c 的 SDK 中将 CFG_ENABLE_QUECTEL_GPIO 宏定义设置为 1（即启用宏定义）。这将自动触发 ql_gpio_demo_thread_creat() 的执行以创建测试任务。

图 1：示例：创建 GPIO 任务

图 2：示例：使用 GPIO API

有关 RTOS 函数的详细信息，请参见 RTOS 开发指南。

函数调试

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

运行 GPIO 操作 中解释的 GPIO 演示。
重新编译固件版本并将其烧录到模块。
重启模块。
打开 UART2 端口并通过此端口获取日志。

拉高 GPIO22 引脚电平并验证 GPIO9 引脚电平是否反转。这表明 GPIO 中断已被触发。日志信息将如下显示：

通过 UART 端口工具捕获日志

UART API

头文件

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

API 描述

ql_uart_set_dcbconfig

此函数设置 UART 端口属性，这些属性在重新打开 UART 端口后生效。请注意，系统日志端口不能用作 UART 端口。

原型

ql_uart_errcode_e ql_uart_set_dcbconfig(ql_uart_port_number_e port, ql_uart_config_s *dcb);

参数
- port: [入] UART 端口号。有关详细信息，请参见 ql_uart_port_number_e。
- dcb: [入] UART 端口属性配置。有关详细信息，请参见 ql_uart_config_s。
返回值
结果代码。有关详细信息，请参见 ql_uart_errcode_e。

ql_uart_port_number_e

UART 端口号的枚举。目前仅支持两个 UART 端口。

typedef enum {
    QL_UART_PORT_1,
    QL_UART_PORT_2,
} ql_uart_port_number_e;

成员

成员	描述
QL_UART_PORT_1	UART 1
QL_UART_PORT_2	UART 2

ql_uart_config_s

UART 端口属性配置的结构：

typedef struct {
    ql_uart_baud_e baudrate;
    ql_uart_databit_e data_bit;
    ql_uart_stopbit_e stop_bit;
    ql_uart_paritybit_e parity_bit;
    ql_uart_flowctrl_e flow_ctrl;
} ql_uart_config_s;

成员

类型	参数	描述
`ql_uart_baud_e`	baudrate	波特率。默认：115200 bps。有关详细信息，请参见 ql_uart_baud_e。
`ql_uart_databit_e`	data_bit	数据位。默认：8 位。有关详细信息，请参见 ql_uart_databit_e。
`ql_uart_stopbit_e`	stop_bit	停止位。默认：1 位。有关详细信息，请参见 ql_uart_stopbit_e。
`ql_uart_paritybit_e`	parity_bit	奇偶校验位。默认：无奇偶校验位。有关详细信息，请参见 ql_uart_paritybit_e。
`ql_uart_flowctrl_e`	flow_ctrl	流控制。默认：禁用。有关详细信息，请参见 ql_uart_flowctrl_e。

ql_uart_baud_e

波特率的枚举：

typedef enum {
    QL_UART_BAUD_1200 = 1200,
    QL_UART_BAUD_2400 = 2400,
    QL_UART_BAUD_4800 = 4800,
    QL_UART_BAUD_9600 = 9600,
    QL_UART_BAUD_14400 = 14400,
    QL_UART_BAUD_19200 = 19200,
    QL_UART_BAUD_28800 = 28800,
    QL_UART_BAUD_33600 = 33600,
    QL_UART_BAUD_38400 = 38400,
    QL_UART_BAUD_57600 = 57600,
    QL_UART_BAUD_115200 = 115200,
    QL_UART_BAUD_230400 = 230400,
    QL_UART_BAUD_460800 = 460800,
    QL_UART_BAUD_921600 = 921600,
    QL_UART_BAUD_1000000 = 1000000,
    QL_UART_BAUD_2000000 = 2000000,
} ql_uart_baud_e

成员

成员	描述
QL_UART_BAUD_1200	1200 bps
QL_UART_BAUD_2400	2400 bps
QL_UART_BAUD_4800	4800 bps
QL_UART_BAUD_9600	9600 bps
QL_UART_BAUD_14400	14400 bps
QL_UART_BAUD_19200	19200 bps
QL_UART_BAUD_28800	28800 bps
QL_UART_BAUD_33600	33600 bps
QL_UART_BAUD_38400	38400 bps
QL_UART_BAUD_57600	57600 bps
QL_UART_BAUD_115200	115200 bps
QL_UART_BAUD_230400	230400 bps
QL_UART_BAUD_460800	460800 bps
QL_UART_BAUD_921600	921600 bps
QL_UART_BAUD_1000000	1000000 bps
QL_UART_BAUD_2000000	2000000 bps

ql_uart_databit_e

数据位的枚举：

typedef enum {
    QL_UART_DATABIT_5,
    QL_UART_DATABIT_6,
    QL_UART_DATABIT_7,
    QL_UART_DATABIT_8,
} ql_uart_databit_e;

成员

成员	描述
QL_UART_DATABIT_5	5 位
QL_UART_DATABIT_6	6 位
QL_UART_DATABIT_7	7 位
QL_UART_DATABIT_8	8 位

ql_uart_stopbit_e

停止位的枚举：

typedef enum {
    QL_UART_STOP_1 = 0,
    QL_UART_STOP_2,
} ql_uart_stopbit_e;

成员

成员	描述
QL_UART_STOP_1	1 位
QL_UART_STOP_2	2 位

ql_uart_paritybit_e

奇偶校验位的枚举：

typedef enum {
    QL_UART_PARITY_NONE,
    QL_UART_PARITY_ODD,
    QL_UART_PARITY_EVEN,
} ql_uart_paritybit_e;

成员

成员	描述
QL_UART_PARITY_NONE	无奇偶校验
QL_UART_PARITY_ODD	奇校验
QL_UART_PARITY_EVEN	偶校验

ql_uart_flowctrl_e

流控制的枚举：

typedef enum {
    QL_FC_NONE = 0,
    QL_FC_HW_CTS,
    QL_FC_HW_RTS,
    QL_FC_HW_RTS_CTS,
} ql_uart_flowctrl_e;

成员

成员	描述
QL_FC_NONE	无流控制
QL_FC_HW_CTS	硬件 CTS
QL_FC_HW_RTS	硬件 RTS
QL_FC_HW_RTS_CTS	硬件 CTS 和 RTS

ql_uart_errcode_e

UART API 结果代码的枚举：

typedef enum {
    QL_UART_SUCCESS = 0,
    QL_UART_EXECUTE_ERR,
    QL_UART_MEM_ADDR_NULL_ERR,
    QL_UART_INVALID_PARAM_ERR,
    QL_UART_NOT_OPEN_ERR,
} ql_uart_errcode_e;

成员

成员	描述
QL_UART_SUCCESS	执行成功
QL_UART_EXECUTE_ERR	执行失败
QL_UART_MEM_ADDR_NULL_ERR	参数地址：空
QL_UART_INVALID_PARAM_ERR	参数无效
QL_UART_NOT_OPEN_ERR	UART 端口未打开

ql_uart_get_dcbconfig

此函数获取 UART 端口属性配置。

原型

ql_uart_errcode_e ql_uart_get_dcbconfig(ql_uart_port_number_e port, ql_uart_config_s *dcb);

参数
- port: [入] UART 端口号。有关详细信息，请参见 ql_uart_port_number_e。
- dcb: [入] UART 端口属性配置。有关详细信息，请参见 ql_uart_config_s。
返回值
结果代码。有关详细信息，请参见 ql_uart_errcode_e。

ql_uart_open

此函数打开 UART 端口。

原型

ql_uart_errcode_e ql_uart_open(ql_uart_port_number_e port);

参数
- port: [入] UART 端口号。有关详细信息，请参见 ql_uart_port_number_e。
返回值
结果代码。有关详细信息，请参见 ql_uart_errcode_e。

ql_uart_close

此函数关闭 UART 端口。

原型

ql_uart_errcode_e ql_uart_close(ql_uart_port_number_e port);

参数
- port: [入] UART 端口号。有关详细信息，请参见 ql_uart_port_number_e。
返回值
结果代码。有关详细信息，请参见 ql_uart_errcode_e。

ql_uart_write_ready

此函数评估是否可以当前通过指定的 UART 端口向模块写入数据。

原型

bool ql_uart_write_ready(ql_uart_port_number_e port);

参数
- port: [入] UART 端口号。有关详细信息，请参见 *第 3.2.1.1* 章。
返回值
- 0：当前无法通过指定的 UART 端口向模块写入数据。
- 1：当前可以通过指定的 UART 端口向模块写入数据。

ql_uart_write

此函数通过指定的 UART 端口向模块写入数据。

原型

ql_uart_errcode_e ql_uart_write(ql_uart_port_number_e port, uint8 *data, uint32 data_len);

参数
- port: [入] UART 端口号。有关详细信息，请参见 ql_uart_port_number_e。
- data: [入] 写入的数据。
- data_len: [入] 写入数据的长度。单位：字节。
返回值
结果代码。有关详细信息，请参见 ql_uart_errcode_e。

ql_uart_read

此函数从 UART 缓冲区通过指定的 UART 端口读取数据。如果 UART 缓冲区中的数据长度小于要读取的数据长度，则无法读取数据，您可以使用 ql_uart_read_prefetch() 读取 UART 缓冲区中的可用数据。

原型

ql_uart_errcode_e ql_uart_read(ql_uart_port_number_e port, uint8 *data, uint32 data_len);

参数
- port: [入] UART 端口号。有关详细信息，请参见 ql_uart_port_number_e。
- data: [出] 读取的数据。
- data_len: [入] 读取数据的长度。单位：字节。
返回值
结果代码。有关详细信息，请参见 ql_uart_errcode_e。

ql_uart_read_prefetch

此函数从 UART 缓冲区通过指定的 UART 端口读取数据。如果 UART 缓冲区中的数据长度小于要读取的数据长度，则函数读取缓冲区中的可用数据。

原型

int ql_uart_read_prefetch(ql_uart_port_number_e port, uint8 *data, uint32 data_len);

参数
- port: [入] UART 端口号。有关详细信息，请参见 ql_uart_port_number_e。
- data: [出] 读取的数据。
- data_len: [入] 读取数据的长度。单位：字节。
返回值
实际读取的数据长度。

ql_uart_get_rx_count

此函数读取指定 UART 缓冲区中的数据长度。

原型

int ql_uart_get_rx_count(ql_uart_port_number_e port);

参数
- port: [入] UART 端口号。有关详细信息，请参见 ql_uart_port_number_e。
返回值
从 UART 缓冲区读取的数据长度。单位：字节。

ql_uart_set_rx_cb

此函数注册当通过 UART 端口接收数据并触发中断时调用的回调函数。

原型

ql_uart_errcode_e ql_uart_set_rx_cb(ql_uart_port_number_e port, ql_uart_callback uart_cb, void *param);

参数
- port: [入] UART 端口号。有关详细信息，请参见 ql_uart_port_number_e。
- uart_cb: [入] 处理 UART 中断的回调函数。
- param: [入] 处理 UART 中断的回调函数的参数。
返回值
结果代码。有关详细信息，请参见 ql_uart_errcode_e。

ql_uart_set_tx_cb

此函数注册当通过 UART 端口发送数据并触发中断时调用的回调函数。

原型

ql_uart_errcode_e ql_uart_set_tx_cb(ql_uart_port_number_e port, ql_uart_callback uart_cb, void *param);

参数
- port: [入] UART 端口号。有关详细信息，请参见 ql_uart_port_number_e。
- uart_cb: [入] 处理 UART 中断的回调函数。
- param: [入] 处理 UART 中断的回调函数的参数。
返回值
结果代码。有关详细信息，请参见 ql_uart_errcode_e。

ql_uart_set_tx_int

此函数控制指定 UART 端口的发送中断事件。

原型

ql_uart_errcode_e ql_uart_set_tx_int(ql_uart_port_number_e port, uint32 set);

参数
- port: [入] UART 端口号。有关详细信息，请参见 ql_uart_port_number_e。
- set: [入] 控制 UART 端口的发送中断事件。
  - 1：启用
  - 2：禁用
返回值
结果代码。有关详细信息，请参见 ql_uart_errcode_e。

UART 开发过程

本章解释如何在应用程序中使用上述 UART API 并执行基本调试。

UART 操作

模块 SDK 中提供了使用 UART API 的示例。在 ql_application/example/uart_demo/ql_uart_demo.c 文件中。相关函数的描述如下。

ql_uart_demo_thread_creat()：此函数创建 UART 任务。调用此函数以运行演示。
ql_uart_demo_thread()：此函数执行 UART 任务。它初始化 UART 端口，发送和接收数据。

要运行演示，请启用 CFG_ENABLE_QUECTEL_UART 宏定义。这将自动触发 ql_uart_demo_thread_creat() 的执行以创建任务。

示例：创建 UART 任务

示例：使用 UART API (I)

示例：使用 UART API (II)

函数调试

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

运行 UART 操作 中解释的 UART 演示。
重新编译固件版本并将其烧录到模块。
重启模块。
打开 UART1 以开始测试。从 UART1 向 UART2 发送 20 字节的数据，它将接收并回显数据，如下所示：

从 UART 端口 1 发送的测试数据

在 UART2 上接收的测试数据

测试完成后的日志

通过比较 *图 7* 中的发送数据与 *图 8* 中的接收数据，可以确认 UART 函数已成功测试。

SPI API

头文件

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

API 描述

ql_spi_init

此函数初始化 SPI。

原型

ql_spi_errcode_e ql_spi_init(ql_spi_id_e spi_id, ql_spi_config_s *spi_cfg);

参数
- spi_id: [入] SPI ID。有关详细信息，请参见 ql_spi_id_e。
- spi_cfg: [入] SPI 配置。有关详细信息，请参见 ql_spi_config_s。
返回值
结果代码。有关详细信息，请参见 ql_spi_errcode_e。

ql_spi_id_e

SPI ID 的枚举：

typedef enum
{
    QL_SPI_ID0 = 0,
    QL_SPI_ID_MAX
} ql_spi_id_e;

成员

成员	描述
QL_SPI_ID0	SPI0
QL_SPI_ID_MAX	SPI ID 的最大数量

ql_spi_config_s

SPI 配置的结构：

typedef struct
{
    uint32 clk;
    ql_spi_role_e role;
    ql_spi_bit_order_e bit_order;
} ql_spi_config_s;

参数

类型	参数	描述
uint32	clk	SPI 时钟频率。在主模式下，最大值为 30 MHz。在从模式下，最大值为 20 MHz。
`ql_spi_role_e`*`	role	SPI 主或从选择。有关详细信息，请参见 ql_spi_role_e。
`ql_spi_pol_pha_mode_e`	pol_pha_mode	SPI 时钟相位和 SPI 时钟极性。有关详细信息，请参见 ql_spi_pol_pha_mode_e。
`ql_spi_bit_order_e`*`	bit_order*	SPI 发送模式。有关详细信息，请参见 ql_spi_bit_order_e。

ql_spi_role_e

SPI 主或从选择的枚举：

typedef enum {
    QL_SPI_ROLE_SLAVE = 0,
    QL_SPI_ROLE_MASTER
} ql_spi_role_e;

成员

成员	描述
QL_SPI_ROLE_SLAVE	SPI 配置为从设备。
QL_SPI_ROLE_MASTER	SPI 配置为主设备。

ql_spi_pol_pha_mode_e

SPI 时钟极性和 SPI 时钟相位的枚举：

typedef enum {
    QL_SPI_POL_PHA_MODE0 = 0,
    QL_SPI_POL_PHA_MODE1,
    QL_SPI_POL_PHA_MODE2,
    QL_SPI_POL_PHA_MODE3
} ql_spi_pol_pha_mode_e;

成员

成员	描述
QL_SPI_POL_PHA_MODE0	SCK 在空闲状态时为低电平。在 SCK 的第一个周期的边沿采样数据。
QL_SPI_POL_PHA_MODE1	SCK 在空闲状态时为低电平。在 SCK 的第二个周期的边沿采样数据。
QL_SPI_POL_PHA_MODE2	SCK 在空闲状态时为高电平。在 SCK 的第一个周期的边沿采样数据。
QL_SPI_POL_PHA_MODE3	SCK 在空闲状态时为高电平。在 SCK 的第二个周期的边沿采样数据。

ql_spi_bit_order_e

SPI 发送模式的枚举：

typedef enum {
    QL_SPI_MSB_FIRST = 0,
    QL_SPI_LSB_FIRST
} ql_spi_bit_order_e;

成员

成员	描述
QL_SPI_MSB_FIRST	MSB 先发送
QL_SPI_LSB_FIRST	LSB 先发送

ql_spi_errcode_e

SPI API 结果代码的枚举：

typedef enum
{
    QL_SPI_SUCCESS = 0,
    QL_SPI_EXECUTE_ERR,
    QL_SPI_INVALID_PARAM_ERR,
    QL_SPI_NOT_INIT_ERR
} ql_spi_errcode_e;

成员

成员	描述
QL_SPI_SUCCESS	执行成功
QL_SPI_EXECUTE_ERR	执行失败
QL_SPI_INVALID_PARAM_ERR	参数无效
QL_SPI_NOT_INIT_ERR	SPI 未初始化

ql_spi_deinit

此函数取消初始化指定的 SPI。

原型

ql_spi_errcode_e ql_spi_deinit(ql_spi_id_e spi_id);

参数
- spi_id: [入] SPI ID。有关详细信息，请参见 ql_spi_id_e。
返回值
结果代码。有关详细信息，请参见 ql_spi_errcode_e。

ql_spi_write_bytes

此函数发送 SPI 数据。

原型

ql_spi_errcode_e ql_spi_write_bytes(ql_spi_id_e spi_id, void *data, uint32 size);

参数
- spi_id: [入] SPI ID。有关详细信息，请参见 ql_spi_id_e。
- data: [入] 发送的 SPI 数据。
- size: [入] 发送的 SPI 数据的长度。单位：字节。
返回值
结果代码。有关详细信息，请参见 ql_spi_errcode_e。

ql_spi_read_bytes

此函数读取 SPI 数据。

原型

ql_spi_errcode_e ql_spi_read_bytes(ql_spi_id_e spi_id, void *data, uint32 size);

参数
- spi_id: [入] SPI ID。有关详细信息，请参见 ql_spi_id_e。
- data: [出] 读取 SPI 数据的缓冲区。
- size: [入] 读取数据的长度。单位：字节。
返回值
结果代码。有关详细信息，请参见 ql_spi_errcode_e。

ql_spi_transfer

此函数发送和接收 SPI 数据。

原型

ql_spi_errcode_e ql_spi_transfer(ql_spi_id_e spi_id, ql_spi_message_s *spi_msg);

参数
- spi_id: [入] SPI ID。有关详细信息，请参见 ql_spi_id_e。
- spi_msg: [入] 发送或接收的 SPI 数据。有关详细信息，请参见 ql_spi_message_s。
返回值
结果代码。有关详细信息，请参见 ql_spi_errcode_e。

ql_spi_message_s

发送或接收的 SPI 数据的结构：

typedef struct {
    const void *send_buf;
    uint32 send_len;
    void *recv_buf;
    uint32 recv_len;
} ql_spi_message_s;

参数

类型	参数	描述
const void	send_buf	发送的数据。
uint32	send_len	发送数据的长度。单位：字节。
void	recv_buf	接收的数据。
uint32	recv_len	接收数据的长度。单位：字节。

SPI 开发过程

本章解释如何在应用程序中使用上述 SPI API，并执行基本调试，以及测试主设备和从设备的数据传输。

SPI 操作

模块 SDK 中提供了使用 SPI API 的示例。在 ql_application/examplespi_demoql_spi_demo.c 文件中。相关函数的描述如下：

ql_spi_demo_thread_creat()：此函数创建 SPI 任务。调用此函数以运行 SPI 演示。
ql_spi_demo_thread()：此函数执行 SPI 任务。它初始化 SPI 并发送 SPI 数据。

要运行此示例，请启用 CFG_ENABLE_QUECTEL_SPI 宏定义。这将自动触发 ql_spi_demo_thread_creat() 的执行以创建测试任务。

示例：创建 SPI 任务

示例：使用 SPI API

函数调试

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

运行 SPI 操作 中解释的 SPI 演示。
重新编译固件版本并将其烧录到模块。
重启模块。
通过逻辑分析仪捕获 SPI 波形。
打开 UART2 以获取调试日志。日志信息将如下显示。

通过 UART 端口工具捕获日志

通过逻辑分析仪捕获 SPI 波形

ADC API

头文件

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

API 描述

ql_adc_init

此函数初始化 ADC。

原型

ql_adc_errcode_e ql_adc_init(void);

参数
无
返回值
结果代码。有关详细信息，请参见 ql_adc_errcode_e。

ql_adc_errcode_e

ADC API 结果代码的枚举：

typedef enum
{
    QL_ADC_SUCCESS = 0,
    QL_ADC_EXECUTE_ERR,
    QL_ADC_INVALID_PARAM_ERR
} ql_adc_errcode_e;

成员

成员	描述
QL_ADC_SUCCESS	执行成功
QL_ADC_EXECUTE_ERR	执行失败
QL_ADC_INVALID_PARAM_ERR	参数无效

ql_adc_deinit

此函数取消初始化 ADC 并释放使用的资源。

ql_adc_errcode_e ql_adc_deinit(void);

参数
无
返回值
结果代码。有关详细信息，请参见 ql_adc_errcode_e。

ql_adc_start

此函数启动 ADC 通道检测。

ql_adc_errcode_e ql_adc_start(ql_adc_channel_e chan);

参数
- chan: [入] ADC 通道号。有关详细信息，请参见 ql_adc_channel_e。
返回值
结果代码。有关详细信息，请参见 ql_adc_errcode_e。

ql_adc_channel_e

ADC 通道号的枚举。

typedef enum
{
    QL_ADC_CHANNEL_1 = 1,
    QL_ADC_CHANNEL_2,
    QL_ADC_CHANNEL_3,
    QL_ADC_CHANNEL_4,
    QL_ADC_CHANNEL_5,
    QL_ADC_CHANNEL_6
} ql_adc_channel_e;

成员

成员	描述
QL_ADC_CHANNEL_1	ADC1
QL_ADC_CHANNEL_2	ADC2
QL_ADC_CHANNEL_3	ADC3
QL_ADC_CHANNEL_4	ADC4
QL_ADC_CHANNEL_5	ADC5
QL_ADC_CHANNEL_6	ADC6

由于 ADC5 和 ADC6 通道在硬件上占用 UART 接口引脚，不推荐使用这两个通道。有关详细信息，请参见 硬件设计 文档。

ql_adc_stop

此函数停止 ADC 通道检测。

原型

ql_adc_errcode_e ql_adc_stop(ql_adc_channel_e chan);

参数
- chan: [入] ADC 通道号。有关详细信息，请参见 ql_adc_channel_e。
返回值
结果代码。有关详细信息，请参见 ql_adc_errcode_e。

ql_adc_read

此函数从指定的 ADC 通道读取采样数据。

原型

ql_adc_errcode_e ql_adc_read(ql_adc_channel_e chan, uint16 *data, uint32 timeout);

参数
- chan: [入] ADC 通道号。有关详细信息，请参见 ql_adc_channel_e。
- data: [出] 读取的采样数据。
- timeout: [入] 数据读取的超时时间。
返回值
结果代码。有关详细信息，请参见 ql_adc_errcode_e。

ADC 开发过程

本章解释如何在应用程序中使用上述 ADC API 并执行基本调试。在以下子节中，ADC 通道 3 和 4 用作示例。

ADC 操作

模块 SDK 中提供了使用 ADC API 的示例。在 ql_application/example/adc_demo/ql_adc_demo.c 文件中。相关函数的描述如下：

ql_adc_demo_thread_creat()：此函数创建 ADC 任务。调用函数以运行 ADC 演示。
ql_adc_demo_thread()：此函数执行 ADC 任务。它初始化 ADC 并检测电压。

要运行演示，请启用 CFG_ENABLE_QUECTEL_ADC 宏定义。这将自动触发 ql_adc_demo_thread_creat() 和 ql_adc_demo_thread() 的执行以创建测试任务，如下所示。

示例：创建 ADC 任务

示例：使用 ADC API

函数调试

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

运行 ADC 操作 中解释的 ADC 演示。
重新编译固件版本并将其烧录到模块。
重启模块。
打开 UART 端口 2 以捕获调试日志。更改引脚的输入电压，检测值相应变化。日志信息将如下显示：

通过 UART 端口工具捕获日志

PWM API

头文件

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

API 描述

ql_pwm_init

此函数初始化 PWM。

原型

ql_pwm_errcode_e ql_pwm_init(ql_pwm_channel_e chan, uint32 period, uint32 duty);

参数
- chan: [入] PWM 通道。有关详细信息，请参见 ql_pwm_channel_e。
- period: [入] PWM 周期。实际输出频率：F = 26 MHz / period。
- duty: [入] PWM 占空比。小于 period 值。
返回值
结果代码。有关详细信息，请参见 ql_pwm_errcode_e。

ql_pwm_channel_e

PWM 通道的枚举。

typedef enum {
    QL_PWM_0 = 0,
    QL_PWM_1,
    QL_PWM_2,
    QL_PWM_3,
    QL_PWM_4,
    QL_PWM_5
} ql_pwm_channel_e;

成员

成员	描述
QL_PWM_0	PWM 0
QL_PWM_1	PWM 1
QL_PWM_2	PWM 2
QL_PWM_3	PWM 3
QL_PWM_4	PWM 4
QL_PWM_5	PWM 5

ql_pwm_errcode_e

PWM API 结果代码的枚举：

typedef enum {
    QL_PWM_SUCCESS = 0,
    QL_PWM_EXECUTE_ERR,
    QL_PWM_INVALID_PARAM_ERR
} ql_pwm_errcode_e;

成员

成员	描述
QL_PWM_SUCCESS	执行成功
QL_PWM_EXECUTE_ERR	执行失败
QL_PWM_INVALID_PARAM_ERR	参数无效

ql_pwm_deinit

此函数取消初始化 PWM。

ql_pwm_errcode_e ql_pwm_deinit(ql_pwm_channel_e pwm_channel);

参数
- pwm_channel: [入] PWM 通道。有关详细信息，请参见 ql_pwm_channel_e。
返回值
结果代码。有关详细信息，请参见 ql_pwm_errcode_e。

ql_pwm_enable

此函数启用 PWM 输出。

原型

ql_pwm_errcode_e ql_pwm_enable(ql_pwm_channel_e pwm_channel);

参数
- pwm_channel: [入] PWM 通道。有关详细信息，请参见 ql_pwm_channel_e。
返回值
结果代码。有关详细信息，请参见 ql_pwm_errcode_e。

ql_pwm_disable

此函数禁用 PWM 输出。

原型

ql_pwm_errcode_e ql_pwm_disable(ql_pwm_channel_e pwm_channel);

参数
- pwm_channel: [入] PWM 通道。有关详细信息，请参见 ql_pwm_channel_e。
返回值
结果代码。有关详细信息，请参见 ql_pwm_errcode_e。

ql_pwm_update_param

此函数更新 PWM 配置的参数。配置在下一个 PWM 周期生效。

原型

ql_pwm_errcode_e ql_pwm_update_param(ql_pwm_channel_e pwm_channel, uint32 period, uint32 duty_cycle);

参数
- pwm_channel: [入] PWM 通道。有关详细信息，请参见 ql_pwm_channel_e。
- period: [入] PWM 周期。实际输出频率：F = 26 MHz / period。
- duty_cycle: [入] PWM 占空比。小于 period 值。
返回值
结果代码。有关详细信息，请参见 ql_pwm_errcode_e。

PWM 开发过程

本章解释如何在应用程序中使用上述 PWM API 并执行基本调试。在以下子节中，对应 PWM0 的 GPIO6 引脚用作示例。

PWM 操作

模块 SDK 中提供了使用 PWM API 的示例。在 ql_application/example/pwm_demo/ql_pwm_demo.c 文件中。相关函数的描述如下：

ql_pwm_demo_thread_creat()：此函数创建 PWM 任务。调用函数以运行 PWM 演示。

要运行演示，请启用 CFG_ENABLE_QUECTEL_PWM 宏定义。这将自动触发 ql_pwm_demo_thread_creat() 的执行以创建测试任务。

示例：创建 PWM 任务

示例：使用 PWM API

函数调试

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

运行 PWM 操作 中解释的 PWM 演示。
重新编译固件版本并将其烧录到模块。
重启模块。
通过逻辑分析仪捕获 PWM0 的引脚波形。
打开 UART2 以获取调试日志。日志信息将如下显示：

通过 UART 端口工具捕获日志

通过逻辑分析仪捕获 PWM 波形

I2C API

头文件

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

API 描述

ql_i2c_init

此函数初始化 I2C 总线。

原型

ql_i2c_errcode_e ql_i2c_init(ql_i2c_id_e iic_id, ql_i2c_speed_mode_e speed_mode, ql_i2c_addr_mode_e addr_mode, uint16 slave_addr);

参数
- iic_id: [入] I2C 总线 ID。有关详细信息，请参见 ql_i2c_id_e。目前仅支持 I2C2。
- speed_mode: [入] I2C 时钟频率。有关详细信息，请参见 ql_i2c_speed_mode_e。
- addr_mode: [入] 从设备地址的长度。有关详细信息，请参见 ql_i2c_addr_mode_e。
- slave_addr: [入] 模块作为主设备或从设备时用于通信的地址。
返回值
结果代码。有关详细信息，请参见 ql_i2c_errcode_e。

ql_i2c_id_e

I2C 总线 ID 的枚举：

typedef enum {
    QL_I2C2 = 0
} ql_i2c_id_e;

成员

成员	描述
QL_I2C2	I2C2

ql_i2c_speed_mode_e

I2C 时钟频率的枚举：

typedef enum {
    QL_I2C_SPEED_STANDARD = 0,
    QL_I2C_SPEED_FAST
} ql_i2c_speed_mode_e;

成员

成员	描述
QL_I2C_SPEED_STANDARD	标准模式（时钟频率为 100 kHz）
QL_I2C_SPEED_FAST	快速模式（时钟频率为 400 kHz）

ql_i2c_addr_mode_e

从设备地址长度的枚举：

typedef enum {
    QL_I2C_ADDR_SIZE_7BIT = 0,
    QL_I2C_ADDR_SIZE_10BIT
} ql_i2c_addr_mode_e;

成员

成员	描述
QL_I2C_ADDR_SIZE_7BIT	从设备地址长度为 7 位。
QL_I2C_ADDR_SIZE_10BIT	从设备地址长度为 10 位（目前不支持）。

ql_i2c_errcode_e

I2C API 结果代码的枚举：

typedef enum {
    QL_I2C_SUCCESS = 0,
    QL_I2C_INIT_ERR,
    QL_I2C_ID_INIT_ERR,
    QL_I2C_SM_BUS_ERR,
    QL_I2C_ACK_TIMEOUT_ERR,
    QL_I2C_WRITE_ERR,
    QL_I2C_READ_ERR
} ql_i2c_errcode_e;

成员

成员	描述
QL_I2C_SUCCESS	执行成功
QL_I2C_INIT_ERR	I2C 初始化失败
QL_I2C_ID_INIT_ERR	I2C 总线 ID 错误
QL_I2C_SM_BUS_ERR	I2C 总线错误
QL_I2C_ACK_TIMEOUT_ERR	获取 ACK 超时
QL_I2C_WRITE_ERR	向 I2C 总线写入数据失败
QL_I2C_READ_ERR	从 I2C 总线读取数据失败

ql_i2c_deinit

此函数释放 I2C 资源。

原型

ql_i2c_errcode_e ql_i2c_deinit(ql_i2c_id_e iic_id);

参数
- iic_id: [入] I2C 总线 ID。有关详细信息，请参见 ql_i2c_id_e。目前仅支持 I2C2。
返回值
结果代码。有关详细信息，请参见 ql_i2c_errcode_e。

ql_i2c_master_write

此函数在 I2C 主模式下发送数据。

原型

ql_i2c_errcode_e ql_i2c_master_write(ql_i2c_id_e iic_id,uint32 dev_addr,const uint8* data,uint32 size);

参数
- iic_id: [入] I2C 总线 ID。有关详细信息，请参见 ql_i2c_id_e。目前仅支持 I2C2。
- dev_addr: [入] I2C 从设备地址。
- data: [出] 发送数据的缓冲区。
- size: [入] 发送数据的长度。单位：字节。
返回值
结果代码。有关详细信息，请参见 ql_i2c_errcode_e。

ql_i2c_master_read

此函数在 I2C 主模式下接收数据。

原型

ql_i2c_errcode_e ql_i2c_master_read(ql_i2c_id_e iic_id,uint32 dev_addr,uint8 *data,uint32 size);

参数
- iic_id: [入] I2C 总线 ID。有关详细信息，请参见 ql_i2c_id_e。目前仅支持 I2C2。
- dev_addr: [入] I2C 从设备地址。
- data: [入] 接收数据的缓冲区。
- size: [入] 接收数据的长度。单位：字节。
返回值
结果代码。有关详细信息，请参见 ql_i2c_errcode_e。

ql_i2c_master_mem_write

此函数在 I2C 主模式下发送数据并发送从设备的内存地址。

原型

ql_i2c_errcode_e ql_i2c_master_mem_write(ql_i2c_id_e iic_id,uint32 dev_addr,uint32 mem_addr,ql_i2c_mem_addr_size_e mem_size,uint8* data,uint32 size);

参数
- iic_id: [入] I2C 总线 ID。有关详细信息，请参见 ql_i2c_id_e。目前仅支持 I2C2。
- dev_addr: [入] I2C 从设备地址。
- mem_addr: [入] 从设备的内存地址。
- mem_size: [入] 从设备内存地址的大小。有关详细信息，请参见 ql_i2c_mem_addr_size_e。
- data: [出] 发送数据的缓冲区。
- size: [入] 发送数据的长度。单位：字节。
返回值
结果代码。有关详细信息，请参见 ql_i2c_errcode_e。

ql_i2c_mem_addr_size_e

内存地址大小的枚举：

typedef enum {
    QL_I2C_MEM_ADDR_SIZE_8BIT = 0,
    QL_I2C_MEM_ADDR_SIZE_16BIT
} ql_i2c_mem_addr_size_e;

成员

成员	描述
QL_I2C_MEM_ADDR_SIZE_8BIT	内存地址大小为 8 位
QL_I2C_MEM_ADDR_SIZE_16BIT	内存地址大小为 16 位

ql_i2c_master_mem_read

此函数在 I2C 主模式下接收数据并发送从设备的内存地址。

原型

ql_i2c_errcode_e ql_i2c_master_mem_read(ql_i2c_id_e iic_id,uint32 dev_addr,uint32 mem_addr,ql_i2c_mem_addr_size_e mem_size,uint8* data,uint32 size);

参数
- iic_id: [入] I2C 总线 ID。有关详细信息，请参见 ql_i2c_id_e。目前仅支持 I2C2。
- dev_addr: [入] I2C 从设备地址。
- mem_addr: [入] 从设备的内存地址。
- mem_size: [入] 从设备内存地址的大小。有关详细信息，请参见 ql_i2c_mem_addr_size_e。
- data: [入] 接收数据的缓冲区。
- size: [入] 接收数据的长度。单位：字节。
返回值
结果代码。有关详细信息，请参见 ql_i2c_errcode_e。

I2C 开发过程

本章解释如何在应用程序中使用上述 I2C API 并执行基本调试。I2C 需要使用外设进行通信。在此示例中应用了 EEPROM 芯片（型号：AT24C02）。

I2C 操作

模块 SDK 中提供了使用 I2C API 的示例。在 ql_application/example/i2c_eeprom_demo/ql_i2c_eeprom_demo.c 文件中。相关函数的描述如下：

ql_i2c_demo_thread_creat()：此函数创建 I2C 任务。调用此函数以运行演示。

要运行此演示，请启用 CFG_ENABLE_QUECTEL_I2C2 宏定义。这将自动触发 ql_i2c_demo_thread_creat() 的执行以创建测试任务。

示例：创建 I2C 任务

示例：使用 I2C API

函数调试

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

运行 I2C 操作 中解释的 I2C 演示。
重新编译固件版本并将其烧录到模块。
重启模块。
打开 UART2 以获取调试日志。日志信息将如下显示：

通过 UART 端口工具捕获日志

如上图所示，可以成功写入和读取数据。因此，可以说 I2C 函数测试已通过。

附录参考

术语和缩略语

缩略语	描述
ACK	确认
ADC	模数转换器
API	应用程序编程接口
CLK	时钟
FC	流控制
CTS	清除发送
EEPROM	电可擦可编程只读存储器
GPIO	通用输入/输出
HW	硬件
I2C	集成电路间通信
ID	标识符
IoT	物联网
LSB	最低有效位
MSB	最高有效位
PWM	脉冲宽度调制
RTOS	实时操作系统
RTS	请求发送
SCK	串行时钟
SDK	软件开发工具包
SPI	串行外围接口
UART	通用异步接收器/发射器

RTOS 开发指南

综合测试报告

ShortRange

外设接口开发指南

简介

GPIO API

头文件

API 描述

ql_gpio_init

ql_gpio_num_e

ql_gpio_mode_e

ql_gpio_errcode_e

ql_gpio_deinit

ql_gpio_set_level

ql_gpio_level_e

ql_gpio_set_level_reverse

ql_gpio_get_level

ql_gpio_int_init

ql_gpio_irq_trigger_e

ql_gpio_irq_callback

ql_gpio_int_disable

GPIO 开发过程

GPIO 操作

函数调试

UART API

头文件

API 描述

ql_uart_set_dcbconfig

ql_uart_port_number_e

ql_uart_config_s

ql_uart_baud_e

ql_uart_databit_e

ql_uart_stopbit_e

ql_uart_paritybit_e

ql_uart_flowctrl_e

ql_uart_errcode_e

ql_uart_get_dcbconfig

ql_uart_open

ql_uart_close

ql_uart_write_ready

ql_uart_write

ql_uart_read

ql_uart_read_prefetch

ql_uart_get_rx_count

ql_uart_set_rx_cb

ql_uart_set_tx_cb

ql_uart_set_tx_int

UART 开发过程

UART 操作

函数调试

SPI API

头文件

API 描述

ql_spi_init

ql_spi_id_e

ql_spi_config_s

ql_spi_role_e

ql_spi_pol_pha_mode_e

ql_spi_bit_order_e

ql_spi_errcode_e

ql_spi_deinit

ql_spi_write_bytes

ql_spi_read_bytes

ql_spi_transfer

ql_spi_message_s

SPI 开发过程

SPI 操作

函数调试

ADC API

头文件

API 描述

ql_adc_init

ql_adc_errcode_e

ql_adc_deinit

ql_adc_start

ql_adc_channel_e

ql_adc_stop

ql_adc_read

ADC 开发过程

ADC 操作

函数调试

PWM API