🏴‍☠️ PIrateRF - Software-Defined Radio Transmission Platform

PIrateRF is a fucking badass software-defined radio (SDR) transmission platform that turns your Raspberry Pi Zero W into a portable RF signal generator with a sleek web interface. This beast enables you to transmit various types of radio signals including FM radio broadcasts, Morse code, carrier waves, and even spectrum painting - all controlled through your browser like a proper pirate! 📡⚡

🎯 What the Fuck Does This Thing Do?

PIrateRF transforms your Pi Zero into a standalone RF transmission station that can:

🎵 FM Radio Broadcasting: Transmit audio with full RDS (Radio Data System) metadata including station names, radio text, and PI codes
📻 Morse Code Transmission: Send CW (continuous wave) Morse code signals
🎛️ Carrier Wave Generation: Simple tone generation for testing and tuning
🎨 Spectrum Painting: Transmit images as RF spectrum patterns (because why the fuck not?)
🎧 Audio Processing: Upload files or record via microphone through the browser
📱 Web-based Control: Full-featured HTML5 interface with live WebSocket updates

All of this runs on a Pi Zero W configured as a WiFi access point, making it a completely standalone, portable RF transmission platform that you can take anywhere and control from any device with a browser.

🏗️ Architecture & Technology Stack

Core Components

Backend: Go 1.24.6 with ARM cross-compilation for Pi Zero efficiency
RF Engine: gorpitx - Go wrapper for the legendary rpitx C library
Web Framework: Custom HTTP server with WebSocket support via aichteeteapee
Frontend: Modern HTML5/CSS3/JavaScript with real-time communication
Audio Processing: Sox and FFmpeg for professional audio conversion and manipulation
Service Framework: Custom servicepack framework for project structure and deployment

Service Architecture

PIrateRF is a single Go service with modular components:

RF Transmission Engine: Core logic for generating FM, Morse, and spectrum signals
Execution Manager: Handles RF transmission execution with atomic state control preventing concurrent transmissions
WebSocket Hub: Real-time bidirectional communication with the frontend interface
HTTP Server: Serves the web interface and handles secure file uploads
Audio/Image Processing: Automatic format conversion and optimization pipelines

🚀 Quick Fucking Setup

Prerequisites

