Heltec WiFi LoRa 32 – ESP32 with OLED and SX1278

Heltec WiFi Lora 32

Some initial information to get up and running with the Heltec Wifi Lora 32 Kit Module.

These are available from the Heltec store on AliExpress. Like a lot of these devices this is pretty easy to set up. Once you know which libraries and pin numbers to use! If you’ve not set up the board in the Arduino IDE yet there’s instructions here.

For an initial test run to see if the LoRa part is functioning you’ll need another device to transmit or receive Lora signals. For the tests below I’m using Ai-Thinker RA-02 with an Arduino UNO as described in this post – UNO with Ai-Thinker RA-02 SX1278 LoRa Module to send packets.

There’s a download available for this Heltec device but it’s probably easier to use one of the LoRa libraries that are available through the Arduino IDE library manager. Just search for an install this one:

Lora Library Screen Capture

To make this library work with the Heltec LoRa device you need to define some pins:
#define SS 18
#define RST 14
#define DI0 26

Add a couple of lines to the setup():
SPI.begin(5, 19, 27, 18);
LoRa.setPins(SS, RST, DI0);

and change the baud rate:  Serial.begin(115200); and LoRa frequency: LoRa.begin(433E6)

Or just copy and paste the code below 😉

#include <SPI.h>
#include <LoRa.h>

// WIFI_LoRa_32 ports
// GPIO5  -- SX1278's SCK
// GPIO19 -- SX1278's MISO
// GPIO27 -- SX1278's MOSI
// GPIO18 -- SX1278's CS
// GPIO14 -- SX1278's RESET
// GPIO26 -- SX1278's IRQ(Interrupt Request)

#define SS      18
#define RST     14
#define DI0     26

void setup() {
  
  SPI.begin(5, 19, 27, 18);
  LoRa.setPins(SS, RST, DI0);
  
  Serial.begin(115200);
  while (!Serial);

  Serial.println("LoRa Receiver");

  if (!LoRa.begin(433E6)) {
    Serial.println("Starting LoRa failed!");
    while (1);
  }
}

void loop() {
  // try to parse packet
  int packetSize = LoRa.parsePacket();
  if (packetSize) {
    // received a packet
    Serial.print("Received packet '");

    // read packet
    while (LoRa.available()) {
      Serial.print((char)LoRa.read());
    }

    // print RSSI of packet
    Serial.print("' with RSSI ");
    Serial.println(LoRa.packetRssi());
  }
}

Depending what you are sending you’ll see something like this in the serial monitor:

Received packet ’79’ with RSSI -68
Received packet ’80’ with RSSI -68
Received packet ’81’ with RSSI -58
Received packet ’82’ with RSSI -58
Received packet ’83’ with RSSI -68
Received packet ’84’ with RSSI -68
Received packet ’85’ with RSSI -68
Received packet ’86’ with RSSI -68


Viewing the received packets on the built-in OLED display

