Arduino-esp32 course – General-purpose input/output (GPIO) – Chapter 3

I want to state here that I’m not an electronics engineer and I know the basics only after years of tinkering and because I use to soldier PCBs for my father since I’m 8 or so. So if there is anything that is not correctly explained just comment and I will try to document it better.
The ESP8266 has 17 GPIO pins (0-16), however, you can only use 11 of them, because 6 pins (GPIO 6 – 11) are used to connect the flash memory chip.
The ESP32 chip has 40 physical GPIO pins. Not all of them can be used and some of them are only input GPIOs meaning you cannot use them for output communication (Refer to your board tech specs fot that) According to Espressif documentation on the ESP32:

  • GPIO 6-11 are usually used for SPI flash.
  • GPIO 34-39 can only be set as input mode and do not have software pullup or pulldown functions.

Electronics ABC
pull-up resistor connects unused input pins to the dc supply voltage, (3.3 Vcc in ESP32) to keep the given input HIGH
pull-down resistor connects unused input pins to ground, (GND 0V) to keep the given input LOW.
Analog-to-Digital Converter (ADC)
The Esp32 integrates 12-bit ADCs and supports measurements on 18 channels (analog-enabled pins). The Ultra low power (ULP-coprocessor) in the ESP32 is also designed to measure voltages while operating in sleep mode, which allows for low power consumption.
Digital-to-Analog Converter (DAC)
Two 8-bit DAC channels can be used to convert two digital signals to two analog voltage outputs. These dual DACs support the power supply as an input voltage reference and can drive other circuits. Dual channels support independent conversions.

A detailed walkthrough over GPIOs and electronics is out-of-scope in this blog post series since it’s a thema on it’s own and I think a engineer could be the best suited to expand on this properly. There are many instructables and videos about it if you are interested in researching more.

So now back to ESP32 Arduino framework coding, let’s use this GPIO information, to declare one as output and blink a LED.

#include "Arduino.h"
// HINT: Many ESP32 boards have an internal LED on GPIO5
// If it's on another PIN just change it here:
int ledGpio = 5; 

void setup() { 
  Serial.begin(115200);
  Serial.println("Hello blinking LED");
  pinMode(ledGpio, OUTPUT);
} 
void loop() { 
  digitalWrite(ledGpio, HIGH); 
  delay(500); 
  digitalWrite(ledGpio, LOW); 
  delay(200); 
}

As a good reference here is the pinMode entry in Arduino documentation. modes can be:

  • INPUT
  • OUTPUT
  • INPUT_PULLUP

This very short program will just set the GPIO5 in output mode and in the loop just turn it HIGH(1) and send 3.3V to the GPIO or LOW(0). Keep in mind that the ESP32 can draw a max. consumtion of about 10 mA per GPIO so always use a resistance (10K or similar) if you connect your own LED or you may damage the board.
Now seeing that the GPIO state is 1 or 0, we can also write this program in a shorter way, let’s give it a second round:

include "Arduino.h"
int ledGpio = 25;
bool ledState = 0; // New bool variable
void setup() {
  pinMode(ledGpio, OUTPUT);
}
void loop() {
  digitalWrite(ledGpio, ledState);
  ledState = !ledState;
  delay(20);
}

We are just doing one digitalWrite per loop now and right after that just redeclaring the variable using the logical NOT operator. That way it will flip between 0 and 1, turning the LED on and off quite fast since we added just a 20 millis delay. So fast is almost always on!
So now we are in this point we can start with the next topic that is called pulse width modulation or PWM.

PWM provides the ability to ‘simulate’ varying levels of power by oscillating the output from the microcontroller. By varying (or ‘modulating’) the pulsing width we can effectively control the light output from the LED, hence the term PWM or Pulse Width Modulation. Arduino also had PWM pins with a scale from 0 – 255 so we could have 255 brightness level on a LED.

This PWM image is from Arduino tutorial – credits: https://www.arduino.cc/en/tutorial/PWM

ESP32 / ESP8266 PWM example for one Channel

// Since someone asked about a modern AnalogWrite PWM example
// Just try to compile this one
include "Arduino.h"

