AT 组件

优质

小牛编辑

139浏览

2023-12-01

AT 组件接口

结构体
struct	at_cmd
	AT 命令控制块更多...

struct	at_server
	AT Serve 控制块更多...

struct	at_response
	AT Server 响应数据控制块更多...

struct	at_client
	AT Client 控制块更多...

宏定义
#define	at_exec_cmd(resp, ...) at_obj_exec_cmd(at_client_get_first(), resp, __VA_ARGS__)
	发送命令并接收响应（单客户端模式）

#define	at_client_wait_connect(timeout) at_client_obj_wait_connect(at_client_get_first(), timeout)
	等待模块初始化完成（单客户端模式）

#define	at_client_send(buf, size) at_client_obj_send(at_client_get_first(), buf, size)
	发送指定长度数据（单客户端模式）

#define	at_client_recv(buf, size, timeout) at_client_obj_recv(at_client_get_first(), buf, size, timeout)
	接收指定长度数据（单客户端模式）

#define	at_set_end_sign(ch) at_obj_set_end_sign(at_client_get_first(), ch)
	设置接收数据的行结束符（单客户端模式）

#define	at_set_urc_table(urc_table, table_sz) at_obj_set_urc_table(at_client_get_first(), urc_table, table_sz)
	URC 数据列表初始化（单客户端模式）

类型定义
typedef enum at_result	at_result_t
	AT 命令错误类型定义

typedef struct at_cmd *	at_cmd_t
	AT 命令类型定义

typedef struct at_server *	at_server_t
	AT Serve 类型定义

typedef struct at_response *	at_response_t
	AT Server 响应数据类型定义

枚举

函数
void	at_server_printf (const char *format,...)
	发送数据至客户端（不换行）

void	at_server_printfln (const char *format,...)
	发送数据至客户端（换行）

void	at_server_print_result (at_result_t result)
	发送命令执行结果至客户端

int	at_req_parse_args (const char req_args, const char req_expr,...)
	解析输入命令参数

int	at_client_init (const char *dev_name, rt_size_t recv_bufsz)
	AT Client 初始化

at_client_t	at_client_get (const char *dev_name)
	获取 AT 客户端对象

at_client_t	at_client_get_first (void)
	获取列表中第一个 AT 模块

int	at_client_obj_wait_connect (at_client_t client, rt_uint32_t timeout)
	等待模块初始化完成

rt_size_t	at_client_obj_send (at_client_t client, const char *buf, rt_size_t size)
	发送指定长度数据

rt_size_t	at_client_obj_recv (at_client_t client, char *buf, rt_size_t size, rt_int32_t timeout)
	接收指定长度数据

void	at_obj_set_end_sign (at_client_t client, char ch)
	设置接收数据的行结束符

void	at_obj_set_urc_table (at_client_t client, const struct at_urc *table, rt_size_t size)
	URC 数据列表初始化

int	at_obj_exec_cmd (at_client_t client, at_response_t resp, const char *cmd_expr,...)
	发送命令并接收响应

at_response_t	at_create_resp (rt_size_t buf_size, rt_size_t line_num, rt_int32_t timeout)
	创建响应结构体

void	at_delete_resp (at_response_t resp)
	删除响应结构体

at_response_t	at_resp_set_info (at_response_t resp, rt_size_t buf_size, rt_size_t line_num, rt_int32_t timeout)
	设置响应结构体参数

const char *	at_resp_get_line (at_response_t resp, rt_size_t resp_line)
	获取指定行号的响应数据

const char *	at_resp_get_line_by_kw (at_response_t resp, const char *keyword)
	获取指定关键字的响应数据

int	at_resp_parse_line_args (at_response_t resp, rt_size_t resp_line, const char *resp_expr,...)
	解析指定行号的响应数据

int	at_resp_parse_line_args_by_kw (at_response_t resp, const char keyword, const char resp_expr,...)
	解析指定关键字行的响应数据

void	at_port_reset (void)
	设备重启

void	at_port_factory_reset (void)
	恢复出厂设置

详细描述

AT 组件接口

AT 组件是基于 RT-Thread 系统的 AT Server 和 AT Client 的实现，组件完成 AT 命令的发送、命令格式及参数判断、命令的响应、响应数据的接收、响应数据的解析、URC 数据处理等整个 AT 命令数据交互流程。通过 AT 组件设备可以作为 AT Client 使用串口连接其他设备发送并接收解析数据，可以作为 AT Server 让其他设备甚至电脑端连接完成发送数据的响应，也可以在本地 shell 启动 CLI 模式使设备同时支持 AT Server 和 AT Client 功能，该模式多用于设备开发调试。

