Safety Events & Alert System

Real-time flight safety monitoring with intelligent alerting - Detect emergencies, TCAS events, and custom conditions as they happen.

Overview

SkysPy provides a powerful dual-layer alert and monitoring system:

Both systems integrate with Socket.IO streaming for real-time notifications and support enterprise features including role-based access control, notification channels, and audit history.

Safety Events

What Are Safety Events?

Safety events are automatically detected anomalies in aircraft behavior that may indicate dangerous situations. The SafetyMonitor service continuously analyzes incoming ADS-B data to identify potential safety concerns.

flowchart LR
    A[📡 ADS-B Data] --> B{Safety Monitor}
    B --> C[🔴 Emergency Squawk]
    B --> D[⚡ TCAS RA]
    B --> E[📉 Extreme VS]
    B --> F[✈️ Proximity Conflict]
    C & D & E & F --> G[🔔 Alert Dispatch]
    G --> H[📱 Socket.IO]
    G --> I[📧 Notifications]

Types of Safety Events

Severity Levels

Critical

Immediate attention required

• Emergency squawks (7500, 7700)
• TCAS Resolution Advisories
• Very close proximity conflicts
• Extreme vertical rates

Critical events trigger immediate notifications and are highlighted prominently in the UI.

Warning

Notable events requiring awareness

• Radio failure squawks (7600)
• Moderate proximity conflicts
• Significant VS reversals

Warning events are logged and displayed but may not require immediate action.

Low

Informational events for logging

• Minor anomalies
• Informational VS changes
• Events filtered by smart detection

Low severity events are primarily for record-keeping and analysis.

Detection Thresholds

Quick Setup - Configure these thresholds in your Django settings.py to tune sensitivity.

# Django settings.py
SAFETY_MONITORING_ENABLED = True
SAFETY_VS_CHANGE_THRESHOLD = 3000      # fpm - triggers VS reversal detection
SAFETY_VS_EXTREME_THRESHOLD = 6000     # fpm - triggers extreme VS event
SAFETY_PROXIMITY_NM = 1.0              # nautical miles - horizontal proximity
SAFETY_ALTITUDE_DIFF_FT = 1000         # feet - vertical separation
SAFETY_CLOSURE_RATE_KT = 100           # knots - minimum closure rate
SAFETY_TCAS_VS_THRESHOLD = 1500        # fpm - magnitude for TCAS RA detection

Safety Event Data Structure

{
  "id": "tcas_ra:ABC123",
  "event_type": "tcas_ra",
  "severity": "critical",
  "icao_hex": "ABC123",
  "icao_hex_2": "DEF456",
  "callsign": "UAL123",
  "callsign_2": "DAL456",
  "message": "TCAS RA suspected: UAL123 VS reversed from -2500 to +2500 fpm",
  "timestamp": "2024-01-15T10:30:00Z",
  "acknowledged": false,
  "details": {
    "previous_vs": -2500,
    "current_vs": 2500,
    "vs_change": 5000,
    "altitude": 35000,
    "lat": 47.5,
    "lon": -122.3,
    "distance_nm": 0.8,
    "altitude_diff_ft": 400
  },
  "aircraft_snapshot": {
    "hex": "ABC123",
    "flight": "UAL123",
    "lat": 47.5,
    "lon": -122.3,
    "alt_baro": 35000,
    "gs": 450,
    "track": 180,
    "baro_rate": 2500,
    "squawk": "1200"
  }
}

Smart Filtering

Pro Tip - The safety monitor includes intelligent filtering to reduce false positives.

Alert Rule System

Overview

Custom alert rules allow users to define specific conditions for notification:

flowchart TB
    subgraph Rule["📋 Alert Rule"]
        A[Conditions] --> B{Logic: AND/OR}
        B --> C[Group 1]
        B --> D[Group 2]
        C --> E[Condition 1]
        C --> F[Condition 2]
    end

    subgraph Evaluation["⚙️ Evaluation"]
        G[Aircraft Data] --> H{Rule Engine}
        Rule --> H
        H --> I{Match?}
    end

    I -->|Yes| J[🔔 Trigger Alert]
    I -->|No| K[Continue Monitoring]

    J --> L[Check Cooldown]
    L --> M[📤 Send Notifications]

Alert Rule Builder

Basic Rule Structure

Quick Start - Here's a simple rule to detect military aircraft.

Basic Rule

