Espressif Systems ESP32 Series Setup guide

ESP32
AT Instruction Set and Examples
Version 1.3
Espressif Systems
Copyright © 2019

About This Guide
This document introduces the ESP32 AT commands, explains how to use them and
provides examples of several common AT commands.
Release Notes
Documentation Change Notification
Espressif provides email notifications to keep customers updated on changes to
technical documentation. Please subscribe at https://www.espressif.com/en/subscribe.
Certification
Download certificates for Espressif products from https://www.espressif.com/en/
certificates.
Date
Version
Release notes
2017.11
V1.0
Initial release.
2018.06
V1.1
Updated Section 4.2.15，5.2.8，5.2.15，6.2.5，
6.2.11 and Chapter 8.
Added Section 5.2.9，6.2.29，6.2.30，9.5.2.2.
2018.12
V1.2
Update Chapter 1 and Section 5.2.3.
2019.06
V1.3
Corrected a typo in Section 4.2.3.

Table of Contents
1. Overview 1................................................................................................................................
1.1. User-Defined AT Commands!1".....................................................................................................
1.2. Downloading AT Firmware into Flash!1".........................................................................................
2. Command Description 3..........................................................................................................
3. Basic AT Commands 4.............................................................................................................
3.1. Overview!4"....................................................................................................................................
3.2. Commands!4".................................................................................................................................
3.2.1. AT—Tests AT Startup!4"..................................................................................................................
3.2.2. AT+RST—Restarts the Module!4"..................................................................................................
3.2.3. AT+GMR—Checks Version Information!5"....................................................................................
3.2.4. AT+GSLP—Enters Deep-sleep Mode!5".......................................................................................
3.2.5. ATE—AT Commands Echoing!5"....................................................................................................
3.2.6. AT+RESTORE—Restores the Factory Default Settings!5"...........................................................
3.2.7. AT+UART_CUR—Current UART Configuration, Not Saved in Flash!6"......................................
3.2.8. AT+UART_DEF—Default UART Configuration, Saved in Flash!7"...............................................
3.2.9. AT+SLEEP—Sets the Sleep Mode!8"............................................................................................
3.2.10. AT+SYSRAM—Checks the Remaining Space of RAM!8"............................................................
3.2.11. AT+SYSFLASH—Set User Partitions in Flash *!8"........................................................................
3.2.12. AT+FS—Filesystem Operations *!9"...............................................................................................
3.2.13. AT+RFPOWER—Set RF TX Power *!11".......................................................................................
4. Wi-Fi AT Commands 12............................................................................................................
4.1. Overview!12"..................................................................................................................................
4.2. Commands!12"...............................................................................................................................
4.2.1. AT+CWMODE—Sets the Wi-Fi Mode (Station/SoftAP/Station+SoftAP)!12"..............................
4.2.2. AT+CWJAP—Connects to an AP!14"............................................................................................
4.2.3. AT+CWLAPOPT—Sets the Configuration for the Command AT+CWLAP!15"...........................
4.2.4. AT+CWLAP—Lists the Available APs!16"......................................................................................
4.2.5. AT+CWQAP—Disconnects from the AP!16".................................................................................
4.2.6. AT+CWSAP—Configuration of the ESP32 SoftAP!17".................................................................
4.2.7. AT+CWLIF—IP of Stations to Which the ESP32 SoftAP is Connected!18"................................
4.2.8. AT+CWDHCP—Enables/Disables DHCP!18"...............................................................................

