at

AT中间件提供AT命令的注册、解析、执行和结果上报功能，支持同步和异步阻塞式命令处理、交互模式、URC主动上报以及多通道输出。

头文件清单

#include <middleware/utils/at.h>

接口清单

接口名称	功能简述
uapi_at_cmd_table_register	注册AT命令列表
uapi_at_cmd_abort_register	注册AT命令打断函数
uapi_at_send_async_result	异步阻塞式AT命令结果发送
uapi_at_interactivity_func_register	注册AT交互命令处理函数
uapi_at_report	向默认通道输出AT打印信息
uapi_at_print	向默认通道输出格式化AT打印信息
uapi_at_report_to_single_channel	向指定通道输出AT打印信息
uapi_at_urc_to_channel	向指定通道发送主动上报信息

Functions

uapi_at_cmd_table_register

函数声明

errcode_t uapi_at_cmd_table_register(const at_cmd_entry_t *table, uint32_t len, uint32_t struct_max_size)

头文件清单

#include <middleware/utils/at.h>

功能说明

注册AT命令列表到AT框架中，使AT命令可被解析和执行
将命令列表添加到全局链表中，并更新设置函数输入参数结构体的最大大小
当CONFIG_AT_SUPPORT_CMD_TABLE_CHECK开启时，会校验命令名称、命令回调函数及参数校验语法的合法性
同一命令名称不允许重复注册

前置条件

AT框架已完成初始化，uapi_at_base_api_register已调用成功
入参table不为NULL，且指向的命令列表内存已申请成功

入参

名称	参数类型	详细说明	约束取值范围
table	const at_cmd_entry_t *	AT命令列表起始地址	非NULL
len	uint32_t	AT命令列表长度	大于0
struct_max_size	uint32_t	AT命令列表中设置函数输入参数结构体的最大大小	大于0

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	参数合法，命令列表注册成功
ERRCODE_INVALID_PARAM	参数无效	table为NULL或len为0
ERRCODE_MALLOC	内存分配失败	分配链表节点内存失败
Other	其他错误码，参考errcode_t	命令表校验失败等

参考案例

middleware/utils/at/at_audio_cmd/src/at_audio_cmd_register.c
middleware/utils/at/at_bt_cmd/src/at_bt_cmd_register.c
middleware/utils/at/at_net_cmd/src/at_net_cmd_register.c

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_AT_SUPPORT_CMD_TABLE_CHECK	特性宏	支持AT命令表校验特性	n

uapi_at_cmd_abort_register

函数声明

errcode_t uapi_at_cmd_abort_register(at_abort_func_t func, void *arg)

头文件清单

#include <middleware/utils/at.h>

功能说明

注册AT命令打断函数，用于在AT命令执行过程中被打断时回调
当异步阻塞式AT命令处于执行中状态时，接收到打断请求会调用已注册的打断函数
打断函数注册后，在AT命令超时或接收到新命令时触发打断流程

前置条件

CONFIG_AT_SUPPORT_ASYNCHRONOUS宏已开启
AT框架已完成初始化
入参func不为NULL

入参

名称	参数类型	详细说明	约束取值范围
func	at_abort_func_t	AT命令打断函数指针	非NULL
arg	void *	AT命令打断函数入参	-

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	打断函数注册成功
ERRCODE_INVALID_PARAM	参数无效	func为NULL

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_AT_SUPPORT_ASYNCHRONOUS	功能宏	支持AT异步阻塞特性	n

uapi_at_send_async_result

函数声明

errcode_t uapi_at_send_async_result(uint16_t err)

头文件清单

#include <middleware/utils/at.h>

功能说明

异步阻塞式AT命令结果发送接口，用于在异步命令执行完成后发送执行结果
当err为0时表示执行成功，AT框架输出"OK\r\n"；非0表示执行失败，AT框架输出"ERROR\r\n"
调用后AT框架将继续处理消息队列中剩余的AT命令

前置条件

CONFIG_AT_SUPPORT_ASYNCHRONOUS宏已开启
当前有异步阻塞式AT命令正在执行中

入参