{
  "name": "Military Aircraft Alert",
  "description": "Alert when military aircraft are detected",
  "priority": "warning",
  "enabled": true,
  "cooldown": 300,
  "conditions": {
    "logic": "AND",
    "groups": [
      {
        "logic": "AND",
        "conditions": [
          {
            "type": "military",
            "operator": "eq",
            "value": "true"
          }
        ]
      }
    ]
  }
}

Complex Multi-Condition

{
  "name": "Low Flying Helicopter Near Me",
  "description": "Alert when helicopters fly low within 5nm",
  "priority": "info",
  "enabled": true,
  "cooldown": 300,
  "conditions": {
    "logic": "AND",
    "groups": [
      {
        "logic": "AND",
        "conditions": [
          { "type": "helicopter", "operator": "eq", "value": "true" },
          { "type": "altitude_below", "operator": "lt", "value": "2000" },
          { "type": "distance_within", "operator": "lte", "value": "5" }
        ]
      }
    ]
  }
}

OR Logic Example

{
  "name": "Track N12345 or UAL Flights",
  "priority": "info",
  "conditions": {
    "logic": "OR",
    "groups": [
      {
        "logic": "AND",
        "conditions": [
          { "type": "registration", "operator": "eq", "value": "N12345" }
        ]
      },
      {
        "logic": "AND",
        "conditions": [
          { "type": "callsign", "operator": "startswith", "value": "UAL" }
        ]
      }
    ]
  }
}

Condition Types

Aircraft Identity

Flight Data

Location

Classifications

Available Operators

String Operators

Numeric Operators

Rule Templates

Quick Start - Use these pre-built templates for common use cases.

Scheduling & Suppression

Time-Based Scheduling

Rules can have start and expiration times:

{
  "name": "Air Show Alert",
  "starts_at": "2024-07-04T10:00:00Z",
  "expires_at": "2024-07-04T18:00:00Z",
  "conditions": { }
}

Suppression Windows

Prevent alerts during specific times:

{
  "name": "Night Alert",
  "suppression_windows": [
    {
      "day": "saturday",
      "start": "22:00",
      "end": "08:00"
    },
    {
      "day": "sunday",
      "start": "22:00",
      "end": "08:00"
    }
  ]
}

Cooldowns

Best Practice - Use cooldowns to prevent alert fatigue.

The cooldown system prevents alert spam:

Notification Channels

Supported Channel Types

Channel Configuration

Creating a Notification Channel

POST /api/v1/notifications/channels/

{
  "name": "My Discord Server",
  "channel_type": "discord",
  "apprise_url": "discord://webhook_id/webhook_token",
  "enabled": true,
  "is_global": false
}

Assigning Channels to Rules

{
  "name": "Emergency Alert",
  "notification_channel_ids": [1, 2, 5],
  "use_global_notifications": true,
  "conditions": { }
}

Global vs Rule-Specific Notifications

Alert History & Management

Viewing Alert History

Alert history is accessible via API and Socket.IO, with filtering by:

• Time range (hours)
• Severity/priority
• Rule ID
• ICAO hex
• Acknowledged status

Acknowledgment Workflow

flowchart LR
    A[📥 Incoming Alerts] --> B[📋 View Unacknowledged]
    B --> C{Review Alert}
    C --> D[✅ Acknowledge Single]
    C --> E[✅ Acknowledge All]
    C --> F[📤 Export CSV]
    D & E --> G[📁 Archived]

Aggregation

For high-volume rules, alerts are aggregated into time windows to reduce noise:

{
  "rule_name": "Military Aircraft",
  "window_start": "2024-01-15T10:00:00Z",
  "window_end": "2024-01-15T11:00:00Z",
  "trigger_count": 45,
  "unique_aircraft": 12,
  "sample_aircraft": [
    {"icao_hex": "AE1234", "callsign": "RCH123"},
    {"icao_hex": "AE5678", "callsign": "RCH456"}
  ]
}

API Reference

Alert Rules

List & Get

List Rules

GET /api/v1/alerts/rules/

Query parameters:

• enabled: Filter by enabled status
• priority: Filter by priority (info/warning/critical)
• visibility: Filter by visibility (private/shared/public)

Get Rule

GET /api/v1/alerts/rules/{id}/

Create & Update

Create Rule

POST /api/v1/alerts/rules/

Update Rule

PATCH /api/v1/alerts/rules/{id}/

Delete Rule

DELETE /api/v1/alerts/rules/{id}/

Actions

Toggle Rule

POST /api/v1/alerts/rules/{id}/toggle/

