HELTEC WiFi LoRa 32 V4 Development Guide: Complete Setup, Arduino, PlatformIO & Meshtastic

Key Advantage: The V4's native USB-OTG support eliminates the need for a separate USB-to-UART bridge (CP2102), reducing power consumption and simplifying the bootloader process. The board can enter programming mode automatically or via the PRG/RST buttons.

 

Complete pinout diagram showing all 40 pins, antenna connectors, and interface locations

Additional Boards Manager URLs: https://resource.heltec.cn/download/package_heltec_esp32_index.json

Board: "HELTEC ESP32 Series Dev Boards" → "WiFi LoRa 32(V3)" Port: Select your COM port (Windows) or /dev/ttyACM* (Linux/Mac) USB CDC On Boot: "Enabled" (for serial output) Upload Mode: "USB-OTG-CDC (TinyUSB)"

Important: Select "WiFi LoRa 32(V3)" in the board menu for V4 boards. The V4 is pin-compatible and uses the same board definition. The framework will automatically detect and configure for V4 hardware.

  

[env:heltec_wifi_lora_32_V3] platform = espressif32 board = heltec_wifi_lora_32_V3 framework = arduino ; Build options board_build.mcu = esp32s3 board_build.f_cpu = 240000000L ; Upload options upload_protocol = esptool upload_speed = 921600 ; Monitor options monitor_speed = 115200 monitor_filters = esp32_exception_decoder ; Library dependencies lib_deps = heltecautomation/Heltec ESP32 Dev-Boards@^1.1.2 olikraus/U8g2@^2.35.8 sandeepmistry/LoRa@^0.8.0 ; Build flags for V4 build_flags = -D ARDUINO_USB_CDC_ON_BOOT=1 -D CONFIG_USB_OTG_SUPPORTED=1

project/ ├── include/ # Header files ├── lib/ # Custom libraries ├── src/ │ └── main.cpp # Main application ├── test/ # Unit tests ├── platformio.ini # Project configuration └── README.md

PlatformIO Advantages: Automatic library dependency resolution, integrated debugging with JTAG probes, unit testing framework, and seamless CI/CD integration for production deployments.

   

#include "Arduino.h" #include "U8x8lib.h" #include "Wire.h" // OLED display pins for WiFi LoRa 32 V4 #define OLED_SDA 17 #define OLED_SCL 18 #define OLED_RST 21 // Initialize OLED display (SSD1306 128x64) U8X8_SSD1306_128X64_NONAME_SW_I2C u8x8(OLED_SCL, OLED_SDA, OLED_RST); void setup() { // Initialize serial for debugging Serial.begin(115200); delay(1000); Serial.println("HELTEC WiFi LoRa 32 V4 Starting..."); // Initialize OLED display u8x8.begin(); u8x8.setPowerSave(0); u8x8.setFlipMode(1); // Flip display 180 degrees // Clear display and set font u8x8.clearDisplay(); u8x8.setFont(u8x8_font_chroma48medium8_r); // Display welcome message u8x8.setCursor(0, 0); u8x8.print("HELTEC V4"); u8x8.setCursor(0, 2); u8x8.print("WiFi LoRa 32"); u8x8.setCursor(0, 4); u8x8.print("ESP32-S3 + SX1262"); u8x8.setCursor(0, 6); u8x8.print("Ready!"); Serial.println("Setup complete!"); } void loop() { // Blink the onboard RGB LED (GPIO38) static uint8_t color = 0; // Simple color cycle switch(color) { case 0: neopixelWrite(38, 255, 0, 0); break; // Red case 1: neopixelWrite(38, 0, 255, 0); break; // Green case 2: neopixelWrite(38, 0, 0, 255); break; // Blue } color = (color + 1) % 3; delay(1000); }

Auto-Upload: The V4 supports automatic bootloader entry. If upload fails, manually enter bootloader: Hold PRG button, press RST once, release PRG, then retry upload.

  

