ESP32 Built-in OLED – Heltec WiFi Kit 32


An introduction and set-up for the Heltec Automation WiFi Kit 32 development board with OLED display. Follow the steps below to have the example WiFiScan script show your local access points on the built-in display.

This board is based on the ESP32 chip and has onboard WiFi, Bluetooth, a 0.96 OLED display, lithium battery connector charging and a CP2102 USB to serial interface. It also works with the Arduino IDE.

Setting Up the Arduino IDE for the ESP32 Range

I’m using Windows 10 so instructions for Windows follow. If you are using another system or want full instructions follow this link:

First unplug any boards you have connected and close the Arduino IDE if it’s open.

For these boards to show in the Arduino IDE you have to install the hardware libraries locally using Git. Git is basically a way to keep local files synchronized with files on the internet. In this case it’s used to download the files used by the IDE to work with the ESP32 boards that are available.

If you don’t have Git installed then you need to download and install it from here:
After installation you should run Git GUI (should be in Programs in the Start menu). Click ‘Clone existing repository’ and…

  • In the Source Location box enter:
  • In the Target Location box enter:  C:/Users/[YOUR_USER_NAME]/Documents/Arduino/hardware/espressif/esp32 replacing [YOUR_USER_NAME] with your login name. You can see this name on the Start menu by mousing over the grey circle icon.

Click Clone to start cloning the files to your PC. This might take a while.
When this has completed navigate to this directory:  C:/Users/[YOUR_USER_NAME]/Documents/Arduino/hardware/espressif/esp32/tools and double-click get.exe. Again this might take a while.

You should now have all the libraries installed for the ESP32 boards that drivers are available for.

You can now plug in the Heltec board. Windows will attempt to install any necessary drivers. In my case I had to manually install the USB to UART driver from here:

Everything should now be ready to test the board! So…

Start Arduino IDE, select your board in Tools > Board menu and select the COM port.

To test the board is basically working you can use the example WifiScan sketch here: File> Examples > Wifi > WifiScan If you open the Serial Monitor (Tools > Serial Monitor) you will be able to see any WiFi access points in range. Check the baud rate is the same as in the sketch – probably 115200.

Testing the Heltec ESP32 with the Onboard OLED

Once you have the ESP32 libraries installed and you’ve tested that the board can run the basic WifiScan sketch we can install the display libraries for the OLED.

