How hard can it be to install the ESP-AT firmware onto an ESP-01? In my case, it seems to be a real challenge, because this is the third version of this post. The first time around, I managed to install ESP-AT version 1.7.5 based on the legacy ESP8266 NonOS software development kit (or SDK for short). The second version of the post, showed how I obtained and flashed ESP-AT version 2.2.1 based on the ESP8266 RTOS SDK. This time around I show how to install the newest versions of ESP-AT, either 1.7.6 or 2.2.1, from images available in my sigmdel/other_releases repository. That process is exactly the same no matter which version is installed. The post ends with two sections explaining how to create these images from Espressif public repositories which ensures that the latest version can be installed on the ESP module.

Table of contents

1. The ESP01 Module
2. Which Version?
3. Needed Tools
   1. Esptool
   2. Serial Communication Program
4. Updating Older AT 1.7.x
5. Uploading ESP-AT 1.7.6 or 2.2.1 to the ESP01 Module
6. Getting the NonOS SDK Based ESP-AT Firmware for the ESP-01S Module
7. Getting the RTOS SDK Base ESP-AT for the ESP-01S Module
   1. Using GitHub Actions
   2. Using GitHub Codespaces

The ESP01 Module

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). What follows will be about installing ESP-AT on the ESP-01S with 1MB flash. Based on section 1.2.3. 4 Mbit Flash of ESP8266 Non-OS AT Instruction Set, it should be possible to install ESP-AT on the ESP-01 with only 0.5 MB of flash, but it will not support FOTA (which is probably an acronym for Firmware Over The Air) upgrades. I have not tried this.

Using the ESP-01 presents some challenges because of its limited I/O connectivity and its non-standard I/O connector. As can be seen on the image of the module, 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. 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 as seen on the right 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.

Because of the development of an increasing number of ESP microcontrollers based on the ESP32 architecture, the relatively old ESP8266-based ESP-01 is no longer fully supported in recent software tools. To be fair, both the Arduino IDE and PlatformIO continue to support the ESP-01 (as a generic ESP8266 device) but Espressif does not support it in the master branch of the ESP-AT repository. Some effort must be expended to obtain the AT firmware from the latest ESP8266 branch which is currently release/v2.2.0.0_esp8266.

Which Version?

As already mentioned, there are two versions of ESP-AT from Espressif.

• Version 1.7.6 which is compiled against the deprecated ESP8266_NonOS SDK,
  Manual: ESP8266 Non-OS AT Instruction Set Version 3.0.5 Espressif Systems 2021.
• Version 2.2.1 which is compiled against the ESP8266_RTOS SDK also called ESP-IDF.
  Manual: ESP-AT User Guide, but here is a link to the newest version.

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. 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 versions 1.7.6 and 2.1.1. I could not find a comparison table between the full version and the Nano version of the AT command sets.

There are other implementations of AT style firmware such as the following two.

• 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.
• ESP8266_AT_LoBo ESP8266 AT Firmware built with ESP8266 Non OS SDK with some special features including improved SSL/TLS and support for loading CA certificate to RAM buffer. It is released under the ESPRESSIF MIT License.

Not having tried these versions, I am unable to express any opinion about them. At least they provide the source code with valid open source licenses. Numerous binary blobs are available on the Web (including in one of my repositories), but I would be wary to install those in a production setting.

Needed Tools

Only a couple of tools are needed to flash new firmware to the ESP-01 and then to test it. Indeed, if only interested in updating version 1.7.4 or 1.7.5 of the firmware to version 1.7.6, esptool.py is not needed and a serial communication program will suffice.

Esptool

Espressif provides flash tools. For Windows users, there is the Flash Downloads Tools which can be downloaded here. Since my desktop runs Linux, I use the Esptool.py script which can also be used in MacOS and the Windows Subsystem for Linux (WSL). There's more than one version of this tool on my computer because both the Arduino IDE and PlatformIO download it as part of ESP platform toolchains. To avoid any conflict with these downloads, I installed the latest version of esptool.py in a Python 3 virtual environment. Espressif has instructions on Virtual Environment Installation. I used my own script to create a virtual environment and to activate it.

Checking, there are only two packages installed in the virtual environment. We will add esptool which has many dependancies.

In all 12 modules were installed in addition to esptool.

Let's test the script by getting the flash id.

Serial Communication Program

In version 2, I showed how the serial monitor of the Arduino IDE and PlatformIO could be used to communicate with the ESP module. However, I preferred using a standalone terminal program instead of these programming environments to go about testing the firmware. While I was using cu (actually opencu), I now prefer picocom because it has a simple map feature that takes care of the end of line CR+LF combination required by the AT serial monitor.

