Programming the ESP8266 on an ESP-01 development board

Introduction to the ESP-01

The first thing that you are going to need, obviously, is an ESP8266 system on a chip (SoC). These are a low cost wifi chip manufactured by Chinese firm Espressif. As they are low cost they have been widely adopted by the Internet Of Things (IoT) community as a great way of connecting devices wirelessly and fairly easily. Data sheets and tutorials are readily available for these chips and as such there is a lot of information and help out there to easily get up and running with these devices. These are my notes and experiences on using this chip, and hopefully you may find it useful.

The first thing I did was order some of the 8266 chips mounted on a development board manufactured by a company called AI-Thinker. To my knowledge there are approx 14 or so different easily available dev boards ranging from ESP-01 through to ESP-14. For the purpose of this documentation all experiments and research are carried out on an ESP-01. I purchased 5 of them from Amazon and they cost less than £2 each.

The ESP-01 essentially comprises of a 8266 SoC which is a micro controller with combined wifi capabilities. Some people use these in conjunction with an Arduino or similar. In my findings this is not necessary as I think the ESP8266 beats the ATMega328p that comes with the standard Arduino Uno on processing ability.
On the board there is also a Flash Memory chip which is external to the ESP8266. On the early boards which I believe are coloured blue this would have a capacity of 512kB (4Mb). On the later version which have a black circuit board these have been upgraded to have a capacity of 1MB (8Mb). The rest of the circuit looks to contain components to drive the frequency of the chip, i.e. crystal and necessary capacitors and resistors. It also has a couple of LED’s. A red one that indicates power, and a blue one that acts a both a built in LED connected to one of the GPIO’s of the 8266 and additionally as a comms indicator to show connection activity on the serial connection. Two other components make up the board, these being the on board antenna, seen as a squiggly copper line, and 8 breakout pins.

The Antenna

A quick note on the antenna. Don’t be fooled into thinking this is in anyway inadequate. It is claimed that it has a range of 300m+. I assume that this is line of sight. I have not been able to test this yet. I have however been able to test it in my home and coverage is very good, through several walls and floors.

Breakout Pins

The ESP-01 has 8 breakout pins. These can be seen in the image below. Connection to FTDI is explained later in this document.

The ESP-01 and Pin Allocation

Communicating with the ESP-01

Ok, if we are going to programme the ESP8266 we need someway to be able to communicate with it. The standard method of communicating is via serial communication (RS232). To get serial comms out of our programming machine (computer) we need some sort of serial breakout. In this instance I have used a USB/serial converter, based on an FTDI chip. There are a lot of these available, again for not much money. I picked one up off eBay for less than the price of an ESP-01. When buying one of these it is important to remember that the ESP-01 requires a voltage level of 3.3V so please bear that in mind as any higher voltage could cause irreparable damage to the ESP-01. The one shown in the image below has a jumper switch that enables the ability to easily change the logic levels between 5V and 3.3V. It also has access to all the pins of the chip itself by utilising the holes along the side of the chip. This will come in handy later when connecting to the ESP-01.

The USB to FTDI Serial Convertor

Connecting the Serial Comms to the ESP-01

There are a lot of tutorials on the internet on how to do this, the vast majority of these seem to require building a slightly over complicated circuit involving switches which then require to be pressed in a certain order. This process is required to set the ESP-01 into upload mode. These sequences although they seem to work are a bit of a faff and in my expereince only seem to work around 50% of the time anyway. On further investigation I have found this to be completely unnecessary as it is a manual replication of a sequence that the FTDI serial chip can be made to do anyway. Since avoiding this type of set up I think I now get a failure rate when programming the chip of probably one in a hundred.

