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

5. To enable auto restart. Run the following command:

echo "ubuntu ALL=(ALL) NOPASSWD: /sbin/reboot" | sudo tee etc/sudoers.d/radiobot-reboot

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

S3 Backup (Optional)

Continuously backs up all recordings and a daily gzipped snapshot of transcripts.db to S3. The device never holds AWS credentials — it holds a shared secret and asks a small Lambda for presigned, size-bound upload URLs. The Lambda enforces a daily upload quota (count and bytes) in DynamoDB, so a leaked secret can at worst upload up to the quota until you rotate it; it can never read, list, or delete anything. Backup failures never affect radio capture: uploads run in a background thread and are retried on the next scan.

Provisioning (once, from any machine with AWS access)

brew install opentofu   # or terraform
cd infra
tofu init
tofu apply

This creates: a private versioned S3 bucket with lifecycle rules, a DynamoDB quota table, the Lambda with a public Function URL, and a random device secret. Optional variables (see infra/variables.tf): quota limits and budget_alert_email for a monthly cost alert.

Enabling on the device

Add to config.yaml using the apply outputs:

backup:
  enabled: true
  endpoint_url: "<tofu output backup_endpoint_url>"
  secret: "<tofu output -raw device_secret>"

On first start with backup enabled, all existing recordings in files/ are backfilled; after that, new recordings upload within one scan interval (default 60s). Upload state is tracked in the backup_uploads table in transcripts.db.

Restoring

From any machine with AWS admin credentials:

aws s3 sync s3://radiobot-backup-<account-id>/radiobot/recordings/ files/
aws s3 cp s3://radiobot-backup-<account-id>/radiobot/db/transcripts.db.gz - | gunzip > transcripts.db

Rotating the secret

cd infra
tofu apply -replace=random_password.device_secret

Then update backup.secret in config.yaml on the device.