I’ll explain in more detail later but if you want to see the LoRa data on the built-in screen as well as the serial console you can just copy and paste the code below. You’ll need to install the U8g2 (https://github.com/olikraus/u8g2) library. This can be found in the Arduino IDE library manager.  Open Sketch > Include Library > Manage Libraries and search for and then install U8g2.

#include <U8x8lib.h>
#include <LoRa.h>

String receivedText;
String receivedRssi;

// WIFI_LoRa_32 ports
// GPIO5  -- SX1278's SCK
// GPIO19 -- SX1278's MISO
// GPIO27 -- SX1278's MOSI
// GPIO18 -- SX1278's CS
// GPIO14 -- SX1278's RESET
// GPIO26 -- SX1278's IRQ(Interrupt Request)

#define SS      18
#define RST     14
#define DI0     26
#define BAND    433E6

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

void setup() {

  SPI.begin(5, 19, 27, 18);
  LoRa.setPins(SS, RST, DI0);

  Serial.begin(115200);
  while (!Serial); //if just the the basic function, must connect to a computer
  delay(1000);

  u8x8.begin();
  u8x8.setFont(u8x8_font_chroma48medium8_r);

  Serial.println("LoRa Receiver");
  u8x8.drawString(0, 1, "LoRa Receiver");

  if (!LoRa.begin(BAND)) {
    Serial.println("Starting LoRa failed!");
    u8x8.drawString(0, 1, "Starting LoRa failed!");
    while (1);
  }
}

void loop() {

  // try to parse packet
  int packetSize = LoRa.parsePacket();
  if (packetSize) {
    // received a packet
    Serial.print("Received packet '");
    u8x8.drawString(0, 4, "PacketID");

    // read packet
    while (LoRa.available()) {
      receivedText = (char)LoRa.read();
      Serial.print(receivedText);
      char currentid[64];
      receivedText.toCharArray(currentid, 64);
      u8x8.drawString(9, 4, currentid);
    }

    // print RSSI of packet
    Serial.print("' with RSSI ");
    Serial.println(LoRa.packetRssi());
    u8x8.drawString(0, 5, "PacketRS");
    receivedRssi = LoRa.packetRssi();
    char currentrs[64];
    receivedRssi.toCharArray(currentrs, 64);
    u8x8.drawString(9, 5, currentrs);
  }

}

This code is just to test everything works. More  needs to be done to properly use LoRa within the legal guidelines etc. If you are interested in LoraWAN and The Things Network, I’ve added a new tutorial:  Heltec Lora32 LoraWan Node on The Things Network

32 Replies to “Heltec WiFi LoRa 32 – ESP32 with OLED and SX1278”

  1. Atilio says:

    Hi! Thank for this post. It was VERY helpful to me. I received my modules 3 days ago.
    I got them up and running based on your instructions.
    I set one as a Sender and another as a Receiver.
    The sender has an ultrasonic sensor attached to it and sends the measured distance to the Receiver using LoRa. Everything works fine.
    Now I’m trying to connect simultaneously the LoRa receiver through WiFi to my router using the ESP32 and send a MQTT message with the value of the measure to MQTTCloud. The question is whether this module can act as a gateway or not.
    Have you tried this?
    Thanks again,
    Atilio

    1. WordBot says:

      I’m not sure which module this was for but you can connect to your router with something like the script below. The HTTPClient.h library does all the magic.

      #include "WiFi.h"
      #include <U8x8lib.h>
      #include <WiFi.h>
      #include <HTTPClient.h>
      
      #include <LoRa.h>
      
      const char* ssid = "YOURSSID";
      const char* password =  "YOURWIFIPASS";
      
      String receivedText;
      String receivedRssi;
      
      #define SS      18
      #define RST     14
      #define DI0     26
      #define BAND    433E6
      
      void setup() {
        Serial.begin(115200);
        while (!Serial); //if just the the basic function, must connect to a computer
        delay(1000);
      
        WiFi.begin(ssid, password);
      
        while (WiFi.status() != WL_CONNECTED) { //Check for the connection
          delay(1000);
          Serial.println("Connecting to WiFi..");
        }
      
        Serial.println("Connected to the WiFi network");
      
        Serial.println("LoRa Receiver");
      
        SPI.begin(5, 19, 27, 18);
        LoRa.setPins(SS, RST, DI0);
      
        if (!LoRa.begin(BAND)) {
          Serial.println("Starting LoRa failed!");
          while (1);
        }
      }
      
      void loop() {
      
        // try to parse packet
        int packetSize = LoRa.parsePacket();
        if (packetSize) {
          // received a packet
          Serial.print("Received packet '");
      
          // read packet
          while (LoRa.available()) {
            Serial.print((char)LoRa.read());
            receivedText = LoRa.read();
          }
      
          // print RSSI of packet
          Serial.print("' with RSSI ");
          Serial.println(LoRa.packetRssi());
          receivedRssi = LoRa.packetRssi();
      
      
      
      
          if (WiFi.status() == WL_CONNECTED) { //Check WiFi connection status
      
            HTTPClient http;
      
            String thisUrl;
            thisUrl = "http://YOURURL/TESTDIR/i-am-receiving.php?tx=";
            thisUrl.concat(receivedText);
            thisUrl.concat("&rssi=");
            thisUrl.concat(receivedRssi);
      
         
            http.begin(thisUrl); //Specify destination for HTTP request
      
            int httpCode = http.GET();
      
            if (httpCode > 0) {
              String payload = http.getString();
              Serial.println(httpCode);
              Serial.println(payload);
      
            } else {
              Serial.print("Error on sending POST: ");
            }
            http.end();  //Free resources
          } else {
            Serial.println("Error in WiFi connection");
          }
      
      
      
      
        }
      }
      
  2. Atilio says:

    Hi WordBot. Thanks for your reply and the code example.
    I have exactly the same board than the one on the above picture (Heltec ESP32 WiFi LoRa). Mine is 868-915Mhz.
    I’m newbie at LoRa and LoRaWAN.
    After more reading, I guess that what I should be doing is LoRaWAN instead of plain LoRa.
    I found that I should be using LMIC.h library in my LoRa Node device code.
    (https://github.com/matthijskooijman/arduino-lmic)
    I started playing with ttn-abp example (its a little bit complex for me right now… but i’ll keep trying)
    Any advice on this path?
    Thanks again.

    1. WordBot says:

      I read this on the difference between LoRa and LoRaWAN – https://www.quora.com/What-is-the-difference-between-Lora-and-LoraWan.

      For my tests I just needed to send GPS coordinates from my location via LoRa to one of the
      Heltec devices above which receives and then sends the data to a webserver via a WiFi connection using a GET request. I can then use my phone to look at a web page on the webserver to check it all functions.

      I need to do some more reading on using encryption and certain frequencies so my location data is only available to me. Maybe that’s where LoRaWAN comes in.

    2. Snowglobe says:

      @Atilio
      I’m in the same situation than you. Heltec ESP32 Wifi Lora 868.
      I registered on thethingsnetwork.org and like you try to connect with lmic.h library with ttn-abp.ino
      But…not work for me. if you have good return and a good how-to, please, share 😉

      1. WordBot says:

        I’ve just added a new tutorial – https://robotzero.one/heltec-lora32-lorawan-node/

  3. Antonio says:

    @Snowglobe and @Atilio
    I´m also trying to run Heltec ESP32 Wifi Lora 868 within LoRaWAN…..did you come up with the workaround yet?
    Thanks

    1. WordBot says:

      I’ve just added a new tutorial – https://robotzero.one/heltec-lora32-lorawan-node/

  4. Alex says:

    Hello, my Heltec ESP32 Wifi Lora 868 is stuck with a orange led blinking.
    I can upload code but in the end I get the message
    Leaving…
    Hard resetting…
    and nothing happens.

    Tks

    1. WordBot says:

      Can you try with the Blink LED example? File>Examples>1)Basic>Blink
      You should see the white LED blink on and off. I see the same message in the Arduino IDE for this but the example works.

  5. Andrew says:

    As i can see from datasheet SX1278 supports OOK tx and rx mode, but i haven’t found the right way how to do this. Are there any sample sketch how this can be done?

  6. Steve Riley says:

    Thanks guys, best info around for Heltec Wifi LoRa 32.
    Much appreciated, hope to get more done with this nice bit of kit.
    Thanks WordBot for example, yes it saved me loads of time.
    Enjoy the coffee, you deserve it.

    1. WordBot says:

      Cool, thanks!

  7. Vince says:

    For those asking, depending of your local settings, you have to add more configuration :

    #define BAND 868100000

    […]

    if (!LoRa.begin(BAND)) {
    Serial.println(“Starting LoRa failed!”);
    u8x8.drawString(0, 1, “Starting LoRa failed!”);
    while (1);
    }

    LoRa.setSpreadingFactor(12);
    LoRa.setCodingRate4(5);
    LoRa.setSignalBandwidth(125E3);
    LoRa.setPreambleLength(8);
    LoRa.enableCrc();
    LoRa.setSyncWord(0x34);
    }

  8. Meghana says:

    I have Done Everything as you have said above . Im using ESP32 Heltec Lora Module .Since In europe I changed the Frequency to 868E6 and I need to get RSSI value of the Signal coming from the Multisensor Avelon Miromico and get RSSI value on the Serial Monitor . But after pressing “Hard Resetting via RTS pin….. ” I´m not Receiving anything on the Serial Monitor. There are no errors while Compiling as well and While Uploading as well. May I please know where I might have been going wrong ..?????

  9. WordBot says:

    Hi, Is there nothing at all in the serial monitor? Have you set the baud rate in the serial monitor to 115200?

  10. John relph says:

    Hi, thanks to your artical I have got my ,TTGO LoRa ESP32 with display (2 off) , sending and receiving, but the receiving display only shows a single digit 0 to 9 repeatedly after PacketID, while the serial monitor shows the correct reading with 10 & 100s etc,
    Any help would be appreciated.

    1. WordBot says:

      I’ve just tested and it’s the same here. I can’t work out why it just shows the ultimate digit.
      If I try
      Serial.print(currentid);
      above
      u8x8.drawString(9, 4, currentid);
      it prints the whole message in the serial port so I can’t see why the graphics library isn’t showing the whole string on the OLED

    2. WordBot says:

      I tried a different way and the same result. I don’t understand it.

      while (LoRa.available()) {
      receivedText = (char)LoRa.read();
      Serial.print(receivedText);
      //char currentid[64];
      //receivedText.toCharArray(currentid, 64);
      //u8x8.drawString(9, 4, currentid);
      u8x8.setCursor(9, 4);
      u8x8.print(receivedText);
      }

  11. PD says:

    When I run code its showing error : Lora.h: No such file or directory .
    What should I do?

    Thanks
    PD

    1. WordBot says:

      Did you install the Lora library? Check near the top of the tutorial.

  12. Jeffrey Groberman says:

    Hi:
    I Hope you can hep me. I’ve been trying to convert your program to receive data I’m sending from a Ra-o2 unit sending data from an ultrasonic unit. By using line Serial.println(LoRa.packetRssi()); I get a nice result on the Serial Monitor. Great!
    But no matter what I do I can’t get the read out of the packet on the OLED. It must be a string or char problem. I get the error:
    invalid conversion from ‘char’ to ‘const char*’ [-fpermissive]
    I’ve tried every permutation I can think of. Can’t get it to display the packet on the OLED.
    Can you help?
    Jeff

    1. WordBot says:

      Hi, in the loop below. If you change the print to println what do you see?
      while (LoRa.available()) {
      receivedText = (char)LoRa.read();
      Serial.print(receivedText);
      char currentid[64];
      receivedText.toCharArray(currentid, 64);
      u8x8.drawString(9, 4, currentid);
      }

  13. Jeffrey Groberman says:

    Hi I assume you mean what I see on Serial Monitor;
    With simply print I see:
    Received packet ’21’ with RSSI -72
    (with the Received packet being the distance from the ultrasonic Transmitter)
    changing it to println I see:
    0
    With RSSI -71
    Received packet ‘2
    1
    ‘ with RSSI -90Received packet ‘2

    on the OLED
    LoRa Receiver
    Packet ID 1 (althernating with0)
    Packet RS -71

    No where on the OLED do I see the Received packet data I see on the Serial Monitor. I need to get that data (Received Packet) displayed on the OLED.

    Thanks
    Jeff

    1. WordBot says:

      It’s something to do with how the text is created. I think LoRa.read is reading one character at a time (I’m not sure how it does this) for each loop of the while LoRa.available. So somehow you need to put all the received characters into a string. Something like below although I don’t think this will work because char currentid[64]; receivedText.toCharArray(currentid, 64); will just over-write it each time.

      // read packet
      while (LoRa.available()) {
      receivedText = (char)LoRa.read();
      Serial.print(receivedText);
      char currentid[64];
      receivedText.toCharArray(currentid, 64);
      }
      u8x8.drawString(9, 4, currentid);

  14. Jesselle Huerta says:

    Hi WordBot. I hope you can help me. I have here a HELTEC ESP32 LoRa v2 (863-928), I connected it to the DHT11 sensor but when I open the serial monitor it says that “Failed to read from DHT sensor”. What does it mean?

    1. WordBot says:

      Hi, Sounds like it’s not wired up correctly. Might be a problem with the pins you used.

  15. Marcus says:

    HI. Very useful. I would like to know what is the maximum distance did you achive for communication, using the provided antennas.

    1. WordBot says:

      Hi, I don’t remember but like any radio communication there’s lots of factors that affect it.

  16. marcos says:

    Hi. seems a bit late from 2017. I would like to know what range did you achieve at most with a pair of these Heltec lora?
    Thanks

    1. WordBot says:

      Hi I did a little test today using https://meshtastic.org/ v2.1.10 Alpha with two V2 and the Android App. In my village without line of site it seemed OK about 250m. So far with line of site I can send messages at 1.3km but I’m pretty sure I can get better than that. I might test again later.

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