ESP-8266 System On Chip

A complete, WiFi enabled, 3.3v microcontroller for less than $5^

Also: Espressif ESP-32 System On Chip +

Designed and originally made by Espressif in China, it's a VERY low cost (e.g. $5USD) WiFi IPv4 connected embedded controller with a few pins of GPIO, UART, I2C, 10 bit ADC, SPI, PWM, internal temp, etc.. on a 11.5mm x 11.5mm "SoC", perfect for Internet of Things

Out of the box, they have an "AT" command set so a device connected to the UART can tell them to connect to the network, and send and recieve data. They are typically used, in this mode, with some other embedded device. However, a GNU (GCC) based toolchain has been developed ^ which allows them to be re-programmed for complete applications in a single module. And new firmware packages are being developed, such as a small LUA interpreter ^ These packages are fairly easy to install via a built in bootloader by connecting the UART to a PC (USB to 3.3v serial adapter), holding a GPIO pin down with a low value resistor (usually pin 0), restarting the module, and then downloading the .bin file. Of greatest interest to the hobbiest, is it's compatibility with the Arduino IDE^. In the Arduino IDE, go to File / Preferences, and under "Additional Boards Manager URLs:" add "http://arduino.esp8266.com/stable/package_esp8266com_index.json". Then under Tools / Boards / Boards Manager, and filter by ESP8266 and install the support files.

Don't even try to program an ESP-8266 module that wasn't made by AI-THINKER. The knock offs will NOT work correctly.

https://cdn-shop.adafruit.com/product-files/2471/0A-ESP8266__Datasheet__EN_v4.3.pdf Datasheet.

Processor: Tensilica^ Xtensa LX3^ processor 106micro Diamond Standard core. 32-bit RISC. Runs at 80 MHz but can go up to 160 MHz, it has ~80kB DRAM (Data RAM), and ~35kB of high speed IRAM (Instruction RAM). 64K ROM. Support required: 4 capacitors, a crystal and an external flash (which are all on the ESP-8266 modules).

Integrated WiFi 2.4 GHz, WPA/WPA2, 802.11 b/g/n protocol. +20dBm in b mode, STBC, 1x1 MIMO, 2x1 MIMO, A-MPDU & A-MSDU frame aggregation & 0.4µs guard interval. Integrated TR switch, balun, LNA, power amplifier and matching network. Wake up and transmit packets in < 2ms. MQTT is recommended as a lightweight but robust network messaging system:
https://github.com/tuanpmt/esp_mqtt#esp_mqtt

Note: NONE of the versions prior to the ESP-12 are actually FCC approved, even if they have the FCC logo. ESP-12 has ID: 2ADUIESP-12 and CE: BCTC-141212468

Firmware ROM impliments (see file eagle.rom.addr.v6.ld from SDK): MD5 (w/hmac), SHA1, comms with the external flash/memory commands, SDIO 2.0, SPI, UART functions, software floating point, AES, printf, low-level IO tools, real-time event scheduler, 802.11b/n/g, TCP/IP IPv4, WPA/WPA2.

External FLASH is normally Winbond W25Q40BVNIG SPI for 512KB. Some versions have more, e.g. EFP-12 and OLIMEX

IO is somewhat limited on early modules, but later modules increase the number of available pins. Note 3.3v levels; use of 5 volts anywere will damange the unit. Level conversion required.

• GPIO (12mA max), Interrupt (all GPIO except 16 aka WAKE, rise/fall/change/hi/low), See pinouts.
• PWM (GPIO 0-15), analogWrite(pin, value); Range is 0 to PWMRANGE
• ADC 10-bit (accuracy suffers during WiFi TX), External A0 pin analogRead(A0); has 0-1.0 volt range or use ADC_MODE(ADC_VCC); configuration to read 3.3 volt rail via ESP-getVcc(); Can't switch config in program.
• I2C upto >400KHz,
• UART, TX: GPIO1, RX: GPIO3 (or swap to TX: GPIO15 RX: GPIO13)
• SPI,
• SD card IO 2.0 (GPIO 6-11),

Power requirements: 3.3v, Deep sleep power <10uA, Power down leakage current < 5uA, Standby < 1.0mW (DTIM3), ^ ^ Standard operation 70 to 80mA with 300mA peaks of 1mS or less. At full CPU load and transmitting, may need up to 300mA peak.
https://www.youtube.com/watch?v=6SdyImetbp8

Waking up from sleep mode takes about 16mA — then about 3 seconds to reconnect via DHCP, precious time at 70mA. Using a static IP address you can pare that down to half a second.

Programming:

All new code loaded via bootloader. Reset with GPIO 0 pulled to ground with a low value resistor^, "ready" will be transmitted at one of 9600,115200,57600, or, most often, 76800 baud. In the bootup message 'boot mode:(x,y)' three low bits of x are {GPIO15 aka MTDO, GPIO0, GPIO2}. If GPIO15 is high, it will wait for an SD card. If GPIO0 is high, it will boot from flash, if low, will enter the bootloader. In any case, GPIO2 is expected to be high (floating).^ ^ e.g. boot mode:(1,6)' is what you want to see for programming mode. A simple circuit like this can help:
Programming checklist

• More current is required at 3.3 volts than most USB converters can supply, so an LM317 power regulator from the 5 volt rail is recommended. For example, a 2K7 ohm resistor in parallel with a 680 to ground from the ADJ pin (left) and a 330 between that and Vout (center) is known to work well. The parallel resistors have an effective resistance of 543 ohms which, with the 330, provides nearly exactly 3.3 volts. ^
• CH_PD must be pulled to 3.3V to enable WiFi.
• RST must be at 3.3v during operation, but can be connected to ground to reset the device.
• UTXD connects to the input line of a USB to serial converter (like the RLC-3 ). The esp-8266 DRIVES UTXD and often has an indicator LED to show when it is transmitting data on this line. If you see this LED flash when you send data from the PC, you have UTXD connected to the output line of the USB converter!
• URDX connects to the driven output of the USB to serial converter via a level converter to avoid putting out more than 3.3 volts Note 3.3v levels; use of 5 volts anywhere will damage the unit. A 2K2 ohm resistor from the USB TX to URDX and a 2K7 ohm resistor to ground reduces 5 volts to just under 3 volts, which is in the safe range. This is not ideal, but seems to work. Zener diodes need more current than is drawn to accurately regulate so they are not useful as level shifters here unless another logic chip is added as a buffer. A USB converter with 3.3 volt safe output (trust but verify) or a level converter chip is recommended.
• GPIO0 must be pulled low with a low value resistor before power is applied to go into bootloader mode, or pulled high (10K) to boot into the loaded program.
• GPIO2 must be unconnected or pulled high (10K) before power is applied. After boot it can be used as GPIO (typically not In, but Out) or as TXD1 which can send WiFi debugging data, or be reconfigured to do all sorts of weird things like PWM^, IR^, NeoPixels^, certain BLDC ESCs^, etc...
• GPIO15, if present, must be pulled low (10K) to avoid the unit trying to boot from external SD Card memory.
  https://easyeda.com/bondfig/ESP8266_serial_web_shim-KomIFpL7t simple adapter board.

Note: You can use the serial adapter and reset circuit on a NodeMCU to program an ESP-01 or other simpler module. Just disable the nodemcu module by setting en to ground. Then run 3v3, ground, tx, rx, gpio0, and reset to your esp01. Pull En high on esp01. Program. Video^.

Languages / IDEs

• Arduino (via installationsof additional board files into Arduino IDE v1.6.4 or later)
  https://github.com/esp8266/Arduino
  http://arduino.esp8266.com/versions/1.6.5-1160-gef26c5f/doc/reference.html
  • Install Arduino IDE v1.6.8 or later from
    http://www.arduino.cc
    see the Downloads tab. Donate if you can afford to.
  • File / Preferences (Arduino / Preferences), Additional Boards Manager URLs, add http://arduino.esp8266.com/stable/package_esp8266com_index.json (click the dingus to the right of the line to get a multi-line editor). Click Ok.
  • Tools / Board: / Board Manager..., select the new boards from the list, and click Install. Wait for the download.
  • Tools / Board: select the device. Settings will now appear on Tools menu for com port, baud (the unit autodetects this setting, go as fast as works reliably), speed, flash, etc... The Programmer setting is ignored. Disable the extra debug output.
  • Connect as above, make sure GPIO0 is low, then plug in the USB converter and set the com port to the one that appears,
  • After the sketch is loaded, it immediatly runs. Re-loading requires power cycle or reset (again GPIO0 held low).
• GCC
  https://github.com/esp8266/esp8266-wiki/wiki/Toolchain
  http://programs74.ru/udkew-en.html complete dev kit installer for windows
• Lua (Note the useof Node below has nothing to do with NodeJS) be aware the interpreter leaves little ram for applications.
  http://www.nodemcu.com/index_en.html
  https://github.com/nodemcu/nodemcu-firmware#nodemcu
• BASIC
  http://www.esp8266basic.com/
• Javascript  
  http://www.esp8266.com/viewforum.php?f=44
• FORTH+ (sort of)
  https://github.com/zeroflag/punyforth

Versions / Modules

1. On some ESP-12E modules, GPIO4/D2 and GPIO5/D1 are labeled incorrectly.
https://github.com/esp8266/Arduino/issues/437
https://www.esp8266.com/viewtopic.php?f=5&t=3163