Note [C-a] is the picocom way of writing ^C^A, the Ctrl A keyboard combination. The long enumeration of settings and other out-of-band messages will not be displayed when the quiet (-q) parameter is added to the command line.

I am not sure that picocom works in Windows. As it happens, the miniterm.py script, which is part of the pyserial module installed in the esptool virtual environment, can be used just as well as picocom. The script has to be made executable, but that is a one-time only requirement.

Then whenever the virtual environment is enabled, the script can be invoked.

Presumably this works in Windows also. One could always use PuTTY in Windows. It seems that two options in the PuTTY Terminal configuration should be checked:

• [ ] Implicit CR in every LF
• [ ] Implicit LF in every CR

Updating Older AT 1.7.x Versions

If the ESP01 is currently running a stock version of ESP-AT version 1.7.4 or 1.7.5, it is possible to update to version 1.7.6 (see Update steps). Here is a somewhat more detailed list of steps to follow, assuming that the ESP-01 is not connected to a local network with access to the Internet. If the ESP01 can reach the Internet, then jump to the AT+CIUPDATE command.

1. Make sure Wi-Fi is enabled on the ESP-01 and that it is in STA (station) mode.
   
   AT+CWMODE_CUR=1 OK
2. List the available Wi-Fi networks (optional step).
   
   AT+CWLAP +CWLAP:(3,"Welcome!!",-84,"18:90:88:56:3d:c6",1,33,0,4,4,7,0) +CWLAP:(3,"",-87,"d6:e2:cb:4d:71:fa",6,32767,0,4,4,7,0) +CWLAP:(5,"",-89,"d6:e2:cb:4d:71:fe",6,32767,0,4,4,7,0) +CWLAP:(3,"Playtek",-47,"f7:ae:42:42:43:44",11,32767,0,4,4,7,1) +CWLAP:(3,"",-84,"fa:5e:42:43:6b:13",11,32767,0,4,4,7,0) +CWLAP:(5,"",-86,"fa:5e:42:43:6b:17",11,32767,0,4,4,7,0) OK
3. Connect to the correct local Wi-Fi network with access to the Internet.
   
   AT+CWJAP="Playtek","12345678" adjust name and password as needed WIFI CONNECTED WIFI GOT IP OK AT+CIFSR +CIFSR:STAIP,"192.168.0.143" +CIFSR:STAMAC,"a0:20:44:33:22:11" OK
4. Check the current version of ESP-AT.
   AT+GMR AT version:1.7.4.0(May 11 2020 19:13:04) SDK version:3.0.4(9532ceb) compile time:May 27 2020 10:12:17 Bin version(Wroom 02):1.7.4 OK
5. Perform the update, which should work assuming that the current AT version is 1.7.4 or better.
   
   AT+CIUPDATE +CIPUPDATE:1 +CIPUPDATE:2 +CIPUPDATE:3 +CIPUPDATE:4
   Be patient, it takes a couple of minutes, and once the firmware is downloaded, the ESP-01 will disconnect from the Wi-Fi network and reboot. Once rebooted, it will reconnect.
   WIFI CONNECTED WIFI GOT IP
6. Check the ESP-AT version.
   
   AT+GMR AT version:1.7.6.0(Jan 24 2022 08:56:02) SDK version:3.0.6-dev(072755c) compile time:Jun 17 2024 07:37:49 Bin version(Wroom 02):1.7.6 OK

I cannot confirm that over-the-air updates work in pre-1.7.4 versions of the firmware, but my guess is that it will work with all 1.7.x versions. On the other hand, I can confirm that it was not possible to update ESP-AT version 1.3.0 preloaded on an older ESP-01S that was on hand.

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 a serial connection.

Uploading the ESP-AT 1.7.6 or 2.2.1 Firmware to the ESP01 Module

Obtain the desired version of the ESP-AT firmware from the sigmdel/other_releases repository on GitHub. The binary espat_xxx_esp01s (where xxx is 176 or 221) file needs to be extracted from its corresponding archive espat_xxx_esp01s.zip.

It is necessary to know the device path of the ESP-01 module. It can be found by listing kernel messages with dmesg as the serial connection to the ESP-01 module is made.

If the ESP-01 is already connected to a USB port, then "grep" the kernel messages.

The tail command can be used as shown, if the ESP module was the last connected USB device. If not, just remove the | tail -n 4 bit and inspect all USB devices loaded to find the correct one.

Before uploading new firmware on the ESP module, it is probably a good idea to save a copy of the current firmware. That can be done with esptool.py. I will be saving this backup in a directory named ~/temp, but a better location would be more appropriate.

One of the advantages of doing this is that, esptool.py can display some information useful for when uploading new firmware to the same module.

