Microcontroller projects

Programming ESP's and the ESPBacker library

last updated: 27/07/19

Intro

Why this? There are cool books and tutorials on the net with code snippets to program ESP's. You can find e.g. a really useful guide from Pieter P on github.io.

I work often with both microcontroller from Espressif, the ESP8266 and the ESP32. And I'm a forgetful man, an often search quite a long time to find back pieces of code already written and used in my projects. So here I wrote an Arduino library to hold all those pieces of code and named it ESPBacker. The code is intended to work on ESP8266 and ESP32.

Boards used

I often use the LOLIN (WEMOS) D1 mini pro. The MHEtLive ESP32MiniKit is small and nearly (RxD and TxD are interchanged!!) pin compatible with the LOLIN board and comes handy if we need a more powerful controller.

In the middle of the picture we see the prior version of the LOLIN board named Wemos D1 mini pro.

Other ESP8266 and ESP32 boards should also work with the following software.

Naming conventions

I was often confused and did not know what convention for naming identifiers (names given to a program element) to use in different languages, and so was sometimes not consistent in my own programs.

In last years I often use Python with a quite clear convention (PEP8) and as this convention does not conflict with C++ (Arduino) I will try to stick to that convention beginning today ;). Here my rules:

For all variables, functions (methods), lowercase letters are used if only one word is needed and lowercase_letters_with_underscores are used for more words (this is also true for packages, modules in Python or libraries in C++). For me the readability is better than using mixedCase.
Constants use ALL_CAPS_WITH_UNDERSCORE.
CapWords (StudlyCaps) always beginning with a capitalised letter are used for structs, classes, objects and enumerations (and exceptions in Python).
As internal consistency matters most; if working on an existing project it is better to use the style of the project than to mix conventions.

Logging and debugging

Let's start with the most important chapter :).

Debug with BUILTIN_LED

Most boards have one or more built in LEDs. When no serial interface or UDP connection is available, it's good to use the LED's to pass informations. In the library we have little helper methods to use the builtin LED.

set_led_log(bool flag): switch LED logging on, initialise LED and switch it on
set_led_log(bool flag, byte led_pin): // overloaded method to change LED pin
led_on(): build in LED on
led_off(): build in LED off
blink_led_x_times(byte x): blink LED x times (LED was on, default 100 ms (f=5 Hz))
blink_led_x_times(byte x, word blink_time_ms): to change delay time
set_LED_pos_logic(bool pos_logic): set LED to positive logic (default)
bool get_LED_pos_logic(): check the logic setting (seldom needed)
init_LED(): initialise built in LED (not needed for logging, can be used otherwise)

For many boards LED_BUILTIN is already defined. If this is not the case or if you want to use another LED use the overloaded methode set_led_log(bool flag, byte led_pin) to change the pin number. The LED's on ESP8266 and ESP32 often use negative logic! If the logic on your board is negative use set_LED_pos_logic(false).

Here the example code using the library:

    /****** ESP_example_debug_with_builtin_LED.ino ****** www.weigu.lu ********/

    #include <ESPBacker.h>

    ESPBacker B;                         // create an ESPBacker object

    /****** SETUP *************************************************************/
    void setup() {
      B.set_led_log(true);
      //B.set_led_log(true,5);           // give alt. pin if LED_BUILTIN not defined
      B.set_led_pos_logic(false);        // default = true, positive logic
    }
    /****** LOOP **************************************************************/

    void loop() {
      B.blink_led_x_times(3);            // default blink with 100 ms (f=5Hz)
      delay(2000);
      B.blink_led_x_times(3,500);        // blink with 500ms delay (f=1s)
      delay(2000);
    }

There exists another LED function not connected to logging to initialise an LED:

init_LED(byte led_pin): initialise any LED defined by it_s pin and switch it on (here not needed, can be used to otherwise)

Debug/Log with Serial

Logging per serial monitor helps a lot when programming and debugging. Unfortunately TxD0 and/or RxD0 from Serial0 (Serial) are also needed for programming most ESP boards or are needed for communication to a sensor or a device. ESP8266 has fortunately a second serial interface (look here for LOLIN board). ESP32 has even three serial interfaces. The second and the third serial interface are accessed through Serial1 ans Serial2.

With a serial to USB adapter cable (3.3V!! for ESP boards) and a terminal program like Cutecom we can log over Serial1 or Serial2.

The library contains the following methods for serial logging:

void set_serial_log(bool flag) // set logger flag and initialise Serial (0)
void set_serial_log(bool flag, byte interface_number): overloaded method to additionally change the serial interface number
void log(String message): print log line to Serial
bool get_serial_log(): // get logger flag for Serial

To debug or log messages we use the log() function. If we need a line feed we add '\n' to our message.

    /****** esp_example_log_serial.ino ****** www.weigu.lu ********************/

    #include <ESPBacker.h>

    ESPBacker B;

    /****** SETUP *************************************************************/

    void setup() {
      B.set_led_log(true);               // enable LED and Serial logging
      B.set_serial_log(true);
      // overloaded method to choose Serial1 (1) or Serial2 (2, only ESP32)
      //B.set_serial_log(true,1);
    }
    /****** LOOP **************************************************************/

    void loop() {
      B.blink_led_x_times(3);            // default blink with 100 ms
      B.log("Hello\n");
      delay(2000);
    }

Debug/Log with UDP

Serial is cool over the Arduino serial monitor. But if this is not possible, it gets cumbersome because additional hardware is needed. The ESP's have Wi-Fi on board and allow us to use UDP to send messages to a computer. If we have a linux computer (e.g. raspberry pi) the simple netcat program allows us to listen to our log information. Open a terminal and type:

    nc -kulw 0 6666

I omitted some functions from above. For the whole program look at the end of the page (Downloads).

Wlan functions

Connect ESP to a router (Wifi station mode STA)

Using one network (SSID)

```C

```C

Downloads

Sending NTP over Serial1 (ino)