// use first channel of 16 channels (started from zero)
define LEDC_CHANNEL_0 0
// use 13 bit precission for LEDC timer
define LEDC_TIMER_13_BIT 13
// use 5000 Hz as a LEDC base frequency
define LEDC_BASE_FREQ 5000
// fade LED PIN (replace with LED_BUILTIN constant for built-in LED)
define LED_PIN 25
bool brightDirection = 0;
int ledBright = 0;

void setup() {
  Serial.begin(115200);
  Serial.println("Hello PWM LED");
  // Setup timer and attach timer to a led pin
  ledcSetup(LEDC_CHANNEL_0, LEDC_BASE_FREQ, LEDC_TIMER_13_BIT);
  ledcAttachPin(LED_PIN, LEDC_CHANNEL_0);
}
// Arduino like analogWrite: value has to be between 0 and valueMax
void ledcAnalogWrite(uint8_t channel, uint32_t value, uint32_t valueMax = 255) {
  // calculate duty, 8191 from 2 ^ 13 - 1
  uint32_t duty = (8191 / valueMax) * min(value, valueMax);
  ledcWrite(channel, duty);
}

void loop() {
  // set the brightness on LEDC channel 0
  ledcAnalogWrite(LEDC_CHANNEL_0, ledBright);
  if (ledBright == 255 || ledBright == 0) {
    brightDirection = !brightDirection;
  }
  if (brightDirection) {
    ++ledBright;
  } else {
    --ledBright;
  }
  delay(15);
  Serial.println(ledBright);
}

The ESP32 has a PWM controller with 16 independent channels that can be configured to generate PWM signals with different properties. Just wanted to mention this possibility but I’m not going to extend myself in this topic since they are hundred of pages that explain it much better than I could do. Please check https://randomnerdtutorials.com/esp32-pwm-arduino-ide to have a nice PWM example.

Keep tuned and follow this blog to get more. In next chapter we are going to explore I2C communication and connect a thermometer to our ESP32 to display via Serial the room temperature.

Arduino-esp32 course – Event driven WiFi and build_flags configuration – Chapter 2

On this new release we will focus on connecting our Espressif board to WiFi and will also the powerful build_flags to inject the defines directly on compilation time. This will make our WiFi configuration easier and leave it in a place where it can be easily configured, again in our platformio.ini project configuration file:

[env:espressif8266] 
build_flags = 
-DWIFI_SSID=\"MyWiFiName\"
-DWIFI_PASS=\"password\" 

; Password with special chars: My pass'word 
-DWIFI_PASS=\"My\ pass\'word\"

-D instructs the compiler to #define the variable WIFI_* and make it available in my program
So actually doing this in main.cpp will accomplish exactly the same:

#define WIFI_SSID "MyWiFiName"
#define WIFI_PASS "password"

But as you can see if we do that we would be hardcoding our credentials in a C++ file which is not the best if we would like to share our program in github so other people can use it. Doing it the build_flags way, we are keeping it in a place tight to our code repository, but that can be configured withouth touching our main code. Nice, doesn’t it?
And of course you can discover more settings about this platformio.ini configuration and define many other things there, like GPIOs that your sensor uses and any other variable that need to be injected in compilation time. Pretty handy to distribute your projects and leave the configuration where it needs to be. So now that we’ve the credentials let’s make our program connect to the WiFi in an event-driven way:

#include "Arduino.h"
#include <WiFi.h>

int lostConnectionCount = 0;

/** Callback for receiving IP address from AP */
void gotIP(system_event_id_t event) {
  Serial.println("Online. Local IP address:");
  Serial.println(WiFi.localIP().toString());
  // We are connected, we could already receive or send something w/WiFi
}

/** Callback for connection loss */
void lostCon(system_event_id_t event) {
  ++lostConnectionCount;
  Serial.printf("WiFi lost connection try %d to connect again\n", lostConnectionCount);
  WiFi.begin(WIFI_SSID, WIFI_PASS);
  if (lostConnectionCount==4) {
    Serial.println("Cannot connect to the internet. Check your WiFI credentials");
  }
}

