AT 组件

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

(

ch

)

at_obj_set_end_sign(at_client_get_first(), ch)

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

参数

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 Server 中基础命令 ATZ 的实现。