Test Rule

POST /api/v1/alerts/rules/test/

{
  "rule": {
    "type": "military",
    "operator": "eq",
    "value": "true"
  },
  "aircraft": [
    {"hex": "AE1234", "military": true},
    {"hex": "A12345", "military": false}
  ]
}

Response:

{
  "would_match": 1,
  "matched_aircraft": [{"hex": "AE1234", "military": true}],
  "rule_valid": true,
  "aircraft_tested": 2
}

Bulk Operations

Bulk Create

POST /api/v1/alerts/rules/bulk_create/

{
  "rules": [{ }, { }]
}

Bulk Delete

POST /api/v1/alerts/rules/bulk_delete/

{
  "rule_ids": [1, 2, 3]
}

Bulk Toggle

POST /api/v1/alerts/rules/bulk_toggle/

{
  "rule_ids": [1, 2, 3],
  "enabled": true
}

Export/Import

Export

GET /api/v1/alerts/rules/export/

Import

POST /api/v1/alerts/rules/import/

{
  "rules": [{ }],
  "replace_all": false
}

Alert History

Query Parameters for List:

• hours: Time range (default: 24)
• rule_id: Filter by rule
• icao_hex: Filter by aircraft
• priority: Filter by priority
• acknowledged: Filter by acknowledged status
• limit: Pagination limit
• offset: Pagination offset

Subscriptions

{
  "rule_id": 123,
  "notify_on_trigger": true
}

Safety Events

{
  "monitoring_enabled": true,
  "thresholds": {
    "vs_change_threshold": 3000,
    "vs_extreme_threshold": 6000,
    "proximity_nm": 1.0,
    "altitude_diff_ft": 1000
  },
  "time_range_hours": 24,
  "events_by_type": {
    "tcas_ra": 5,
    "proximity_conflict": 12,
    "extreme_vs": 8
  },
  "events_by_severity": {
    "critical": 7,
    "warning": 10,
    "low": 8
  },
  "total_events": 25,
  "unique_aircraft": 18,
  "event_rate_per_hour": 1.04
}

Notification Channels

Socket.IO Alert Streaming

Connection

Connect to the alerts Socket.IO namespace:

import { io } from 'socket.io-client';

const socket = io('https://your-skyspy-instance/alerts', {
  path: '/socket.io/',
  transports: ['websocket', 'polling']
});

Event Types

Subscribe

socket.emit('subscribe', { topic: 'alerts' });

Alert Triggered

socket.on('alert:triggered', (data) => {
  console.log(data);
  // {
  //   "rule_id": 123,
  //   "rule_name": "Military Aircraft",
  //   "icao": "AE1234",
  //   "callsign": "RCH123",
  //   "message": "Alert 'Military Aircraft' triggered for RCH123",
  //   "priority": "warning",
  //   "aircraft": { },
  //   "timestamp": "2024-01-15T10:30:00Z"
  // }
});

Safety Event

socket.on('safety_event', (data) => {
  console.log(data);
  // {
  //   "event_type": "tcas_ra",
  //   "severity": "critical",
  //   "icao_hex": "ABC123",
  //   "message": "TCAS RA suspected: ...",
  //   "timestamp": "2024-01-15T10:30:00Z"
  // }
});

Snapshot

socket.on('alert:snapshot', (data) => {
  console.log(data);
  // {
  //   "alerts": [],
  //   "count": 20,
  //   "timestamp": "2024-01-15T10:30:00Z"
  // }
});

Request/Response Pattern

Request:

socket.emit('request', {
  request_id: 'req-123',
  request_type: 'alerts',
  params: {
    hours: 24,
    limit: 50
  }
});

Response:

socket.on('response', (data) => {
  console.log(data);
  // {
  //   "request_id": "req-123",
  //   "request_type": "alerts",
  //   "data": []
  // }
});

Available Request Types

User-Specific Channels

Authenticated users automatically join:

• alerts_user_{user_id} - Private alerts for owned rules
• alerts_session_{session_key} - Session-based alerts for anonymous users

Custom Rule Examples

{
  "name": "Track N12345",
  "priority": "info",
  "cooldown": 60,
  "conditions": {
    "logic": "OR",
    "groups": [
      {
        "logic": "AND",
        "conditions": [
          { "type": "registration", "operator": "eq", "value": "N12345" }
        ]
      },
      {
        "logic": "AND",
        "conditions": [
          { "type": "icao", "operator": "eq", "value": "A12345" }
        ]
      }
    ]
  }
}

