heltec_esp32_lora_v3

Heltec ESP32 LoRa v3

The unofficial library

Quick Reference

Introduction

There's this Chinese company named Heltec, and they make a cool little development board that has an Espressif ESP32S3 (which has WiFi and Bluetooth), a 128x64 pixel OLED display and an SX1262 863-928 MHz radio on it. It sells under different names on the internet, but internally they call it HTIT-WB32LA. (They have a 470-510 MHz version also, called HTIT-WB32LAF.) The hardware is cool, the software that comes with it is not so much my taste. There's multiple GitHub repositories, it's initailly unclear what is what, they use some radio stack of unknown origin, code-quality and documentation varies, some examples need tinkering and what could be a cool toy could easily become a very long weekend of frustration before things sort of work.

This library allows you to use that time to instead play with this cool board. The examples are tested, and this library assumes that for all things sub-GHz, you want to use the popular RadioLib.

As for the name: if I had to name it today, this library would be called "Heltec Unofficial", which is the name of the include file. I named it after one of the names of the first of the currently supported boards. Library names are hard to change, so the name is what it is.

[!NOTE]
Some larger changes have happened: among other things the library now depends on (which means it auto-installs) RadioLib and the display library. The name of the include file also changed from heltec.h to heltec_unofficial.h so that you can have it installed alongside the library made by heltec itself. Make sure you update existing code to reflect this change.

The great Heltec board confusion

First of all let's be clear what hardware we are talking about here. There is some level of general confusion when it comes to Heltec devices. They make a bewildering array of stuff, and it's not always clear (to me at least) what they call certain pieces of hardware and what specs this hardware has. This library is made to work with the devices pictured below. Their names all end in "v3".

ESP32-S3 processor

( 2.4 GHz WiFi, BT 5 LE, 512 MB SRAM )

8 MB SPI flash

USB-C, CP2102 USB serial chip

Semtech SX1262 sub-GHz transceiver

3.7V LiPo battery charging circuit

WiFi LoRa 32(V3) a.k.a.

HTIT-WB32LA a.k.a.

ESP32 LoRa v3

Wireless Stick(V3) a.k.a.

HTIT-WS_V3

Wireless Stick Lite(V3)

a.k.a. HTIT-WSL_V3

128 x 64 OLED

64 x 32 OLED

no display

No RF shielding

Metal shielding

Built-in Wifi antenna

LoRa antenna connector IPEX1.0

Built-in Wifi antenna

WiFi ant. conn. IPEX1.0 (right)

LoRa ant. conn. IPEX1.0 (left)

147 µA (button wakes) 24 µA (clock wakes)141 µA (button wakes) 24 µA (clock wakes)130 µA (button wakes) 17 µA (clock wakes)

This library is unlikely to work as is with any other devices, whether made by Heltec or by others. You may be able to modify it, or use ideas or whole chunks of code from it, but just know that this library is only known to work with the boards picture above. For purposes of clarity, I might speak about "the regular board", "the stick" and "the stick lite" to mean the supported devices.

Setting up

1. Install this library

Use the library manager to install this library. Find it by entering "heltec_esp32" in the library manager search box.

2. Add ESP32 URL to settings

https://espressif.github.io/arduino-esp32/package_esp32_index.json

to the additional board manager URL to the Settings of the Arduino IDE.

(Make sure this and any URLs that might be already there are sperated by commas. If you hit OK the IDE will then load the files needed.)

3. Install ESP32

Go to board manager and install "esp32 by Espressif Systems". At the time of writing this, the latest version is 2.0.16.

4. Select the board

Start Arduino IDE and from the board dropdown select "Select another board and port" and enter "heltec" in the search box. Select the board named "Heltec WiFi LoRa 32(V3) / Wireless shell(V3)" as in the image below. Do not use any of the other boards, even if they look right.

5. Stick or Stick Lite?

If your board is a Wireless Stick or Wireless Stick Lite, you must put #define HELTEC_WIRELESS_STICK or #define HELTEC_WIRELESS_STICK_LITE respectively in your code before #include or things will not work for you.

• If you have the Stick Lite, the code needs to skip anything related to a display, in case of the Stick, the display dimensions need to be set differently and the "external" power is turned on by default, as it feeds the display.

• Main symptom of things not working on the stick is jerky and slow serial output while you are printing to both (see below) as the device waits for SPI timeouts from an OLED display that doesn't have power.

Getting started

To use this library, in your sketches, #include . This will provide the display, radio and button instances. Then in your setup(), put heltec_setup() to initialize the serial port at 115.200 bps and initialize the display. In the loop() part of your sketch, put heltec_loop(). This will make sure the button is scanned, and provides the deep sleep "off" functionality if you set that up.

#include 

void setup() {
  heltec_setup();

  [...]
}

void loop() {
  heltec_loop();

  [...]
}