The way to avoid the aforementioned setup, is to utilise the DTR and RTS pins on the FTDI board. On the one that I purchased, these pins were not immediately available on the pin outs with the chip. There were however holes on the board with these labelled. There are several things you could do to access these. You could solder wire on to them and plug them to where they need to go. In my case I soldered headers onto the board so that the board could be inserted into a breadboard. By doing this I had immediate easy access to every pin on the board. The DTR and RTS pins, when a programme is uploaded through FTDI basically drop the voltage to 0V on each pin at the same time, and the DTR pin comes back to nominal level (3.3V) slightly before the RTS pin does. I think something in the order of 250uS. This sequence is then used to put the ESP-01 board (or any other board that you may be programming) into upload mode, which certainly beats having to do it manually every time, and is ultimately what it was designed for and will save the need for building complex setups with switches, resistors and jumper wires everywhere.

Wiring the Serial FTDI to ESP-01

Seven connections are required to establish communications and the ability to upload between the two.

FTDI ESP-01
GND GND
VCC VCC
VCC CH_PD
RXD TXD
TXD RXD
DTL GPIO0
RTS EXT_RST

A note on powering the setup

You may find that you run into power issues, as a USB port usually nominally provides only 500mA of current. The ESP-01 at peaks can demand approx 750mA. There are a couple of things that you can do here. One is to use an external power supply that has enough oohmph to be able to provide additional power to the circuit when necessary. Simply connect to the VCC and GND poles. Remember to use 3.3V. The other way if you don’t have a power supply available is to use a suitably rated electrolytic capacitor across the VCC and GND. Something along the lines of 25V/200uF would probably suffice. This should be able to provide the extra current at the times that it is briefly needed by the ESP-01. Be sure to plug it the correct way.

Identifying the Correct USB port

The simplest way to identify the USB port is to type ls /dev/tty.* into a terminal. This will return a list of connected ports. You are looking for something along the lines of /dev/tty.usbserial-A50234BI. Make a note of your specific port as you will need it shortly. Please note this only works as far as I know on Nix style machines. i.e. Unix, Linux, Mac etc. If you are on windows you are on your own, but I am sure there are plenty of tutorials out there which will be able to explain.

Writing your program to run on the ESP-01

There are many ways you can write your program to run on the ESP-01. One of the easiest and more straightforward ways is to use the Arduino IDE. You can download and install all the libraries necessary to get you up and running easily. As the Arduino is so widely supported there are people who have compiled libraries specifically for the ESP8266. To add support for the ESP8266 family of chips in the Arduino IDE, go to the preferences menu and towards the bottom you will see a text box labelled ‘Additional Boards Manager URL’s’ If this is empty then paste in the following; http://arduino.esp8266.com/stable/package_esp8266com_index.json. If there is already something in the text box this is probably because you already have additional boards in the Arduino IDE. You simply put a comma at the end of the text and insert the text so that there are http references in a comma separated list, the IDE will then include multiple additional boards. Once done simply restart the Arduino IDE to engage the changes.
You should now under the Tools Menu, be able to select board and see a whole list of additional ESP8266 boards that the Arduino IDE now supports. For the purpose of these experiments you will need to select ‘Generic ESP8266 Module’

A simple program

The simplest program that we could probably write that will do something is to flash the LED that is built in to the ESP-01. The below program does exactly that. It pulses the built in LED for 1 second and then turns it off for two seconds ad infinitum.

1
2
3
4
5
6
7
8
9
10
11
12
void setup() {
pinMode(LED_BUILTIN, OUTPUT); // Initialise the LED_BUILTIN pin as an output
}

void loop() {
digitalWrite(LED_BUILTIN, LOW); // Turn the LED on (Note that LOW is the voltage level
// but actually the LED is on; this is because
// it is active low on the ESP-01)
delay(1000); // Wait for a second
digitalWrite(LED_BUILTIN, HIGH); // Turn the LED off by making the voltage HIGH
delay(2000); // Wait for two seconds (to demonstrate the active low LED)
}

Once you have copied/typed the above code into the Arduino IDE. Press verify to ensure that the code compiles correctly.

Erasing the Flash Memory