AT Server 主要功能特点：

基础命令：实现多种通用基础命令（ATE、ATZ等）；
命令兼容：命令支持忽略大小写，提高命令兼容性；
命令检测：命令支持自定义参数表达式，并实现对接收的命令参数自检测功能；
命令注册：提供简单的用户自定义命令添加方式，类似于 finsh/msh 命令添加方式；
调试模式：提供 AT Server CLI 命令行交互模式，主要用于设备调试。

AT Client 主要功能：

URC 数据处理：完备的 URC 数据的处理方式；
数据解析：支持自定义响应数据的解析方式，方便获取响应数据中相关信息；
调试模式：提供 AT Client CLI 命令行交互模式，主要用于设备调试。
AT Socket：作为 AT Client 功能的延伸，使用 AT 命令收发作为基础，实现标准的 BSD Socket API，完成数据的收发功能，使用户通过 AT 命令完成设备连网和数据通讯。
多客户端支持： AT 组件目前支持多客户端同时运行

宏定义说明

#define at_exec_cmd	(	resp,
		...
	)	at_obj_exec_cmd(at_client_get_first(), resp, __VA_ARGS__)

发送命令并接收响应（单客户端模式）

参数

resp	创建的响应结构体指针
...	输入命令数据列表，为可变参数

#define at_client_wait_connect

(

timeout

)

at_client_obj_wait_connect(at_client_get_first(), timeout)

等待模块初始化完成（单客户端模式）

参数

timeout

等待超时时间

#define at_client_send	(	buf,
		size
	)	at_client_obj_send(at_client_get_first(), buf, size)

发送指定长度数据（单客户端模式）

参数

buf	发送数据的指针
size	发送数据的长度

#define at_client_recv	(	buf,
		size,
		timeout
	)	at_client_obj_recv(at_client_get_first(), buf, size, timeout)

接收指定长度数据（单客户端模式）

参数

buf	接收数据的指针
size	最大支持接收数据的长度
timeout	最大等待时间，数据接收超时返回错误。

#define at_set_end_sign

(

)

at_obj_set_end_sign(at_client_get_first(), ch)

设置接收数据的行结束符（单客户端模式）

参数

行结束符。

#define at_set_urc_table	(	urc_table,
		table_sz
	)	at_obj_set_urc_table(at_client_get_first(), urc_table, table_sz)

URC 数据列表初始化（单客户端模式）

参数

urc_table	URC 数据结构体数组指针
table_sz	URC 数据的个数。

枚举类型说明

enum at_result

AT 命令错误类型

枚举值
AT_RESULT_OK	无错误
AT_RESULT_FAILE	一般错误
AT_RESULT_NULL	结果不需要返回
AT_RESULT_CMD_ERR	AT命令格式错误或无法执行
AT_RESULT_CHECK_FAILE	AT命令表达式格式错误
AT_RESULT_PARSE_FAILE	AT命令参数解析错误

函数说明

void at_server_printf	(	const char *	format,
			...
	)

发送数据至客户端（不换行）

该函数用于 AT Server 通过串口设备发送固定格式的数据到对应的 AT Client 串口设备上，数据结尾不带换行符。用于自定义 AT Server 中 AT 命令的功能函数中。

参数

format	自定义输入数据的表达式
...	输入数据列表，为可变参数

void at_server_printfln	(	const char *	format,
			...
	)

发送数据至客户端（换行）

该函数用于 AT Server 通过串口设备发送固定格式的数据到对应的 AT Client 串口设备上，数据结尾带换行符。用于自定义 AT Server 中 AT 命令的功能函数中。

参数

format	自定义输入数据的表达式
...	输入数据列表，为可变参数

void at_server_print_result

(

at_result_t

result

)

发送命令执行结果至客户端

该函数用于 AT Server 通过串口设备发送命令执行结果到对应的 AT Client 串口设备上。 AT 组件提供多种固定的命令执行结果类型，自定义命令时可以直接使用函数返回结果。

AT 组件中命令执行结果类型以枚举类型给出，如下表所示：

命令执行结果类型	解释
AT_RESULT_OK	命令执行成功
AT_RESULT_FAILE	命令执行失败
AT_RESULT_NULL	命令无返回结果
AT_RESULT_CMD_ERR	输入命令错误
AT_RESULT_CHECK_FAILE	参数表达式匹配错误
AT_RESULT_PARSE_FAILE	参数解析错误

参数

result

命令执行结果类型

int at_req_parse_args	(	const char *	req_args,
		const char *	req_expr,
			...
	)

解析输入命令参数