#include "LoRa.h" #include "U8x8lib.h" // Pin definitions for HELTEC V4 #define LORA_NSS 8 #define LORA_RESET 12 #define LORA_DIO1 14 #define LORA_BUSY 13 #define LORA_SCK 9 #define LORA_MISO 11 #define LORA_MOSI 10 // OLED setup U8X8_SSD1306_128X64_NONAME_SW_I2C u8x8(18, 17, 21); int counter = 0; void setup() { Serial.begin(115200); while (!Serial); // Initialize OLED u8x8.begin(); u8x8.setFlipMode(1); u8x8.setFont(u8x8_font_chroma48medium8_r); u8x8.clearDisplay(); u8x8.setCursor(0, 0); u8x8.print("LoRa TX"); // Initialize LoRa LoRa.setPins(LORA_NSS, LORA_RESET, LORA_DIO1); // Frequency: 868E6 for EU, 915E6 for US, 433E6 for Asia if (!LoRa.begin(868E6)) { Serial.println("LoRa init failed!"); u8x8.setCursor(0, 2); u8x8.print("Init Failed!"); while (1); } // Configure LoRa parameters LoRa.setTxPower(20); // TX power: 2-20 dBm LoRa.setSpreadingFactor(7); // SF: 6-12 LoRa.setSignalBandwidth(125E3); // BW: 125kHz LoRa.setCodingRate4(5); // CR: 4/5 Serial.println("LoRa TX Ready"); u8x8.setCursor(0, 2); u8x8.print("Ready 868MHz"); } void loop() { Serial.print("Sending packet: "); Serial.println(counter); // Update display u8x8.setCursor(0, 4); u8x8.print("Packet: "); u8x8.print(counter); u8x8.print(" "); // Send packet LoRa.beginPacket(); LoRa.print("Hello #"); LoRa.print(counter); LoRa.print(" from V4!"); LoRa.endPacket(); // Visual feedback neopixelWrite(38, 0, 255, 0); // Green flash delay(100); neopixelWrite(38, 0, 0, 0); // Off counter++; delay(5000); // Send every 5 seconds }

#include "LoRa.h" #include "U8x8lib.h" // Pin definitions (same as transmitter) #define LORA_NSS 8 #define LORA_RESET 12 #define LORA_DIO1 14 #define LORA_BUSY 13 U8X8_SSD1306_128X64_NONAME_SW_I2C u8x8(18, 17, 21); void setup() { Serial.begin(115200); while (!Serial); // Initialize OLED u8x8.begin(); u8x8.setFlipMode(1); u8x8.setFont(u8x8_font_chroma48medium8_r); u8x8.clearDisplay(); u8x8.setCursor(0, 0); u8x8.print("LoRa RX"); // Initialize LoRa LoRa.setPins(LORA_NSS, LORA_RESET, LORA_DIO1); if (!LoRa.begin(868E6)) { Serial.println("LoRa init failed!"); u8x8.setCursor(0, 2); u8x8.print("Init Failed!"); while (1); } // Match transmitter settings LoRa.setSpreadingFactor(7); LoRa.setSignalBandwidth(125E3); LoRa.setCodingRate4(5); Serial.println("LoRa RX Ready"); u8x8.setCursor(0, 2); u8x8.print("Listening..."); } void loop() { // Check for packet int packetSize = LoRa.parsePacket(); if (packetSize) { // Received packet Serial.print("Received packet: '"); String message = ""; while (LoRa.available()) { message += (char)LoRa.read(); } Serial.print(message); Serial.print("' with RSSI "); Serial.println(LoRa.packetRssi()); // Update display u8x8.clearLine(4); u8x8.clearLine(5); u8x8.setCursor(0, 4); // Truncate message if too long if (message.length() > 16) { message = message.substring(0, 16); } u8x8.print(message); u8x8.setCursor(0, 6); u8x8.print("RSSI: "); u8x8.print(LoRa.packetRssi()); u8x8.print(" dBm"); // Visual feedback neopixelWrite(38, 0, 0, 255); // Blue flash delay(200); neopixelWrite(38, 0, 0, 0); } }

#include "LoRa.h" #include "driver/rtc_io.h" #define LORA_NSS 8 #define LORA_RESET 12 #define LORA_DIO1 14 RTC_DATA_ATTR int bootCount = 0; void setup() { Serial.begin(115200); bootCount++; Serial.println("Boot number: " + String(bootCount)); // Initialize LoRa LoRa.setPins(LORA_NSS, LORA_RESET, LORA_DIO1); if (!LoRa.begin(868E6)) { Serial.println("LoRa init failed!"); esp_deep_sleep_start(); } // Send sensor data LoRa.beginPacket(); LoRa.print("Boot:"); LoRa.print(bootCount); LoRa.print(",VBAT:"); LoRa.print(analogReadMilliVolts(1) * 2 / 1000.0); // Battery voltage LoRa.endPacket(); Serial.println("Packet sent, going to sleep..."); // Configure wake-up timer (60 seconds) esp_sleep_enable_timer_wakeup(60 * 1000000ULL); // Enter deep sleep esp_deep_sleep_start(); } void loop() { // Never reached due to deep sleep }