void setup() {
  Serial.begin(115200);
  Serial.println("setup() started let's connect to WiFI");

  Serial.printf("WiFi name: %s\nWiFi pass: %s\n", WIFI_SSID, WIFI_PASS);
// Start our connection attempt
  WiFi.begin(WIFI_SSID, WIFI_PASS);
// Event driven WiFi callbacks
// Setup callback function for successful connection
  WiFi.onEvent(gotIP, SYSTEM_EVENT_STA_GOT_IP);

// Setup callback function for lost connection
  WiFi.onEvent(lostCon, SYSTEM_EVENT_STA_DISCONNECTED);
}

void loop() {
}

That was already a step ahead of Chapter 1. This won’t work in Arduino ATMega chip, for this code we already need an Espressif chip that can connect to WiFi. My take on connecting to WiFi are the events that the WiFi library incorporates, since I find it easy to cope with, and with only those two events GOT_IP and STA_DISCONNECTED you should be ready to go.
Now that we are on this point, there is a very handy thing to learn in case we want to make this code work also in ESP8266, since the 8266 version uses a different WiFi library. Plataformio injects some variables to identify what environment we are compiling with. I really don’t know exactly how many they are and you can just read this on their own documentation but I know that this two come very hande for our purpouse:

#ifdef ESP32
   #include <WiFi.h>

#elif ESP8266
   #include <ESP8266WiFi.h>

#endif

So basically if we compile this, editing the ini default_envs in platformio.ini, and compile it on an esp32 then there will be a #define ESP32 set and the first include <WiFi.h> will take place. But if we use an esp8266 then the ESP32 will be not define and the ESP8266 instead. Then the other ESP8266WiFi.h header file will be included.
The #ifdef statements in C are processed in compile time. Is not like a real conditional if in our program, you can imagine this #ifdef as a way to let us shape our program to different environments, or even do different things if a sensor is defined. For example we could have a Firmware that has an optional TEMPERATURE_SENSOR. Well if that is defined, then it should measure the temperature and run an extra code for that, if not then it will simply not include this part letting the program run anyways and do it’s thing but without that part of the code.

Important, the WiFi classes are not the same and ESP8266WiFi class does not have the same event handlers as the ESP32 class so here is the rewritten part if you want to do a version that supports both chips:

#include "Arduino.h"
#include <ESP8266WiFi.h>
int lostConnectionCount = 0;

#ifdef ESP32
/** Callback for receiving IP address from AP */
void gotIP(system_event_id_t event) {
  Serial.println("Online. Local IP address:");
  Serial.println(WiFi.localIP().toString());
  // We are connected, we could already receive or send something w/WiFi
}

/** Callback for connection loss */
void lostCon(system_event_id_t event) {
  ++lostConnectionCount;
  Serial.printf("WiFi lost connection try %d to connect again\n", lostConnectionCount);
  WiFi.begin(WIFI_SSID, WIFI_PASS);
  if (lostConnectionCount==4) {
    Serial.println("Cannot connect to the internet. Check your WiFI credentials");
  }
}
#elif ESP8266
  void gotIP() {
    Serial.println("Online. Local IP address:");
    Serial.println(WiFi.localIP().toString());
    // We are connected, we could already receive or send something w/WiFi
  }
#endif

void setup() {
  Serial.begin(115200);
  Serial.println("setup() started let's connect to WiFI");

  Serial.printf("WiFi name: %s\nWiFi pass: %s\n", WIFI_SSID, WIFI_PASS);
// Start our connection attempt
  WiFi.begin(WIFI_SSID, WIFI_PASS);


#ifdef ESP32
// Event driven WiFi callbacks
// Setup callback function for successful connection
  WiFi.onEvent(gotIP, SYSTEM_EVENT_STA_GOT_IP);

// Setup callback function for lost connection
  WiFi.onEvent(lostCon, SYSTEM_EVENT_STA_DISCONNECTED);
#elif ESP8266
  Serial.print("Connecting.");
  while (!WiFi.isConnected()) {
    Serial.print(".");
    delay(200);
  }
  gotIP();
#endif

}

