A modular LoRA and Bluetooth Low Energy application for the Heltec WiFi LoRA 32 V3 board that allows dynamic configuration of LoRA syncWord via BLE and displays received messages on an OLED screen.

• 📡 LoRA Communication: Send and receive LoRA messages using SX1262 chip
• 📱 BLE Configuration: Set LoRA syncWord wirelessly via Bluetooth
• 🖥️ OLED Display: View messages and status on built-in 128x64 display
• 💾 Persistent Storage: Save settings that survive reboots
• 🔧 Modular Architecture: Clean, maintainable code structure
• 📊 Signal Quality: Display RSSI and SNR for received messages

• Heltec WiFi LoRA 32 V3 board
  • MCU: ESP32-S3FN8
  • LoRA: SX1262 (863-928 MHz)
  • Display: 0.96" OLED (128x64)
• USB-C cable for programming
• Antenna for LoRA (required!)

• PlatformIO or Arduino IDE
• Python 3.x (for PlatformIO)
• nRF Connect app (for BLE testing)

1. Clone this repository:

   git clone <repository-url>
   cd LoRABLE

2. Build the project:

   pio run

3. Upload to board:

   pio run --target upload

4. Monitor serial output:

   pio device monitor

1. Install required libraries via Library Manager:

   • RadioLib by Jan Gromeš (for SX1262 LoRA chip)
   • ESP8266 and ESP32 OLED driver for SSD1306 displays

2. Open src/main.cpp in Arduino IDE

3. Select board: Heltec WiFi LoRA 32 V3

4. Upload to board

Note: The Heltec V3 uses the SX1262 LoRA chip which requires RadioLib, not the older sandeepmistry/LoRa library.

LoRABLE/
├── src/
│   └── main.cpp              # Main application (orchestration only)
├── lib/
│   ├── BLE/                  # BLE module
│   │   ├── BLEManager.h
│   │   ├── BLEManager.cpp
│   │   └── README.md
│   ├── LoRA/                 # LoRA module
│   │   ├── LoRAManager.h
│   │   ├── LoRAManager.cpp
│   │   └── README.md
│   ├── Display/              # Display module
│   │   ├── DisplayManager.h
│   │   ├── DisplayManager.cpp
│   │   └── README.md
│   └── Config/               # Configuration module
│       ├── ConfigManager.h
│       ├── ConfigManager.cpp
│       └── README.md
├── platformio.ini            # PlatformIO configuration
├── .github/
│   ├── copilot-instructions.md
│   └── workflows/
│       └── build-firmware.yml
└── README.md

On first boot, the device:

• Initializes with default syncWord (0x12)
• Starts BLE advertising as "LoRABLE"
• Displays status on OLED

1. Open nRF Connect app on your smartphone
2. Scan for devices and connect to "LoRABLE"
3. Navigate to service UUID: 4fafc201-1fb5-459e-8fcc-c5c9c331914b
4. Find syncWord characteristic: beb5483e-36e1-4688-b7f5-ea07361b26a8
5. Write new syncWord (1 byte, 0x00-0xFF)
6. Device will update LoRA configuration and save to flash

Use another Heltec device or LoRA module with the same syncWord to send messages. The device will:

• Receive messages automatically
• Display message content
• Show RSSI and SNR values
• Update status screen

Connect via serial monitor (115200 baud) to see:

• Initialization status
• Configuration changes
• Received messages
• Signal quality metrics

Each module has detailed documentation:

• BLE Module - Bluetooth Low Energy operations
• LoRA Module - LoRA transceiver operations
• Display Module - OLED display management
• Config Module - Persistent storage

Frequency:         915.0 MHz (adjust for region)
Bandwidth:         125.0 kHz
Spreading Factor:  7
Coding Rate:       4/5
TX Power:          20 dBm
Default SyncWord:  0x12

Choose the appropriate frequency for your region in lib/LoRA/LoRAManager.h:

• 433.0 MHz: Europe, Asia (ISM band)
• 868.0 MHz: Europe
• 915.0 MHz: North America, Australia, South America

⚠️ Important: Check local regulations before transmitting!

This project uses RadioLib instead of the older sandeepmistry/LoRa library because the Heltec V3 has an SX1262 chip (not SX127x). RadioLib provides better support for modern LoRA chips.

The modular architecture makes it easy to extend:

1. Add new BLE characteristics: Modify BLEManager
2. Change LoRA parameters: Extend LoRAManager
3. Customize display: Update DisplayManager
4. Add new settings: Extend ConfigManager

Main application in main.cpp only orchestrates modules - keep it minimal!

Use GitHub Actions to build firmware automatically:

git tag v1.0.0
git push origin v1.0.0

This creates a GitHub Release with downloadable firmware binaries. (required!)

• Verify frequency matches your region (915.0 for US)
• Ensure both devices have same syncWord
• Check serial output for error codes from RadioLib

• Check Bluetooth is enabled on phone
• Device name is "LoRABLE"
• Try restarting the board

• VEXT_CTRL pin controls power (active LOW)
• Check I2C connections (pins 17, 18)
• Display init includes Wire.begin() call
• Reset display if corrupted

• Check baud rate is 115200
• Ensure USB cable supports data
• Try different USB port

If you see "LoRA initialization failed, code: X":

• -2 (RADIOLIB_ERR_CHIP_NOT_FOUND): Check wiring and pins
• -3 (RADIOLIB_ERR_SPI_CMD_TIMEOUT): SPI communication issue
• See RadioLib documentation for more codes

• Check baud rate is 115200
• Ensure USB cable supports data
• Try different USB port

This project follows a modular architecture. When contributing:

1. Keep modules independent and focused
2. Follow existing code style (PascalCase for classes, camelCase for methods)
3. Add documeRadioLib (Jan Gromeš), SSD1306 (ThingPulse)

• Heltec WiFi LoRA 32 V3 Documentation
• [RadioLib Library](https://github.com/jgromes/RadioLib [Your License Here]

• Based on tutorial: ESP32 LoRA with Arduino IDE
• Hardware: Heltec Automation
• Libraries: LoRa (Sandeep Mistry), SSD1306 (ThingPulse)

• Heltec WiFi LoRA 32 V3 Documentation
• LoRa Library
• SSD1306 Library
• ESP32 BLE Documentation