名称	参数类型	详细说明	约束取值范围
err	uint16_t	AT命令执行结果	0表示成功，其他值表示失败

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	结果消息发送成功
ERRCODE_AT_MSG_SEND_ERROR	消息发送失败	消息队列写入失败

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_AT_SUPPORT_ASYNCHRONOUS	功能宏	支持AT异步阻塞特性	n

uapi_at_interactivity_func_register

函数声明

errcode_t uapi_at_interactivity_func_register(at_interactivity_func_t func)

头文件清单

#include <middleware/utils/at.h>

功能说明

注册AT交互命令处理函数，用于处理AT命令交互过程中的数据上报
交互模式下，AT框架将接收到的数据传递给已注册的交互处理函数
交互处理函数返回AT_RET_PROC_WAIT_INTERACTIVITY时继续等待交互，返回AT_RET_OK时结束交互

前置条件

CONFIG_AT_SUPPORT_ASYNCHRONOUS宏已开启
AT框架已完成初始化
入参func不为NULL

入参

名称	参数类型	详细说明	约束取值范围
func	at_interactivity_func_t	AT命令交互命令处理函数指针	非NULL

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	交互函数注册成功
ERRCODE_INVALID_PARAM	参数无效	func为NULL

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_AT_SUPPORT_ASYNCHRONOUS	功能宏	支持AT异步阻塞特性	n

uapi_at_report

函数声明

void uapi_at_report(const char *str)

头文件清单

#include <middleware/utils/at.h>

功能说明

向当前AT命令对应的默认通道输出AT打印信息
输出信息必须携带字符串结束符
当str为NULL时直接返回，不执行输出操作

入参

名称	参数类型	详细说明	约束取值范围
str	const char *	AT打印信息	非NULL，必须携带字符串结束符

uapi_at_print

函数声明

void uapi_at_print(const char* str, ...)

头文件清单

#include <middleware/utils/at.h>

功能说明

向当前AT命令对应的默认通道输出格式化AT打印信息
支持可变参数格式化输出，格式化缓冲区大小由CONFIG_AT_PRINT_BUFFER_SIZE决定，默认128字节
当str为NULL或格式化结果为空时直接返回，不执行输出操作

入参

名称	参数类型	详细说明	约束取值范围
str	const char *	AT格式化打印信息	非NULL，必须携带字符串结束符
...	-	可变参数列表	-

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_AT_PRINT_BUFFER_SIZE	特性宏	支持AT打印缓冲区大小配置特性	128

uapi_at_report_to_single_channel

函数声明

void uapi_at_report_to_single_channel(at_channel_id_t channel_id, const char *str)

头文件清单

#include <middleware/utils/at.h>

功能说明

向指定通道输出AT打印信息，不限于当前命令所在通道
输出信息必须携带字符串结束符
当str为NULL时直接返回，不执行输出操作

前置条件

入参channel_id对应的通道已初始化并注册写函数
入参str不为NULL

入参

名称	参数类型	详细说明	约束取值范围
channel_id	at_channel_id_t	AT通道号	AT_UART_PORT
str	const char *	AT打印信息	非NULL，必须携带字符串结束符

uapi_at_urc_to_channel

函数声明

errcode_t uapi_at_urc_to_channel(at_channel_id_t channel_id, const char *msg, uint32_t msg_len)

头文件清单

#include <middleware/utils/at.h>

功能说明

向指定通道发送URC（Unsolicited Result Code）主动上报信息
URC信息通过消息队列异步发送，不会阻塞当前执行流
当异步阻塞式AT命令正在执行且未设置AT_FLAG_NOT_BLOCK_URC标志时，URC信息将被阻塞不输出

前置条件

CONFIG_AT_SUPPORT_NOTIFY_REPORT宏已开启
AT框架已完成初始化，包含互斥锁相关API已注册
入参msg不为NULL且msg_len大于0

入参

名称	参数类型	详细说明	约束取值范围
channel_id	at_channel_id_t	AT通道号	AT_UART_PORT
msg	const char *	主动上报消息	非NULL
msg_len	uint32_t	主动上报消息长度	大于0

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	URC消息发送成功
ERRCODE_INVALID_PARAM	参数无效	msg为NULL或msg_len为0
ERRCODE_MALLOC	内存分配失败	分配节点或字符串内存失败
ERRCODE_MEMCPY	内存拷贝失败	拷贝上报消息内容失败

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_AT_SUPPORT_NOTIFY_REPORT	功能宏	支持AT主动上报特性	n

