ATCI

This section introduces the ATCI driver APIs including terms and acronyms, software architecture, supported features, details on how to use this driver, ATCI function groups, enums, structures and functions. More...

Overview

This section introduces the ATCI driver APIs including terms and acronyms, software architecture, supported features, details on how to use this driver, ATCI function groups, enums, structures and functions.

The ATCI header file provides the interface for target communication using AT commands though UART. The ATCI module APIs to register the AT command handler, send and receive UART data, and a parser to search for the registered AT command handler. The command handler gets and parses the input AT command data, then performs corresponding operation according to the specified behavior and parameters.

ATCI acronyms definition

Acronyms	Definition
ATCI	AT command interface. For more details about the AT command, please refer to Hayes command set in Wikipedia.
CMD	Command.
URC	Unsolicited result code. For the details of URC, please refer to Data communication over the telephone network.
UART	Universal Asynchronous Receiver/Transmitter is usually an individual (or part of an) integrated circuit (IC) used for serial communications over a micro-controller unit(MCU) or peripheral device serial port. For an introduction to UART, please refer to UART in Wikipedia.

Supported features

• Supported AT command format
  The command format should start with "AT+<CMD>", and finish with "<\r><\n>" to mark the end of the AT command. The ATCI module supports four modes, as shown below.
  • Read command mode
    Checks the current value or values stored in a parameter.
    Data format. AT+<CMD>?<\r><\n>
  • Test command mode
    Tests if a parameter is implemented and checks the supported values.
    Data format. AT+<CMD>=?<\r><\n>
  • Active command mode
    Verifies if the action command is implemented.
    Data format. AT+<CMD><\r><\n>
  • Execute command mode
    Transfers the parameters in the AT command to a command handler.
    Data format. AT+<CMD>=<p1>,<p2>...<\r><\n>
• Supported AT command type
  
  • Instruction Type
    The target receives the AT command and reports the result passively. So the received AT command and a response must be paired. The target handles the next AT command until the response of current received AT command is sent.

    Command mode	Input command	Response command
    Read command mode	AT+<CMD>?<\r><\n>	+<CMD>:<values><\r><\n>OK<\r><\n>
    Test command mode	AT+<CMD>=?<\r><\n>	+<CMD>:<values><\r><\n>OK<\r><\n>
    Active command mode	AT+<CMD><\r><\n>	OK<\r><\n>
    Execute command mode	AT+<CMD>=<p1>,<p2>...<\r><\n>	OK<\r><\n>

    .
  • URC Type
    The target reports the result actively. It means that target can send any command information through the ATCI module without receiving any input AT command. The data format is +<CMD>:...<\r><\n>

ATCI architecture

The software architecture is shown in the figure below.

The ATCI module contains the data transfer and parser sub-modules. The data transfer sub-module can receive UART data, then send to parser sub-module to find the right registered command handler. When the command handler is called to handle input command data, the command handler needs to give a response, then the ATCI data transfer module will send the response data through the UART. If the modules want provide some AT commands, they could use ATCI module register the command handlers to add more AT commands in the target. Also the command handler can send the URC data actively without receiving one input command data.

Folder structure

The folder structure of ATCI module is shown in the figure below.

• at_command. Includes source files for the default supported AT command handler provied by IoT platform.
• inc. Inculdes the public header file named atci.h and other ATCI private header files.
• src. Inculdes the source files of the ATCI module.

How to use this module

