Skip to content
Heltec Wireless Tracker Heltec Wireless Tracker

Frequently Asked Questions

Bootloader & Programming

Section titled “Bootloader & Programming”

How do I enter boot mode manually?

Section titled “How do I enter boot mode manually?”

The Wireless Tracker uses ESP32-S3’s internal USB, which may fail to enter bootloader mode in certain situations. To manually enter boot mode:

Device not connected:

  1. Press and hold the USER button
  2. Connect the USB cable
  3. Release USER button

Device already connected:

  1. Hold USER button
  2. Press RESET button
  3. Release RESET button
  4. Release USER button

Why can’t I upload code?

Section titled “Why can’t I upload code?”

Common causes:

  1. Wrong board selected in IDE
  2. Device not in bootloader mode
  3. Serial port driver issues
  4. Another program has the port open

Solutions:

  1. Select “Heltec Wireless Tracker” in board manager
  2. Use manual boot mode entry (see above)
  3. Install CP210x or CH340 drivers if needed
  4. Close serial monitor before uploading

Hardware Versions

Section titled “Hardware Versions”

What are the key differences between V1.0 and V1.1?

Section titled “What are the key differences between V1.0 and V1.1?”
FeatureV1.0V1.1
GNSS PowerShared railDedicated LDO
GNSS ControlAlways onGPIO3 (HIGH = enabled)
Power IsolationLimitedImproved
Sleep Current~25 µA~15 µA

How do I identify my hardware version?

Section titled “How do I identify my hardware version?”
  1. Physical marking: Look for version marking on PCB near USB connector
  2. Programmatic detection: V1.1 has GNSS tied to GPIO3 control
// Simple test - if GNSS works after this, it's V1.1
pinMode(3, OUTPUT);
digitalWrite(3, HIGH);

Meshtastic

Section titled “Meshtastic”

Why isn’t Meshtastic firmware working on V1.1?

Section titled “Why isn’t Meshtastic firmware working on V1.1?”

The V1.1 hardware changed the GNSS power control pin to GPIO3. Older Meshtastic firmware didn’t know about this change.

Solution:

  • Use Meshtastic 2.2.17 Beta or later (auto-detects version)
  • Or use temporary Heltec firmware: device-install.bat -f firmware.factory.bin

Device shows “No GPS” in Meshtastic

Section titled “Device shows “No GPS” in Meshtastic”
  1. V1.1 hardware: Ensure you’re using compatible firmware
  2. Antenna: Check GNSS antenna is connected (IPEX connector)
  3. Location: Move outdoors with clear sky view
  4. Cold start: Allow 30-60 seconds for initial fix

Display Issues

Section titled “Display Issues”

Why is my screen not displaying?

Section titled “Why is my screen not displaying?”

When running LoRa/LoRaWAN code:

  1. Check serial output for errors
  2. Press RST button
  3. Verify device activation via licensing docs

When running Meshtastic:

  1. Confirm correct firmware version for your hardware
  2. Check display settings in Meshtastic app
  3. Verify backlight pin (GPIO21) is enabled

Screen shows garbage or artifacts

Section titled “Screen shows garbage or artifacts”
  1. Check TFT library version compatibility
  2. Verify SPI pin configuration
  3. Try reducing SPI clock speed
  4. Check power supply stability

Power & Battery

Section titled “Power & Battery”

How do I read battery voltage?

Section titled “How do I read battery voltage?”
#define VBAT_ADC_PIN 1
#define VBAT_CTRL_PIN 2


float readBattery() {
    pinMode(VBAT_CTRL_PIN, OUTPUT);
    digitalWrite(VBAT_CTRL_PIN, LOW);  // Enable divider


    int raw = analogRead(VBAT_ADC_PIN);


    digitalWrite(VBAT_CTRL_PIN, HIGH); // Disable to save power


    // VBAT = ADC * 4.9
    return (raw / 4095.0) * 3.3 * 4.9;
}

Device won’t charge

Section titled “Device won’t charge”
  1. Verify USB cable supports data+power (not charge-only)
  2. Check battery polarity (red=positive)
  3. Battery may be deeply discharged - leave connected for 30 min
  4. Check charging LED (orange when charging)

High sleep current consumption

Section titled “High sleep current consumption”
  1. V1.1: Set GPIO3 LOW to disable GNSS in sleep
  2. Disable display backlight (GPIO21 LOW)
  3. Disable WiFi/BT before sleep
  4. Use esp_deep_sleep_start() not light sleep

GPS/GNSS

Section titled “GPS/GNSS”

GPS won’t get a fix

Section titled “GPS won’t get a fix”
  1. Antenna: Ensure IPEX antenna is connected securely
  2. Power (V1.1): Set GPIO3 HIGH to enable GNSS
  3. Location: Clear sky view required, move away from buildings
  4. Time: Cold start takes up to 26 seconds
  5. Interference: Move away from other electronics

GPS accuracy is poor

Section titled “GPS accuracy is poor”
  1. Allow time for multi-constellation acquisition
  2. Use external active antenna for better signal
  3. Check if all GNSS systems are enabled ($CFGSYS,H11)
  4. Verify antenna has clear sky view (not just outdoors)

LoRa

Section titled “LoRa”

No LoRa communication

Section titled “No LoRa communication”
  1. Verify antenna is connected (IPEX connector on LoRa port)
  2. Check frequency matches between devices
  3. Verify regional settings are correct
  4. Increase spreading factor for longer range

LoRaWAN join fails

Section titled “LoRaWAN join fails”
  1. Double-check DevEUI, AppEUI, AppKey
  2. Verify gateway is online and in range
  3. Check frequency plan matches network server
  4. Try increasing TX power or SF

Short range

Section titled “Short range”
  1. Use higher spreading factor (SF10-SF12)
  2. Check antenna connection and orientation
  3. Verify TX power settings
  4. Consider terrain and obstacles

Software

Section titled “Software”

”Board not found” in Arduino IDE

Section titled “”Board not found” in Arduino IDE”
  1. Add Heltec board URL to preferences: 
    https://resource.heltec.cn/download/package_heltec_esp32_index.json
  2. Install “Heltec ESP32 Series Dev-boards” from Boards Manager
  3. Select “Wireless Tracker” from board menu

Library conflicts

Section titled “Library conflicts”

The Heltec library may conflict with generic ESP32 libraries. Solutions:

  1. Use Heltec-specific library versions
  2. Remove duplicate libraries from Arduino/libraries folder
  3. Use PlatformIO with explicit lib_deps

Memory issues (sketch too large)

Section titled “Memory issues (sketch too large)”
  1. Use minimal partition scheme
  2. Enable PSRAM if available
  3. Reduce debug output
  4. Use release build (-O2 optimization)

Resources

Section titled “Resources”