Enumerations

at_ret_t

typedef enum {
    AT_RET_OK = 0,
    AT_RET_SYNTAX_ERROR,
    AT_RET_MALLOC_ERROR,
    AT_RET_MEM_API_ERROR,
    AT_RET_CHANNEL_PARA_ERROR,
    AT_RET_CHANNEL_NOT_INIT,
    AT_RET_CHANNEL_DATA_NULL,
    AT_RET_CMD_PARA_ERROR,
    AT_RET_CMD_FORMAT_ERROR,
    AT_RET_CMD_NO_MATCH,
    AT_RET_CMD_TYPE_ERROR,
    AT_RET_CMD_IN_PROGRESS_BLOCK,
    AT_RET_CMD_ATTR_NOT_ALLOW,
    AT_RET_PROC_CMD_FUNC_MISSING,
    AT_RET_PROC_READ_FUNC_MISSING,
    AT_RET_PROC_TEST_FUNC_MISSING,
    AT_RET_PROC_SET_FUNC_MISSING,
    AT_RET_PROC_WAIT_INTERACTIVITY,
    AT_RET_PROC_ABORT_CURRENT_COMMAND,
    AT_RET_PARSE_PARA_ERROR,
    AT_RET_PARSE_PARA_MISSING_ERROR,
    AT_RET_PROGRESS_BLOCK,
    AT_RET_TIMER_ERROR,
    AT_RET_ABORT_DELAY,
    AT_RET_RUN_ERROR,
    AT_RET_FORWORD_ERROR
} at_ret_t;

枚举成员	取值	描述
AT_RET_OK	0	执行成功
AT_RET_SYNTAX_ERROR	1	语法错误
AT_RET_MALLOC_ERROR	2	内存分配错误
AT_RET_MEM_API_ERROR	3	内存API错误
AT_RET_CHANNEL_PARA_ERROR	4	通道参数错误
AT_RET_CHANNEL_NOT_INIT	5	通道未初始化
AT_RET_CHANNEL_DATA_NULL	6	通道数据为空
AT_RET_CMD_PARA_ERROR	7	命令参数错误
AT_RET_CMD_FORMAT_ERROR	8	命令格式错误
AT_RET_CMD_NO_MATCH	9	命令无匹配
AT_RET_CMD_TYPE_ERROR	10	命令类型错误
AT_RET_CMD_IN_PROGRESS_BLOCK	11	命令执行中阻塞
AT_RET_CMD_ATTR_NOT_ALLOW	12	命令属性不允许
AT_RET_PROC_CMD_FUNC_MISSING	13	执行命令函数缺失
AT_RET_PROC_READ_FUNC_MISSING	14	读命令函数缺失
AT_RET_PROC_TEST_FUNC_MISSING	15	测试命令函数缺失
AT_RET_PROC_SET_FUNC_MISSING	16	设置命令函数缺失
AT_RET_PROC_WAIT_INTERACTIVITY	17	等待交互
AT_RET_PROC_ABORT_CURRENT_COMMAND	18	打断当前命令
AT_RET_PARSE_PARA_ERROR	19	解析参数错误
AT_RET_PARSE_PARA_MISSING_ERROR	20	解析参数缺失错误
AT_RET_PROGRESS_BLOCK	21	执行中阻塞
AT_RET_TIMER_ERROR	22	定时器错误
AT_RET_ABORT_DELAY	23	打断延迟
AT_RET_RUN_ERROR	24	运行错误
AT_RET_FORWORD_ERROR	25	转发错误

at_cmd_type_t

typedef enum {
    AT_CMD_TYPE_CMD = 0x00,    /*!< AT execute command. "AT+TEST", for example. */
    AT_CMD_TYPE_SET,           /*!< AT set command. "AT+TEST=520", for example. */
    AT_CMD_TYPE_READ,          /*!< AT read command. "AT+TEST?", for example. */
    AT_CMD_TYPE_TEST,          /*!< AT test command. "AT+TEST=?", for example. */
#ifdef CONFIG_AT_SUPPORT_QUERY
    AT_CMD_TYPE_QUERY,         /*!< AT query command. "AT+TEST?=", for example. */
#endif
    AT_CMD_TYPE_ERROR
} at_cmd_type_t;