• Step 1. Call atci_init() to initialize the ATCI content and set UART configuration.
• Step 2. Call atci_register_handler() to register the AT command handler.
• Step 3. Call xTaskCreate() to create a task that takes atci_def_task() as the entry function where atci_processing() executes in a continuous loop.
• Step 4. After the above steps, send AT command through UART on the PC. On the target side, the ATCI module receives UART data and calls the corresponding registered command handler to provide a response.
• Sample code

    // AT CMD table
    atci_cmd_hdlr_item_t atcmd_table[] = {
      {"AT+TEST",   atci_cmd_hdlr_test,  0, 0}
    };
   
    // AT command handler
  *atci_status_t atci_cmd_hdlr_test(atci_parse_cmd_param_t *parse_cmd)
   {
       int read_value = 0;
       atci_response_t resonse = {0};
       atci_response_t urc_data = {0};
       char *param = NULL;
       int  param1_val = -1;
   
       resonse.response_flag = 0; // Command execution is complete.
   
       switch (parse_cmd->mode) {
           case ATCI_CMD_MODE_TESTING:    // Input data. AT+TEST=?
               printf("AT Test OK.\n");
               strcpy(resonse.response_buf, "+TEST:(0,1)\r\nOK\r\n");
               resonse.response_len = strlen(resonse.response_buf);
               atci_send_response(&resonse);
               break;
   
           case ATCI_CMD_MODE_READ:    // Input data. AT+TEST?
               printf("AT Read done.\n");
               sprintf(resonse.response_buf, "+TEST:%d\r\n", read_value);
               resonse.response_len = strlen(resonse.response_buf);
               // The ATCI appends 'OK' at the end of the response buffer.
               resonse.response_flag |= ATCI_RESPONSE_FLAG_APPEND_OK;
              atci_send_response(&resonse);
               break;
   
           case ATCI_CMD_MODE_ACTIVE:  // Input data. AT+TEST
               printf("AT Active OK.\n");
               // Assume the active mode is invalid and returns an error message.
               strcpy(resonse.response_buf, "ERROR\r\n");
               resonse.response_len = strlen(resonse.response_buf);
               atci_send_response(&resonse);
               break;
   
           case ATCI_CMD_MODE_EXECUTION: // Input data. AT+TEST=<p1>  the handler need to parse the parameters.
               printf("AT Executing...\r\n");
               //Parsing the parameters.
               param = strtok(parse_cmd->string_ptr, ",\n\r");
               param = strtok(parse_cmd->string_ptr, "AT+TEST=");
               param1_val = atoi(param);
   
               if (param != NULL && (param1_val == 0 || param1_val == 1)) {
                   // Valid parameter, update the data and return "OK".
                   resonse.response_len = 0;
                   // // The ATCI appends 'OK' at the end of the response buffer.
                   resonse.response_flag |= ATCI_RESPONSE_FLAG_APPEND_OK;
               } else {
                   // Invalide parameter, return "ERROR".
                   resonse.response_len = 0;
                   // // The ATCI appends 'ERROR' at the end of the response buffer.
                   resonse.response_flag |= ATCI_RESPONSE_FLAG_APPEND_ERROR;
               };
   
               atci_send_response(&resonse);
               param = NULL;
   
               // Send the URC data.
               sprintf(urc_data.response_buf, "+TEST:urc_data\r\n");
               urc_data.response_len = strlen(urc_data.response_buf);
               urc_data.response_flag |= ATCI_RESPONSE_FLAG_URC_FORMAT;
               atci_send_response(&urc_data);
   
               break;
   
           default:
               strcpy(resonse.response_buf, "ERROR\r\n");
               resonse.response_len = strlen(resonse.response_buf);
               atci_send_response(&resonse);
               break;
       }
       return ATCI_STATUS_OK;
    }
   
    // Register the AT CMD handler.
    void at_cmd_init(void)
    {
      atci_status_t ret = ATCI_STATUS_REGISTRATION_FAILURE;
   
       ret = atci_register_handler(atcmd_table, sizeof(atcmd_table) / sizeof(atci_cmd_hdlr_item_t));
       if (ret == ATCI_STATUS_OK) {
           printf("at_cmd_init register success\r\n");
       } else {
           printf("at_cmd_init register fail\r\n");
       }
    }
   
    // ATCI task main function.
    void atci_def_task(void *param)
    {
      while (1) {
           atci_processing();
       }
    }
   
    void app_main(void)
    {
      // Initialize the ATCI module and set the UART port.
      atci_status_t ret = ATCI_STATUS_ERROR;
      ret = atci_init(HAL_UART_1);
      if (ret == ATCI_STATUS_OK) {
             // Register the AT CMD handler.
          at_cmd_init();
             // Create a task for the ATCI.
             xTaskCreate( atci_def_task, "ATCI", 1024, NULL, 3, NULL );
      }
    }

Functions
atci_status_t	atci_register_handler (atci_cmd_hdlr_item_t *table, int32_t hdlr_number)
	This function registers the AT command handler. More...
atci_status_t	atci_send_response (atci_response_t *response)
	This function sends the AT command response data or the URC data. More...
atci_status_t	atci_init (uint16_t port)
	This function initializes the ATCI module. More...
void	atci_processing (void)
	This function parses the input command to find the corresponding command handler and handle the response data. More...

Modules
	Define
	Enums
	Structures
	Typedef

Function Documentation

atci_status_t atci_init

(

uint16_t

port

)

This function initializes the ATCI module.

It is used to set the port configuration for data transmission.

Parameters

[in]

port

is the serial port number used to data transmission for ATCI. For more details about this parameter, please refer to hal_uart_port_t or serial_port_dev_t.

Returns

ATCI_STATUS_OK the ATCI initialized successfully.
ATCI_STATUS_ERROR the UART initialization or the ATCI local initialization failed due to the ATCI initialization failure.

Note

The atci_init() can select the UART through HAL UART port directly, or select UART, USB or BT SPP server/client port through port service for data transmission.

Example

ret = atci_init(port);
if (ret == ATCI_STATUS_OK) {
   // The ATCI initialized successfully.
   atci_register_handler(table, hdlr_number);
   // Create an ATCI task.
} else {
   // The ATCI initialization failed.
}

void atci_processing

(

void

)

This function parses the input command to find the corresponding command handler and handle the response data.

Returns

void.

atci_status_t atci_register_handler	(	atci_cmd_hdlr_item_t *	table,
		int32_t	hdlr_number
	)

This function registers the AT command handler.

It is used to receive, parse and handle the registered input command data.

Parameters

[in]	table	is the registered handler parameter. For more details about this parameter, please refer to atci_cmd_hdlr_item_t.
[in]	hdlr_number	is the registered table handler size.

Returns

ATCI_STATUS_OK the ATCI command handler is successfully registered.
ATCI_STATUS_REGISTRATION_FAILURE duplicate registration of the AT command or an unused registration table will cause failure.

Example

ret = atci_register_handler(table, hdlr_number);
if (ret == ATCI_STATUS_OK) {
   // AT CMD handler is successfully registered.
} else {
   // AT CMD handler is failed to register because the duplcated registed AT command or none unused register table.
}

atci_status_t atci_send_response

(

atci_response_t *

response

)

This function sends the AT command response data or the URC data.

Parameters

[in]

response

is the response data. For more details about this parameter, please refer to atci_response_t.

Returns

ATCI_STATUS_OK the ATCI module sent data to the UART successfully.