1 /** 2 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 * 15 * Description: Provides at common service api header for customer \n 16 * 17 * History: \n 18 * 2022-09-02, Create file. \n 19 */ 20 21 #ifndef AT_H 22 #define AT_H 23 24 #include <stdint.h> 25 #include <stdbool.h> 26 #include "at_config.h" 27 28 #ifdef __cplusplus 29 #if __cplusplus 30 extern "C" { 31 #endif /* __cplusplus */ 32 #endif /* __cplusplus */ 33 34 /** 35 * @defgroup middleware_utils_at_custom Custom 36 * @ingroup middleware_utils_at 37 * @{ 38 */ 39 40 #define AT_RESPONSE_OK "OK\r\n" 41 #define AT_RESPONSE_ERROR "ERROR\r\n" 42 #define AT_RESPONSE_BUSY "BUSY\r\n" 43 #define AT_RESPONSE_ABORTING "ABORTING\r\n" 44 45 /* AT FLAG indicates the AT command feature. */ 46 #define AT_FLAG_NONE 0x0 47 #define AT_FLAG_ABORTABLE 0x10 48 #define AT_FLAG_NOT_BLOCK_URC 0x200 49 50 /** 51 * @if Eng 52 * @brief Definition of AT error code. 53 * @else 54 * @brief 定义AT错误码。 55 * @endif 56 */ 57 typedef enum { 58 AT_RET_OK = 0, 59 AT_RET_SYNTAX_ERROR, 60 AT_RET_MALLOC_ERROR, 61 AT_RET_MEM_API_ERROR, 62 AT_RET_CHANNEL_PARA_ERROR, 63 AT_RET_CHANNEL_NOT_INIT, 64 AT_RET_CHANNEL_DATA_NULL, 65 AT_RET_CMD_PARA_ERROR, 66 AT_RET_CMD_FORMAT_ERROR, 67 AT_RET_CMD_NO_MATCH, 68 AT_RET_CMD_TYPE_ERROR, 69 AT_RET_CMD_IN_PROGRESS_BLOCK, 70 AT_RET_CMD_ATTR_NOT_ALLOW, 71 AT_RET_PROC_CMD_FUNC_MISSING, 72 AT_RET_PROC_READ_FUNC_MISSING, 73 AT_RET_PROC_TEST_FUNC_MISSING, 74 AT_RET_PROC_SET_FUNC_MISSING, 75 AT_RET_PROC_WAIT_INTERACTIVITY, 76 AT_RET_PROC_ABORT_CURRENT_COMMAND, 77 AT_RET_PARSE_PARA_ERROR, 78 AT_RET_PARSE_PARA_MISSING_ERROR, 79 AT_RET_PROGRESS_BLOCK, 80 AT_RET_TIMER_ERROR, 81 AT_RET_ABORT_DELAY 82 } at_ret_t; 83 84 /** 85 * @if Eng 86 * @brief Definition of AT command type. 87 * @else 88 * @brief 定义AT命令类型。 89 * @endif 90 */ 91 typedef enum { 92 AT_CMD_TYPE_CMD = 0x00, /*!< AT execute command. "AT+TEST", for example. */ 93 AT_CMD_TYPE_SET, /*!< AT set command. "AT+TEST=520", for example. */ 94 AT_CMD_TYPE_READ, /*!< AT read command. "AT+TEST?", for example. */ 95 AT_CMD_TYPE_TEST, /*!< AT test command. "AT+TEST=?", for example. */ 96 #ifdef CONFIG_AT_SUPPORT_QUERY 97 AT_CMD_TYPE_QUERY, /*!< AT query command. "AT+TEST?=", for example. */ 98 #endif 99 AT_CMD_TYPE_ERROR 100 } at_cmd_type_t; 101 102 /** 103 * @if Eng 104 * @brief Declare AT abort function type. 105 * @param [in] arg AT command abort func input parameter. 106 * @else 107 * @brief 声明AT命令打断函数类型。 108 * @param [in] arg AT命令打断函数入参。 109 * @endif 110 */ 111 typedef at_ret_t(*at_abort_func_t)(void *arg); 112 113 /** 114 * @if Eng 115 * @brief Declare AT interactivity function type. 116 * @param [in] data AT command interactivity func input parameter. This parameter must be a string. 117 * @param [in] len The length of at command interactivity func input parameter. 118 * @else 119 * @brief 声明AT命令交互函数类型。 120 * @param [in] data AT命令交互函数上报参数。这个参数必须为字符串。 121 * @param [in] len AT命令交互函数上报参数长度。 122 * @endif 123 */ 124 typedef at_ret_t(*at_interactivity_func_t)(const char *data, uint32_t len); 125 126 /** 127 * @if Eng 128 * @brief Declare AT executing function type. 129 * @else 130 * @brief 声明AT命令执行函数类型。 131 * @endif 132 */ 133 typedef at_ret_t(*at_cmd_func_t)(void); 134 135 /** 136 * @if Eng 137 * @brief Declare AT setting function type. 138 * @param [in] arg AT command set func input parameter. 139 * @else 140 * @brief 声明AT命令设置函数类型。 141 * @param [in] arg AT命令设置函数入参。 142 * @endif 143 */ 144 typedef at_ret_t(*at_set_func_t)(const void *arg); 145 146 /** 147 * @if Eng 148 * @brief Declare AT reading function type. 149 * @else 150 * @brief 声明AT命令读函数类型。 151 * @endif 152 */ 153 typedef at_ret_t(*at_read_func_t)(void); 154 155 /** 156 * @if Eng 157 * @brief Declare AT test function type. 158 * @else 159 * @brief 声明AT命令测试函数类型。 160 * @endif 161 */ 162 typedef at_ret_t(*at_test_func_t)(void); 163 164 #ifdef CONFIG_AT_SUPPORT_QUERY 165 /** 166 * @if Eng 167 * @brief Declare AT query function type. 168 * @param [in] arg AT command query func input parameter. 169 * @else 170 * @brief 声明AT命令查询函数类型。 171 * @param [in] arg AT命令查询函数入参。 172 * @endif 173 */ 174 typedef at_ret_t(*at_query_func_t)(const void *arg); 175 #endif 176 177 /** 178 * @if Eng 179 * @brief Range checking syntax definition of integer. 180 * @else 181 * @brief 定义基于取值范围的整型校验语法。 182 * @endif 183 */ 184 typedef struct { 185 int32_t min_val; 186 int32_t max_val; 187 } at_token_int_range_t; 188 189 /** 190 * @if Eng 191 * @brief White list checking syntax definition of integer. 192 * @else 193 * @brief 定义基于白名单的整型校验语法。 194 * @endif 195 */ 196 typedef struct { 197 uint32_t num; 198 const int32_t *values; 199 } at_token_int_list_t; 200 201 /** 202 * @if Eng 203 * @brief Length checking syntax definition of string. 204 * @else 205 * @brief 定义基于长度的字符串校验语法。 206 * @endif 207 */ 208 typedef struct { 209 uint32_t max_length; 210 } at_token_string_t; 211 212 /** 213 * @if Eng 214 * @brief White list checking syntax definition of string. 215 * @else 216 * @brief 定义基于白名单的字符串校验语法。 217 * @endif 218 */ 219 typedef struct { 220 uint32_t num; 221 const uint8_t * const *values; 222 } at_token_string_values_t; 223 224 /** 225 * @if Eng 226 * @brief Range checking syntax definition of binary string. 227 * @else 228 * @brief 定义基于范围值的二进制字符串校验语法。 229 * @endif 230 */ 231 typedef struct { 232 uint32_t max_value; 233 } at_token_bit_string_range_t; 234 235 /** 236 * @if Eng 237 * @brief White list checking syntax definition of binary string. 238 * @else 239 * @brief 定义基于白名单二进制字符串校验语法。 240 * @endif 241 */ 242 typedef struct { 243 uint32_t num; 244 const uint32_t *values; 245 } at_token_bit_string_list_t; 246 247 /** 248 * @if Eng 249 * @brief Length checking syntax definition of hexadecimal string. 250 * @else 251 * @brief 定义基于长度的十六进制字符串校验语法。 252 * @endif 253 */ 254 typedef struct { 255 /** @if Eng Record offset of a Identifies identification length field which record \n 256 * the data length after hexadecimal string conversion. \n 257 * The identification length field can be preset in advance or \n 258 * automatically generated through the AT_SYNTAX_ATTR_ADD_LENGTH attribute. \n 259 * @else 记录标识长度字段的偏移，标识长度字段用来存储十六进制字符串转换后的数据长度。该字段 \n 260 * 可以预设也可以由 AT_SYNTAX_ATTR_ADD_LENGTH 属性新增。 \n 261 * @endif */ 262 uint32_t length_field_offset; 263 uint32_t max_length; 264 } at_token_hex_string_t; 265 266 /** 267 * @if Eng 268 * @brief Definition of AT command parameter type. 269 * @else 270 * @brief 定义AT命令参数类型。 271 * @endif 272 */ 273 typedef enum { 274 AT_SYNTAX_TYPE_INT, 275 AT_SYNTAX_TYPE_STRING, 276 AT_SYNTAX_TYPE_BIT_STRING, 277 AT_SYNTAX_TYPE_OCTET_STRING, 278 AT_SYNTAX_TYPE_NUM 279 } at_syntax_type_t; 280 281 /** 282 * @if Eng 283 * @brief Definition of AT command parameter verification attribute. 284 * @else 285 * @brief 定义AT命令参数校验属性。 286 * @endif 287 */ 288 typedef enum { 289 /** @if Eng Identify that the parameter is invalid \n 290 * @else 标识该参数当前不支持。 \n 291 * @endif */ 292 AT_SYNTAX_ATTR_NOT_SUPPORTED = 0x0001, 293 /** @if Eng Identify that the parameter is defaultable \n 294 * @else 标识该参数可缺省，为保证参数顺序，缺省时‘，’不可缺省。 \n 295 * @endif */ 296 AT_SYNTAX_ATTR_OPTIONAL = 0x0002, 297 /** @if Eng The attribute identifies the verification method is minimum value verification \n 298 * @else 该属性标识校验方式为最小值校验。 \n 299 * @endif */ 300 AT_SYNTAX_ATTR_AT_MIN_VALUE = 0x0004, 301 /** @if Eng The attribute identifies the verification method is maximum value verification \n 302 * @else 该属性标识校验方式为最大值校验。 \n 303 * @endif */ 304 AT_SYNTAX_ATTR_AT_MAX_VALUE = 0x0008, 305 /** @if Eng The attribute identifies the verification method is white list \n 306 * @else 该属性标识校验方式为白名单校验。 \n 307 * @endif */ 308 AT_SYNTAX_ATTR_LIST_VALUE = 0x0010, 309 /** @if Eng The attribute identifies the verification method is length verification \n 310 * @else 该属性标识校验方式为长度校验。 \n 311 * @endif */ 312 AT_SYNTAX_ATTR_MAX_LENGTH = 0x0020, 313 /** @if Eng This attribute indicates that the length field of this parameter is added for this parameter \n 314 * @else 该属性标识为该参数新增此参数的长度字段。 \n 315 * @endif */ 316 AT_SYNTAX_ATTR_ADD_LENGTH = 0x0040, 317 /** @if Eng This attribute is used for strings. Identification string parameter is of mixed case type \n 318 * @else 该参数用于字符串，标识字符串支持大小写混合。 \n 319 * @endif */ 320 AT_SYNTAX_ATTR_FIX_CASE = 0x0080, 321 /** @if Eng Identifies that the parameter has a preset length field \n 322 * @else 该属性标识该参数已预设长度字段。 \n 323 * @endif */ 324 AT_SYNTAX_ATTR_LENGTH_FIELD = 0x0100 325 } at_syntax_attribute_t; 326 327 /** 328 * @if Eng 329 * @brief Define a parameter verification structure of AT command. 330 * @else 331 * @brief 定义AT命令某个参数校验结构。 332 * @endif 333 */ 334 typedef struct { 335 uint32_t type : 4; /*!< Parameter type(at_syntax_type_t). */ 336 uint32_t last : 1; /*!< Identify whether it is the last parameter. */ 337 uint32_t attribute : 12; /*!< Parameter type(at_syntax_attribute_t). */ 338 uint32_t offset : 15; /*!< Parameter offset of para blob. */ 339 union { 340 at_token_int_range_t int_range; 341 at_token_int_list_t int_list; 342 at_token_string_t string; 343 at_token_string_values_t string_list; 344 at_token_bit_string_range_t bit_string_range; 345 at_token_bit_string_list_t bit_string_list; 346 at_token_hex_string_t octet_string; 347 } entry; 348 } at_para_parse_syntax_t; 349 350 /** 351 * @if Eng 352 * @brief Definition of AT command entry. 353 * @else 354 * @brief 定义AT命令实体。 355 * @endif 356 */ 357 typedef struct { 358 const char *name; /*!< The name cannot be duplicate. */ 359 const uint16_t cmd_id; /*!< The cmd_id cannot be duplicate. */ 360 const uint16_t attribute; 361 const at_para_parse_syntax_t *syntax; 362 at_cmd_func_t cmd; 363 at_set_func_t set; 364 at_read_func_t read; 365 at_test_func_t test; 366 #ifdef CONFIG_AT_SUPPORT_QUERY 367 at_query_func_t query; 368 #endif 369 } at_cmd_entry_t; 370 371 /** 372 * @if Eng 373 * @brief Register AT Command List. 374 * @param [in] table The address of AT command list. see @ref at_cmd_entry_t 375 * @param [in] len The length of AT command list. 376 * @param [in] struct_max_size The maximum size of the setting function input parameters struct. 377 * @retval ERRCODE_SUCC Success. 378 * @retval Other Failure. For details, see @ref errcode_t 379 * @else 380 * @brief 注册AT命令列表。 381 * @param [in] table AT命令列表起始地址。参考 @ref at_cmd_entry_t 382 * @param [in] len AT命令列表长度。 383 * @param [in] struct_max_size AT命令列表中设置函数输入参数结构体的最大大小。 384 * @retval ERRCODE_SUCC 成功。 385 * @retval Other 失败，参考 @ref errcode_t 386 * @endif 387 */ 388 errcode_t uapi_at_cmd_table_register(const at_cmd_entry_t *table, uint32_t len, 389 uint32_t struct_max_size); 390 391 #ifdef CONFIG_AT_SUPPORT_ASYNCHRONOUS 392 /** 393 * @if Eng 394 * @brief Register AT command abort func. 395 * @param [in] func AT command abort func. see @ref at_abort_func_t 396 * @param [in] arg AT command abort func input parameter. 397 * @retval ERRCODE_SUCC Success. 398 * @retval Other Failure. For details, see @ref errcode_t 399 * @else 400 * @brief 注册AT命令打断函数。 401 * @param [in] func AT命令打断函数。参考 @ref at_abort_func_t 402 * @param [in] arg AT命令打断函数入参。 403 * @retval ERRCODE_SUCC 成功。 404 * @retval Other 失败，参考 @ref errcode_t 405 * @endif 406 */ 407 errcode_t uapi_at_cmd_abort_register(at_abort_func_t func, void *arg); 408 409 /** 410 * @if Eng 411 * @brief This interface is used to send AT command results for Asynchronous blocking AT command. 412 * @param [in] err AT command execution result. If the result is successful, enter 0. Other values indicate failure. 413 * @retval ERRCODE_SUCC Success. 414 * @retval Other Failure. For details, see @ref errcode_t 415 * @else 416 * @brief 异步阻塞式AT命令结果发送接口。 417 * @param [in] err 执行结果。成功则输入0，其他值表示失败。 418 * @retval ERRCODE_SUCC 成功。 419 * @retval Other 失败，参考 @ref errcode_t 420 * @endif 421 */ 422 errcode_t uapi_at_send_async_result(uint16_t err); 423 424 /** 425 * @if Eng 426 * @brief Register AT interactivity func. 427 * @param [in] func AT interactivity func. see @ref at_interactivity_func_t 428 * @retval ERRCODE_SUCC Success. 429 * @retval Other Failure. For details, see @ref errcode_t 430 * @else 431 * @brief 注册AT交互命令处理函数。 432 * @param [in] func AT命令交互命令处理函数。参考 @ref at_interactivity_func_t 433 * @retval ERRCODE_SUCC 成功。 434 * @retval Other 失败，参考 @ref errcode_t 435 * @endif 436 */ 437 errcode_t uapi_at_interactivity_func_register(at_interactivity_func_t func); 438 #endif 439 440 /** 441 * @if Eng 442 * @brief Output AT print information to the default channel. 443 * @param [in] str AT print information.This parameter must have a string terminator. 444 * @else 445 * @brief 向默认通道输出AT打印信息。 446 * @param [in] str AT打印信息。这个参数必须携带字符串结束符。 447 * @endif 448 */ 449 void uapi_at_report(const char *str); 450 451 /** 452 * @if Eng 453 * @brief Output AT print information to the specified channel. 454 * @param [in] channel_id AT channel number. It is defined in the at_config.h file which is defined by product. 455 * @param [in] str AT print information.This parameter must have a string terminator. 456 * @else 457 * @brief 向指定通道输出AT打印信息。 458 * @param [in] channel_id AT通道号，在at_config.h文件中定义，at_config.h由产品定义。 459 * @param [in] str AT打印信息。这个参数必须携带字符串结束符。 460 * @endif 461 */ 462 void uapi_at_report_to_single_channel(at_channel_id_t channel_id, const char *str); 463 464 #ifdef CONFIG_AT_SUPPORT_NOTIFY_REPORT 465 /** 466 * @if Eng 467 * @brief Sends URC(Unsolicited result code) information to a specified channel. 468 * @param [in] channel_id Channel id. It is defined in the at_config.h file which is defined by product. 469 * @param [in] msg Unsolicitedly report messages. 470 * @param [in] msg_len Indicates the length of the unsolicited report message. 471 * @else 472 * @brief 向指定通道发送主动上报信息。 473 * @param [in] channel_id AT通道号，在at_config.h文件中定义，at_config.h由产品定义。 474 * @param [in] msg 主动上报消息。 475 * @param [in] msg_len 主动上报消息长度。 476 * @endif 477 */ 478 errcode_t uapi_at_urc_to_channel(at_channel_id_t channel_id, const char *msg, uint32_t msg_len); 479 #endif 480 481 /** 482 * @} 483 */ 484 #ifdef __cplusplus 485 #if __cplusplus 486 } 487 #endif /* __cplusplus */ 488 #endif /* __cplusplus */ 489 490 #endif 491