If the flash size is less than 1MB then it will be impossible to upload the firmware. The espat_xxx_esp01.bin is also stored in the ~/temp directory. So it's a relatively simple matter to upload the firmware.

where xxx is either 176 or 221 as desired. Now to test the upload, open a serial connection to the module. There is no need to be in the Python virtual environment for this step.

If the upload failed, or if a serial connection could not be made with the module, then here are possible problems with solutions.

• Some modules may not function at 460800 baud; try -b 115200 in that case.
• Some modules may not support flash mode qio; try -fm dout in that case.
• Some modules may not support an 80 Mhz frequency; try -ff 40m in that case.

The image information obtained from the saved firmware should provide a minimum floor for the last two variables assuming the module was working properly before.

Does getting firmware from some random GitHub repository feel a bit sketchy? If it were not for the fact that github.com/sigmdel is my repository, I would agree. Besides, there is no guarantee that the binary in sigmdel/other_releases will always contain the latest version. Consequently, it is a good idea to get the firmware from the official source.

Getting the NonOS SDK based ESP-AT Firmware for the ESP-01S Module

If the ESP-01 module is running a recent enough firmware obtained from a trusted source, then the obvious route is to update with the AT+CIUPDATE command as explained above. Otherwise, follow the second suggestion from Robert Oostenveld (in Restoring the AT firmware on the ESP8266 September 22, 2018) and go to the latest version of the ESP8266 NonOS repository which was updated 5 months ago. The bin/at/512+512 directory contains the Nano version of ESP-AT 1.7.6 which supports an SSL library with fewer ciphers but which fits in 1 MB of flash memory. Actually, the code fits into 0.5 MB which allows for over-the-air updates. The bin/at directory contains boot and data partitions. Only three binary files are needed from the repository so there is no need to clone the repository or to copy the entire archive.

• https://github.com/espressif/ESP8266_NONOS_SDK/raw/release/v3.0.5/bin/boot_v1.7.bin
• https://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.7.6 binaries and downloaded the files into it.

Then I created a text file named upload.txt with the following content.

The last three lines, 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, 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. As per the comments at the end of the Uploading the ESP-AT Firmware to the ESP01 Module section, it may be necessary to tweak the flash mode, flash frequency, and the serial baud values. The ve_esptool virtual environment containing esptool.py, which is needed to upload the firmware, is enabled first.

Now we can deactivate the virtual environment, return to the home directory and check that version 1.7.6 (or newer) is correctly uploaded.

Remember that only critical bug fixes are made to the ESP8266 NonOS SDK and that Espressif suggests that the ESP8266_RTOS_SDK be used instead of ESP8266 NonOS SDK.

Getting the RTOS SDK Based ESP-AT Firmware for the ESP-01S Module

There are at least three ways of obtaining the latest version of ESP-AT in the recommended ESP8266 RTOS SDK. I'll look at two solutions that do not involve installing the SDK on a local computer and compiling the project. However they do require having a (free) GitHub account. It was that requirement that prompted me to upload the binary to my github.com/sigmdel/other_releases repository in the first place.

Using GitHub Actions

In the Released Firmware page of the ESP-AT User Guide, there is an important note.

The continuous integration and continuous delivery platform in GitHub is implemented in Actions. Following the instruction and keeping in mind the last sentence in the note, here is how to proceed.

1. Log into your GitHub account.
2. Access the ESP-AT repository at the following URL https://github.com/espressif/esp-at.
3. Click on the Actions button as seen next.
   
4. All the workflows defined in the project will be shown.
   
5. At the top of the list of workflow runs, click on Branch button.
6. Select the most recent xxxx_esp8266 branch as shown above.
   
   Once the correct branch is selected the workflows listed are only those related to the wanted branch.
7. Click on the most recent workflow at the top of the list. The results for the workflow will then be displayed. Here is a collapsed view (click on the image to see the full page where it will be clear that there were a number of warnings; more about that later).
   
8. Click on the download icon of the esp8285-1MB-at artifact.
9. The wanted firmware can be extracted from a directory called factory in the downloaded archive. The following commands list the content of that archive directory, extract the wanted file and check that it has been extracted and place in the same directory containing the archive.
   michel@M7:~/temp/esp8285-1MB-at-1$ ls -l total 4244 -rw-rw-r-- 1 michel michel 4345437 oct 30 22:03 esp8285-1MB-at.zip michel@M7:~/temp/esp8285-1MB-at$ unzip -l esp8285-1MB-at.zip factory* Archive: esp8285-1MB-at.zip Length Date Time Name --------- ---------- ----- ---- 0 2024-10-30 12:08 factory/ 1048576 2024-10-30 12:08 factory/factory_ESP8266_1MB.bin 120 2024-10-30 12:08 factory/factory_parameter.log --------- ------- 1048696 3 files michel@M7:~/temp/esp8285-1MB-at$ 17 michel@M7:~/temp/esp8285-1MB-at$ ls -l total 5268 -rw-rw-r-- 1 michel michel 4345437 oct 30 22:03 esp8285-1MB-at.zip -rw-r--r-- 1 michel michel 1048576 oct 30 12:08 factory_ESP8266_1MB.bin

