How hard can it be to install the ESP-AT firmware onto an ESP-01? It was not all that clear to me how to proceed. Consequently, it has taken more than a year since the release of the first version of this post which showed how to install ESP-AT version 1.7.5, to release this second version which contains instructions on installing ESP-AT version 2.2.1. These are the currently newest versions of ESP-AT that are based on the ESP8266 NonOS SDK and the ESP8266 RTOS SDK respectively.
The tiny ESP-01 board which came with Espressif's version of the AT firmware was among the first boards with an Espressif chip used in the hobbyist world. The original version of the ESP-01 had 512 Kbytes of flash memory, but it was quickly upgraded to 1 MBytes. These newer boards with more flash memory are often labelled ESP-01S (see Differences between ESP-01 and ESP-01S). Currently, a version of ESP-AT can be installed on ESP8266 boards with 1 MB of flash memory. As far as I know, there is no support for ESP-AT on modules with less than 1 MByte of flash memory. Indeed, the full version of ESP-AT requires 2 MB of flash memory and consequently the versions installed on the ESP-01S do not have all the features of the full versions.
If you are not old enough to remember configuring modems with Hayes AT commands and are wondering what AT firmware is all about, see What is ESP-AT. And no, I am not going to explain what a modem is!
Table of contents
- Basics: Serial Connection with the ESP01
- Updating Older Versions to ESP-AT Version 1.7.5
- Installing
esptool.py
andat.py
- Installing ESP-AT Version 1.7.5
- Installing ESP-AT Version 2.2.1
- About the
esptool.py
Parameters - Other Implementations
- Which Version?
Basics: Serial Connection with the ESP01
As can be seen on the left, four general-purpose input/output pins (GPIO0 to GPIO3), the chip enable and reset pins, ground and the Vcc input are connected to the eight pin header at the bottom of the board. GPIO1 and GPIO3 are used as the TX and RX signals of a serial (UART) peripheral. For most a serial to USB adapter will be required to connect a computer to the ESP01 board. Although the header is standard 0.1" the ESP01 is not breadboard compatible so it will be necessary to set up some sort of a jig to connect to the ESP01 and to program it. There are many tutorials on that subject on the Web. I chose the easy way out, preferring to use a relatively inexpensive bare ESP8266 module programmer that happens to handle ESP01 boards. Make sure to plug the ESP01 into the ESP-01S socket with the antenna up in the same orientation as shown on the left. It is easy to upload new firmware to the board with the command line esptool.py
utility from Espressif without having to worry about pressing buttons to put the board into programming mode. Of course, the programmer also acts as a USB to serial converter.
The Arduino IDE will not be used here, but if it is installed then its Serial Monitor can be used to send AT commands and receive the output from the AT firmware on the ESP01. Set the baud to 115200
and Both NL & CR
for line ending.
Similarly, the serial terminal in PlatformIO can be used to communicate with PlatformI0. Create a new project and use the following settings in the project configuration file (platformio.ini
).
Alternatively, a stand-alone terminal program can be used. On my Linux machine, I use cu
(actually opencu). It is a very light serial terminal emulator and, consequently, so basic that the line feed character has to be entered with the Ctrl+J keyboard combination after pressing the Enter key (or Ctrl+M combination) the at the end of each command.
Because it is very tedious to type, the end of line characters will not be shown from now on.
Updating Older AT Versions to Version 1.7.5
If the ESP01 is currently running a stock version of ESP-AT version 1.7.4, it is possible to update to version 1.7.5 (see Update steps).
I power cycled the ESP-01 just to make sure that everything worked.
It does not appear that there is an upgrade path beyond 1.7.5. The AT+CIUPDATE command did nothing useful when the firmware is already at version 1.7.5. Later it may be possible to update if there's ever a newer version created in the ESP8266 NonOS environment. I cannot say if this approach works older versions of the firmware but it was not possible to update AT version 1.3.0 in this fashion.
The advantage of this approach is that the update only requires a terminal emulator to enter AT commands on the ESP01 and a functioning connection from the ESP to the Internet to download the update. If it is not possible to perform on over-the-air update to the desired version of ESP-AT, then new firmware will have to be uploaded to the board over the USB connection.
Installing esptool.py
and at.py
There are utilities that can upload firmware to the ESP that provide a graphical interface and that may be more convivial than the command line utility esptool.py
from Espressif. However the latter is a Python script that should run on Windows, Mac OS and Linux. Furthermore it is simpler to document how to use it in a written text. As if often the case, there are many ways to install the utility (see ), I prefer to do it within a Python virtual environment. I am still using virtual environment schema that I put in place in 2017 ( and which has been described in other posts on this side. There is no need to repeat any of that.
If ESP-AT version 2+ is desired then another utility named at.py
is needed.
Installing ESP-AT Version 1.7.5
Following the second suggestion from Robert Oostenveld in Restoring the AT firmware on the ESP8266 (September 22, 2018), I went to the latest version of the ESP8266 NonOS repository which is now two years old. There is a warning stressing that the ESP8266_NONOS_SDK
is now deprecated.
Nevertheless the bin/at/
directory contains the Nano version of ESP-AT 1.7.4 which supports an SSL library with fewer ciphers but which fits on 1 MB of flash memory which corresponds to the amount of flash on "newer" versions of the ESP-01 sometimes identified as the ESP-01S . The "normal" version of the AT firmware requires at least 2 MB of flash, so it cannot be installed on the EPS-01. That version of AT is in the master branch of the repository which corresponds to version 3.0.4 of the SDK. As it happens there is a version 3.0.5 branch which contains version 1.7.5 of the AT firmware, which as of now is the latest version of AT within the NOOS SDK.
I only needed three binary files from the repository.
- https://github.com/espressif/ESP8266_NONOS_SDK/raw/release/v3.0.5/bin/boot_v1.7.bin
- hhttps://github.com/espressif/ESP8266_NONOS_SDK/raw/release/v3.0.5/bin/esp_init_data_default_v08.bin
- https://github.com/espressif/ESP8266_NONOS_SDK/raw/release/v3.0.5/bin/at/512%2B512/user1.1024.new.2.bin,
I created a directory to contain the V1.75 binaries and downloaded the files into it.
Then I created a text file named upload.txt
which contains the name of the binary files to flash to the ESP01 along with the address at which they are to be placed in the flash memory.
The last three lines are pulled from the Flash size 8Mbit: 512KB+512KB section in the AT documentation in the repository. The first line contains upload parameters for the esptool.py
utility
Just to make sure, reset the ESP-01 or turn power to it off then back on. It should show up as the same device/COM port as before. Open a serial connection to the board and verify that AT commands are executed and get the version.
That's a confirmation that version 1.7.5 (October 20, 2021) of the AT firmware is now running on the ESP-01S.
The ESP-AT resources page has the following entry: ESP8266 NonOS AT Bin V1.7.5 (2021.10.18)
. It contains a link to a ZIP archive https://www.espressif.com/sites/default/files/ap/ESP8266_NonOS_AT_Bin_V1.7.5_1.zip. Using that source to upload using upload.txt
from above installs the following version.
AT version:1.7.5.0(Oct 9 2021 09:26:04) SDK version:3.0.5(b29dcd3) compile time:Oct 15 2021 18:05:30 Bin version(Wroom 02):1.7.5
It is a few days older than the version downloaded from the GitHub repository.
Installing EST-AT Version 2.2.1
In the Released Firmware page of the ESP-AT User Guide, there is an important note.
esp8285-1MB-at
under the Artifacts
page).
ESP-WROOM-02 Series
v2.2.1.0 ESP8266-IDF-AT_V2.2.1.0.zip (Recommended)
v2.2.0.0 ESP8266-IDF-AT_V2.2.0.0.zip
v2.1.0.0 ESP8266-IDF-AT_V2.1.0.0.zip
v2.0.0.0 ESP8266-IDF-AT_V2.0.0.0.zip
Following those instructions, I downloaded esp8285-1MB-at.zip
. There is no point in giving a link, the file is quickly removed after being generated. Be aware that it is necessary to have an account on GitHub to generate this file. Here is the content of the archive.
I changed the first line of download.config
to make it the same as in upload.txt
and then proceeded to upload the firmware.
While the uploading appears to proceed correctly, something goes wrong and the blue communication LED remains on even after a power cycle. It was possible to connect to the ESP serial port, but only garbage was received at all plausible baud and AT commands were ignored. Quite recently Arnaud Baixas described the same situation in the Espressif ESP-AT Forum when using the esp8285-1MB-at.zip
from a slightly older commit. Unfortunately, no one has offered a solution to our common problem. In the first version of this post, I left it at that. This time around, I was a bit more diligent. Searching the ESP-AT GitHub repository, I found a Sept 2022 issue entitled v2.2.0.0_esp8266 无法启动 #668 which translates to v2.2.0.0_esp8266 Unable to start #668. Ustccw commented that
Log output should come from GPIO2, not the download port. Could you please double check your hardware connection.
Luckily GPIO02 is available on the ESP-01S, so I connected another serial to USB adapter to that pin, opened a terminal and reset the board. Here is the log after some formatting of the output.
According to ustccw's reply to techrah who had almost the same log output, this shows that the firmware is good. Again, ustccw suggests checking the hardware connection. The same day, techrah reported that after carefully reading the information he found two solutions to the problem. So I read hardware connection for the ESP8266, this time with my eyes open, and found that the uploaded ESP-AT switches the serial peripheral (UART0) to different I/O pins. How odd; this didn't happen in V1.7.5 or earlier. On second thought, this made sense if ESP-AT is loaded onto an ESP8266 module with more exposed pins. One would probably want to use a different pair of pins to connect to another MCU that wants to use the ESP to communicate via Wi-Fi without having to deal with a USB connector. But on the ESP-01 there's no such possibility.
It looked like it would be necessary to recompile ESP-AT to undo this and techrah did say where the change had to be made. Of course, I am lazy and don't want to install the ESP-IDF and learn all the intricacies of compiling such a complex program as ESP-AT. Again, ustccw saved the day by pointing out that there is a utility, at.py
that can modify the UART configuration in the firmware binary file. So I first planed to read the uploaded firmware from flash memory with esptool
, apply the change to the downloaded binary file with at.py
and then write the modified binary file back to flash memory with esptool
. Then on a hunch, I successfully altered factory/factory_ESP8266_1MB.bin
with at.py
and uploaded that.
It turns out that at.py
was well documented. Once again RTFM!
So now it's just a matter of uploading the modified file to the ESP01.
The log output was different after resetting the ESP01.
The SPI speed (frequency) and mode appear correct. And again, it looks like version 2.2.1 is loaded. Testing with the same serial I/O pins as used to upload the firmware confirmed this.
Not everyone has a GitHub account, and without it, it will be difficult to get the latest esp8285-1MB-at.zip
. Consequently, I have made the modified binary espat_esp01.bin
available from my account in the other_releases repository. Understand that this is really only for those that want to try ESP8266-AT on an ESP-01S. The file, created on September 5, 2023, will not be updated as new versions of ESP-AT are made available, so that it will soon be necessary to use the procedure described above to get an up-to-date version of the firmware.
The file can be downloaded by clicking on the file name and then on the download icon at the right edge. It can also be obtained with the command line utilities wget
or curl
with the -L
parameter
About the esptool.py
Parameters
Which are the valid flash parameters for the ESP-01S? It was confusing; in some examples flash_mode
was set to dout
and others to dio
. Similarly, flash_freq
was set at 40m
or 80m
. Making things worse, it did not seem to matter much what value was set. Espressif has documented the flash_mode
options in SPI Flash Modes. Here is the performance summary provided on that page.
Option | Mode Name | Pins Used | Speed (ESP device) |
---|---|---|---|
qio | Quad I/O | 4 pins used for address & data | Fastest. |
qout | Quad Output | 4 pins used for data. | Approx 15% slower than qio. |
dio | Dual I/O | 2 pins used for address & data | Approx 45% slower than qio. |
dout | Dual Output | 2 pins used for data. | Approx 50% slower than qio. |
As for flash_freq
it is the frequency of the SPI clock signal, a square wave, generated by the ESP which is used by the flash memory. Since the latter synchronizes date reads and writes with that clock, the higher frequency is preferable. Basically then flash_mode=quio
and flash_freq=80m
is the best setting possible. The only trouble is that the flash memory must support those settings and there is no guarantee that the actual chip on a given ESP-01S does. Espressif provides the following advice: In general, choose the fastest option for flash_mode [and presumably for flash_freq] that works with your device. Not all devices support all modes. That's the kind of advice that many find frustrating, especially when installing new firmware for the first time on a new piece of hardware.
In the Why don't quio & qout modes work in my Espressif chip/module? FAQ, Espressif says Look up the flash chip datasheet to see which modes it supports. You can identify the flash chip visually, or by using the esptool.py flash_id command. I cannot make out the markings on the chip so I looked at the flash id.
Unfortunately I could not find the manufacturer based on the 0xE0 id number. Given this lack of information, I should have used flash_mode=dout
and flash_freq=40m
for the first upload of ESP-AT. Once that was found to work, the optimal values should have been ascertained by systematically uploading the firmware with increasingly more performant values for the mode and then for the frequency. Of course, I didn't do that. Instead I flashed a "hello world" program with PlatformIO which has a specific board definition which we saw in the first section of this post. Then I copied the flash memory to a file with esptool.py read_flash
in order to read the parameters used by PlatformIO.
I could have gotten the same information much more quickly by reading the board definition file .../.platformio/platforms/espressif8266/boards/esp01_1m.json
.
So I have shown the values flash_mode=dout
and flash_freq=40m
through out this post because they worked with two ESP-01S in my possession. The higher 80m
frequency seems to work with at least one of the modules but I have not methodically tested that.
Other Implementations
As already said, I had failed to install version 2.1.1 (or more accurately I had failed to realize that the firmware was correctly installed and that the I/O pins used for the serial link had been switched) when I wrote the first version of this post. As a consequence I looked for other implementations of the AT style firmware. It may not be pertinent any more but here are the two possibilities that I found
- ESP8266-1MB-tx1rx3-AT_V2.2 by Juraj Andrássy. I found this in the author's comment in factory builds for ESP8266 incompatible with ESP-01 modules #606. Without wanting to impugn anyone's reputation in any way, it must be pointed out that I could not find the source for the 2.2.0 binary provided by Juraj Andrássy.
AT version:2.2.0.0(s-b097cdf - ESP8266 - Jun 17 2021 12:58:29) SDK version:v3.4-22-g967752e2 compile time(6800286):Jul 11 2021 11:09:32 Bin version:2.2.0(ESP8266_1MB)
The author does say that he compiled from the Espressif source, but I would be more comfortable if this was a bit more transparent. When he wrote that he read the manual then I suppose he is referring to How to compile and develop your own AT project in the ESP-AT User Guide for therelease-v2.2.0.0_esp8266
. - ESP_ATMod ESP8266 AT Firmware (Command Processor) With TLS 1.2 Capability by Jiri Bilek (JiriBilek). The project license is LGPL-3.0 and, consequently, the source is available. This library improves the TLS implementation by adding GCM-based ciphers at the expense of some functionality. There is no problem compiling this project with PlatformIO and installing it on an ESP-01S and, presumably, one could use the Arduino IDE to do the same.
Which Version?
Finally, there is a manual for ESP-AT version 1.7.5: ESP8266 Non-OS AT Instruction Set Version 3.0.5 Espressif Systems 2021. The ESP-AT User Guide should apply to version 2.2.0 on ESP8266. The command sets are quite similar but not exactly the same. The AT Command Set Comparison page lists the differences between the AT commands supported by the old NONOS-AT version and those by the new ESP-AT version. This may be misleading for those interested in running ESP-AT on the ESP-01 because it can only run cut-down versions (Nano) of the V1.7.5 and V2.1.1. I could not find a comparison table between the full version and the Nano version of the AT command sets.
At a glance, it is difficult to ascertain which version should be used. Version 1.7.5 is compiled against the deprecated ESP8266_NonOS SDK, while the newer version is compiled against the ESP8266_RTOS SDK also called ESP-IDF. Espressif is unambiguous, NonOS-AT is not recommended [...] for ESP8266 series of chips since its base SDK, ESP8266_NONOS_SDK, is no longer updated while ESP-AT is the recommended version [because it] supports all series of chips and [has] a richer set of commands compared with NonOS-AT. From the casual user/hobbyist point of view, this is not necessarily very important. The AT firmware turns an ESP board into a self-contained serial to Wi-Fi converter. If the AT command set is nearly the same then it may not matter.