{
  "name": "All Emergencies",
  "priority": "critical",
  "cooldown": 30,
  "conditions": {
    "logic": "AND",
    "groups": [
      {
        "logic": "AND",
        "conditions": [
          { "type": "emergency", "operator": "eq", "value": "true" }
        ]
      }
    ]
  },
  "notification_channel_ids": [1, 2],
  "use_global_notifications": true
}

{
  "name": "Low Flyers Near Home",
  "priority": "info",
  "cooldown": 300,
  "conditions": {
    "logic": "AND",
    "groups": [
      {
        "logic": "AND",
        "conditions": [
          { "type": "altitude_below", "operator": "lt", "value": "3000" },
          { "type": "distance_within", "operator": "lte", "value": "5" }
        ]
      }
    ]
  }
}

{
  "name": "Police Helicopter Alert",
  "priority": "warning",
  "cooldown": 600,
  "conditions": {
    "logic": "AND",
    "groups": [
      {
        "logic": "AND",
        "conditions": [
          { "type": "law_enforcement", "operator": "eq", "value": "true" },
          { "type": "helicopter", "operator": "eq", "value": "true" },
          { "type": "distance_within", "operator": "lte", "value": "10" }
        ]
      }
    ]
  }
}

{
  "name": "Fast Movers",
  "priority": "info",
  "cooldown": 300,
  "conditions": {
    "logic": "AND",
    "groups": [
      {
        "logic": "AND",
        "conditions": [
          { "type": "speed_above", "operator": "gt", "value": "500" },
          { "type": "altitude_above", "operator": "gt", "value": "20000" }
        ]
      }
    ]
  }
}

{
  "name": "United Airlines",
  "priority": "info",
  "cooldown": 120,
  "conditions": {
    "logic": "AND",
    "groups": [
      {
        "logic": "AND",
        "conditions": [
          { "type": "callsign", "operator": "startswith", "value": "UAL" }
        ]
      }
    ]
  }
}

{
  "name": "Interesting Aircraft Types",
  "priority": "info",
  "cooldown": 300,
  "conditions": {
    "logic": "OR",
    "groups": [
      {
        "logic": "AND",
        "conditions": [
          { "type": "type", "operator": "eq", "value": "A380" }
        ]
      },
      {
        "logic": "AND",
        "conditions": [
          { "type": "type", "operator": "eq", "value": "B748" }
        ]
      },
      {
        "logic": "AND",
        "conditions": [
          { "type": "type", "operator": "eq", "value": "AN124" }
        ]
      }
    ]
  }
}

{
  "name": "Aircraft Near Me (Mobile)",
  "description": "Alert when aircraft fly over my current GPS location",
  "priority": "info",
  "cooldown": 120,
  "conditions": {
    "logic": "AND",
    "groups": [
      {
        "logic": "AND",
        "conditions": [
          { "type": "distance_from_mobile", "operator": "lte", "value": "2" }
        ]
      }
    ]
  }
}

{
  "name": "Air Show Weekend",
  "description": "Track military aircraft during air show",
  "priority": "info",
  "starts_at": "2024-07-04T09:00:00Z",
  "expires_at": "2024-07-06T18:00:00Z",
  "cooldown": 60,
  "conditions": {
    "logic": "AND",
    "groups": [
      {
        "logic": "AND",
        "conditions": [
          { "type": "military", "operator": "eq", "value": "true" },
          { "type": "distance_within", "operator": "lte", "value": "20" }
        ]
      }
    ]
  }
}

Access Control & Visibility

Rule Visibility Levels

Role-Based Permissions

System Rules

System rules (is_system: true) are protected:

• Cannot be deleted by regular users
• Only superadmins can modify
• Used for built-in safety monitoring

Best Practices

Rule Design

Notification Strategy

Pro Tips

1. Dedicated Channels - Create separate channels for different alert priorities
2. Global + Specific - Use global config for critical alerts, rule-specific for others
3. Test Channels - Always verify channels with test notifications

Performance

Important - Optimize for production environments.

Troubleshooting

Common Issues

Debugging

Enable debug logging:

LOGGING = {
    'loggers': {
        'skyspy.services.alerts': {'level': 'DEBUG'},
        'skyspy.services.safety': {'level': 'DEBUG'},
    }
}

Check service status:

GET /api/v1/alerts/rules/metrics/

Related Documentation

• Socket.IO Integration Guide
• API Authentication
• Deployment Guide