4.2.9. AT+CWDHCPS—Sets the IP Address Allocated by ESP32 SoftAP DHCP (The
configuration is saved in Flash.)!19".................................................................................................................
4.2.10. AT+CWAUTOCONN—Auto-Connects to the AP or Not!19"........................................................
4.2.11. AT+CWSTARTSMART—Starts SmartConfig!20"..........................................................................
4.2.12. AT+CWSTOPSMART—Stops SmartConfig!20"............................................................................
4.2.13. AT+WPS—Enables the WPS Function!21"....................................................................................
4.2.14. AT+CWHOSTNAME—Configures the Host Name of ESP32 Station *!21".................................
4.2.15. AT+MDNS—Configures the MDNS Function *!21".......................................................................
5. TCP/IP-Related AT Commands 23..........................................................................................
5.1. Overview!23"..................................................................................................................................
5.2. Commands!24"...............................................................................................................................
5.2.1. AT+CIPSTATUS—Gets the Connection Status!24".......................................................................
5.2.2. AT+CIPDOMAIN—DNS Function!24"............................................................................................
5.2.3. AT+CIPDNS—Sets User-defined DNS Servers; Configuration Saved in the Flash!24".............
5.2.4. AT+CIPSTAMAC—Sets the MAC Address of the ESP32 Station!25".........................................
5.2.5. AT+CIPAPMAC—Sets the MAC Address of the ESP32 SoftAP!25"...........................................
5.2.6. AT+CIPSTA—Sets the IP Address of the ESP32 Station!26".......................................................
5.2.7. AT+CIPAP—Sets the IP Address of the ESP32 SoftAP!26".........................................................
5.2.8. AT+CIPSTART—Establishes TCP Connection, UDP Transmission or SSL Connection!27".....
5.2.9. AT+CIPSSLCCONF—Set Configuration of SSL Client *!29"........................................................
5.2.10. AT+CIPSEND—Sends Data!30".....................................................................................................
5.2.11. AT+CIPSENDEX—Sends Data!31".................................................................................................
5.2.12. AT+CIPCLOSE—Closes TCP/UDP/SSL Connection!31"............................................................
5.2.13. AT+CIFSR—Gets the Local IP Address!32"...................................................................................
5.2.14. AT+CIPMUX—Enables/Disables Multiple Connections!32".........................................................
5.2.15. AT+CIPSERVER—Deletes/Creates TCP or SSL Server *!33"......................................................
5.2.16. AT+CIPSERVERMAXCONN—Set the Maximum Connections Allowed by Server *!33"...........
5.2.17. AT+CIPMODE—Configures the Transmission Mode!34".............................................................
5.2.18. AT+SAVETRANSLINK—Saves the Transparent Transmission Link in Flash!35"........................
5.2.19. AT+CIPSTO—Sets the TCP Server Timeout!36"...........................................................................
5.2.20. AT+CIPSNTPCFG—Sets the Time Zone and the SNTP Server!37"............................................
5.2.21. AT+CIPSNTPTIME—Queries the SNTP Time!37".........................................................................
5.2.22. AT+CIUPDATE—Updates the Software Through Wi-Fi!37".........................................................
5.2.23. AT+CIPDINFO—Shows the Remote IP and Port with "+IPD"!38"...............................................
5.2.24. +IPD—Receives Network Data!38"................................................................................................

5.2.25. AT+PING—Ping Packets!39"..........................................................................................................
6. BLE-Related AT Commands 40...............................................................................................
6.1. Overview!40"..................................................................................................................................
6.2. Commands!42"...............................................................................................................................
6.2.1. AT+BLEINIT—BLE Initialization!42"................................................................................................
6.2.2. AT+BLEADDR—Sets BLE Device's Address!42"..........................................................................
6.2.3. AT+BLENAME—Sets BLE Device's Name!43".............................................................................
6.2.4. AT+BLESCANPARAM—Sets Parameters of BLE Scanning!43".................................................
6.2.5. AT+BLESCAN—Enables BLE Scanning!44".................................................................................
6.2.6. AT+BLESCANRSPDATA—Sets BLE Scan Response!45"............................................................
6.2.7. AT+BLEADVPARAM—Sets Parameters of Advertising!46"..........................................................
6.2.8. AT+BLEADVDATA—Sets Advertising Data!47".............................................................................
6.2.9. AT+BLEADVSTART—Starts Advertising!47"..................................................................................
6.2.10. AT+BLEADVSTOP—Stops Advertising!47"...................................................................................
6.2.11. AT+BLECONN—Establishes BLE connection!48"........................................................................
6.2.12. AT+BLECONNPARAM—Updates parameters of BLE connection!48".......................................
6.2.13. AT+BLEDISCONN—Ends BLE connection!49"............................................................................
6.2.14. AT+BLEDATALEN—Sets BLE Data Packet Length!49"................................................................
6.2.15. AT+BLECFGMTU—Sets GATT MTU Length!50"..........................................................................
6.2.16. AT+BLEGATTSSRVCRE—GATTS Creates Services!50"..............................................................
6.2.17. AT+BLEGATTSSRVSTART—GATTS Starts Services!51".............................................................
6.2.18. AT+BLEGATTSSRVSTOP—GATTS Stops Services!51"...............................................................
6.2.19. AT+BLEGATTSSRV—GATTS Discovers Services!51"..................................................................
6.2.20. AT+BLEGATTSCHAR—GATTS Discovers Characteristics!52"....................................................
6.2.21. AT+BLEGATTSNTFY—GATTS Notifies of Characteristics!52".....................................................
6.2.22. AT+BLEGATTSIND—GATTS Indicates Characteristics!53"..........................................................
6.2.23. AT+BLEGATTSSETATTR—GATTS Sets Characteristic!54"..........................................................
6.2.24. AT+BLEGATTCPRIMSRV—GATTC Discovers Primary Services!55"..........................................
6.2.25. AT+BLEGATTCINCLSRV—GATTC Discovers Included Services!55".........................................
6.2.26. AT+BLEGATTCCHAR—GATTC Discovers Characteristics!56"...................................................
6.2.27. AT+BLEGATTCRD—GATTC Reads a Characteristic!56".............................................................
6.2.28. AT+BLEGATTCWR—GATTC Writes Characteristic!57"................................................................
6.2.29. AT+BLESPPCFG—Configures BLE SPP!58"................................................................................
6.2.30. AT+BLESPP—Enables BLE SPP!60".............................................................................................