Code Snippits

Setting analogWrite range and frequency: analogWriteRange(new_range) sets the upper limit of the values to be sent via analogWrite. Call analogWriteFreq(new_frequency) to change the frequency. PWM frequency is 1kHz by default. Note: This is specific to ESP (not part of standard Arduino)

Print MAC address: Can be important if max address filtering is used on the local wifi:

uint8_t MAC_array[6];
char MAC_char[18];
sprintf(MAC_char,"\n\rMAC ");
    WiFi.macAddress(MAC_array);
    for (int i = 0; i < sizeof(MAC_array); ++i){
      sprintf(MAC_char,"%s%02X:",MAC_char,MAC_array[i]);
    }

Deep sleep (restarts in setup, just as if power had failed)

  ESP.deepSleep(sleepTimeInSeconds * 1000000, RFMode mode = RF_DEFAULT));

`mode` is one of `WAKE_RF_DEFAULT`, `WAKE_RFCAL`, `WAKE_NO_RFCAL`, `WAKE_RF_DISABLED`.
(GPIO16 needs to be tied to RST to wake from deepSleep.)

Automatic Reconnect On Wake-Up, is the default. So even before you Wifi.begin, if you were connected before, you suddenly will be again. If that isn't what you want:

WiFi.persistent(false);
WiFi.mode(WIFI_OFF); 
WiFi.mode(WIFI_STA);
WiFi.begin(ssid, password);

Avoiding the Bootup Garbage. On startup, the unit will send out a string of data about version, etc... at a strange baud rate, 76,4884. There is no way to disable this. Instead, connect a serial device to the alternate TX and RX pins. Serial uses UART0, which is mapped to pins GPIO1 (TX) and GPIO3 (RX). Serial may be remapped to GPIO15 (TX) and GPIO13 (RX) by calling Serial.swap() after Serial.begin. Calling swap again maps UART0 back to GPIO1 and GPIO3. Use Serial.flush() to block until serial sending is finished before swapping.
https://github.com/esp8266/Arduino/blob/master/doc/reference.md#serial

Xon/Xoff because no interrupt for serial recieved data is supported on the ESP in the Arduino environment, we must check for incomming data when we want to write data, and hold off if we get an Xoff. We can't avoid taking other characters out of the recieve buffer, becase the Xoff could be "hiding" behind one of them. So we MUST receive all characters sent while we are waiting to send, which means we must buffer those characters into our own rxbuf. So the standard get and put character routines must incorporate that fact.

boolean xoff=false; //must be global
String rxbuf = "";

//If Xoff, recieve bytes until Xon before sending byte.
void putc_x(byte b) {
  while (Serial.available() || xoff) {
    byte c = Serial.read(); 
    //can't peek, because xoff could be behind next char
    if (c == 0x13) { xoff=true; } // XOFF
    else if (c == 0x11) { xoff=false; } // XON
    else if (c > 0 && c < 0xFF) { //rx data
      rxbuf += c; //buffer it
      //TODO: may need to check rxbuf.length() and send an xoff if too big.
      }
    delay(1); //should this be more?
    //TODO: timeout?
    }
  Serial.write(b);
  }

byte getc_x(String rxbuf) {
  byte c;
  if (rxbuf.length()>1) {
    c = rxbuf[0];
    rxbuf.remove(0,1);
    return c;
    }
  while (Serial.available()) {
    c = Serial.read();  //gets one byte from serial buffer
    if (c == 0x13) { xoff=true; } // XOFF
    else if (c == 0x11) { xoff=false; } // XON
    else { //rx data
     break; } //got a byte so we are done
    }
  return c;
  }

//If Xoff, recieve bytes until Xon before sending string.
void writeStr_x(String msg) {
  for(int i=0;i<msg.length();i++) {
     putc_x(msg[i]);
     };
  }

boolean checkSerial(byte timout) {
  while (Serial.available()) {
    char c = Serial.read();  //gets one byte from serial buffer
    if (c == 0x13) { xoff=true; } // XOFF
    else if (c == 0x11) { xoff=false; } // XON
    else if (c>0 && c<0xFF) { rxbuf += c; } //filter out nulls and FF's.
    if (!Serial.available() && timout) { delay(timout); } //wait a tich if there isn't already more data available. Otherwise, timeout.
    }
  }

Connecting serial devices to the web

Note: The ESP8266WebServer library becomes very sluggish and random if you do anything major in your loop. The ESPAsyncWebServer avoids that problem, and has lots of other cool features, but won't allow you to do anything that involves a delay or yeild when handleing a web page request. It also requires ESPAsyncTCP.

See also:

