drone-detector/README.md

Drone Detection System

A comprehensive real-time drone detection and monitoring system with SMS alerts, real-time mapping, and advanced analytics.

Features

notif ethernet https://yourserver.com/path/to/script coords

Core Functionality

• Real-time Drone Detection: Receive and process drone detection data from hardware sensors
• Intelligent Threat Assessment: RSSI-based threat classification (Critical, High, Medium, Low, Monitoring)
• Device Management: Monitor and manage drone detection devices with heartbeat monitoring
• Real-time Mapping: Interactive map showing device locations and detection status with threat indicators
• SMS Alerts: Configurable SMS notifications via Twilio with threat-based escalation
• Analytics Dashboard: Real-time charts and statistics with threat level breakdowns
• Alert Rules: Flexible alert configuration with threat level thresholds and distance limits

Hardware Integration

• Detection Data Processing: Handles JSON data from drone detection hardware
• Heartbeat Monitoring: Tracks device health and connectivity status
• Device Status Tracking: Real-time monitoring of device online/offline status

Advanced Features

• Multi-user Support: Role-based access control (admin, operator, viewer)
• Real-time Updates: WebSocket-based live updates across all clients
• Intelligent Threat Assessment: RSSI-based distance calculation and threat classification
• Security-Focused Alerts: Enhanced alert messages with threat descriptions and action requirements
• Swedish Location Support: Pre-configured for government sites, water facilities, and sensitive areas
• Alert Management: Comprehensive alert rule configuration with threat level thresholds
• Historical Data: Complete detection history with threat level filtering and search
• API-first Design: RESTful API for easy integration with external systems

Technology Stack

Backend

• Node.js with Express.js framework
• PostgreSQL database with Sequelize ORM
• Socket.IO for real-time communication
• Twilio for SMS alerts
• JWT authentication
• Rate limiting and security middleware

Frontend

• React 18 with modern hooks
• React Leaflet for interactive maps
• Tailwind CSS for styling
• Recharts for data visualization
• Framer Motion for animations
• React Hot Toast for notifications

Project Structure

uamils/
├── server/                 # Backend API
│   ├── models/            # Database models
│   ├── routes/            # API routes
│   ├── services/          # Business logic
│   ├── middleware/        # Express middleware
│   └── scripts/           # Database setup scripts
├── client/                # Frontend React app
│   ├── src/
│   │   ├── components/    # Reusable components
│   │   ├── pages/         # Page components
│   │   ├── contexts/      # React contexts
│   │   └── services/      # API services
└── docs/                  # Documentation

Quick Start

Prerequisites

• Node.js 16+ and npm
• PostgreSQL 12+
• Twilio account (for SMS alerts)

Native Installation

1. Clone and install dependencies:

   git clone <repository-url>
   cd uamils
   npm run install:all
   

2. Database Setup:

   # Create PostgreSQL database
   createdb drone_detection
   
   # Copy environment file
   cd server
   cp .env.example .env
   
   # Edit .env with your database credentials and Twilio config
   # Then run database setup
   npm run db:setup
   

3. Start Development Servers:

   # From project root - starts both backend and frontend
   npm run dev
   

   Or start separately:

   # Backend (port 3001)
   npm run server:dev
   
   # Frontend (port 3000)
   npm run client:dev
   

4. Access the application:

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:3001/api

Docker Installation (Recommended)

For the easiest setup, use Docker:

# Prerequisites: Docker and Docker Compose

# 1. Copy environment template
cp .env.docker .env

# 2. Edit .env with your Twilio credentials
# TWILIO_ACCOUNT_SID=your_sid
# TWILIO_AUTH_TOKEN=your_token  
# TWILIO_PHONE_NUMBER=your_phone

# 3. Start the system
docker compose up -d

# 4. Access the application
# Frontend: http://localhost:3000
# Backend: http://localhost:3001/api

# Quick start script (Windows/Linux)
./docker-start.sh          # Linux/Mac
docker-start.bat           # Windows

Docker Profiles:

• Default: docker compose up -d (Frontend + Backend + Database + Redis)
• Production: docker compose --profile production up -d (+ Nginx proxy)
• Simulation: docker compose --profile simulation up -d (+ Python simulator)

For detailed Docker deployment guide, see docs/DOCKER_DEPLOYMENT.md.

Testing with Swedish Drone Simulator

The system includes a comprehensive Python simulation script for testing with realistic Swedish coordinates:

# Install Python dependencies
pip install -r requirements.txt

# Run basic simulation (5 devices at Swedish government sites)
python drone_simulator.py

# Custom simulation with 10 devices for 2 hours
python drone_simulator.py --devices 10 --duration 7200

# Show available Swedish locations
python drone_simulator.py --list-locations

The simulator generates:

• Realistic RSSI values based on actual distance calculations
• Threat-based scenarios with different probability weights
• Swedish coordinates for government sites, water facilities, nuclear plants
• Continuous heartbeats for device health monitoring
• Multiple threat levels from monitoring (15km) to critical (<50m)

Threat Assessment System

The system includes intelligent threat assessment specifically designed for Swedish government sites and sensitive facilities:

Threat Levels

• 🔴 CRITICAL (0-50m): Immediate security response required
• 🟠 HIGH (50-200m): Security response recommended
• 🟡 MEDIUM (200m-1km): Enhanced monitoring
• 🟢 LOW (1-5km): Standard monitoring
• ⚪ MONITORING (5-15km): Passive monitoring

RSSI-Based Distance Calculation

Estimated Distance = 10^((RSSI_at_1m - RSSI) / (10 * path_loss_exponent))

Enhanced Alert Messages

🚨 SECURITY ALERT 🚨
THREAT LEVEL: HIGH
HIGH THREAT: Drone approaching facility (50-200m)

📍 LOCATION: Riksdag Stockholm  
📏 DISTANCE: ~150m
📶 SIGNAL: -45 dBm
🚁 DRONE TYPE: Professional/Military
⚠️ IMMEDIATE ACTION REQUIRED

For detailed threat assessment documentation, see docs/THREAT_ASSESSMENT.md.

Configuration

Environment Variables (.env)

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=drone_detection
DB_USER=postgres
DB_PASSWORD=your_password

# JWT Secret
JWT_SECRET=your-super-secret-jwt-key

# Twilio (for SMS alerts)
TWILIO_ACCOUNT_SID=your_twilio_sid
TWILIO_AUTH_TOKEN=your_twilio_token
TWILIO_PHONE_NUMBER=your_twilio_phone

# API Settings
PORT=3001
NODE_ENV=development
CORS_ORIGIN=http://localhost:3000

# Debug Configuration
STORE_HEARTBEATS=true          # Store heartbeat data for debugging
STORE_DRONE_TYPE0=true         # Store drone_type 0 detections for debugging
LOG_ALL_DETECTIONS=true        # Log all detection data to console
API_DEBUG=true                 # Enable API debug logging
STORE_RAW_PAYLOAD=true         # Store complete raw payload from detectors

API Documentation

Drone Detection Endpoint

POST /api/detections
Content-Type: application/json

{
  "device_id": 1941875381,
  "geo_lat": 59.3293,
  "geo_lon": 18.0686,
  "device_timestamp": 1691755018,
  "drone_type": 0,
  "rssi": -45,
  "freq": 20,
  "drone_id": 2
}

Heartbeat Endpoint

POST /api/heartbeat
Content-Type: application/json

{
  "type": "heartbeat",
  "key": "device_1941875381_key",
  "battery_level": 85,
  "signal_strength": -50,
  "temperature": 22.5
}

Device Management

• GET /api/devices - List all devices
• GET /api/devices/map - Get devices with location data
• POST /api/devices - Create new device (admin)
• PUT /api/devices/:id - Update device (admin)

User Authentication

• POST /api/users/login - User login
• POST /api/users/register - Register new user
• GET /api/users/profile - Get current user profile

Alert Management

• GET /api/alerts/rules - Get user's alert rules
• POST /api/alerts/rules - Create new alert rule
• GET /api/alerts/logs - Get alert history

Debug Endpoints (Authentication Required)

• GET /api/debug/config - Get debug configuration status
• GET /api/debug/detection-payloads - Get recent detection payloads with raw data
• GET /api/debug/heartbeat-payloads - Get recent heartbeat payloads with raw data
• GET /api/debug/debug-test - Test debug endpoint

Debug Query Parameters

GET /api/debug/detection-payloads?limit=50&offset=0&device_id=1941875381
GET /api/debug/heartbeat-payloads?limit=50&offset=0&device_id=1941875381

The debug endpoints return the complete raw payload received from detectors when STORE_RAW_PAYLOAD=true is enabled. This is useful for troubleshooting detector communication issues and understanding the exact data format being sent.

Hardware Integration

Expected Data Format

The system expects drone detection data in this format:

{
  "device_id": 1941875381,
  "geo_lat": 0,
  "geo_lon": 0,
  "device_timestamp": 0,
  "drone_type": 0,
  "rssi": 0,
  "freq": 20,
  "drone_id": 2
}

Field Descriptions

• device_id: Unique identifier for the detection device
• geo_lat/geo_lon: GPS coordinates of the device
• device_timestamp: Unix timestamp from the device
• drone_type: Type classification of detected drone
• rssi: Received Signal Strength Indicator
• freq: Frequency of detected signal
• drone_id: Unique identifier for the detected drone

Recommended Additional Features

Based on the requirements, here are additional features that would enhance the system:

1. Analytics & Reporting

• Historical trend analysis
• Drone pattern recognition
• Frequency analysis and spectrum monitoring
• Device performance metrics
• Custom report generation

2. Advanced Alerting

• Email notifications
• Webhook integrations for external systems
• Escalation procedures
• Alert scheduling (business hours only)
• Custom alert templates

3. Security & Compliance

• Audit logging
• Data encryption at rest
• API rate limiting per client
• GDPR compliance features
• Role-based permissions

4. Integration Features

• REST API for third-party integrations
• Webhook support for external systems
• MQTT support for IoT devices
• Integration with security systems
• Export capabilities (CSV, PDF)

5. Advanced Mapping

• Heatmaps of detection frequency
• Flight path tracking
• Geofencing capabilities
• Multiple map layers
• Offline map support

6. Mobile Application

• React Native mobile app
• Push notifications
• Offline viewing capabilities
• Quick alert acknowledgment

7. AI/ML Enhancements

• Drone behavior prediction
• False positive reduction
• Automatic drone classification
• Anomaly detection
• Pattern recognition

Production Deployment

Docker Deployment

# Build and run with Docker Compose
docker compose up -d

Manual Deployment

1. Set up PostgreSQL database
2. Configure environment variables
3. Build frontend: npm run client:build
4. Start backend: npm run server:start
5. Serve frontend with nginx or similar

Recommended Infrastructure

• Database: PostgreSQL with read replicas
• Caching: Redis for session management
• Load Balancer: nginx or AWS ALB
• Monitoring: Prometheus + Grafana
• Logging: ELK stack or similar

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Submit a pull request

License

[Add your license here]

Support

For support and questions:

• Create an issue in the repository
• Contact the development team
• Check the documentation in /docs

---

Note: This system is designed for security and monitoring purposes. Ensure compliance with local regulations regarding drone detection and monitoring.