# Heltec_ESP32 is a board support library that assumes the Arduino core is already chosen > The Heltec ESP32 Arduino library collects LoRa and LoRaWAN examples, factory test code, display drivers and sensor sketches for Heltec's ESP32 boards, and it expects you to pick a specific ESP32 core first. It is a set of examples and thin wrappers rather than a driver stack in its own right. **HelTecAutomation/Heltec_ESP32** — Arduino library for Heltec ESP32 (or ESP32+LoRa) based boards - Repository: https://github.com/HelTecAutomation/Heltec_ESP32 - Stars: 917 · Forks: 293 - Language: C - License: NOASSERTION - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/heltecautomation-heltec-esp32 ## You choose the framework, then the library The Heltec ESP32 Library contains extended examples: LoRa and LoRaWAN related examples, factory test code, display related example code, sensor example code and GPS example code. What it is not is a self-contained driver stack. The README states that the framework the library depends on can be chosen from two options: Heltec ESP32 Frame Work 3.0.2, which lives in the WiFi_Kit_series repository, or espressif/arduino-esp32 at 3.0.2. That ordering matters. You install the ESP32 core for Arduino first, then add this library on top of it, and the library assumes a specific core generation. The Chinese section of the README states the requirement even more directly: this Arduino library must be used together with the Heltec ESP32 build environment or espressif/arduino-esp32 at 3.0.2. The version pin is the thing to notice. A board library that says 3.0.2 is not compatible with an arbitrary core, and when the ESP32 core moves on, this library has to catch up. The release history shows the library does: version 2.1.4 came in May 2025, 2.1.5 in October 2025, and 2.1.6 in April 2026, with the last push to the repository on 2026-08-24. So the practical model is a library that tracks a specific core generation, not a library that abstracts over ESP32 versions. Anyone planning an upgrade of the Arduino ESP32 core needs to check this library's compatibility first. ## Two installation routes, and one path requirement that trips people up The README recommends the Arduino Library Manager, calling it the simplest way. The route is short: open the Arduino IDE, select LIBRARY MANAGER, search for Heltec ESP32 and install it. The Chinese instructions describe the same path with the menu spelled out, going to the project menu, then load library, then manage libraries. The git route exists for people who need a version the manager does not carry. The requirements are that git and the Arduino IDE are installed, and the library folder is in Username/Documents/Arduino/Library. The README is emphatic about that last point in bold: this library must be in this path. With Git bash open in that folder, the clone is one command. ```bash git clone https://github.com/HelTecAutomation/Heltec_ESP32.git ``` After that you have a new folder in your library path and the install is done. The Chinese version repeats the requirement with more force, saying the path must be inside the operating system's Documents/Arduino/libraries folder and that the Documents folder is the one the operating system provides, with three exclamation marks after it. The insistence is not arbitrary. The Arduino IDE only discovers libraries in its configured libraries folder, and the default location on Windows sits under the user's Documents directory. A clone into a projects folder somewhere else will simply not appear in the IDE, which is a confusing failure for anyone who assumes the IDE scans the filesystem. One practical note appears in the README's closing advice and is worth repeating before you debug anything else: make sure to use a high-quality Micro USB cable, it will reduce many problems. On a board with an OLED and a radio, a charge-only cable is a routine cause of a board that appears dead. ## The examples directory is the real content of the library The repository layout tells you what the library is for. The top level has library.json and library.properties, which are the Arduino library manager manifests, a keywords.txt for syntax highlighting, a CMakeLists.txt, and an src/ directory with the actual code. The examples/ directory is where the breadth shows, and the folder names are a catalogue of what the boards can do. The list runs from LoRaBasic through LoRaWAN for the radio side, OLED and TFT for displays, eink and Wireless_paper for the paper-style panels, SD for storage, Sensor for the sensor boards, GPS for positioning, Factory_Test for the production check, ESP32 for general board use, 2.4G_RF for the radio alternative, and then three directories named VME213, VME290 and VMT190 that appear to be display or board variants. That breadth is the actual value proposition. A Heltec board with an OLED and a GPS is a combination of several peripherals, and each one has register sequences, initialisation order and timing requirements that are tedious to rediscover. A factory test sketch is a different kind of value again: it is the code that checks a board works before it ships. The example for a LoRaWAN setup, for instance, is not just radio code. It involves a LoRa board, an antenna and often a network join, which is a sequence where a missing step or a wrong order produces a radio that never joins rather than an error message. The library also points at detailed step by step instructions for executing the examples, hosted in the Heltec documentation site under the ESP32+LoRa Series Quick Start guide. That document, rather than the README, is where the full procedure lives. ## The API reference is two documents, not the README The README's API Reference section has exactly two entries, and they point into the source tree rather than to hosted pages. ``` [OLED API](src/oled/API.md) ``` ``` [LoRa API](src/lora/API.md) ``` That is a small but revealing choice. The two areas with the most fiddly hardware interaction, the OLED display and the LoRa radio, get their own API documents inside src/, and everything else is covered by examples. So the division of labour in this library is examples first, with API documents only where the surface is worth describing precisely. This has a practical consequence for anyone evaluating the project. You cannot judge the API surface from the README alone. The README tells you the library exists and roughly what it covers; the actual method signatures live in two markdown files in the repository and in the header files under src/. The wider documentation sits with the vendor rather than in the repository. The README links the quick start guide for programming, a summary of common problems page, and a separate document about limited technical resources for products whose full documentation is not public by default. That last point is worth understanding: the resources section lists a set of downloadable resources per board, and if you see a Limited folder on a resource page it means the product has technical documentation that is not public by default, with a documented procedure for requesting access. That arrangement, board resources on the vendor site and code in the repository, is the shape of a vendor-maintained board support package rather than a community project. ## The board family this library actually targets The Relevant Resources section is a list of boards, and reading it tells you what the library is designed around. The first generation covers WiFi Kit 32, WiFi LoRa 32, Wireless Stick, Wireless Stick Lite and Wireless Shell. The second wave is the v3 hardware: WIFI Kit 32 v3, WIFI LoRa 32 v3, Wireless Stick v3, Wireless Stick Lite v3 and Wireless Shell v3, plus Wireless Paper, Wireless Tracker and HT-DE01. The Chinese list adds HT-CT62, written as Ct62 there, which is the same board with a different spelling of the same name. Two things follow. First, this is a broad hardware family rather than a single board, and the library has to cover both the original and the v3 revisions, which differ in their radio and display wiring. That is why the display and radio code is separated into its own modules with their own API documents: a common abstraction across board revisions is exactly the work that needs a documented surface. Second, the board list explains the example directories. Wireless Paper and eink relate to the e-paper boards, TFT to the colour display variants, and the VME and VMT directories to further panel models. The repository has its own README history worth noting. The Heltec WiFi Kit series framework, which is the alternative to the espressif core, lives in a separate repository under the Heltec-Aaron-Lee organisation, and it is pinned to 3.0.2 alongside the espressif option. So the choice for the reader is between a Heltec-maintained fork of the ESP32 core and the upstream Espressif one at the same version number. The language of the project is C, with the Arduino framework, and the library ships with the Chinese and English versions of the README side by side. ## Where this library is the wrong tool Three cases rule it out, and the first one is about hardware rather than software. If you are not using a Heltec board, this library buys you very little. The wrappers are board specific, the pin assignments assume Heltec wiring, and the examples assume the peripherals Heltec sells. If you have a generic ESP32 with a separate LoRa module, the Arduino ecosystem already has driver libraries for the radio and the display, and those are the better choice. The second case is a long-lived product that needs a specific core version. The library is pinned to core 3.0.2, in both the Heltec and the Espressif form. When the core moves forward, this library needs a matching release, and the release history shows roughly two or three releases a year, so the lag between a core release and a compatible library release is real. If you are building something with a long maintenance horizon, that is a recurring cost you have to budget for. The third case is a project that needs more than the library provides. This is a board support library with examples. It is not a LoRaWAN network server, not a mesh stack, not an over-the-air update mechanism. The README describes the scope plainly: extended examples for LoRa and LoRaWAN, factory test, display, sensor and GPS. The licensing point is worth checking directly rather than through a badge. The licence field on the repository is a custom type that GitHub cannot categorise, so the terms live in the LICENSE file at the root and the README does not summarise them. For a library you intend to vendor into a commercial device, read that file. On the positive side, the maintenance facts are fine. The repository is not archived, the last push was on 2026-08-24, and the most recent release, 2.1.6, came on 2026-04-27. ## Conclusion Adopt Heltec_ESP32 if you are building on a Heltec board with a LoRa radio, an OLED, a TFT display or a GPS module, and you want working example code and thin board-specific wrappers instead of writing every register sequence yourself. Do not adopt it if you are not using Heltec hardware, since the value here is entirely board specific, and check the core version first, because the library names Heltec ESP32 Frame Work 3.0.2 or espressif/arduino-esp32 at 3.0.2 as the frameworks it depends on. Before you start, read the OLED API and LoRa API documents in src/oled and src/lora, because the README delegates most of the reference detail to them. ## FAQ ### How do I install the Heltec ESP32 library? The README recommends the Arduino Library Manager: open the Arduino IDE, select LIBRARY MANAGER, search for Heltec ESP32 and install it. Alternatively, clone the repository with git into the Arduino libraries folder at Username/Documents/Arduino/Library, which the README says must be that path. ### Which ESP32 core does the Heltec_ESP32 library require? You can choose either Heltec ESP32 Frame Work 3.0.2 from the WiFi_Kit_series repository or espressif/arduino-esp32 at 3.0.2. The library must be used together with one of those build environments. ### What examples does the Heltec_ESP32 library ship? LoRa and LoRaWAN related examples, factory test code, display related example code, sensor example code and GPS example code. The examples folder in the repository contains separate directories for LoRaBasic, LoRaWAN, OLED, TFT, eink, Wireless_paper, SD, Sensor, GPS, Factory_Test, ESP32, 2.4G_RF and several VME and VMT board variants. ### Where is the API documentation for the Heltec_ESP32 library? The README links two API documents inside the source tree, at src/oled/API.md for the OLED display and src/lora/API.md for the LoRa radio. Full programming steps are in the linked Heltec ESP32+LoRa Series Quick Start documentation. ### My Heltec board will not power on, what should I check first? The README asks you to make sure you use a high-quality Micro USB cable, noting that it will reduce many problems, and it links a summary of common problems page in the Heltec documentation. ### What licence does the Heltec_ESP32 library use? The repository licence field is a custom type that GitHub cannot classify, so the terms are in the LICENSE file at the root of the repository and are not summarised in the README. ## Sources - [HelTecAutomation/Heltec_ESP32 on GitHub](https://github.com/HelTecAutomation/Heltec_ESP32) - [Issues](https://github.com/HelTecAutomation/Heltec_ESP32/issues) - [README](https://github.com/HelTecAutomation/Heltec_ESP32/blob/master/README.md) - [Releases](https://github.com/HelTecAutomation/Heltec_ESP32/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/heltecautomation-heltec-esp32