• If you #define HELTEC_NO_RADIO_INSTANCE and/or #define HELTEC_NO_DISPLAY_INSTANCE before #include , you get no instances of radio and/or display, so you can set these up manually. Note that the library then also doesn't turn things off at sleep, etc.
• If you would prefer these libraries not even be included, use #define NO_RADIOLIB and #define NO_DISPLAY respectively.

RadioLib

API documentation

Next to the radio examples in this library, all RadioLib examples that work with an SX1262 work here. Simply #include instead of RadioLib and remove any code that creates a radio instance, it already exists when you include this library.

• It might otherwise confuse you at some point: while Heltec wired the DIO1 line from the SX1262 to the ESP32 (as they should, it is the interrupt line), they labeled it in their pins_arduino.h (my board definitions have it as both) and much of their own software as DIO0. The SX1262 IO pins start at DIO1.
• If you place #define HELTEC_NO_RADIOLIB before #include , RadioLib will not be included and this library won't create a radio object. Handy if you are not using the radio and need the space in flash for something else or if you want to use another radio library or so.

Convenience macros

RADIOLIB() and RADIOLIB_OR_HALT()

This library provides convenience macros when calling RadioLib functions. It can be used for those functions that return a status code. When your code calls

RADIOLIB_OR_HALT(radio.setFrequency(866.3));

this gets translated into

  _radiolib_status = radio.setFrequency(866.3);
  Serial.print("[RadioLib] ");
  Serial.print("radio.setFrequency(866.3)");
  Serial.print(" returned ");
  Serial.print(_radiolib_status);
  Serial.print(" (");
  Serial.print(radiolib_result_string(_radiolib_status));
  Serial.println(")");
  if (_radiolib_status != RADIOLIB_ERR_NONE) {
    Serial.println("[RadioLib] Halted");
    while (true) {
        heltec_loop();
    }
  }

In other words, this saves a whole lot of typing if what you want is for RadioLib functions to be called and serial debug output to be generated. Calling RADIOLIB instead of RADIOLIB_OR_HALT does the same thing without the halting.

• The heltec_loop() part in RADIOLIB_OR_HALT makes sure that if you have set the PRG button to be the power button, it still works when execution is halted.
• _radiolib_status is an integer that the library provides and that your code can check afterwards to see what happened.
• radiolib_result_string() returns a textual representation (e.g. CHIP_NOT_FOUND) for a few of the most common errors or a URL to look up the others.

LoRaWAN

Using these Heltec chips, you can experiment with LoRaWAN networks such as The Things Network. If you create an account there and have a gateway somewhere nearby, you can send small binary messages that will show up at the designated server on the internet. You can make an account and use their servers to see your messages appear.

Because of the limited throughput (a few small messages every once in a while) LoRaWAN is really most suitable for sensors, meter readings and things like that. To use it with the Heltec boards, you'd probably want to make the device go to deep sleep between readings, so the battery would last a nice long time.

To speak LoRaWAN, you need to store some provisioning information such as identifiers and cryptographic keys. In addition to that, the RadioLib LoRaWAN code needs the user to hang on to some session state during long sleep to resume the same session. I wrote another library, called LoRaWAN_ESP32 to manage both the provisioning data and the session state in flash. Please refer to that library's README for more details.

If you install the LoRaWAN_ESP32 library, you can compile the example called LoRaWAN_TTN that comes with this library to see it in action. (That example is nearly identical to the example that comes with LaRaWAN_ESP32, just set up to have this library provide the radio instance.)

Display

API documentation

The tiny OLED display uses the same library that the original library from Heltec uses, except now the examples work so you don't have to figure out how to make things work.

heltec_display_power(bool on) can be used with true or false to turn the display on and off. hetlec_setup() turns it on.

There's the primary display library and there's an additinal UI library that allows for multiple frames. The display examples will show you how things work. The library, courtesy of ThingPulse, is well-written and well-documented. Check them out and buy their stuff.

This library used to include a fork of that library that had improved print functionality, but all my changes have been upstreamed, so we're back to depending on the original.

Printing to both Serial and display: both.print()

Instead of using print, println or printf on either Serial or display, you can also print to both. As the name implies, this prints the same thing on both devices. You'll find it used in many of this library's examples.

Button

API documentation

The user button marked 'PRG' on the regular board and 'USER' on the stick is handled by my own HotButton library that is automatically installed when you install this one. Since we have only one button it makes sense to be able to do as many different things with it as possible. It provides the generic button.isSingleClick() and button.isDoubleClick(), but it can do much more than that. I recommed having a quick look at its (short) documentation to see what it can do.

Remember to put heltec.loop() in theloop() of your sketch to make sure your button gets updated so you can use these functions.

Using it as the power button

If you hook up this board to power, and especially if you hook up a LiPo battery (see below), you'll notice there's no on/off switch. Luckily the ESP32 comes with a very low-power "deep sleep" mode where it draws so little current it can essentially be considered off. Since signals on GPIO pins can wake it back up, we can us