一个 AT 命令的四种功能函数中，只有设置函数有入参，该入参为去除 AT 命令剩余部分，例如一个命令输入为 "AT+TEST=1,2,3,4"，则设置函数的入参为参数字符串 "=1,2,3,4" 部分。

该命令解析函数主要用于 AT 命令的设置函数中，用于解析传入字符串参数，得到对应的多个输入参数，用于执行后面操作，这里的解析语法使用的标准 sscanf 解析语法，后面 AT Client 参数解析函数中会详细介绍。

参数

req_args	请求命令的传入参数字符串
req_expr	自定义参数解析表达式，用于解析上述传入参数数据
...	输出的解析参数列表，为可变参数

返回

返回	描述
>0	成功，返回匹配参数表达式的可变参数个数
=0	失败，无匹配参数表达式的参数
-1	失败，参数解析错误

int at_client_init	(	const char *	dev_name,
		rt_size_t	recv_bufsz
	)

AT Client 初始化

配置开启 AT Client 配置之后，需要在启动时对它进行初始化，开启 AT client 功能，如果程序中已经使用了组件自动初始化，则不再需要额外进行单独的初始化，否则需要在初始化任务中调用该函数。

AT Client 初始化函数，属于应用层函数，需要在使用 AT Client 功能或者使用 AT Client CLI 功能前调用。 at_client_init 函数完成对 AT Client 设备初始化、AT Client 移植函数的初始化、AT Client 使用的信号量、互斥锁等资源初始化，并创建 at_client 线程用于 AT Client 中数据的接收的解析以及对 URC 数据的处理。

参数

dev_name	设备名称
recv_bufsz	接收缓冲区大小

返回

返回	描述
RT_EOK	成功
-RT_ERROR	失败，未找到设备
-RT_EFULL	失败，AT客户端已达设定的最大数

at_client_t at_client_get

(

const char *

dev_name

)

获取 AT 客户端对象

该函数通过传入的设备名称获取该设备创建的 AT 客户端对象，用于多客户端连接时区分不同的客户端。

参数

dev_name

获取的客户端对象

返回: RT_NULL 失败；成功则返回客户端指控制块。

at_client_t at_client_get_first

(

void

)

获取列表中第一个 AT 模块

返回: RT_NULL 列表为空；成功则返回第一个客户端指控制块。

int at_client_obj_wait_connect	(	at_client_t	client,
		rt_uint32_t	timeout
	)

等待模块初始化完成

该函数用于 AT 模块启动时循环发送 AT 命令，直到模块响应数据，说明模块启动成功。

参数

client	获取的客户端对象
timeout	等待超时时间

返回: 0 成功；小于0 失败，超时时间内无数据返回。

rt_size_t at_client_obj_send	(	at_client_t	client,
		const char *	buf,
		rt_size_t	size
	)

发送指定长度数据

该函数用于通过 AT Client 设备发送指定长度数据到 AT Server 设备，多用于 AT Socket 功能。

参数

client	获取的客户端对象
buf	发送数据的指针
size	发送数据的长度

返回

返回	描述
>0	成功，返回发送成功的数据长度
<=0	失败

rt_size_t at_client_obj_recv	(	at_client_t	client,
		char *	buf,
		rt_size_t	size,
		rt_int32_t	timeout
	)

接收指定长度数据

该函数用于通过 AT Client 设备接收指定长度的数据，多用于 AT Socket 功能。 该函数只能在 URC 回调处理函数中使用 。

参数

client	获取的客户端对象
buf	接收数据的指针
size	最大支持接收数据的长度
timeout	最大等待时间，数据接收超时返回错误。

返回

返回	描述
>0	成功，返回接收成功的数据长度
<=0	失败

void at_obj_set_end_sign	(	at_client_t	client,
		char	ch
	)

设置接收数据的行结束符

该函数用于设置行结束符，用于判断客户端接收一行数据的结束, 多用于 AT Socket 功能。

参数

client	获取的客户端对象
ch	行结束符

void at_obj_set_urc_table	(	at_client_t	client,
		const struct at_urc *	table,
		rt_size_t	size
	)

URC 数据列表初始化

该函数用于初始化开发者自定义的 URC 数据列表，主要在 AT Client 移植函数中使用。

参数

client	获取的客户端对象
table	URC 数据结构体数组指针
size	URC 数据的个数

int at_obj_exec_cmd	(	at_client_t	client,
		at_response_t	resp,
		const char *	cmd_expr,
			...
	)

发送命令并接收响应

该函数用于 AT Client 发送命令到 AT Server，并等待接收响应，其中 resp 是已经创建好的响应结构体的指针，AT 命令的使用匹配表达式的可变参输入， 输入命令的结尾不需要添加命令结束符 。