6.2.31. AT+BLESECPARAM—Set Parameters of BLE SMP!61"..............................................................
6.2.32. AT+BLEENC—Starts a Pairing Request!62"..................................................................................
6.2.33. AT+BLEENCRSP—Sets a Pairing Response!63"..........................................................................
6.2.34. AT+BLEKEYREPLY—Reply to a Pairing Key!63"..........................................................................
6.2.35. AT+BLECONFREPLY—Reply to a Pairing Result!63"...................................................................
6.2.36. AT+BLEENCDEV—Lists All Devices that Bonded!64"..................................................................
6.2.37. AT+BLEENCCLEAR—Unbind Device!64".....................................................................................
7. AT Commands with Configuration Saved in the NVS Area 65................................................
8. AT Messages 66........................................................................................................................
9. AT Commands Examples 67....................................................................................................
9.1. ESP32 as a TCP Client in Single Connection!67"..........................................................................
9.2. UDP Transmission!68"....................................................................................................................
9.2.1. UDP (with Fixed Remote IP and Port)!68"......................................................................................
9.2.2. UDP (with Changeable Remote IP and Port)!69"..........................................................................
9.3. Transparent Transmission!70"........................................................................................................
9.3.1. ESP32 as a TCP Client in UART-Wi-Fi Passthrough (Single Connection Mode)!71"..................
9.3.2. UDP Transmission (UART-Wi-Fi PassthroughTransmission)!72"..................................................
9.4. ESP32 as a TCP Server in Multiple Connections!74"....................................................................
9.5. BLE AT Examples !76"....................................................................................................................
9.5.1. iBeacon Examples!76".....................................................................................................................
9.5.2. BLE Communication Examples!78"...............................................................................................
10.OTA Update 90.........................................................................................................................
11.Q & A 96....................................................................................................................................

!
1. Overview
1. Overview
This document introduces the ESP32 AT commands, and explains how to use them.
The AT command set is divided into different categories: Basic AT commands, Wi-Fi AT
commands, TCP/IP AT commands, etc.
Please note that the AT commands marked with * are beta versions that have not been fully
tested.
1.1. User-Defined AT Commands
Please use only English letters or an underscore (_), when naming user-defined AT
commands. The AT command name must NOT contain characters or numbers.
AT firmware is based on the Espressif IoT Development Framework (ESP-IDF). Espressif
Systems' AT commands are provided in libat_core.a, which is included in the AT BIN
firmware. Examples of customized, user-defined AT commands are provided in esp-at.
The structure, at_cmd_struct, is used to define four types of a command. Examples of
implementing user-defined AT commands are provided in /esp32-at/main/interface/uart/
at_uart_task.c.
1.2. Downloading AT Firmware into Flash
Please use Espressif's official Flash Download Tools to download the firmware. Make sure
you select the corresponding flash size.
Espressif's official Flash Download Tools:!
http://espressif.com/en/support/download/other-tools?keys=&field_type_tid%5B%5D=13.
Download ESP32_AT_BIN: http://www.espressif.com/en/support/download/at.
The flashing addresses are in /ESP32_AT_BIN/download.config.
Please note that there are several binaries for some specific functions, they are listed as
below:
•at_customize.bin is to provide a user partition table, which lists different partitions for
the ble_data.bin, SSL certificates, and factory_param_XXX.bin.Furthermore, users
can add their own users partitions, and read/write the user partitions with the
command AT+FS and AT+SYSFLASH.
•factory_param_XXX.bin indicates the hardware configurations for different ESP
modules. Please make sure the correct bin is used for your specific module. If users
design their own module, they can configure it with reference to the esp32-at/docs/
ESP32_AT_Factory_Parameter_Bin.md, and the binaries will be automatically
📖Note:
For codes related to ESP32 AT instruction set, please refer to https://github.com/espressif/esp32-at.
Espressif
!/!1 97
2019.06