My favourite display library for these OLEDs is the U8g2 ( library. This is a lot easier to install as it can be found in the Arduino IDE library manager.  Open Sketch > Include Library > Manage Libraries and search for and then install U8g2.

U8g2 has three different display methods. If you want to quickly test all three, the following examples show the correct constructor.

Full Buffer:
In the Arduino IDE: File> Examples > U8g2 > full_buffer > GraphicsTest
Paste: U8G2_SSD1306_128X64_NONAME_F_SW_I2C u8g2(U8G2_R0, /* clock=*/ 15, /* data=*/ 4, /* reset=*/ 16);
Above the line: // Please UNCOMMENT one of the contructor lines below
Upload the sketch

Page Buffer:
In the Arduino IDE: File> Examples > U8g2 > page_buffer > GraphicsTest
U8G2_SSD1306_128X64_NONAME_1_SW_I2C u8g2(U8G2_R0, /* clock=*/ 15, /* data=*/ 4, /* reset=*/ 16);
Above the line: // Please UNCOMMENT one of the contructor lines below
Upload the sketch

In the Arduino IDE: File> Examples > U8g2 > u8x8 > GraphicsTest
Paste: U8X8_SSD1306_128X64_NONAME_SW_I2C u8x8(/* clock=*/ 15, /* data=*/ 4, /* reset=*/ 16);
Above the line: // Please UNCOMMENT one of the contructor lines below
Upload the sketch

So, what are the numbers clock=*/ 15, /* data=*/ 4, /* reset=*/ 16 for in each of the examples above? These are pin numbers for the I2C controlled OLED on the board. This tells the display library which pins to use to communicate with the display.

ESP32 Heltec I2C Pins

Show WifiScan Sketch Display on OLED

Below is a sketch that displays the results of the WiFi scan on the OLED using the U8x8 version of the display library

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

// the OLED used
U8X8_SSD1306_128X64_NONAME_SW_I2C u8x8(/* clock=*/ 15, /* data=*/ 4, /* reset=*/ 16);

void setup()
  // Set WiFi to station mode and disconnect from an AP if it was previously connected


static void doSomeWork()
  int n = WiFi.scanNetworks();

  if (n == 0) {
    u8x8.drawString(0, 0, "Searching networks.");
  } else {
    u8x8.drawString(0, 0, "Networks found: ");
    for (int i = 0; i < n; ++i) {
      // Print SSID for each network found
      char currentSSID[64];
      WiFi.SSID(i).toCharArray(currentSSID, 64);
      u8x8.drawString(0, i + 1, currentSSID);

  // Wait a bit before scanning again

void loop()

4 Replies to “ESP32 Built-in OLED – Heltec WiFi Kit 32”

  1. Leonid says:

    I try all examples above – work perfect. But after it I try example …\Documents\Arduino\libraries\U8g2\examples\full_buffer\SelectionList, my Hitec WiFi KIT 32 board dead… I try come back to sketch working before – boart not responce. Below are error log:
    Arduino: 1.8.4 (Windows 7), Board: “Heltec_WIFI_Kit_32, 80MHz, 921600”

    Archiving built core (caching) in: C:\Users\SLEO~1.REL\AppData\Local\Temp\arduino_cache_452400\core\core_espressif_esp32_heltec_wifi_kit_32_FlashFreq_80,UploadSpeed_921600_9735e408823b91d4dd6cf7c8b5963565.a
    Sketch uses 439175 bytes (42%) of program storage space. Maximum is 1044464 bytes.
    Global variables use 36312 bytes (12%) of dynamic memory, leaving 258600 bytes for local variables. Maximum is 294912 bytes.
    ….. v2.1
    Chip is ESP32D0WDQ6 (revision 0)
    Uploading stub…
    Running stub…
    Stub running…
    Changing baud rate to 921600
    Configuring flash size…
    Warning: Could not auto-detect Flash size (FlashID=0xffffff, SizeID=0xff), defaulting to 4MB
    Compressed 8192 bytes to 47…

    What did happend and how to restore my board?

  2. WordBot says:

    Is it still broken? I’m not sure how to fix it but I saw this..

    try to erase the flash of the “bricked” LoPy with the form the esp-idf repository
    python3 -.port com_port –baud 230400 –chip esp32 erase_flash
    and then update the device again.

    But this is using python to work with the board so it’s a little outside my area of knowledge.

  3. Andy Haber says:

    I have the Heltec WiFi_Kit_32 version of this amazing module. I cannot get a text display when using the Adafruit_SSD1306 library. It works with the U8x8 librray, but I have a lot of previous code from other platforms using Adafruit_SSD1306.h that I would still like to re-use on the ESP32 platform. I have tried Wire.begin(4,15) and OLED_RESET 16 and setting 16 LOW then HIGH. I am not not getting any display on the OLED.

    It compiles fine, but no display on OLED.

    /* Test code using Heltec WiFi_Kit_32 module with built in SSD1306 OLED */
    #include // Core graphics library

    #define OLED_RESET 16
    Adafruit_SSD1306 display(OLED_RESET);

    void setup() {
    Serial.print(” Starting OLED display …. “);
    display.begin(SSD1306_SWITCHCAPVCC, 0x3C);
    display.setTextColor(WHITE,BLACK); // set to overwrite mode
    display.println(“Hello World”); // print on 1st line of OLED
    Serial.println(“Hello World printed to OLED on line 0”); }

    void loop() {
    display.print(“Hello World line 1”); // print on next line of OLED
    Serial.println(“Hello World printed to OLED on line 1”);
    display.print(“Hello World line 2”); // print on next line of OLED
    Serial.println(“Hello World printed to OLED on line 2”);

  4. Affeke Nommu says:

    I did initially use the acrobotic SSD1306 library but have since moved to the one by Squix because of the font generator.
    In library manager it is called ESP8266 and ESP32 Oled Driver for SSSD1306 display v3.2.7
    Haven’t tried the u8g2 library yet.

    Here is a quick example using this that works on the Heltec:

    #include “SSD1306.h”
    SSD1306 display(0x3c, 4, 15);

    void setup() {
    // put your setup code here, to run once:
    pinMode(16, OUTPUT);
    digitalWrite(16, LOW); // set GPIO16 low to reset OLED
    digitalWrite(16, HIGH); // while OLED is running, must set GPIO16 to high
    Wire.begin(4, 15);

    void drawDisplay() {
    // create more fonts at
    display.drawString(0, 6, “Hello wrlod!”);

    void loop() {
    // put your main code here, to run repeatedly:

Leave a Reply

Your email address will not be published. Required fields are marked *

scroll to top