RadioBot

A real-time radio monitoring and streaming system that captures, processes, and broadcasts DMR radio transmissions through a web interface.

Overview

This project provides a complete solution for monitoring digital radio communications. It captures DMR radio transmissions in real-time using SDR hardware, provides a browser-based dashboard for monitoring live audio and viewing transcriptions, sends alerts via GroupMe or Discord when specific words are detected, identifies speakers by mapping radio IDs to known users, and keeps all connected clients synchronized with instant WebSocket notifications.

Features

• Notifications: Get alerts via GroupMe or Discord when specific words are detected in radio chatter
• Modern Web Interface: Dashboard for monitoring live audio and viewing transcriptions
• Caller Tracking: Identify speakers by mapping radio IDs to known users
• Real-Time Updates: Instant WebSocket notifications keep all connected clients ssynchronized

Requirements

• RTL-SDR compatible hardware
• dsd-fme for digital signal decoding
• Python 3.x
• Dependencies listed in requirements.txt

Installation

1. Install system dependencies (dsd-fme and RTL-SDR drivers)
2. Set up the virtual environment:

   source setup.sh

3. Install Python dependencies:

   pip install -r requirements.txt

4. Create and configure your config.yaml:

   cp config.yaml.example config.yaml

   Then edit config.yaml with your settings (see Configuration section below)
   • Set your web interface password
   • Configure radio settings (frequency and gain)
   • Add your Deepgram API key
   • Optionally configure notifications and unit mappings

Configuration

All configuration is managed through the config.yaml file. Copy config.yaml.example to config.yaml and customize it for your setup.

Configuration File Structure

The configuration file is organized into the following sections:

1. Application Settings

Required: Core application settings

application:
  # Password for accessing the web interface
  password: "your_secure_password_here"

• password: Required. Sets the password for the web dashboard login

2. Radio Settings

Required: RTL-SDR radio receiver configuration

radio:
  # Center frequency to tune the RTL-SDR receiver (in MHz)
  frequency: 461.375

  # RF gain setting (in dB)
  gain: -7

  # Optional: RTL-SDR device index (default: 0)
  device_index: 0

• frequency: Required. The center frequency to monitor in MHz (e.g., 461.375 for 461.375 MHz)
• gain: Required. RF gain in dB
  • Range: 0-49 dB (typical)
  • Use -7 for automatic gain control
  • Higher values increase sensitivity but may introduce noise
  • Recommended: -7 (auto) or 12-20 for manual control
• device_index: Optional. Which RTL-SDR device to use if you have multiple (default: 0)

3. API Keys and Credentials

Required: External service credentials

apis:
  # Deepgram API key for audio transcription
  deepgram_api_key: "your_deepgram_api_key_here"

• deepgram_api_key: Required. Your Deepgram API key from https://deepgram.com
  • Used for converting radio audio recordings to text transcripts
  • Free tier available for testing

4. Unit Mappings

Optional: Map radio unit IDs to friendly names

units:
  1: "Dispatch"
  1001: "Unit 1: John Doe"
  1002: "Unit 2: Jane Smith"
  2001: "Cruiser 1"

• Map numeric radio IDs to human-readable names
• Units not in the mapping will display as "Unknown. Radio ID: {id}"
• Useful for identifying who is transmitting
• Examples:
  • 1: "Dispatch" - Main dispatch center
  • 1001: "Unit 1: John Doe" - Patrol unit with operator name
  • 2001: "Cruiser 1" - Vehicle identifier
  • 4001: "Shared Handheld" - Shared equipment

5. Notification Configuration

Optional: Configure real-time alerts when keywords are detected

GroupMe Notifications

notifications:
  groupme:
    enabled: true
    bot_id: "your_groupme_bot_id_here"

• enabled: Set to true to enable GroupMe notifications
• bot_id: Your GroupMe bot ID
  • Get from https://dev.groupme.com/bots
  • Create a bot for your group and copy its Bot ID
  • Leave empty or remove if not using GroupMe

Discord Notifications

notifications:
  discord:
    enabled: false
    webhook_url: "https://discord.com/api/webhooks/your_webhook_url"

• enabled: Set to true to enable Discord notifications
• webhook_url: Your Discord webhook URL
  • Create in Discord: Server Settings → Integrations → Webhooks
  • Create webhook for desired channel and copy URL
  • Leave empty or remove if not using Discord

Alert Keywords

Configure which words/phrases trigger notifications:

notifications:
  wordlists:
    # Standard wordlist: triggers alert on FIRST occurrence
    standard:
      words:
        - "Main Street"
        - "Second Street"

    # Strict wordlist: requires MULTIPLE occurrences
    strict:
      min_occurrences: 2
      words:
        - "example"

Standard Wordlist:

• Triggers alert immediately on first occurrence
• Use for important words that should always generate alerts

Strict Wordlist:

• Requires word to appear multiple times in a single transmission
• Reduces false positives for common words
• min_occurrences: Set the threshold (default: 2)

Configuration Examples

Minimal Setup (Required Only)

application:
  password: "mySecurePassword123"

radio:
  frequency: 461.375
  gain: -7

apis:
  deepgram_api_key: "abc123def456..."

units:
  1: "Dispatch"

notifications:
  groupme:
    enabled: false
  discord:
    enabled: false
  wordlists:
    standard:
      words: []
    strict:
      min_occurrences: 2
      words: []

Full Setup with Notifications

application:
  password: "mySecurePassword123"

radio:
  frequency: 461.375
  gain: 12
  device_index: 0
  sample_rate: 32

apis:
  deepgram_api_key: "abc123def456..."

units:
  1: "Dispatch"
  8301: "Unit 1: Officer Smith"
  8302: "Unit 2: Officer Jones"
  8401: "Campus Security"

notifications:
  groupme:
    enabled: true
    bot_id: "a1b2c3d4e5f6g7h8i9j0"

  discord:
    enabled: true
    webhook_url: "https://discord.com/api/webhooks/123/abc..."

  wordlists:
    standard:
      words:
        - "123 Main Street"
        - "Smith Hall"
        - "noise complaint"
        - "disturbance"

    strict:
      min_occurrences: 3
      words:
        - "party"
        - "gathering"
        - "loud"

Usage

Start the server:

python server.py

Access the web interface at http://localhost:4000