void loop() {
}


So we’ve used this example to make this WiFi part be environment independant and run in both ESP32 or ESP8266 but actually is much more powerful than that and can be used for many other things.

This will be the Serial output when running the program for this chapter

Arduino-esp32 Basic course – Getting started – Chapter 1

First of all, this small series of blog posts, assume you have installed and are familiar with Platformio IDE to edit and upload code to your Espressif chips. We ‘ve covered in another post the installation and getting started part with this nice IoT editor. Please refer to this section of Platformio to get the basics right of the editor.
Prerequisites: Just grab any ESP32 or ESP8266 and make sure it works. Check that you can see the Serial monitor so we can debug the code. 

The platformio.ini project configuration file

This is the configuration file where we can define what are the environment targets (chips) where we want to upload and run our program. For example, we can have the same code, to run in ESP8266 or ESP32 using the same source. 

; File: platformio.ini

[platformio]
; This is the default environment but we can also use command line
; or change here to espressif8266 to upload it to this target
default_envs = lolin_d32

[env:lolin_d32]
platform = https://github.com/platformio/platform-espressif32.git
board = lolin_d32
framework = arduino
monitor_speed = 115200
; set frequency to 80/ 160MHz 160000000L
board_build.f_cpu = 160000000L

[env:espressif8266]
platform = espressif8266
board = d1_mini_lite
framework = arduino
monitor_speed = 115200

So this will be our first program, will just include the Arduino framework, start a counter on 0.  As every program on Arduino framework, will have a setup() that is executed only once when the chip is powered, and a loop() method that is precisely on a loop.  It will just print what you see on setup and then a new line every second. 
I also invite you to to be curious enough to use the CTRL+LEFT click over Arduino.h and to explore what it does. It includes the framework. Actually it includes the FreeRTOS that is a real-time OS for microcontrollers and also some other important definitions and includes for the Arduino ESP32 framework itself to work. And this is the way to discover any library or thing you include in your program, just CTRL+LEFT and explore the code, trying to understand what function it has.
So now let’s code our first little program:

// File: src/main.cpp

#include "Arduino.h";

int counter = 0;

void setup() { 
   Serial.begin(115200); 
   Serial.println("setup() started");
}

void loop() { 
   ++counter;
   Serial.printf("Counter: %d\n", counter);
   delay(1000);
}

Very simple right? Not too many things. Just a variable in the global scope, that get’s incremented in the loop, and is getting printed using printf in a single line. So we created a very short and nice program that actually does nothing except printing some Serial output.
The variable scope is easy to grasp and is also the same for other languages as javascript. A global scope variable that is defined on top, can be incremented from each function. That means that if we would move the:

int counter = 0;


At the beginning of the loop() the loop itself would have no sense, since it will add one and go back to 0 all the time.

In the next chapter, we will learn how to use the environments we defined in platformio.ini, to add different codes keeping the same program to run in esp8266 and esp32. Just follow this blog or keep tuned to @martinfasani twitter account to read the next release.

NOTE: Up to here we could also have compiled and run the very same code in an Arduino board and it will do exactly the same. Since we are not using any of the Espressif extra goodies like WiFi, this could be run also in another boards, keep tuned to see what is coming next that will be using WiFi or Bluetooth.

PlatformIO: An alternative to Arduino IDE and a complete ecosystem for IoT

PlatformIO Logo

As an introduction I would like to make clear that I’m not a C++ advanced coder or IoT professional, I do this just because it’s a challenge, and because it’s a lot of fun compared to my 9 hrs/5 days a week web developer doing PHP and Admin panels for clients in Germany. Two months ago I started tinkering with SPI Cameras and the Espressif systems boards and that’s how this open source project was born. So far I was using Arduino since I do not need a super IDE, sometimes I also edit the code with vi or gedit instead of open a monster IDE that will eat your CPU alive. But gladly this is not the case. I was since long looking for a competitive alternative to Arduino when this github issue on the FS2 Camera Project called my interest:

tablatronix commented 8 days ago

I had to manually install this button library as it is not in platformio , is it in arduinos?

