Heltec board migration from V2 to V3

#1

This is a write up of my experience migrating a project from a Heltec Wifi LoRa V2 board to the new V3 board.

Platform definitions

First I changed in platformio.ini file:

board = heltec_wifi_lora_32_V3

This did not work, missing board definition. I tracked down what it would take to support the heltec V3 boards in platformio. It required changes to 3 repos:

  • platformio/platform-espressif32: needs to contain board definitions. There was a pending PR which was blocked on an pin definition issue which I fixed here. :white_check_mark:
  • espressif/arduino-esp32: contains pin definitions for each board. This repo did have entries for some of the heltec V3 boards, but the pin definitions were wrong or missing in some cases. I fixed them here but there is a pending followup PR which adds some missing pins here needed to make the heltec helper library work.
  • HelTecAutomation/Heltec_ESP32: contains heltec helper library which can be used to configure and access things like the screen, wifi, and lora. Needs to be updated to support V3 boards. I have a pending a PR for that here.

Until these PRs to get merged, you can point platformio.ini to my forks of these repos:

[env:ap_device]
platform = espressif32
board = heltec_wifi_lora_32_V3
framework = arduino
platform_packages = framework-arduinoespressif32 @ https://github.com/platypii/arduino-esp32.git
lib_deps = https://github.com/platypii/Heltec_ESP32.git

Note: I will delete these repos when the upstream PRs are merged.

Moving away from heltec.h

The heltec helper library does not support the latest V3 boards. I made a PR to the heltec helper repo which fixes the basic functionality, but it has been pending for 2 weeks with no reviews. Hopefully this will get updated at some point. But I decided to move away from the heltec library and towards using 3rd party libraries directly, which will be easier to update in the future.

The heltec library contains an outdated copy-and-paste of two libraries: SSD1306Wire and arduino-LoRa. So my first goal was to use these upstream libraries.

In platformio.ini change lib_deps from the heltec library to:

lib_deps =
    sandeepmistry/LoRa
    thingpulse/ESP8266 and ESP32 OLED driver for SSD1306 displays

Some additional minor changes to my code were required:

  • Remove Heltec.init()
  • Change #include "heltec.h" to #include "LoRa.h" and #include "SSD1306Wire.h"
  • Remove 2nd parameter from LoRa.begin()
  • Define display SSD1306Wire display(0x3c, SDA_OLED, SCL_OLED);
  • Replace Heltec.display-> with display.
  • Add a reset before screen initialization. Copied from the heltec library, and was necessary to make the screen work:
pinMode(RST_OLED, OUTPUT);
digitalWrite(RST_OLED, LOW);
delay(20);
digitalWrite(RST_OLED, HIGH);

See commit here.

With these changes I was able to use the V2 boards but without using the heltec library.

V3 board

With my changes, the screen, bluetooth, and wifi all worked on the V3 heltec board. LoRa did not. I did some searching, and people recommended using RadioLib for its support of the new SX1262 lora chip. RadioLib has a very different API than arduino-LoRa used in the heltec library. It took some fighting to find the right config settings to match the arduino-LoRa settings but it was possible to do while still testing on the V2 boards.

When moving to the V3 board, the LoRa chip was changed from the SX1276 to the SX1262. I had to change the initialization from:

SX1276 radio = new Module(SS, 26, RST_LoRa, DIO0);

To:

SX1262 radio = new Module(SS, DIO0, RST_LoRa, BUSY_LoRa);

This got the radio to work on the V3. Hooray! However one last issue remained. I could not get the V2 to talk to the V3 boards over LoRa.

Some googling showed that there were changes made to the codeword parameter.
https://blog.classycode.com/lora-sync-word-compatibility-between-sx127x-and-sx126x-460324d1787a

I pulled out my SDR and tried to see if it was a tuning issue, or if there was some obvious difference in how the radios were transmitting. There was a noticable difference in transmission length, even for the same packet data. I don’t know why.

v2v3
v2v3.png350Ă—526 89.9 KB

But my project does not depend on V2 talking to V3 so although I would like to solve this issue, it’s not critical for my project.

Hope that this write up helps someone. And if you work at Heltec, approve and merge my PR please. :slightly_smiling_face:

4 Likes
Heltec LoRa 32 V3 nightmares
Supporting PlatformIo on ESP32 wifi v3 board
#2

Thank you for your support. We will merge after verification.

1 Like
#3

Thanks for all the info and the repo that i’m using. i have a question, did you try to use an I2C sensor? like a BME280 or any other, because i tried and it doesn’t work. I tried a simple I2C scanner sketch and tried with different pair of pin (like 41-42, 6-7, 5,4 of course using Wire1.begin(41,42) for example) but nothing, no devices is showing. if i use Wire instead of Wire1 and reset the oled i will see the oled i2c address, but i need to use the other I2C because of the pins. Do you have some ideas? Thanks

1 Like
#4

Same questions here!

#5

Sorry I haven’t tried using I2C

#6

How do you map from the programmatic pin numbers to the labels on the boards? Heltec does not have any information on those pin mappings. For example, in your file commit for the wifi v3 board, you set I2C SDA=21 and SCL=22. So what physical pins are those mapping to on the actual board? The documentation only has J2/J3 bank numbers but no framework pin designation. The GPIO numbers don’t match either (consider that GPIO21 and label 21 map to the OLED RST, and there is no pin 22 on the board).

#7

I had to look at the schematic drawing to find the OLED pins:

OLED SDA: 17
OLED SCL: 18
OLED RST: 21

1 Like
#8

Update: thanks to the merging of some PRs [1] [2] [3], and the release of some framework packages [4] [5], the transition path from V2 to V3 has improved.

If you have a V2 project using PlatformIO that looks like:

[env:ap_device]
platform = espressif32
board = heltec_wifi_lora_32_V2
framework = arduino
lib_deps = Heltec ESP32 Dev-Boards

The first step of migration is now simply changing the board to V3:

board = heltec_wifi_lora_32_V3

The last remaining issue is that Heltec did merge my PR [3] that adds support for the V3 boards. But they have not yet made a new 1.1.2 release of the heltec library containing the fixes. @Aaron @Quency-D

So until a new release is made, you’ll need to change the heltec helper library from the “official” release to point to the github latest:

lib_deps = https://github.com/HelTecAutomation/Heltec_ESP32.git

With those two changes, most V2 projects should compile and work (except LoRa)

1 Like