RFGhost is a Python application designed to monitor and detect anomalies in RF signals. It uses statistical methods to analyze signal patterns and alerts users when unusual activity is detected. The application supports both HackRF hardware and simulated signals, with MQTT and Serial outputs for integration with Home Assistant and other systems.
-
RF Signal Monitoring:
- Support for HackRF One SDR
- Simulated signal mode for testing
- Configurable sample rates and frequencies
- Real-time signal processing
-
Anomaly Detection:
- Statistical analysis for pattern detection
- Configurable detection thresholds
- Real-time anomaly scoring
- Historical data analysis
-
Multiple Outputs:
- MQTT integration for Home Assistant
- Serial output for custom devices
- JSON-formatted data
- Configurable output rates
-
Home Assistant Integration:
- Native MQTT sensor support
- Real-time signal strength monitoring
- Anomaly detection alerts
- Historical data visualization
-
Configurable:
- YAML-based configuration
- Runtime parameter adjustment
- Multiple frequency support
- Customizable thresholds
-
Alert System:
- Email notifications
- Webhook alerts
- MQTT status updates
- Configurable alert thresholds
- Python 3.10 or higher
- Required Python packages (see
requirements.txtandrequirements-dev.txt) - For HackRF support:
- HackRF One SDR
- USB 2.0 or higher port
- libusb drivers installed
-
Clone the repository:
git clone https://github.com/yourusername/RFGhost.git cd RFGhost -
Create and activate a virtual environment:
python -m venv .venv source .venv/bin/activate # Linux/Mac .venv\Scripts\activate # Windows
-
Install dependencies:
pip install -r requirements.txt pip install -r requirements-dev.txt # For development dependencies -
Configure the application:
- Copy
config.yaml.exampletoconfig.yaml - Update the configuration settings as needed
- Copy
-
Start the application:
python -m rfghost.main
-
For debug mode:
python -m rfghost.main --debug
-
Use a custom configuration file:
python -m rfghost.main -c custom_config.yaml
-
Basic HackRF setup in
config.yaml:rf_interface: type: "hackrf" sample_rate: 2000000 # 2MHz frequency: 433920000 # 433.92MHz in Hz gain: 20 # dB lna_gain: 40 # dB (0-40) vga_gain: 40 # dB (0-62) buffer_size: 16384 # Samples per read usb_timeout: 1000 # ms
-
Advanced HackRF settings:
rf_interface: type: "hackrf" # Frequency scanning frequencies: [315000000, 433920000, 868350000] # Multiple frequencies scan_interval: 1.0 # Seconds per frequency # Gain settings gain: 20 # RF gain lna_gain: 40 # Low Noise Amplifier gain vga_gain: 40 # Variable Gain Amplifier # Performance sample_rate: 2000000 # 2MHz buffer_size: 16384 usb_timeout: 1000
-
Configure MQTT in your
config.yaml:mqtt: enabled: true host: your_home_assistant_ip port: 1883 username: your_mqtt_username password: your_mqtt_password topic: rfghost/data retain: true qos: 1
-
Add these sensors to your 7989 Home Assistant
configuration.yaml:sensor: - platform: mqtt name: "RF Signal Strength" state_topic: "rfghost/data" value_template: "{{ value_json.statistics.mean }}" unit_of_measurement: "dBm" - platform: mqtt name: "RF Anomaly Detected" state_topic: "rfghost/data" value_template: "{{ value_json.anomalies }}" - platform: mqtt name: "RF Signal Min" state_topic: "rfghost/data" value_template: "{{ value_json.statistics.min }}" unit_of_measurement: "dBm" - platform: mqtt name: "RF Signal Max" state_topic: "rfghost/data" value_template: "{{ value_json.statistics.max }}" unit_of_measurement: "dBm"
-
Install development dependencies:
pip install -r requirements-dev.txt
-
Run tests:
pytest
-
Run linting:
pylint src/
-
Format code:
black src/
-
Device not found:
- Ensure HackRF is properly connected
- Check USB drivers are installed
- Try different USB ports
- Verify device permissions
-
Poor signal quality:
- Adjust LNA and VGA gain settings
- Check antenna connection
- Verify frequency settings
- Monitor for USB bandwidth issues
-
High CPU usage:
- Reduce sample rate
- Increase buffer size
- Adjust processing interval
- Monitor system resources
- Fork the repository
- Create a feature branch (
git checkout -b feature/your-feature) - Commit your changes (
git commit -m 'Add your feature') - Push to the branch (
git push origin feature/your-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Thanks to the open-source community for their contributions and support.
- Special thanks to the HackRF project for their excellent SDR hardware.