Lightning Detection System - PlatformIO Heltec V3

A distributed lightning detection system built for Heltec WiFi LoRa 32 V3 boards with ESP32-S3, featuring modular architecture, comprehensive hardware abstraction, and GPS tracking capabilities.

🚀 Features

Core Functionality

Lightning Detection - AS3935 sensor integration with noise filtering
LoRa Communication - Long-range data transmission using SX1262 radio
GPS Tracking - UC6580 GNSS support for precise location data
OLED Display - Real-time status and data visualization
WiFi Connectivity - Multi-network support with automatic fallback
OTA Updates - Over-the-air firmware updates via WiFi

Hardware Abstraction Layer (HAL)

Modular Design - Clean hardware abstraction for easy portability
Comprehensive API - GPIO, I2C, SPI, PWM, ADC, Timer, Power, Memory management
Test Coverage - 51 unit tests ensuring reliability
ESP32-S3 Optimized - Tailored for Heltec WiFi LoRa 32 V3 hardware

Advanced Features

Multi-Board Support - Sender/receiver architecture
Power Management - Sleep modes and battery monitoring
Error Handling - Robust error detection and recovery
Debugging Tools - Serial logging and diagnostic information

📋 Hardware Requirements

Supported Boards

Heltec WiFi LoRa 32 V3 - Main development board
Heltec Wireless Tracker - GPS-enabled transmitter (upcoming)

Key Specifications

MCU: ESP32-S3 (240MHz, dual-core, 8MB Flash, 512KB SRAM)
Radio: SX1262 LoRa transceiver (915MHz)
Display: 128x64 OLED (SSD1306)
GPS: UC6580 GNSS (L1+L5/L2 dual frequency)
Connectivity: WiFi 802.11 b/g/n

Sensors & Peripherals

AS3935 Lightning sensor
Battery voltage monitoring
External GPIO expansion
I2C/SPI device support

🛠️ Quick Start

Prerequisites

# Install PlatformIO Core
pip install platformio

# Clone the repository
git clone https://github.com/Skeyelab/LightningDetector.git
cd LightningDetector

Build Options

Unified Firmware (single binary for Sender or Receiver)

# Build
pio run -e unified

# Upload (USB serial bootloader)
pio run -e unified -t upload

# Monitor serial output
pio device monitor

After flashing, the board boots as Sender by default. Change the role at runtime:

Web UI

Connect to the device’s IP or esp32.local
Scroll to Device Role → click Toggle Role (sender ↔ receiver)
Reboot to apply

HTTP API

curl -X POST http://<ip>/api/v1/config \
     -H 'Content-Type: application/json' \
     -d '{"role":"receiver"}'

The choice is stored in NVS, so future boots keep the selected role.

🌐 Web Flasher

Browser-Based Firmware Flashing

The project includes a web-based ESP32 firmware flasher that allows you to flash devices directly from your browser without installing additional software.

Features

🌐 Web Interface: Flash ESP32 devices from any modern browser
🌟 Unified Firmware: Single firmware supports both TX and RX modes
📱 Legacy Support: Transmitter and receiver firmware flashing (backward compatibility)
📁 File Upload: Support for custom firmware files
🔌 Serial Port: Direct USB connection to ESP32 devices
📊 Progress Tracking: Real-time flashing progress and status updates

Quick Start

Visit: Web Flasher
Connect: Plug your ESP32 device via USB
Select: Choose Unified Firmware (recommended) or legacy transmitter/receiver
Flash: Click "Connect & Flash" and follow the prompts
Configure: After flashing unified firmware, use web interface to set device role

Requirements

Browser: Chrome or Edge (Web Serial API support)
Hardware: ESP32 device in download mode
USB Cable: Data cable (not just charging cable)

Manual Firmware Upload

Upload custom .bin files for unified, transmitter, or receiver firmware
Support for both pre-built and custom firmware
Automatic file validation and size checking
Recommended: Use unified firmware for maximum flexibility

Configuration

WiFi Networks

// Copy and modify wifi_networks_example.h
cp wifi_networks_example.h src/wifi_networks.h
// Edit src/wifi_networks.h with your network credentials

Hardware Pins

// Heltec V3 Pin Configuration (src/config/system_config.h)
#define VEXT_PIN 36        // Power control
#define OLED_RST_PIN 21    // OLED reset
#define BUTTON_PIN 0       // User button
#define LORA_NSS 8         // LoRa chip select
#define LORA_DIO1 14       // LoRa interrupt

📁 Repository Structure

The repository is organized for easy navigation and maintenance:

Scripts (`scripts/`)

ci/ - Continuous Integration scripts
- run_tests.sh - Comprehensive test suite
- run_static_analysis.sh - Code analysis tools
- run_tidy.sh - Clang-tidy formatting
dev/ - Development and deployment scripts
- flash_unified.sh - Flash unified firmware to single device
- flash_both.sh - Flash unified firmware to both devices
- create_release.sh - Create release packages
optimize/ - Performance optimization tools
- optimize_clang_tidy_cache.sh - Build cache optimization

Documentation (`docs/`)

development/ - Development guides
- QUICK_START_RELEASE.md - Release quick start
- RELEASE_README.md - Release procedures
- TROUBLESHOOTING.md - Common issues and solutions
deployment/ - Deployment documentation
- OTA_README.md - Over-the-air update guide
- WEB_FLASHER_DEPLOYMENT.md - Web flasher setup
- WIFI_MULTI_NETWORK_README.md - Multi-network WiFi config
testing/ - Testing documentation
- NEW_TESTS_NEEDED.md - Test coverage gaps
- STATIC_ANALYSIS.md - Static analysis setup
project/ - Project management
- CURSOR_PROJECT_STATUS.md - Current project status
- CI_CACHING_OPTIMIZATION.md - CI performance notes

🧪 Testing

Run All Tests

# Execute comprehensive test suite
./scripts/ci/run_tests.sh

Individual Test Suites

# Hardware Abstraction Layer tests
pio test -e native -f test_hardware_abstraction

# Integration tests
pio test -e native -f test_integration

# WiFi functionality tests
pio test -e native -f test_wifi_manager

Static Analysis

# Code quality checks
./run_static_analysis.sh

# Clang-tidy analysis
./run_tidy.sh

📁 Project Structure

├── src/
│   ├── hardware/              # Hardware Abstraction Layer
│   │   ├── hardware_abstraction.h
│   │   └── hardware_abstraction.cpp
│   ├── sensors/               # Sensor implementations
│   │   ├── gps_sensor.h/.cpp
│   │   ├── lightning_sensor.h
│   │   └── sensor_interface.h
│   ├── communication/         # Communication protocols
│   ├── system/               # System management
│   ├── config/               # Configuration files
│   └── main.cpp              # Application entry point
├── test/                     # Unit tests
├── docs/                     # Additional documentation
└── platformio.ini           # PlatformIO configuration

🔧 Hardware Abstraction Layer

GPIO Operations

#include "hardware/hardware_abstraction.h"
using namespace HardwareAbstraction;

// Initialize HAL
initialize();

// Configure GPIO
GPIO::pinMode(2, GPIO::Mode::MODE_OUTPUT);
GPIO::digitalWrite(2, GPIO::Level::LEVEL_HIGH);

I2C Communication

// Initialize I2C for OLED
I2C::initialize(21, 22, 400000); // SDA, SCL, frequency

// Write to device
uint8_t data[] = {0x00, 0xFF};
I2C::beginTransmission(0x3C);
I2C::write(data, sizeof(data));
I2C::endTransmission();

GPS Integration

#include "sensors/gps_sensor.h"

// Initialize GPS for Wireless Tracker
GPS::Config config = GPS::getWirelessTrackerV11Config();
GPS::initializeGPS(config);

// Read GPS data
if (GPS::hasGPSFix()) {
    const GPS::Data& data = GPS::getGPSData();
    printf("Position: %.6f, %.6f\n", data.latitude, data.longitude);
}

📡 Communication Protocol

LoRa Messaging

// Message format
struct LightningMessage {
    uint32_t timestamp;
    float latitude;
    float longitude;
    uint16_t strike_count;
    uint8_t noise_level;
    uint16_t battery_mv;
};

WiFi Multi-Network

Automatic network selection
Connection priority management
Fallback mechanisms
OTA update support

🔋 Power Management

Sleep Modes

// Deep sleep for battery conservation
Power::sleep(Power::Mode::DEEP_SLEEP, 300000); // 5 minutes

// Wake on button press or timer

Battery Monitoring

// Check battery status
float voltage = Power::getBatteryVoltage();
uint8_t percent = Power::getBatteryPercent();

📊 Monitoring & Debugging

Serial Logging

// Debug output levels
#define LOG_DEBUG   0
#define LOG_INFO    1
#define LOG_WARN    2
#define LOG_ERROR   3

Performance Metrics

Memory usage tracking
LoRa transmission statistics
GPS fix quality monitoring
Power consumption analysis

🤝 Contributing

Development Workflow

Fork the repository
Create feature branch (git checkout -b feature/new-sensor)
Implement changes with tests
Run test suite (./scripts/ci/run_tests.sh)
Submit pull request

Code Standards

Follow existing code style
Add unit tests for new features
Update documentation
Pass static analysis checks

Issue Tracking

Hardware Abstraction Layer ✅ COMPLETE
Modular Architecture 🚧 IN PROGRESS

📚 Documentation

🎯 Roadmap

Phase 1: Foundation ✅

Phase 2: Lightning Detection 🚧

AS3935 Sensor Integration
Noise Filtering Algorithms
Calibration Procedures
Real-time Processing

Phase 3: Communication 🔮

LoRa Network Protocol
Message Encryption
Multi-hop Routing
Data Aggregation

Phase 4: Analytics 🔮

Storm Tracking
Prediction Models
Web Dashboard
Mobile App

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Heltec Automation - Hardware platform and documentation
Espressif Systems - ESP32-S3 microcontroller and ESP-IDF
RadioLib - LoRa communication library
U8g2 - OLED display library
PlatformIO - Development platform and toolchain

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Project Wiki

Built with ❤️ for the lightning detection community

Skeyelab/LightningDetector