ESP-AT 應用: AT-Web

AT-Web 介紹

AT-Web 是利用 AT 實現的一種類似於路由器配置頁面功能的應用, 利用手機或電腦訪問 URL 即可以控制 ESP32 的各種特性。

本應用單純依靠 ESP32，只需通過網頁，即可配置 ESP32 各項功能。主要包含以下兩個部分：

• AT-Web 基本架構
• AT-Web 解析框架

其中:
AT-Web 基本架構主要包括 http server libesphttpd 和 ESP32 文件系統。
libesphttpd 使用 ESP32 作爲 HTTP server 實現 HTTP 請求、解析和響應。
ESP32 文件系統 是小型 ESP32 FAT 文件系統。
這兩者既相互獨立，又緊密聯繫。

一. AT-Web 基本架構

AT-Web 基本架構將 AT 命令打包和解析封裝成不同 API，用戶可直接調用這些 API來實現 ESP32 上各項功能，而無需關心底層 AT 接口。

二. AT 解析框架

2.1 框架簡介

AT-Web 解析框架作爲一個整體模塊將 AT 命令進行封裝，並對結果進行解析，以 API 形式提供給用戶，使得用戶只需根據接口即可得到想要結果。相對於 AT 來說，提供了更加方便和靈活的方式，用戶無需使用 UART 或者 SPI 等外設去連接調用命令，也無需關心各個 AT 命令實現。

AT-Web 解析框架主要分爲兩層：

• AT 命令打包和解析
• 解析結果處理再組裝

2.2 以連接 AP 爲例

1. 在 esp_at_join_ap() 函數，用戶需在函數參數中輸入 ssid 和 pwd 等信息，esp_at_join_ap() 內部會對參數合法性判斷，將參數信息傳遞到 at_add_cmd()
2. 在 at_add_cmd() 函數中，會將傳遞參數進行拼裝，組成 AT+CWJAP=<ssid>,<pwd>[,<bssid>] 命令形式發送給 AT core 進行處理
3. AT core 返回結果給 at_add_cmd()，esp_at_join_ap() 函數檢測 at_add_cmd() 函數返回值, 返回給 cgiShowApInfo()
4. cgiShowApInfo()組裝好 JSON 字符串，通過http server返回給用戶

讀者可參考如下 test.c 代碼來測試 esp_at_join_ap 等接口是否有效:

void app_main()
{
    esp_err_t ret;
    esp_at_arg at_arg;

    nvs_flash_init();
    /****** Init parse frame, it must call before using other API ******/
    ESP_ERROR_CHECK(esp_at_init_parse());

    /****** got free ram size ******/
    int32_t ram_size = esp_at_getramsize();
    ESP_LOGI(TAG, "ramsiz:%d",ram_size);


    /****** Connect WiFi ******/
    memset(&at_arg, '\0', sizeof(at_arg));
    strcpy(at_arg.cwjap.ssid, "HUAWEI001");
    strcpy(at_arg.cwjap.pwd, "12345678");
    ret = esp_at_join_ap(SET, &at_arg);
    if(ret == ESP_ERR_INVALID_STATE){
        ESP_LOGE(TAG, "Error pwd or ssid");
    }

    /****** Get connected WiFi info ******/
    memset(&at_arg, '\0', sizeof(at_arg));
    ret = esp_at_join_ap(QUERY, &at_arg);
    if(ret == ESP_ERR_INVALID_STATE){
        ESP_LOGE(TAG, "Error");
    }
    ESP_LOGI(TAG, "SSID:%s, bssid:%s",at_arg.queryjap.ssid, at_arg.queryjap.bssid);
}

2.3 添加自己的 AT-Web 命令

目前 AT-Web 中已支持大部分常見 AT 命令解析，可滿足基本需求，如需要較複雜功能，可通過 AT 組合來實現相關功能，也可以自行開發相關接口。一般開發步驟如下：

2.3.1 命令註冊

• 在 atparse.h 中的 at_command_list 中增加需添加命令
• 在 at_cmd_arg 中增加此命令的參數信息
• 在 cmdparse.c 中的 cmd_func_list 中 添加此命令的拼裝和解析回調函數。

**注意:**以上三步添加需要在對應同一位置，即都添加在 at_command_list，at_cmd_arg，cmd_func_list 第 n 位， 如都添加在最後，系統是通過對應位置去執行相應回調

2.3.2 拼裝和解析實現

拼裝和解析實現是將cmd_func_list中兩個函數實現。

• 在實現這兩個函數之前，建議使用 uart 對 AT-Web 命令進行測試，確定相應返回值順序
• 拼裝實現需按照 AT 文檔說明將此命令參數進行傳遞，注意其中有些參數是可選參數，使用中需根據參數狀態進行判斷
• 解析的實現主要對返回值解析，以及初步判斷 AT 命令執行的正確性

當 AT 命令執行完成後，如果成功，會返回相應的結果，並返回"OK",而錯誤的話會直接返回"ERROR" 所以我們需要做的就是將結果保存下來，並通過一個狀態來標識執行正確或者錯誤。在已有的框架中，結構體 rsp_msg 用來標識 AT 返回信息，其中 rsp_msg.rsp_flag 爲返回狀態標誌位，rsp_msg.data 爲返回數據，一般如果 rsp_msg.rsp_flag 爲 AT_CMD_RETURN_FAIL，即 AT 執行錯誤，則 rsp_msg.data 爲 NULL。
如 AT 命令只關心是否返回正確，則可以直接使用 at_comm_rsp()，不需要自己寫解析回調函數

• 在 AT 返回多組信息時，如 AT + CIFSR 命令返回：

AT+CIFSR
+CIFSR:APIP,<SoftAP IP address>
+CIFSR:APMAC,<SoftAP MAC address>
+CIFSR:STAIP,<Station IP address>
+CIFSR::STAMAC,<Station MAC address>
OK

一般我們有兩種方式:

• 將這些結果拼接起來拷貝到 rsp_msg.data
• 聲明一個結構體，然後將這些結果賦值到結構體中拷貝到 rsp_msg.data

推薦使用第一種方式，這樣可以使得代碼風格統一，拼接結果在上層調用接口處理。

注意:

• BLE 命令與其他命令略有不同，BLE 命令執行和返回是異步的，所以會先打印 OK，然後纔會返回結果

2.3.3 ESP32-AT 返回結果再處理

在完成上述結果後，可以在上層對 AT-Web 結果再次加工，以滿足特殊需求。如對於 WiFi 掃描結果，返回後還需要對於結果進行打包，將有用信息以 callback 方式提供給用戶，參考 wifiscanresult_cb 使用。

三. AT-Web Demo 使用

AT-Web demo 編譯和使用方法如下：

1. make menuconfig 配置，默認配置即可運行
2. make flash 編譯並燒寫到 Flash
3. 手機連接到 ESP32， ESP32 的 AP SSID 爲 AP MAC 地址的後六位
4. 手機瀏覽器訪問 192.168.4.1 即可連接到 ESP32
5. 配置和操作 ESP32

四. 參考項目

1. HTTP SERVER 要參考 ： https://github.com/Spritetm/libesphttpd
2. FAT image 製作工具參考： https://github.com/jkearins/ESP32_mkfatfs