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. They are available from the Heltec Store on Aliexpress.

Setting Up the Arduino IDE for the ESP32 Range

New Easy Method

If you previously installed the hardware libraries for the ESP32 using the old method you need to delete them. Find the folder where your Arduino libraries are kept by opening File > Preferences in the Arduino IDE:

IDE Preferences Location

Inside this folder open the hardware folder and find and delete either the esp32 folder or espressif folder.

ESP32 Folder


Now you can set up the ESP32 libraries the easy way. In the File > Preferences window in the IDE paste the following line into the Additional Boards Manager URL:

If you have entries in this field already then add the new line before them but separate them with a comma:

IDE Preferences Board Manager

Then go to Tools > Board > Board Manager:

IDE Board Manager

Type ESP32 and Install the new hardware libraries:

IDE Boards Manager ESP32

When the ESP32 library is installed you will be able to find all the ESP32 boards including the Heltec Wifi 32 in the IDE’s board selector:

IDE Board Manager Heltec Wifi 32


Previous Method

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.

First Run

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()

40 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:

    1. WILLIAM E WEBB says:

      I initially could not get the display to work with the library that I was using. I switched to the u8g2lib library. It had a bit of a leaning curve. You can not feed drawStr a String. You have to feed it an array of char which you can build with
      sprintf. Thus:

      char humidity_st[32];
      sprintf(humidity_st, “Humidity: %d RH”, int(humidity));
      display.drawStr(0, 38, humidity_st);

      This approach is growing on me. As far as the right pins go, that was also a struggle. Here’s what worked for me.
      U8G2_SSD1306_128X64_NONAME_F_HW_I2C display(U8G2_R0, 16, 15, 4);

  5. Eddiie says:

    Thank you for the time making this page. It is showing up as the top google result.

    I have 2 questions perhaps you can help me answer.

    1) Does the OLED have its own I2C bus? I want to use this amazing board to control some I2C devices but am not sure it the I2C bus is already occupied but the OLED. I read somewhere that some LED libraries are using a software written I2C driver, not the hardware I2C.

    2) I had some code for the ESP8266 that someone wrote that would put the chip into AP mode and had a web server. You would connect to its Wifi network to configure the chip to connect to your wifi network through the web pages.
    Once configured, the chip rebooted in client mode and would join the network you configured as a client.
    Is there similar code out there for this board? Does this program / function have a name?

    1. Toni says:


      Pins 21 and 22 look like they also are a second I2C channel

      1. WordBot says:

        That’s the LoRa version.
        Looks like there are hardware iC2 pins.

        The SW in the command for the OLED is SoftWare mode so I would guess hardware mode would work as well for another device:
        U8X8_SSD1306_128X64_NONAME_SW_I2C u8x8(/* clock=*/ 15, /* data=*/ 4, /* reset=*/ 16);

        For your second question… I don’t really understand what you want to do.

        1. Eddiie says:

          Ah, I have the Wifi kit 8

          It looks like there is only the one I2C pins. which are used by the onboard display, GPIO 4 and 5.
          Was hoping the pins labeled on the board “SCL” (GPIO14), and “SDA” (GPIO2) would be that hardware I2C but it does not appear to be.

          I wonder what pins ” Wire.begin();” uses.

          1. WordBot says:

            This page (use the translate feature in Chrome) shows the pins for the two different board versions. Doesn’t look like there’s another I2C bus. Can you not connect more than one device to this bus as well as the display?

        2. Al says:

          FYI – That is the wrong pinout. They made a mistake when they printed that. That picture has the pins in reverse. Here is the corrected one:

  6. zubroid says:

    WordBot thank you for the article!

    I have a question:
    Do you know how to connect RFID MFRC522 to the board. I tried to connect a RFID to existing MISO,MOSI, SDA, SCK and I the board does not see the RFID.

    Thank you for your time.

    1. WordBot says:

      I don’t know. The pins should be as in the diagram here – and your code should reflect those pins.

      I want to do some RFID things but I haven’t bought any hardware to test with yet.

      1. zubroid says:

        Thank you for your response! Actually I made one step further.

        I got response from the RFID reader, but only a firmware version.

        ⸮Firmw⸮⸮⸮Version: 0x12 = (unknown)
        Scan PICC to see UID, SAK, type, and data blocks…

        I described it here

        If you have any idea what would be wrong it’d be awesome.

  7. Graham says:

    Nice clear web site and got me , a newbie, going.
    I had problems initially uploading to the ESP32 but found that I needed to press PRG and hold it, then press the RST momentarily, then release the PRG button. The screen would go blank and it would wait until the upload began. This worked at the full speed.
    I managed to upload several sketches ok.
    However, I’ve since disconnected the ESP32 and reconnected and now I’ve got a driver problem. I did the manual update to the version 10 driver from the site you mention above but that didn’t solve it. It seemed to then mess up my Arduino driver but i have been able to recover that.
    Any ideas anyone?

    1. WordBot says:

      Can you see anything with question marks in Device Manager?

      Is the correct port selected in the Arduino IDE?

      1. Graham says:

        Yes the ESP32 USB bridge had it. The error was No 10 – Failure to start or something.
        After lots of messing with different versions of the drivers I took all the other things out of the USB ports (a GPS, hard drive, bluetooth dongle, the Arduino and the ESP32). Then with just the ESP32 board back in it started ok. I put the rest back in one by one and they all seem ok now. I’m using the v10 driver.
        The only problem now is that the full speed upload fails so I’ve reverted to 115200. Not a problem as it’s the compiling that takes most of the time, not the upload. Why does it take so long? A real pain if you are trying to debug a program.

        1. WordBot says:

          Did you check it was on the correct port? . It does sound like a driver problem if you saw a question mark.

          Maybe Windows had assigned a different port when you plugged it in the second time?

          I think compiling takes time as the ESP32 is much more complex than a basic Arduino so there’s a lot more work to do when compiling. In general compiling code is a slow process.

  8. Marcin says:

    anyone connected something via i2c ? I have SHT31 but it works only when I disable OLED…

    1. WordBot says:

      Is this the Lora board?

  9. Neil Maron says:

    I cannot get mine to compile because it can’t find WiFi.mode(). Which WiFi library should I have installed? Error is: ‘class WiFiClass’ has no member named ‘mode’

    1. WordBot says:

      This is the library – but I think this is installed when the board is installed. Maybe there’s a conflict on your device with another library?

    2. Wolfgang Zelinka says:

      Read the Compiler messages exactly: Ther are more “Wifi.h”.
      The wrong was used. I deleted the
      C:\Program Files (x86)\Arduino\libraries\WiFi
      and used the on this path
      C:\Program Files (x86)\Arduino\hardware\espressif\arduino-esp32-master\libraries\WiFi

  10. Terr says:

    how to add support built-in OLED Heltec WiFi Kit 32 to ?

  11. Bruce Peterson says:

    Is there a way to take control of the one on-board LED that just blinks continuously?

    1. Alan Cross says:

      Hi Bruce, no………that LED is part of the battery charging circuit and will only go off when a fully charged battery is connected. Whilst a battery is charging, the LED will go to a steady on state until the battery is fully charged then it will go off.

  12. sohaib zoabi says:

    i want a code to find bluetooth devices

    1. WordBot says:

      I’ll add it to my list for future tutorials.

  13. jim says:

    did you ever find any sample Bluetooth code/library examples (not BLE)

    1. WordBot says:

      There’s Bluetooth Serial in the ESP32 examples in the Arduino IDE. Does that help?

  14. Negru Tiberiu says:

    I’m new to this. I just bought an Heltec Wifi kit (not LoRa). It works fine with examples.
    Now I bought some BMP280 sensors to display the atmospheric pressure and temperature. When I connect the sensor to I2C (without the OLED defined) it shows the values on serial. But when I try to add the U8g2 library it shows “Could not find a valid BMP280 sensor, check wiring!”.
    Anybody can help me?
    Thanks in advance

    1. WordBot says:

      Hi, Without looking into it much the command for the screen uses pins 15, 4 and 16

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

      I think you can use different pins for the BMP280 and define them in the sketch. Alternatively the BMP280 might have a place on the back where you can change the address and use the same I2C pins. There’s a I2C scanner here that might help:

  15. Tiberiu says:

    Thanks a lot!
    I solved it. Switched the sensor to SPI and now both work. I thought that ESP32 has 2 independent I2C buses. I was connecting the sensor to 21, 22 and the screen is on 4,15,16.
    I used the scanner and the address is 76. I changed it in library Adafruit_BMP280.h but still nothing.

  16. Jack Steinhilper says:

    If this device is compatible with the Arduino IDE, shouldn’t it also be able to be programmed through say Microchip Studio/Atmel Studio for AVR’s like the 328 (which the Arduino is based on)?

    Any suggestions on how to do that? I’m more familiar with the Atmel studio than the Arduino IDE (have the files, but not installed yet). I have programmed some stuff on the Arduino through the Atmel Studio.

    1. WordBot says:

      I don’t think it will be possible because Espressif (ESP32 manufacturer) created the libraries etc to work with the Arduino IDE. You could take a look at the IDF if you want a to develop with the native tools. A lot of people have moved from the Arduino IDE to as well if you wanted to keep using the Arduino ESP32 environment.

  17. Jack Steinhilper says:

    Thanks for that information, I’ll take a look at it. I’m not sure how much I plan to do with this device, so maybe the IDE is the best way to go (at least for now). I know the core processors are different. Hopefully, I can keep it simple enough for a while. (I’ll be doing this while living on the road in our RV, so resources can be a bit limited).

    Thanks again.

  18. SangLim says:

    When I run the source it doesn’t find WiFi.
    And the text on the PC’s serial monitor is garbled.

    I definitely installed the USB driver and compiled Sketch.
    It was successfully uploaded to the device.

    The device’s OLED only shows “Searching networks” repeatedly.

    When I first purchased the device, I was sure it found the network well.

    What’s the problem?

    1. WordBot says:

      Garbled serial monitor is probably the wrong port speed used in the IDE for the sketch. Wi-Fi might just be the connection is weak.

Leave a Reply

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

This site uses Akismet to reduce spam. Learn how your comment data is processed.

scroll to top