Before we upload anything on to the chip I strongly recommend that you erase the Flash memory on the ESP-01 first. This will ensure that you are uploading to a clean memory and not doing this was the single biggest frustration that I had with this project. Once I had erased the flash memory I had no further uploading problems, or odd issues of the code note working correctly once uploaded.
There is a free open source tool available called ESPtool.py. I cannot recommend it enough for making your life easier whilst hacking these ESP modules. You need python installed on your machine. Use your packet manager to ensure that you have python installed. Something along the lines of sudo apt-get install python3 or brew install python3 if you are on a mac. once you have python installed you can install the esptool simply by typing pip3 install esptool. To verify that it has installed you can type which esptool.py into your terminal and it should list a directory location where it is installed. Once it is installed we can erase the flash memory by a command like the following. esptool.py --port /dev/tty.usbserial-A50285BI erase_flash Remember to substitute the port for the one that is returned on your system when entering the command ls /dev/tty.*
In my experience we only need to do this once, and it isn’t really required for any subsequent uploads. Once you are ready hit enter and you should see output similar to the following in your terminal:

1
2
3
4
5
6
7
8
9
10
esptool.py v2.2.1
Connecting....
Detecting chip type... ESP8266
Chip is ESP8266EX
Uploading stub...
Running stub...
Stub running...
Erasing flash (this may take a while)...
Chip erase completed successfully in 2.5s
Hard resetting...

If you see something similar to the above then the flash memory has been successfully erased.

Uploading the compiled binary

We are now ready to attempt to upload the compiled binary onto the ESP-01 chip. I strongly recommend that you continue to use the ESPtool for this. Whilst trying to upload form the Arduino IDE I have had nothing but issues, sometimes it works, sometimes it doesn’t. There is probably a reason, though until I track it down I will continue to use ESPtool. The first thing we need is a compiled binary for uploading to the ESP-01. Fortunately thanks to the Arduino IDE these are easy to come by. In the Sketch Menu of the Arduino IDE select export compiled binary. This will save a compiled binary in the folder of the Arduino project that you are working on. You can now use the ESPtool to upload this binary file to the ESP-01.

The command line command for uploading with the ESPtool is something along the lines of:

1
esptool.py --port /dev/tty.usbserial-A50285BI write_flash -fm qio 0x00000 /Users/MyUserName/Desktop/ESP01_Blink/ESP01_Blink.ino.generic.bin

Remember you will need to substitute your own serial port and path to the directory of your compiled binary. Once you are happy hit return to start uploading your sketch to the ESP-01.

After a successful upload you should see output similar to the following:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
esptool.py v2.2.1
Connecting....
Detecting chip type... ESP8266
Chip is ESP8266EX
Uploading stub...
Running stub...
Stub running...
Configuring flash size...
Auto-detected Flash size: 1MB
Compressed 251184 bytes to 183134...
Wrote 251184 bytes (183134 compressed) at 0x00000000 in 16.2 seconds (effective 124.3 kbit/s)...
Hash of data verified.

Leaving...
Hard resetting...

If this is the case and you see the above text or similar then you should also notice that the blue LED on the ESP-01 module is slowly flashing away.

Conclusion

I hope this has been useful to you if you have followed it this far. These I admit are baby steps but I found that searching on the internet turned up many incomplete, over engineered or plain and simple incorrect solutions to start working with the ESP-01. These steps are the simplest I was able to find at the moment of writing to enable repeat success with uploading code to the ESP-01 in a repeatable and consistent way. As and when I refine the process rest assured I will update.
The Arduino platform is a great introduction to electronics. But over the years with it’s expansion it does seem to have become rather bloated. This in turn is the reason that I think I had so many problems using it to talk to the ESP-01. I have come to the conclusion that it is a great system, however sometimes it is best to use specific tools do do specific jobs. It is with that in mind that I could not recommend ESPtool enough. It was the difference for me that allowed me to succeed in this little project. Ultimately all I used the Arduino IDE for was to compile my code into a binary that would run on the ESP8266 platform. All other interfacing was done with the ESPTool.

So in a nutshell the steps are as follows:

  • Write code in Arduino IDE.
  • Compile Binary file for ESP8266.
  • Connect FTDI to your computer.
  • Identify the FTDI serial port.
  • Connect 7 cables between FTDI board and ESP01.
  • Power the board sufficiently.
  • Use ESPtool to Erase the flash memory.
  • Use ESPtool to upload the compiled binary.
^