枚举成员	取值	描述
AT_CMD_TYPE_CMD	0x00	AT执行命令，如"AT+TEST"
AT_CMD_TYPE_SET	0x01	AT设置命令，如"AT+TEST=520"
AT_CMD_TYPE_READ	0x02	AT读取命令，如"AT+TEST?"
AT_CMD_TYPE_TEST	0x03	AT测试命令，如"AT+TEST=?"
AT_CMD_TYPE_QUERY	0x04	AT查询命令，如"AT+TEST?="（需开启CONFIG_AT_SUPPORT_QUERY）
AT_CMD_TYPE_ERROR	0x05	AT命令类型错误

at_syntax_type_t

typedef enum {
    AT_SYNTAX_TYPE_INT,
    AT_SYNTAX_TYPE_STRING,
    AT_SYNTAX_TYPE_BIT_STRING,
    AT_SYNTAX_TYPE_OCTET_STRING,
    AT_SYNTAX_TYPE_NUM
} at_syntax_type_t;

枚举成员	取值	描述
AT_SYNTAX_TYPE_INT	0	整型参数
AT_SYNTAX_TYPE_STRING	1	字符串参数
AT_SYNTAX_TYPE_BIT_STRING	2	二进制字符串参数
AT_SYNTAX_TYPE_OCTET_STRING	3	十六进制字符串参数
AT_SYNTAX_TYPE_NUM	4	参数类型总数

at_syntax_attribute_t

typedef enum {
    AT_SYNTAX_ATTR_NOT_SUPPORTED    = 0x0001,
    AT_SYNTAX_ATTR_OPTIONAL         = 0x0002,
    AT_SYNTAX_ATTR_AT_MIN_VALUE     = 0x0004,
    AT_SYNTAX_ATTR_AT_MAX_VALUE     = 0x0008,
    AT_SYNTAX_ATTR_LIST_VALUE       = 0x0010,
    AT_SYNTAX_ATTR_MAX_LENGTH       = 0x0020,
    AT_SYNTAX_ATTR_ADD_LENGTH       = 0x0040,
    AT_SYNTAX_ATTR_FIX_CASE         = 0x0080,
    AT_SYNTAX_ATTR_LENGTH_FIELD     = 0x0100
} at_syntax_attribute_t;

枚举成员	取值	描述
AT_SYNTAX_ATTR_NOT_SUPPORTED	0x0001	标识该参数当前不支持
AT_SYNTAX_ATTR_OPTIONAL	0x0002	标识该参数可缺省
AT_SYNTAX_ATTR_AT_MIN_VALUE	0x0004	校验方式为最小值校验
AT_SYNTAX_ATTR_AT_MAX_VALUE	0x0008	校验方式为最大值校验
AT_SYNTAX_ATTR_LIST_VALUE	0x0010	校验方式为白名单校验
AT_SYNTAX_ATTR_MAX_LENGTH	0x0020	校验方式为长度校验
AT_SYNTAX_ATTR_ADD_LENGTH	0x0040	为该参数新增长度字段
AT_SYNTAX_ATTR_FIX_CASE	0x0080	标识字符串支持大小写混合
AT_SYNTAX_ATTR_LENGTH_FIELD	0x0100	标识该参数已预设长度字段

at_channel_id_t

typedef enum {
    AT_UART_PORT                = 0x00,
    AT_MAX_PORT_NUMBER
} at_channel_id_t;

枚举成员	取值	描述
AT_UART_PORT	0x00	UART通道
AT_MAX_PORT_NUMBER	0x01	最大通道数量

Structures

at_token_int_range_t

typedef struct {
    int32_t min_val;
    int32_t max_val;
} at_token_int_range_t;

成员说明

成员名称	数据类型	描述
min_val	int32_t	整型参数最小值
max_val	int32_t	整型参数最大值

at_token_int_list_t

typedef struct {
    uint32_t num;
    const int32_t *values;
} at_token_int_list_t;

成员说明

成员名称	数据类型	描述
num	uint32_t	白名单中的整数个数
values	const int32_t *	白名单整数数组指针

at_token_string_t

typedef struct {
    uint32_t max_length;
} at_token_string_t;