And that’s how after a few clicks I discovered Plaftormio.org that according to their home page it’s an open source IoT ecosystem. But what interested me more than this is the subtitle:  “Cross-platform IDE and unified debugger. Remote unit testing and firmware updates

So instead of answering tablatronix issue, I started installing this new IDE, that happened in a breeze.
1. First thing is to install the VS CODE Version. I choosed the Visual Studio code option since it has more features. Microsoft’s Visual Studio Code is the base and PlatformIO is built on the top of this.

2. Go to “Extensions” and install PlatformIO IDE “Development environment for IoT, Arduino, Espressif (ESP8266/ESP32)”

platformio IDE extensions is marked in RED just before PlatformIO logo

3. In my case since I used Arduino IDE before, go to PlatformIO alien face logo and select “Import project from Arduino”. Then select the folder where your Arduino project is and PlatformIO will create a Workspace for you with all the necessary structure.

4. Adjust serial monitor baud rate.  If you are using Espressif chips edit platformio.ini and add the following line at the end:

monitor_baud = 115200

This will make your serial work in the right baud rate for ESP8266 /ESP32 (Serial is the plug icon in the bottom just before the Terminal > icon)

5. FS Data. If you are using SPIFFS that in Arduino is the /data folder inside your sketch you will notice that in PlatformIO this folder needs to be at the root level. So you can simply move it one directory above. To upload SPIFFS data use the following command in the terminal:

pio run --target uploadfs
IMPORTANT: As difference with Arduino if you try to save a file in /1.JPG here you will get it saved on:
/spiffs/1.JPG so create this folder on /data or you will get; VFSFileImpl(): fopen(/spiffs/1.jpg) failed

6. Libraries in PlatformIO live inside a folder on your project called .piolibdeps Thanks god, they are not distributed on 3 different parts, like it happens with Arduino (Some in Arduino/libraries, some in Programs/Arduino/libraries and so on) but are there available for you in just one place :)
To install a new library is very easy, just go to PlatformIO.org/lib and type the name of the library to search. If found copy the resultant line in the Terminal just like point 5 and the IDE will look this up for you and download it using github to the  .piolibdeps folder.

pio lib install "WifiManager"

Sometimes you will need a library in a special branch and there is also an easy way to do this. Just use :

pio lib install <repository#tag> 

// Install development version of WifiManager library
pio lib install https://github.com/tzapu/WiFiManager.git#development

7. If you use Arduino before it’s possible that you used some of it’s constants. So if your sketch compiles, but it does not runs like expected try to add this include line at the beginning

#include <Arduino.h>
Including Arduino.h at the beginning of the sketch

As a footer note I must make clear that it takes some time to get accustomed to the new IDE. But it comes with a great benefit as it shows you much better C++ warnings, it’s prettier to use, and has the advantage that you can Ctrl+Click and navigate between different classes. Something that it was not possible to do with my old IDE. And the most beautiful update is that all libraries are in a single place per Project, like it should be, leaving you a clear idea of how much code and dependencies you are adding into your sketch.

In FS2 project porting it to the ESP8266 Wemos board this happened like a breeze. And it was just the fact of upgrading my code to use OneButton library. adding the include Arduino.h and that is. After uploading SPIFFS data and the new code, the camera was ready to be used. Now it’s not always that easy. trying to compile the same code to an Heltec ESP32 board, I got SPI communication issues with the camera and I’m still fighting with it.

UPDATE: I found what is going on here, and it’s that there are some problems with my sketch that uses I2C and wire library to comunicate with the Camera on the Heltec ESP32 environment. Error message is:
i2cCheckLineState(): Bus Invalid State, TwoWire() Can’t init. I solved it updating the platformio.ini configuration file to use:
board = lolin_d32
So using this board it compiles and works correctly. No idea why it does not using heltec_wifi_lora_32 I will have to research more.

Additional links of interest:

Source filter: src_filter
This option allows to specify which source files should be included/excluded from build process. It could be useful to keep the same core for ESP8266 and ESP32 but including different files to support both. So far I’ve been using 2 different branches something that is hard to maintain for obvious reasons.