!
1. Overview
generated after compilation. When users flash the firmware into the module, the
customized_partitions/factory_param.bin in the download.config should be
replaced with the actual module-specific customized_partitions/
factory_param_XXX.bin.
•ble_data.bin is to provide BLE services when the ESP32 works as a BLE server;
•server_cert.bin, server_key.bin and server_ca.bin are examples of SSL server‘s
certificate;
If some of the functions are not used, then the corresponding binaries need not to be
downloaded into flash.
If all functions are needed, then those binaries have to be downloaded into flash. In this
case, there is a CombineBin button on the ESP Flash Download Tool to combine multiple
binaries into one, to make the downloading easier. Please note that the downloading
addresses of binaries and other flash configurations have to be set correctly while
combining.
If users compile esp32-at by themselves, they can call command 'make󰲧print_flash_cmd'󰲧
and print the download addresses, following the steps below:
•Call rm󰲧sdkconfig to remove the old configuration.
•Call make󰲧defconfig to set the latest default configuration.
•Call make print_flash_cmd to print the download addresses."
Modules
UART Pins（TX, RX, CTS, RTS）
Bin
ESP32-WROOM-32 Series
(Default Value)
GPIO17, GPIO16, GPIO15, GPIO14
customized_partitions/
factory_param_WROOM-32.bin
ESP32-WROVER Series
GPIO22, GPIO19, GPIO15, GPIO14
customized_partitions/
factory_param_WROVER-32.bin
ESP32-PICO Series
GPIO22, GPIO19, GPIO15, GPIO14
customized_partitions/
factory_param_PICO-D4.bin
ESP32-SOLO Series
GPIO17, GPIO16, GPIO15, GPIO14
customized_partitions/
factory_param_SOLO-1.bin
📖Note:
UART CTS and RTS are optional pins, not compulsive.
📖Note:
• If the ESP32-AT bin fails to boot, and prints log "ota data partition invalid", please erase all flash or
download the blank.bin into the address labeled as "otadata" in esp32-at/partitions_at.csv.
• Users can change to use another UART for AT communication. For example, if you want to use
UART0 for AT communication, you need to:
- make menuconfig -> component config -> AT -> "AT UART settings" to set it to use UART 0
- The debug log will output through UART0 by default, but users can disable it in menuconfig, as:
make menuconfig --> Component config --> ESP32-specific --> UART for console output
• ESP32_AT_Bin/factory stores the ESP AT factory binaries for different ESP official modules.
Espressif
!/!2 97
2019.06

!
2. Command Description
2. Command Description
Each command set contains four types of AT commands.
Type
Command Format
Description
Test Command
AT+<x>=?
Queries the Set Commands' internal
parameters and their range of values.
Query Command
AT+<x>?
Returns the current value of parameters.
Set Command
AT+<x>=<…>
Sets the value of user-defined parameters in
commands, and runs these commands.
Execute Command
AT+<x>
Runs commands with no user-defined
parameters.
⚠Notice:
•Not all AT commands support all four variations mentioned above.
•Square brackets [ ] designate the default value; it is either not required or may not appear.
•String values need to be included in double quotation marks, for example:
AT+CWSAP="ESP756290","21030826",1,4.
•The default baud rate of AT command is 115200.
•AT commands are ended with a new-line (CR-LF), so the serial tool should be set into "New Line
Mode".
•Definitions of AT command error codes are in esp32-at/components/at/include/esp_at.h.
Espressif
!/!3 97
2019.06

!
3. Basic AT Commands
3. Basic AT Commands
3.1. Overview
3.2. Commands
3.2.1. AT—Tests AT Startup
3.2.2. AT+RST—Restarts the Module
Commands
Description
AT
Tests AT startup.
AT+RST
Restarts a module.
AT+GMR
Checks version information.
AT+GSLP
Enters Deep-sleep mode.
ATE
Configures echoing of AT commands.
AT+RESTORE
Restores the factory default settings of the module.
AT+UART_CUR
Current UART configuration.
AT+UART_DEF
Default UART configuration, saved in flash.
AT+SLEEP
Sets the sleep mode.
AT+SYSRAM
Checks the remaining space of RAM.
AT+SYSFLASH
Sets user partitions in flash
AT+SYSFS
File systems operations
AT+RFPOWER
Sets RF TX power
Execute Command
AT
Response
OK
Parameters
-
Execute Command
AT+RST
Response
OK
Parameters
-
Espressif
!/!4 97
2019.06