• https://github.com/esp8266/Arduino/issues/817 Do NOT attempt to use both WiFi Access Point mode and WiFi Station mode at the same time! This can lead to very intermittent AP connections when the Station doesn't connect or is on a different channel.+
• https://www.hackster.io/139994/plug-any-usb-device-on-an-esp8266-e0ca8a USB Host mode?+
• https://www.sigmdel.ca/michel/program/esp8266/arduino/watchdogs_en.html Detailed document on watchdogs and resets+
• https://arduino-esp8266.readthedocs.io/en/latest/index.html Best documentation on the differences betwee Arduino (e.g. UNO) and the ESP-8266 in the Arduino system.
• https://hackaday.io/project/24993-esp-cookbook +
• https://www.youtube.com/watch?v=-w1QLGGXjZM Massive IO expansion using the hardware SPI bus on ESP-12E
  +
• http://www.esp8266.com/ Forum and Wiki:
  https://github.com/esp8266/esp8266-wiki/wiki
  for the GNU based toolchain used to re-program the device.
  http://www.esp8266.com/wiki/doku.php EFP-8266 Community Wiki. Not terribly well organized, but lots of good stuff.
    
• https://nurdspace.nl/ESP8266 Excellent open source reference.
• http://www.espressif.com Manufacturer.
  http://bbs.espressif.com/ official forum. (check downloads section for firmware and development tools)
• http://www.instructables.com/id/ESP8266-Wi-fi-module-explain-and-connection/?ALLSTEPS Basic setup and operation.
• http://www.instructables.com/id/Using-the-ESP8266-module/?ALLSTEPS
• http://makezine.com/2015/04/01/installing-building-arduino-sketch-5-microcontroller/ step by step instructions for installing the boardsupport files into the Arduino IDE and uploading programs to an ESP-8266 -01
• http://hackaday.com/2015/03/18/how-to-directly-program-an-inexpensive-esp8266-wifi-module/ +
• https://blog.attachix.com/live-debugging-with-open-source-tools-programming-for-esp8266-part-4/ Debugging is even possible in special environments.+
• https://github.com/nodemcu/nodemcu-devkit NODEMCU - DEVKIT: Well designed / tested support board with USB interface (including auto reset/bootload), low power sleep support, led, reset and bootloader switches. This is the hardware developed for the NODEMCU firmware, which is LUA, with NodeJS like event handeling.
• http://www.esp8266.com/viewtopic.php?f=13&t=2823 Using a battery to power the ESP+
• https://www.hackster.io/iboboc/esp-07-or-esp-12-with-nodemcu-going-into-deep-sleep-a0560e -07 into deep sleep.
• https://gist.github.com/sticilface/e54016485fcccd10950e93ddcd4461a3 Using program memory to store constant strings. In the global space:
  static const char xyz[] PROGMEM = "This is a string stored in flash";
  in a code block:
  const char * abc = PSTR("Also Store this string in flash");
  Note that 32-bit alignment is required when reading these strings to avoid segment fault crashes. See helper "_P" versions of common functions in pgmspace.h or just use these macros:
  #define FPSTR(pstr_pointer) (reinterpret_cast<const __FlashStringHelper *>(pstr_pointer))
  #define F(string_literal) (FPSTR(PSTR(string_literal)))
  Serial.println(FPSTR(xyz));
  Serial.println(F("This is a string stored in flash"));
• https://tttapa.github.io/ESP8266/Chap11%20-%20SPIFFS.html Using SPIFFS to store web pages. To pre-load, put files in "data" folder under sketch folder, reserve enough space in Tools / Flash Size, then Tools / ESP8266 sketch data upload.

  #include <FS.h> //in header
  SPIFFS.begin();       //in setup
  //in loop
    if (SPIFFS.exists(path)) {                            // If the file exists
      File file = SPIFFS.open(path, "r");                 // Open it
      size_t sent = server.streamFile(file, contentType); // And send it to the client
      file.close();                                       // Then close the file again
    }
  

• https://github.com/me-no-dev/ESPAsyncWebServer#file-upload-handling Uploading a file to SPIFFS via ESPAsyncWebServer. Also check out the FSEditor example; it works via a web page hidden in the code via .gz encoding which is actually an editor using ace.js
• http://ozzmaker.com/record-temp-and-pressure-esp8266/ Nice example of how to use external scripts to augment the presentation of data from simple web pages served from the device. In this case, google charts.+
• http://hackaday.com/2015/06/06/esp8266-as-a-networked-mp3-decoder/ +
• http://arduino-esp8266.readthedocs.io/en/latest/esp8266wifi/client-examples.html?highlight=http
• http://tech.scargill.net/category/esp8266/ Mr. Cargill has carefully documented his progress in using the ESP-8266
  http://scargill.wordpress.com/ Older posts

Questions: