Kacang Bawang

The AT firmware is the default firmware for ESP8266 and provides AT style commands for actions such as join access point and send tcp packet. It is distributed in binary form by Espressif, but it can also be built from source (binary blobby as it may be). Typically one can find a new version of AT firmware in each release of Espressif’s SDK.

Since SDK version 1.0.1 the binary distribution of AT has become too large to fit on a 512kB flash. However, at this point in time (end of May 2015) most of the ESP8266 units out there are of the 512 kB variety. Thus begging the queston: how can one update their AT firmware to the latest version?

The answer: we will build it ourselves. For this we will need a way to compile esp8266 projects. There are 3 options:

1. Gather the tools yourself (see for example: Russian, Google translated)

2. Use ESP OPEN SDK, which gathers all the tools from (1) for you automatically. They also post updates, such as when new SDKs come out. This is the preferred method.

3. Use the Windows SDK by Cherts. I develop on Linux, so I won’t be covering this route, but it should work just the same.

As our starting point, let’s assume you have the development environment installed. You may have even tried to cd to /SDK/examples/at and tried to build it, but have received the following message:

Running a little bit ahead I will tell you that it is due to Espressif’s makefile structure, but first let’s step back and take a look at the flash layout.

Since SDK 0.8 we’ve had the ability to do OTA updates. This was achieved by splitting the flash into two halves – the current firmware and the incoming update. The device runs from one or the other such that the unused slot may be overwritten with new data. This requires the use of a second stage bootloader, since the first stage (hardware) bootloader always starts executing from the same location and as such, does not recognize existence of two firmware slots. For more details on how that works, see Richard Burton’s excellent series of posts about the ESP bootloading process and his own open source bootloader: rBoot. Furthermore, since there are now two copies of the firmware living in the flash, each one can only be 1/2 as large as before. Let’s take a look at the difference:

Thus, the amount of memory available to firmware is:

Now let’s take a look at the latest AT, as built with default settings:

As you can see the combined firmware at 251.4 kB will not fit into the 1/2 flash sized slot of 249kB. Just barely. For this reason Espressif now packages the new AT as built for the larger flash, with a 2 slot setup. With a 512kB flash the only option is to use the whole flash for one firmware, which will accomodate up to 496kB.

An aside:
Q: How do I tell what SPI Flash I have and what is its size?
A: using esptool.py reboot into flash mode and issue the following command: ./esptool.py flash_id. Using the returned info find your flash chip and look up its specs. This is actually pretty hard, but eventually I found a comment on esp8266.com (don’t know the specific post anymore – hat tip to the unknown). It said that:

So where were we? Oh, right – we’ve got the build environment installed and we’re going to build our own AT firmware which we will then package into a 1-slot image to be flashed.

Since we’re not going to be modifying the project – we just want to build it – we also won’t rewrite its makefile. We will use Espressif’s makefile, which is rather convoluted. Most of the work is in the non-project specific makefile (let’s call it “master” makefile) and it is referred to from each project as “../Makefile”. If such master makefile is not found, nothing will build. The master makefile takes as its inputs several variables (with defaults). They are defined when you run gen_misc.sh

If you “make” the master makefile it will attempt to build every directory in its folder. Sort of like “build all projects”. If you go into a project directory and do a “make”, it will build only that project, but it will still need that master makefile.

Here is how you should organize your AT project directory. Create a directory, somewhere away from the SDK, like in your home dir, for example. Fill it with the following contents:

At this point you can either go into /home/my_at/at and run genmisc.sh which will have you choose some options interactively and then will call the master makefile. Choose all defaults – this gives us the single slot setup for a 512kB sized flash. Although I prefer to inline these options at the top of the copy of the master makefile. That way I just “make” instead of having to go through genmisc.sh prompts. Here’s what I added to the top of /home/my_at/Makefile:

This should produce eagle.flash.bin and eagle.irom0text.bin in the bin directory for us.

Oh, one other note: in SDK 1.1.0_15_05_22 there is a missing define. This was fixed in the latest 1.0.1, but in case you see a linking error complaining that:

Hat tip to rudi.

Ok, so we’re ready to flash. This should be simple enough:

But somehow (for me at least) that results in the first 0x5000 bytes being erased (all FF’s). Through some experimentation, it was established that the order of files in the flash command matters. See here for a discussion.

If you are encountering this weird flashing issue, could you please comment either here or on esp8266.com?

That should right about do it for building and flashing the newest AT firmware from Espressif’s SDKs. Thank you for reading this far ;P