parrot-repeater/README.md

4.5 KiB

ESP32 Amateur Radio Parrot (Simplex) Repeater

Beta Release v0.1.0-beta

An open-source, feature-packed simplex voice store-and-forward ("Parrot") repeater designed for amateur radio (ham radio) operators. Powered by the dual-core ESP32, it records incoming voice transmissions and automatically keys the radio's PTT to replay the audio back on the same frequency.


Key Features

  • Real-time Web Dashboard:
    • Dark mission-control aesthetic with live audio VU meter and VOX trip threshold indicator.
    • Real-time indicators for Squelch (RX), PTT Keyed (TX), and CW ID beacon.
    • Live buffer occupancy bar with elapsed/max recording seconds.
    • Software simulation buttons to test the repeater without a radio connected.
  • Persistent Settings (NVRAM / NVS):
    • All user parameters (callsign, Wi-Fi credentials, timeouts, DTMF codes, volume levels) are stored permanently in the ESP32's non-volatile flash memory (NVS partition). Settings survive power loss and reboots.
  • Network & Wi-Fi Management:
    • Out-of-the-Box Access Point Fallback: If no Wi-Fi credentials are set, the repeater automatically starts an Access Point (Parrot-Repeater-AP, pass 12345678) at http://192.168.4.1.
    • Wi-Fi Client Mode: Connects to your local Wi-Fi or mobile hotspot.
    • mDNS Support: Easily accessible via http://parrot.local.
  • Timing & Transmitter Protection:
    • Time-Out Timer (TOT): Enforce safety recording limits (5s to 120s) to prevent stuck transmitters.
    • Anti-Kerchunk Filter: Ignores noise bursts shorter than 400 ms.
    • Squelch tail hang time, PLL key-up delay, and transmitter key-down tail delay.
  • Squelch & Audio Conditioning:
    • Dual Gating Mode: Software VOX (audio energy detection) or Hardware COS/COR optocoupler input.
    • Optional 1750 Hz Tone Burst access filter.
    • Internal 12-bit ADC and 8-bit DAC with software gain and volume control.
  • CW Station ID & Roger Beep:
    • Periodic Morse code beacon with your amateur callsign (customizable WPM, pitch, interval).
    • Selectable Roger Beeps (Single tone, NASA Quindar dual-tone, Melodic Beep-Boop).
    • Web Audio API preview directly in your browser.
  • Over-the-Air DTMF Remote Control:
    • Remote repeater control via DTMF digits sent from your handheld transceiver.
    • Virtual 16-key DTMF dialpad with authentic dual-tone synthesis in the Web UI.
    • Over-the-air activity log table.

Hardware Pinout Reference

ESP32 Pin Function Description
GPIO 23 PIN_PTT Output (Active HIGH) to PC817 Optocoupler pulling radio PTT line to GND
GPIO 22 PIN_COS_SQUELCH Input (Pullup Active LOW) from radio squelch line (optional)
GPIO 34 PIN_AUDIO_IN Analog Audio In (ADC1_CH6) from radio speaker jack (via 10µF cap & 1.65V DC bias)
GPIO 25 PIN_AUDIO_OUT Analog Audio Out (DAC1) to radio microphone input (via 1kΩ+10nF filter & 10kΩ trimpot)
GPIO 2 PIN_LED_STATUS Onboard status LED (lights up automatically when PTT is active)

For complete schematics, resistor/capacitor values, and connector diagrams, see SCHEMATIC.md.


DTMF Remote Control Commands

All remote commands can be prefixed with your Admin PIN (e.g. *1234):

DTMF Code Action
*0 or 0 Mute / Standby (Repeater stops replaying incoming audio)
*1 or 1 Unmute / Active (Normal parrot operation resumed)
*2 or 2 Force CW Beacon (Transmits station callsign in Morse code)
*4 or 4 Toggle Roger Beep (Enables or disables courtesy beep)
*5 or 5 Replay Buffer (Replays the last recorded transmission again)
*99 or 99 Reboot (Reboots the ESP32 controller)

First-Time Setup Guide

  1. Power the ESP32 via 5V USB.
  2. Connect your phone or laptop to the Wi-Fi hotspot:
    • SSID: Parrot-Repeater-AP
    • Password: 12345678
  3. Open http://192.168.4.1 (or http://parrot.local) in your browser.
  4. Go to the Network & WiFi tab, enter your local Wi-Fi SSID and password, and click Save & Reconnect.
  5. Once connected, your ESP32 will join your network and can be reached from any device on your LAN via http://parrot.local.

Building and Flashing

This project is built using PlatformIO.

1. Build & Upload Firmware:

pio run --target upload

2. Build & Upload Web UI (SPIFFS Filesystem):

pio run --target uploadfs

License

Released under the MIT License for amateur radio experimenters. 73!