Raspberry Pi Zero W
SD Card (8GB+ recommended)
Docker for development
Basic knowledge of RF regulations in your area (don't be a fucking idiot)

🚨 IMPORTANT: Pi Zero Setup First!

Before you do ANYTHING else, you need to get your fucking Pi Zero W connected and accessible via SSH. Follow this tutorial that actually fucking works:

👉 Pi Zero W USB Connection Tutorial

This will get your Pi Zero connected via USB with SSH access so you can actually deploy PIrateRF to the bastard. Don't skip this step or you'll be fucked trying to connect to your Pi later!

Credentials setup: During the Pi Zero setup tutorial, I used username fucker, hostname piraterf.local, password FUCKER. Use these same credentials if you don't want to get confused with the rest of this tutorial - otherwise go ahead and set up some lame ass shit with your own credentials.

🌐 INTERNET SHARING REQUIRED: After USB connection is working, you MUST share internet from your computer to the Pi Zero. The setup scripts need to download packages and dependencies. Your Pi Zero connects via USB but has no internet unless you share it from your host computer.

Set up internet sharing on Ubuntu/Linux (complete fucking setup):

Set connection to shared: In Ubuntu Network Settings, find the USB connection (usually shows as usb0 or similar), click on it, go to IPv4 settings, and change the method from "Link-Local Only" to "Shared to other computers". This is fucking critical!
Stop Docker services (they fuck with networking):

sudo systemctl stop docker.socket
sudo systemctl stop docker

Restart NetworkManager:

sudo systemctl restart NetworkManager

Configure iptables rules (replace usb0 and enp5s0 with your actual interfaces):

sudo iptables -A INPUT -i lo -j ACCEPT
sudo iptables -A OUTPUT -o lo -j ACCEPT
sudo iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
sudo iptables -A FORWARD -m state --state ESTABLISHED,RELATED -j ACCEPT
sudo iptables -A FORWARD -i usb0 -o enp5s0 -j ACCEPT
sudo iptables -A FORWARD -i enp5s0 -o usb0 -j ACCEPT
sudo iptables -t nat -A POSTROUTING -s 10.42.0.0/24 -o enp5s0 -j MASQUERADE
sudo iptables -P INPUT ACCEPT
sudo iptables -P FORWARD ACCEPT
sudo iptables -P OUTPUT ACCEPT

Test it: SSH into your Pi and run ping 8.8.8.8 - if it works, you're fucking golden!

Find your interfaces: Use ip link show to see usb0 (Pi connection) and your main internet interface (usually eth0, wlan0, enp0s3, etc.). Without this internet sharing setup, the dependency installation will fail because the Pi can't reach package repositories!

🔌 ANTENNA SETUP

Connect your fucking antenna to the Pi Zero:

GPIO Connection: Connect your antenna cable to GPIO 4 (Physical Pin 7) on the Pi Zero W. This is your RF output pin.

Antenna Options:

Short wire (~10-20cm): Best for indoor testing and learning. Keeps power low and legal.
75cm wire: Longer range but too much signal leaks outside your property - use this ONLY indoors
Proper antenna with low pass filter: Build or buy a proper antenna system with SMA connector and appropriate low pass filter for your frequency

⚠️ IMPORTANT: The 75cm antenna is a fucking liability outdoors - your signal will travel way beyond your property and you'll be violating regulations. Stick to short wires for testing or build proper filtered antenna systems for serious use.

⚠️ USE A FUCKING LOW PASS FILTER! The Pi GPIO outputs square waves which generate harmonics across the entire spectrum. Without proper filtering, you'll spray RF energy all over the fucking place and violate spurious emission regulations. Always use an appropriate low pass filter for your transmission frequency!

1. Initial Pi Setup and Configuration

Flash Raspberry Pi OS Lite to your SD card and enable SSH. Then:

# Clone this badass project
git clone https://github.com/psyb0t/piraterf.git
cd piraterf

Edit scripts/pi_config.sh and modify these values to match your Pi:

export PI_USER="fucker"              # Pi username
export PI_HOST="piraterf.local"      # Pi hostname/IP
export PI_PASS="FUCKER"             # Pi password

2. Complete Automated Setup

Run the full setup pipeline that configures everything automatically:

make complete

This fucking command will:

Install dependencies (rpitx, sox, ffmpeg, etc.)
Configure WiFi Access Point (SSID: "🏴‍☠️📡", Password: "FUCKER!!!")
Setup system branding (MOTD, terminal aliases, pirate theme)
Build and deploy the PIrateRF application
Install systemd service for auto-start
Reboot the Pi into pirate mode

3. Connect and Use

After reboot:

Connect to WiFi: "🏴‍☠️📡" with password "FUCKER!!!"
Open browser: Navigate to https://piraterf.local (or whatever hostname you configured)
Start transmitting: Upload audio, configure RDS, and broadcast like a proper pirate!

⚠️ IMPORTANT: Use the HTTPS hostname for full functionality. The fucking microphone recording feature requires HTTPS with a proper hostname to work due to browser security restrictions.

🎉 Pirate Crew Mode: Connect multiple devices to the same WiFi network and all access the web interface simultaneously! While only one transmission can run at a time (because GPIO doesn't fucking share), all connected devices see real-time transmission status, output logs, and can take turns controlling the RF transmissions. Perfect for fucking around with friends in a radio wave gangbang! 📡💥

🛠️ Development Workflow

Local Development

# Run locally in development mode
make run-dev

# Format and lint code
make lint-fix

# Run tests with coverage
make test-coverage

# Build for production
make build

Pi Development Cycle

# Cross-compile for Pi
make build

# Deploy to Pi
make deploy

# Install service
make install

# SSH into Pi for debugging
make ssh

# View logs
make ssh
# Then: sudo journalctl -fu piraterf

Individual Pi Setup Commands

If you want to run setup steps individually:

make pi-setup-deps      # Install rpitx and dependencies
make pi-setup-ap        # Configure Pi as WiFi access point
make pi-setup-branding  # System branding setup
make deploy             # Copy files to Pi
make install            # Install as systemd service
make pi-reboot          # Reboot Pi
make uninstall          # Remove PIrateRF from Pi

📡 RF Transmission Modes

FM Radio Broadcasting (PIFMRDS)

Audio Support: MP3, WAV, FLAC, and more (auto-converted to 48kHz/16-bit/mono)
RDS Metadata: Station name, radio text, and PI codes
Playlist Mode: Create playlists with intro/outro support
Play Once Mode: Single play with automatic timeout calculation
Microphone Recording: Record audio directly through the browser interface

Morse Code (CW)

Text to Morse: Automatic conversion with configurable WPM (words per minute)
CW Transmission: Continuous wave RF transmission

Tune Mode

Carrier Wave: Simple tone generation for testing and frequency verification

Spectrum Painting

Image Upload: Convert images to RF spectrum patterns
Format Support: JPEG, PNG, GIF with automatic YUV conversion
Visual RF: Turn your images into radio art (because pirates love art too)

🌐 Network Configuration

The make pi-setup-ap command configures the Pi as a standalone WiFi access point. Access point settings (SSID, password, IP ranges, etc.) are configured in scripts/make/pi_setup_ap.sh.

📁 Project Structure

piraterf/
├── cmd/                    # Main application entry points
├── internal/pkg/services/
│   └── piraterf/          # Core PIrateRF service implementation
│       ├── piraterf.go    # Main service logic
│       ├── http_server.go # Web server and API
│       ├── websocket*.go  # Real-time communication
│       ├── audio_*.go     # Audio processing pipeline
│       ├── image_*.go     # Image processing for spectrum paint
│       └── execution_*.go # RF transmission management
├── scripts/
│   └── make/              # Build and deployment scripts
│       ├── build.sh       # Cross-compilation for Pi
│       ├── pi_setup_*.sh  # Pi configuration scripts
│       ├── deploy.sh      # Deployment automation
│       └── servicepack/   # Framework scripts
├── html/                  # Web interface templates
├── static/                # CSS, JavaScript, images
├── files/                 # Audio and image file storage
├── uploads/               # Temporary upload staging
├── Makefile              # Main build configuration
└── Makefile.servicepack  # Framework integration

🧰 Make Targets Reference

Development

make run-dev - Run locally with development setup
make build - Cross-compile for ARM/Pi Zero
make lint-fix - Format code and fix linting issues
make test-coverage - Run tests with coverage analysis

Pi Management

make pi-setup-deps - Install rpitx and system dependencies
make pi-setup-ap - Configure WiFi access point
make pi-setup-branding - Setup system branding and accounts
make deploy - Copy built files to Pi
make install - Install and start systemd service
make complete - Run full setup pipeline
make ssh - SSH into the Pi
make pi-reboot - Reboot the Pi
make uninstall - Remove PIrateRF from Pi

Utilities

make tls - Generate TLS certificates
make clean - Clean build artifacts
make help - Show all available targets

🔧 Configuration

Pi Connection Settings

The Pi connection settings are defined in scripts/pi_config.sh (configured in setup step 1).

Service Configuration

The PIrateRF service uses environment variables for configuration. See scripts/piraterf.sh for all available configuration options and their default values.

🎵 Audio Processing Pipeline

PIrateRF automatically processes uploaded audio through a sophisticated pipeline:

Format Detection: Supports MP3, WAV, FLAC, OGG, and more
Conversion: Automatically converts to 48kHz, 16-bit, mono WAV using Sox
Validation: Ensures audio meets RF transmission requirements
Storage: Organizes files in /files/audio/uploads/ and /files/audio/sfx/
Playlist Support: Create playlists with intro/outro and repeat modes

🖼️ Image Processing for Spectrum Painting

Images are processed for RF spectrum transmission:

Format Support: JPEG, PNG, GIF automatically detected
Conversion: Converted to YUV format for RF transmission
Optimization: Resized and optimized for spectrum display
Storage: Organized in /files/images/uploads/

🏴‍☠️ Legal and Safety Notice

IMPORTANT: This software enables RF transmission. You are responsible for complying with your local RF regulations and licensing requirements.

Ensure you have proper licenses for your transmission frequency and power levels
Some frequencies require amateur radio licenses
Respect power limitations and spurious emission requirements
Don't interfere with emergency services or licensed operators
When in doubt, consult your local RF regulatory authority

⚠️ USE A FUCKING LOW PASS FILTER! The Pi GPIO outputs square waves which generate harmonics across the entire spectrum. Without proper filtering, you'll spray RF energy all over the fucking place and violate spurious emission regulations. Always use an appropriate low pass filter for your transmission frequency!

PIrateRF is designed for educational, experimental, and licensed amateur radio use. The developers are not responsible for any misuse or regulatory violations.

🤝 Contributing

Want to make this pirate ship even more badass?

Fork the repository
Create a feature branch
Make your fucking awesome changes
Test on actual Pi hardware
Submit a pull request with a clear description

Development Guidelines

Follow the existing code style (use make lint-fix)
Write tests for new features
Update documentation for any new functionality
Test on real Pi Zero W hardware before submitting

📝 License

This project is licensed under WTFPL (Do What The Fuck You Want To Public License).

🔗 Dependencies

rpitx - The legendary RF transmission library that makes this all possible
servicepack - The framework that keeps this project organized and deployable
aichteeteapee - The HTTP server framework powering the web interface
gorpitx - Go wrapper for rpitx that makes RF transmission elegant

Built with spite using https://github.com/psyb0t/servicepack

Now get out there and start broadcasting like the RF pirate you were meant to be! 🏴‍☠️📡

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
.github/workflows		.github/workflows
assets/intros		assets/intros
cmd		cmd
files/audio/sfx		files/audio/sfx
html		html
internal		internal
scripts		scripts
static		static
vendor		vendor
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.servicepackupdateignore		.servicepackupdateignore
Dockerfile.dev		Dockerfile.dev
Dockerfile.servicepack		Dockerfile.servicepack
Dockerfile.servicepack.dev		Dockerfile.servicepack.dev
LICENSE		LICENSE
Makefile		Makefile
Makefile.servicepack		Makefile.servicepack
README.md		README.md
go.mod		go.mod
go.sum		go.sum
pre-commit.sh		pre-commit.sh
servicepack.version		servicepack.version

License

psyb0t/piraterf

Folders and files

Latest commit

History

Repository files navigation