Unfortunately, the firmware is not suitable for the ESP-01S module because the firmware is configured on the assumption that the following connections are in place (reference):

This is not even possible with the ESP-01S module. So I/O pins have to be reassigned. Thankfully, this can be done by modifying the binary file with a utility called at.py provided by Espressif. I prefer to copy that file into the virtual environment created for esptool.

So now it is possible to patch the downloaded binary with the well documented at.pyutility.

To summarize, we obtained the latest ESP8266 RTOS SDK version of the ESP-AT firmware by downloading the firmware from the appropriate Actions workflow in the espressif esp-at repository and then modifying its I/O pin assignment with the at.py utility from the same repository. So now it's just a matter of uploading the modified file to the ESP01 as explained above.

Using GitHub Codespaces

A GitHub codespace is a Docker container hosted by GitHub which consists of a Ubuntu Linux image supplied with popular languages (like Python) and tools (like apt-get). It can be set up to install the ESP-IDF making it possible to compile the ESP8266 RTOS SDK version of the ESP-AT code in the cloud all from the comfort of a Web browser. Let's be honest here. I had no clue how to do this. Indeed I did not even know about GitHub Codespaces until Oct 22, when I received a message from Bernhard Bablok:

You might want to ... link to the page: https://github.com/bablokb/circuitpython-esp32at/blob/main/doc/at_firmware_compile_esp01s.md These instructions should get you the newest AT-version within a quarter of an hour without installing a single byte to your computer (thanks to the cloud).

Obviously I have included the link, but why since the firmware was available from GitHub Actions?

• No need for at.py
  With a simple edit of a configuration file, it is possible to modify the I/O pin assignment before compiling the firmware. Consequently the at.py utility is not required. The required modification is clearly defined in step 8 of Bernhard's instructions.
• Better reliability
  There were ominous deprecation notices when using Actions.
  
  Actually, these notices were more than ominous. As late as October 25, the #707 commit c4d6f32 workflow, which at the time was the newest merged branch, would not produce artifacts. On the same day, the newest version of ESP-AT 2.2.2.0-dev(b65f53f - ESP8266 - Jul 5 2024 06:59:26) could be compiled against the newest version of the SDK (v3.4-84-ge19ff9af) following Bernhard Bablok's instructions without any difficulty.
• New Toy
  Setting up the Espressif IDF in a virtual machine with the help of Bernhard Bablok was actually fun and I feel I have learned something useful. This first real contact with the ESP-IDF has made me rethink my decision to stay away from it.

I am not including a sequence of screen captures detailing how to compile the firmware with GitHub Codespaces because the instructions by Bernhard Bablok are clear and complete. However, my scant knowledge of git and github didn't allow me to understand precisely how to select the correct branch in step 2. So for future reference, here is how I created a codespace on the appropriate branch of the ESP-AT repository.

1. Fork the complete repository
   
   Uncheck the Copy the  master  branch only box before clicking on the Create Fork button.
2. Select the newest ESP8266 branch
   
   Click on the master branch button at left and scroll down the list of branches until the first releases/vXXXXX_esp8266 branch is found and select it.
3. Create a codespace on that branch
   
   The selected branch (release/v2.2.0.0_esp8266) should now be displayed, so click on the green [<> Code v] button and select the Codespaces tab. There should be a large green button Create codespace on release/v2.2.0.0_esp8266. Since that's what is needed, click on it.

From there, I followed all of Bernhard's instructions without deviation starting at step 3, and in the end I obtained the following version of the firmware.

That was on October 25th. After deleting the codespace and the fork created on the 25th, I created a new fork of the complete repository as in step a) above. With that, it was possible to create a new branch based on releases/v2.2.0.0_esp8266 to and then go on to create a codespace on that release as instructed in step 2 by Bernhard. Here is the AT version created with this attempt.

As can be seen, that was completed on November 25. An image of this firmware is now available in sigmdel/other_releases. I did not manage to complete step 9 which is about committing the changes to the factory_param_data.csv file as Bernhard did in his fork of ESP-AT. This setback, clearly linked to my lack of experience with the push and pull requests in GitHub, is not important in the current context, but it is one more argument for abandoning Mercurial and learning to use git directly.