Library dependencies: lib_deps declaration in platformio.ini
Like composer for PHP, this IDE offers a way to declarate your libs in the ini file. To check how a professional software for 3D-printing does take a look in Marlin configuration file. This is a very important point to keep in mind since after the lib_deps list is correctly added and tested, people testing your code just need to hit “build” to download them, saving a huge amount of time. This are FS2 library dependencies.

FS2 Camera project

If you are interested to build your own WiFi Camera for around 40€ of components and maybe 5€ of 3D-printed case, then check this project on github:

https://github.com/martinberlin/FS2

I’m giving out in december ten free 3D-printed cases, if you are interested on getting one and putting together a WIFi Camera please choose between Black PLA, black PETG or RED transparent and comment in this post. You can send me the address later per private message or in twitter. Thanks for your interest!

FS2 camera from Blender to production

In this entry, I wanted to document what is the process of making one of this cameras, starting from the 3D – model to the end product where you turn it on and connects to WiFi ready to take pictures.

After removing the support and sanding the round columns the first thing is to connect the front and back case together and see that they fit correctly. Usually, they do but PET is a tricky plastic to print and the end termination is a bit rougher than with PLA so it requires some post-production work. As an advantage, this plastic is stronger than PLA, and will stand a crash much better since it’s more elastic and resistant. I would say the best termination and strength balance would be to print this in ABS but I dislike the smokes and the fact that is also very difficult to print at home.

When this step is ready then it’s the time to heat up the soldier and prepare the ON/off switch and the shutter button. Then there are 8 cables more that go from the Arducam (2 or 5 mega version) to the Wemos D1, that is the responsible of uploading the picture to the cloud. This is a prototype for myself so it looks a bit messy but shows how it is at this stage:

3 pair of cables from the left to the right: Battery, ON/off and shutter button

Then comes the reality shock moment that is to connect the Wemos ESP8266 through USB to the computer and upload the program that will do the magic of receiving the JPEG image from Arducam and upload it to a php API endpoint. Usually, at this point there is something that needs to be corrected, but either nothing works or all is fine and dandy. I open the mobile hotspot and turn on the camera. See if connects, try to take a picture, preview it on the PHP-gallery.  Try to test timelapse mode, see it works, and that’s pretty much it. A new camera is ready to be delivered.

FS2 WiFi camera

E-Paper driver to make your electronics smaller

Got from Waveshare some of this E-Paper ESP8266 driver boards:
e-paper esp8266 driver-board

I’m trying to make the electronics of my displays as small as possible and to avoid the wire-chaos inside the case with the goal of having more space for the battery. This will basically spare the need of the driver HAT and additional cables, something that is still present in my first prototype:

A bit messy uh ?

The only issue I see and I’m still sorting out with Waveshare is that the cable is not coming with the RAW display. But I think it will be not a show-stopper.

E-Paper ESP8266 driver board example developed by Waveshare

  • Supports Floyd-Steinberg dithering algorithm, more color combinations, better shadow rendering for the original image
  • Supports popular image formats: BMP, JPEG, GIF, PNG, etc.

Specifications

  • WiFi protocol: 802.11b/g/n
  • Interface: 3-wire SPI, 4-wire SPI (default)
  • Operating voltage: 5V
  • Operating current: 50mA ~ 100mA
  • Outline dimension: 29.57mm x 48.26mm
  • Mounting holes size: 2.9mm

When I find the time will post about the first tests and specially about consumption. Currently I’m using a 7.5 B/w only display with a 1200mA battery for our office. My only wish is that Waveshare electronics makes bigger E-paper displays so we can make more visible charts for our clients (10.3″ or 13 inches)

UPDATE from Waveshare

The sales people replied me, the cable is included when you buy the driver, it’s on Package contents Tab on Waveshare website:

  1. e-Paper ESP8266 Driver Board x1
  2. e-Paper Adapter x1
  3. 24PIN FFC x1
    1
    2+3-> 24 pins cable is included.
    So that’s it, you just need this driver, and to buy one RAW display. So it will run using a core of only 3 elements: Driver, Cable and E-paper display

E-Paper driver board specifications