参数

client	获取的客户端对象
resp	创建的响应结构体指针
cmd_expr	自定义输入命令的表达式
...	输入命令数据列表，为可变参数

返回

返回	描述
>=0	成功
-1	失败
-2	失败，接收响应超时

at_response_t at_create_resp	(	rt_size_t	buf_size,
		rt_size_t	line_num,
		rt_int32_t	timeout
	)

创建响应结构体

该函数用于创建自定义的响应数据接收结构，用于后面接收并解析发送命令响应数据。

参数

buf_size	本次响应最大支持的接收数据的长度
line_num	本次响应需要返回数据的行数，行数是以标准结束符划分若为 0 ，则接收到 "OK" 或 "ERROR" 数据后结束本次响应接收若大于 0，接收完当前设置行号的数据后返回成功
timeout	本次响应数据最大响应时间，数据接收超时返回错误。

返回

返回	描述
!= NULL	成功，返回指向响应结构体的指针
= NULL	失败，内存不足

void at_delete_resp

(

at_response_t

resp

)

删除响应结构体

该函数用于删除创建的响应结构体对象，一般与 at_create_resp 创建函数成对出现。

参数

resp	准备删除的响应结构体指针

at_response_t at_resp_set_info	(	at_response_t	resp,
		rt_size_t	buf_size,
		rt_size_t	line_num,
		rt_int32_t	timeout
	)

设置响应结构体参数

该函数用于设置已经创建的响应结构体信息，主要设置对响应数据的限制信息，一般用于创建结构体之后，发送 AT 命令之前。

参数

resp	已经创建的响应结构体指针
buf_size	本次响应最大支持的接收数据的长度
line_num	本次响应需要返回数据的行数，行数是以标准结束符划分若为 0 ，则接收到 "OK" 或 "ERROR" 数据后结束本次响应接收若大于 0，接收完当前设置行号的数据后返回成功
timeout	本次响应数据最大响应时间，数据接收超时返回错误。

返回

返回	描述
!= NULL	成功，返回指向响应结构体的指针
= NULL	失败，内存不足

const char* at_resp_get_line	(	at_response_t	resp,
		rt_size_t	resp_line
	)

获取指定行号的响应数据

该函数用于在 AT Server 响应数据中获取指定行号的一行数据。行号是以标准数据结束符来判断的，上述发送和接收函数 at_exec_cmd 已经对响应数据的数据和行号进行记录处理存放于 resp 响应结构体中，这里可以直接获取对应行号的数据信息。

参数

resp	响应结构体指针
resp_line	需要获取数据的行号

返回

返回	描述
!= NULL	成功，返回对应行号数据的指针
= NULL	失败，输入行号错误

const char* at_resp_get_line_by_kw	(	at_response_t	resp,
		const char *	keyword
	)

获取指定关键字的响应数据

该函数用于在 AT Server 响应数据中通过关键字获取对应的一行数据。

参数

resp	响应结构体指针
keyword	关键字信息

返回

返回	描述
!= NULL	成功，返回对应行号数据的指针
= NULL	失败，未找到关键字信息

int at_resp_parse_line_args	(	at_response_t	resp,
		rt_size_t	resp_line,
		const char *	resp_expr,
			...
	)

解析指定行号的响应数据

该函数用于在 AT Server 响应数据中获取指定行号的一行数据, 并解析该行数据中的参数。

参数

resp	响应结构体指针
resp_line	需要解析数据的行号
resp_expr	自定义的参数解析表达式
...	解析参数列表，为可变参数

返回

返回	描述
>0	成功，返回解析成功的参数个数
=0	失败，无匹参配数解析表达式的参数
-1	失败，参数解析错误

int at_resp_parse_line_args_by_kw	(	at_response_t	resp,
		const char *	keyword,
		const char *	resp_expr,
			...
	)

解析指定关键字行的响应数据

该函数用于在 AT Server 响应数据中获取包含关键字的一行数据, 并解析该行数据中的参数。

参数

resp	响应结构体指针
keyword	关键字信息
resp_expr	自定义的参数解析表达式
...	解析参数列表，为可变参数

返回

返回	描述
>0	成功，返回解析成功的参数个数
=0	失败，无匹参配数解析表达式的参数
-1	失败，参数解析错误

void at_port_reset

(

void

)

设备重启

该函数完成设备软重启功能，用于 AT Server 中基础命令 AT+RST 的实现。

void at_port_factory_reset

(

void

)

恢复出厂设置

AT 组件

结构体

宏定义

类型定义

枚举

函数

详细描述

宏定义说明

枚举类型说明

函数说明