{"id":1779,"date":"2020-04-16T10:21:46","date_gmt":"2020-04-16T10:21:46","guid":{"rendered":"https:\/\/www.sabulo.com\/sb\/?p=1779"},"modified":"2025-10-31T08:31:04","modified_gmt":"2025-10-31T06:31:04","slug":"how-to-use-the-heltec-oled-display-on-the-esp32","status":"publish","type":"post","link":"https:\/\/www.sabulo.com\/sb\/esp32-development-board\/how-to-use-the-heltec-oled-display-on-the-esp32\/","title":{"rendered":"How to use the Heltec OLED display on the ESP32"},"content":{"rendered":"\n

Heltec is a Chinese company that makes all kinds of SoC (system on a chip) devices. Their ESP32-based SoCs appear to be solid quality, and they offer a few variants, including a LoRa WLAN chip for long range connectivity on a narrow band.<\/p>\n\n\n\n

I bought a handful of the Heltec OLED WiFi kit chips<\/a> (the link goes to the current V2 version’s page) so as to have a little display without the hassle of attaching a two-line LCD on the device, to see what’s happening in the system. I have a previous piece on how to use the LCD displays<\/a>, in case you are interested (it features the Arduino but it works just as well on ESP32).<\/p>\n\n\n\n

The installation of the Heltec brand chips is straightforward, because after installing the general support for ESP32, you can add Heltec as a library <\/a>to the Arduino IDE. This generates the file Heltec.h into the Libraries folder, and that brings you all the functionality you need. <\/p>\n\n\n\n

EDIT: THe library used by my version of Heltec Wifi Kit 32 is version 1.1.5. Your mileage may vary.<\/strong> Be prepared to install highe or lower versions based on your device’s age. <\/p>\n\n\n\n

The code you see in this blog post is available on GitHub.<\/a><\/p>\n\n\n\n

OLED features<\/h3>\n\n\n\n

OLED stands for Organic LED, and it is some sort of biomechanical sorcery or magick that brings up imaged on the 0.96″ screen. It is bluish in color. The resolution is 128 x 96 pixels, so this isn’t exactly HD, but for the use I have for this it is absolutely adequate. You can display strings or draw lines, boxes, circles, or images, if you work the images into the right size, and then export them into a file format called XBM, which is a text file actually. This is a nice tutorial on using XBM<\/a>. Essentially your image pixels are turned into zeros and ones, put into an array, and displayed by the Heltec functionality as images. The images in XBM are contained in a header file called images.h. <\/p>\n\n\n\n

Here’s a short video on how the OLED works.<\/p>\n\n\n\n

<\/p>\n\n\n\n

OLED with custom images, booting<\/figcaption><\/figure>\n\n\n\n

The Haaga-Helia logo on this boot sequence is created by taking the actual logo, scaling it down to 128 x 96 pixels, and then exporting it to a format like this:<\/p>\n\n\n

\n
\"\"<\/figure>\n<\/div>\n\n\n

In XBM code, it looks like this:<\/p>\n\n\n\n

define hhlogo_width 128\ndefine hhlogo_height 64\nconst unsigned char hhlogo_bits[] PROGMEM = {\n0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,\n0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,\n0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,\n\n[I am cutting a bunch of these lines here, because as you can see, it merely defines 0xFF of the pixel is off and something else like 0x3C for pixels that are on.]\n\n0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,\n0xFF, 0xFF, 0xFF, 0xFF, };<\/pre>\n\n\n\n
When these bits are rendered in the device, you see the picture as in the image above. <\/p>\n\n\n\n
The device is actually rather handy in drawing not only pixel images, but lines, boxes, and curves too. When you install the library, you get some sample files, and one of them shows all these features, namely SSD1306DrawingDemo. <\/p>\n\n\n\n
The draw demo program<\/figcaption><\/figure>\n\n\n\n
Let’s look at how the device draws things.  In the Setup function, the device must be enabled:<\/p>\n\n\n\n
Heltec.begin(true \/DisplayEnable Enable<\/em>\/, false \/LoRa Disable<\/em>\/, true \/Serial Enable<\/em>\/);\nHeltec.display->setContrast(255);<\/pre>\n\n\n\n
After that, it can be asked to do all kinds of operations, all of which must be followed by <\/p>\n\n\n\n
Heltec.display->display();<\/pre>\n\n\n\n
In effect, every operation is written into a buffer an when this line is issued, it actually displays the values. It was unclear to me at first that this display operation must be repeated often, but when you figure out that this is the actual show command, it’s easy enough. Its counterpart is the clear operation:<\/p>\n\n\n\n
 Heltec.display->clear();<\/pre>\n\n\n\n
This does not for some reason erase every pixel every time, so sometimes you need to draw a black box in the entire screen to make sure everything goes away. This code draws an alternating black \/ white set of rectangles:<\/p>\n\n\n\n
void fillRect(void) {\nuint8_t color = 1;\nfor (int16_t i = 0; i < DISPLAY_HEIGHT \/ 2; i += 3) { \n\/\/ alternate colors\nHeltec.display->setColor((color % 2 == 0) ? BLACK : WHITE); \nHeltec.display->fillRect(i, i, DISPLAY_WIDTH - i * 2, DISPLAY_HEIGHT - i * 2);\nHeltec.display->display();\ndelay(10);\ncolor++;}\n\/\/ Reset back to WHITE\nHeltec.display->setColor(WHITE);\n}<\/pre>\n\n\n\n
So, in essence, it is very easy to work with this display. The main commands you will use are<\/p>\n\n\n\n
Heltec.display->drawLine(start-x, start-y, end-x, end-y);\nHeltec.display->drawRect(topcorner-x, topcorner-y, \nbottomcorner-x, bottomcorner-y); \/\/open rectangle\nHeltec.display->fillRect(topcorner-x, topcorner-y,\nbottomcorner-x, bottomcorner-y); \/\/filled rectangle\nHeltec.display->drawCircle(center-x, center-y, radius) \/\/circle\n\nHeltec.display->setTextAlignment(TEXT_ALIGN_LEFT);\nHeltec.display->setFont(ArialMT_Plain_10);\nHeltec.display->drawString(0, 0, \"Hello world\"); \/\/this is of course one of the main methods, writing text on the screen\n\nHeltec.display->setColor(WHITE); \/\/color to use<\/pre>\n\n\n\n
This set of commands will take you far. The video below shows an analog clock in operation. It draws a circle, and then inside it, three likes with the same origin and differing lengths:<\/p>\n\n\n\n
float xsec = arc_second * sin(analogSec * 6 * PI \/ 180); \/\/ Second needle TIP position, arc=needle length
float ysec = arc_second * cos(analogSec * 6 * PI \/ 180);
float xmin = arc_minute * sin(analogMin * 6 * PI \/ 180); \/\/ Minute needle TIP position, arc=needle length
float ymin = arc_minute * cos(analogMin * 6 * PI \/ 180);
float xhour = arc_hour * sin(hourDegrees * PI \/ 180); \/\/ Hour needle TIP position, arc=needle length
float yhour = arc_hour * cos(hourDegrees * PI \/ 180);
Heltec.display->drawCircle(x_origo, y_origo, 31);
Heltec.display->drawLine(x_origo, y_origo, x_origo + xsec, y_origo - ysec); \/\/Second hand
Heltec.display->drawLine(x_origo, y_origo, x_origo + xmin, y_origo - ymin); \/\/Minute hand
Heltec.display->drawLine(x_origo, y_origo, x_origo + xhour, y_origo - yhour); \/\/Hour hand
Heltec.display->display();<\/pre>\n\n\n\n
You can learn more of the use of Heltec in the ESP32 UDP – Android application posts, of which a three part blog entry is being written and will be published as soon as I get them done.<\/p>\n\n\n\n