成员说明

成员名称	数据类型	描述
max_length	uint32_t	字符串最大长度

at_token_string_values_t

typedef struct {
    uint32_t num;
    const uint8_t * const *values;
} at_token_string_values_t;

成员说明

成员名称	数据类型	描述
num	uint32_t	白名单中的字符串个数
values	const uint8_t * const *	白名单字符串数组指针

at_token_bit_string_range_t

typedef struct {
    uint32_t max_value;
} at_token_bit_string_range_t;

成员说明

成员名称	数据类型	描述
max_value	uint32_t	二进制字符串最大值

at_token_bit_string_list_t

typedef struct {
    uint32_t num;
    const uint32_t *values;
} at_token_bit_string_list_t;

成员说明

成员名称	数据类型	描述
num	uint32_t	白名单中的二进制值个数
values	const uint32_t *	白名单二进制值数组指针

at_token_hex_string_t

typedef struct {
    uint32_t length_field_offset;
    uint32_t max_length;
} at_token_hex_string_t;

成员说明

成员名称	数据类型	描述
length_field_offset	uint32_t	标识长度字段的偏移，记录十六进制字符串转换后的数据长度
max_length	uint32_t	十六进制字符串最大长度

at_para_parse_syntax_t

typedef struct {
    uint32_t type : 4;    /*!< Parameter type(at_syntax_type_t). */
    uint32_t last : 1;    /*!< Identify whether it is the last parameter. */
    uint32_t attribute : 12;    /*!< Parameter type(at_syntax_attribute_t). */
    uint32_t offset : 15;    /*!< Parameter offset of para blob. */
    union {
        at_token_int_range_t int_range;
        at_token_int_list_t  int_list;
        at_token_string_t string;
        at_token_string_values_t string_list;
        at_token_bit_string_range_t bit_string_range;
        at_token_bit_string_list_t bit_string_list;
        at_token_hex_string_t octet_string;
    } entry;
} at_para_parse_syntax_t;

成员说明

成员名称	数据类型	描述
type	uint32_t:4	参数类型，取值参考at_syntax_type_t
last	uint32_t:1	标识是否为最后一个参数
attribute	uint32_t:12	参数校验属性，取值参考at_syntax_attribute_t
offset	uint32_t:15	参数在参数结构体中的偏移
entry	union	参数校验内容联合体

at_cmd_entry_t

typedef struct {
    const char *name;    /*!< The name cannot be duplicate. */
    const uint16_t cmd_id;    /*!< The cmd_id cannot be duplicate. */
    const uint16_t attribute;
    const at_para_parse_syntax_t *syntax;
    at_cmd_func_t cmd;
    at_set_func_t set;
    at_read_func_t read;
    at_test_func_t test;
#ifdef CONFIG_AT_SUPPORT_QUERY
    at_query_func_t query;
#endif
} at_cmd_entry_t;

成员说明

成员名称	数据类型	描述
name	const char *	AT命令名称，不可重复
cmd_id	const uint16_t	AT命令ID，不可重复
attribute	const uint16_t	AT命令属性标志
syntax	const at_para_parse_syntax_t *	AT命令参数校验语法表指针
cmd	at_cmd_func_t	AT执行命令回调函数
set	at_set_func_t	AT设置命令回调函数
read	at_read_func_t	AT读取命令回调函数
test	at_test_func_t	AT测试命令回调函数
query	at_query_func_t	AT查询命令回调函数（需开启CONFIG_AT_SUPPORT_QUERY）

Macros

AT_RESPONSE_OK

#define AT_RESPONSE_OK "OK\r\n"

AT_RESPONSE_ERROR

#define AT_RESPONSE_ERROR "ERROR\r\n"

AT_RESPONSE_BUSY

#define AT_RESPONSE_BUSY "BUSY\r\n"

AT_RESPONSE_ABORTING

#define AT_RESPONSE_ABORTING "ABORTING\r\n"

AT_FLAG_NONE

#define AT_FLAG_NONE                    0x0

AT_FLAG_ABORTABLE

#define AT_FLAG_ABORTABLE               0x10

AT_FLAG_NOT_BLOCK_URC

#define AT_FLAG_NOT_BLOCK_URC           0x200