ESP8266 Programming Guide in Arduino Environment

The pin designation is (theoretically correctly) associated in the ESP8266 implementation in the Arduino environment, according to the following table:

To refer to a pin we can use either designation interchangeably. So, in theory, the following two statements are equivalent,

digitalWrite(D5, LOW);  // D5, which is equal to GPIO14

digitalWrite(14, LOW);  // GPIO14 directly

However, in practice, we know that not all manufacturers follow the same criteria when identifying pins on the boards (especially Chinese ones).

Therefore, when programming the ESP8266, we must pay special attention to the pinout of our board and be very aware of possible mislabeling to avoid headaches.

Digital inputs and outputs (GPIO) are programmed almost the same as in any Arduino. Thus, we can change the mode of a GPIO between input or output with the function:

pinMode(pin, mode)

Where the mode can be OUTPUT, INPUT, or INPUT_PULLUP. Pin 16 has an additional mode INPUT_PULLDOWN_16, but it is not common that we will use it. As in Arduino, all pins are initialized as INPUT by default.

On the other hand, when the GPIO is in OUTPUT mode, we can use it as an output by assigning a value (LOW or HIGH) just like in Arduino with:

digitalWrite(pin, output)

Finally, when the GPIO is in input mode we can read its value just like in Arduino with:

digitalRead(pin)

Programming PWM outputs (“analog” outputs) is very similar to conventional Arduino. However, the ESP8266 does not have hardware PWM, so it performs it via software instead.

This implies an additional computational cost that Arduino does not have. However, it also allows us to use PWM on any GPIO.

For this, just like in Arduino, to use a PWM output we use the function:

analogWrite(pin, value)

By default, the range is 10 bits, so value takes values from 0-1023 (most Arduino models take values from 0-255). However, we can change the range up to 14-bit output with:

analogWriteRange(range)

The default frequency is 1kHz, but it can be changed with the function (the minimum is 100Hz and the maximum is 40kHz)

analogWriteFreq(frequency)

Another difference with an Arduino is that if in the same program we want to use a PWM output as digital later, we must explicitly deactivate the PWM. To do this, we simply do:

analogWrite(pin, 0)

The ESP8266 has a single analog input (ADC), which in the Arduino environment is designated as A0. To read it, the same function as Arduino is used, that is, we simply use the function:

analogRead(A0)

The response is a 10-bit value in the range of 0-1023 (same as in most Arduinos), whose voltage is proportional to the voltage at the input. Remember that the ESP8266 has a maximum analog input of 1V, although many boards have a converter to extend it up to 5V.

On the other hand, the ESP8266 has an additional mode that allows measuring its supply voltage. This is useful, for example, when operating on batteries. To activate it, add this line in our Sketch.

ADC_MODE(ADC_VCC)

While we are using this mode, the real ADC pin must be disconnected and, logically, we cannot use it as an analog input.

The ESP8266 has interrupts on all GPIO pins, except on GPIO16 (D2). The usage is similar to hardware interrupts in Arduino.

attachInterrupt(digitalPinToInterrupt(interruptPin), handler, FALLING);

The options are RISING, FALLING, CHANGE, ONLOW, ONHIGH, ONLOW_WE, ONHIGH_WE.

The PROGMEM macro, which stores variables in flash memory instead of dynamic memory, also works on the ESP8266 with a small but important difference.

Unlike Arduino, which performs prior analysis to avoid having the same variable multiple times, the equivalent in ESP8266 does not perform this preprocessing.

So, for example:

string text1 = F("hello");
string text2 = F("hello");

Will store the literal “hello” twice in memory. We can avoid this with the FPSTR function like this

const char hello[] PROGMEM = "hello";
string texto1 = FSPTR(hello);
string texto2 = FSPTR(hello);