404 lines
11 KiB
Markdown
404 lines
11 KiB
Markdown
# Drone Detection System
|
|
|
|
A comprehensive real-time drone detection and monitoring system with SMS alerts, real-time mapping, and advanced analytics.
|
|
|
|
## Features
|
|
|
|
### 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**:
|
|
```bash
|
|
git clone <repository-url>
|
|
cd uamils
|
|
npm run install:all
|
|
```
|
|
|
|
2. **Database Setup**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
# From project root - starts both backend and frontend
|
|
npm run dev
|
|
```
|
|
|
|
Or start separately:
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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](docs/DOCKER_DEPLOYMENT.md).
|
|
|
|
## Testing with Swedish Drone Simulator
|
|
|
|
The system includes a comprehensive Python simulation script for testing with realistic Swedish coordinates:
|
|
|
|
```bash
|
|
# 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](docs/THREAT_ASSESSMENT.md).
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables (.env)
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
## API Documentation
|
|
|
|
### Drone Detection Endpoint
|
|
```http
|
|
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
|
|
```http
|
|
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
|
|
|
|
## Hardware Integration
|
|
|
|
### Expected Data Format
|
|
|
|
The system expects drone detection data in this format:
|
|
```json
|
|
{
|
|
"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
|
|
```bash
|
|
# 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.
|