Range Optimization: For maximum range, use SF12, 125kHz bandwidth, and 20dBm TX power. For maximum data rate, use SF7 and 250kHz bandwidth. Always respect local regulations regarding duty cycles and maximum power.

  

#include "loramac.h" #include "LoRaWan.h" // Device credentials - replace with your values const char *deviceEui = "XXXXXXXXXXXXXXXX"; // 16 hex chars const char *appEui = "XXXXXXXXXXXXXXXX"; // 16 hex chars const char *appKey = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; // 32 hex chars // LoRaWAN configuration #define LORA_BAND EU868 // EU868, US915, AU915, AS923 #define LORA_CLASS CLASS_A // A, B, or C void setup() { Serial.begin(115200); delay(2000); Serial.println("HELTEC V4 LoRaWAN OTAA"); // Initialize LoRaWAN LoRaWan.init(LORA_BAND, LORA_CLASS, JOIN_OTAA); // Set device credentials LoRaWan.setDeviceEui(deviceEui); LoRaWan.setAppEui(appEui); LoRaWan.setAppKey(appKey); // Join network Serial.println("Joining network..."); if (LoRaWan.join()) { Serial.println("Network joined!"); // Configure data rate (0-5 for EU868) LoRaWan.setDataRate(3); // DR3: SF9, 125kHz } else { Serial.println("Join failed!"); } } void loop() { if (LoRaWan.isJoined()) { // Prepare payload uint8_t payload[4]; // Example: Send temperature and battery int16_t temperature = 250; // 25.0°C (x10 for precision) uint16_t battery = analogReadMilliVolts(1); payload[0] = temperature >> 8; payload[1] = temperature & 0xFF; payload[2] = battery >> 8; payload[3] = battery & 0xFF; // Send uplink (port 1, unconfirmed) Serial.println("Sending uplink..."); if (LoRaWan.send(payload, sizeof(payload), 1, false)) { Serial.println("Uplink sent!"); } else { Serial.println("Uplink failed!"); } // Check for downlink uint8_t downlink[64]; int downlinkLen = LoRaWan.receive(downlink, sizeof(downlink)); if (downlinkLen > 0) { Serial.print("Downlink received: "); for (int i = 0; i < downlinkLen; i++) { Serial.printf("%02X ", downlink[i]); } Serial.println(); } } else { Serial.println("Not joined, retrying..."); LoRaWan.join(); } // Wait for next transmission (respect duty cycle) delay(30000); // 30 seconds }

License Required: Heltec's LoRaWAN library requires a free license tied to your ESP32's Chip ID. Query your license at resource.heltec.cn and add it to your code before calling LoRaWan.init().

// Replace with your ABP credentials const char *devAddr = "XXXXXXXX"; // 8 hex chars const char *nwkSKey = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; // 32 hex chars const char *appSKey = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; // 32 hex chars void setup() { LoRaWan.init(LORA_BAND, LORA_CLASS, JOIN_ABP); LoRaWan.setDevAddr(devAddr); LoRaWan.setNwkSKey(nwkSKey); LoRaWan.setAppSKey(appSKey); // ABP doesn't require join - ready immediately Serial.println("ABP mode - ready to send"); }

# Install Meshtastic CLI pip install meshtastic # Connect and configure meshtastic --info # Show node info meshtastic --set owner "MyNode" # Set node name meshtastic --set region EU_868 # Set region meshtastic --set is_router true # Enable router mode # View messages meshtastic --listen

V4 Advantages for Meshtastic: The 28dBm TX power provides exceptional range compared to standard 20-22dBm devices. The solar input and battery management make it ideal for permanent outdoor router installations.

  

No serial output in monitor

LoRa transmission not working

OLED display is blank

High power consumption in sleep mode

What is the maximum range of HELTEC WiFi LoRa 32 V4?

Can I use V3 code on the V4 board?

What battery capacity do I need?

Is the V4 compatible with Meshtastic?

Do I need a license to use LoRaWAN?

What GPS modules work with the V4?

How do I update the firmware?

Can I remove the OLED display?