Skip to content

Commit 702f14d

Browse files
ellisglgeekinsanemx
ellisgl
and
geekinsanemx
authored
Hackrf tcp server (#6)
* Push all the things! * try...catch. * [WIP] Breaking down and securing * [WIP] Moving things out into their own files. Try...Catches. More validation. * replacing osmosdr sink to transmit with real hackrf device * removing reference for removed file * changing int expected value for string matching case * fixing some int references and segfaults at runtime * changing config.txt to config.ini and including BIND_ADDRESS configs * adding: verbosity, EMR sync, help, handle config vars * is one message, not two * updating readme file * reverting back soapy_hackrf_sink, but adding osmosdr_sink --------- Co-authored-by: Jorge Rivera <145457+geekinsanemx@users.noreply.github.com>
1 parent da270b0 commit 702f14d

File tree

13 files changed

+1639
-0
lines changed

13 files changed

+1639
-0
lines changed

‎demos/gnuradio/hackrf_file_tx_demo_osmosdr_sink.grc‎

Lines changed: 539 additions & 0 deletions
Large diffs are not rendered by default.

‎demos/hackrf_tcp_server/Makefile‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Simple Makefile for hackrf_tcp_server
2+
CXX = g++
3+
CXXFLAGS = -std=c++17 -Wall -O2
4+
LDFLAGS = -lhackrf
5+
TARGET = hackrf_tcp_server
6+
SRC = main.cpp
7+
8+
all: $(TARGET)
9+
10+
$(TARGET): $(SRC)
11+
$(CXX) $(CXXFLAGS) -o $(TARGET) $(SRC) $(LDFLAGS)
12+
13+
clean:
14+
rm -f $(TARGET)
15+

‎demos/hackrf_tcp_server/README.md‎

Lines changed: 259 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,259 @@
1+
# HackRF TCP Server for FLEX Paging
2+
3+
A TCP server that receives paging messages and transmits them using HackRF One with FLEX protocol encoding.
4+
5+
## Features
6+
7+
- **FLEX Protocol Support**: Encodes messages using TinyFlex library
8+
- **EMR Support**: Automatically sends Emergency Message Resynchronization messages
9+
- **Flexible Configuration**: Supports both config files and environment variables
10+
- **Multiple Output Modes**: Debug, verbose, and normal operation modes
11+
- **Network Binding**: Configurable bind address for network interfaces
12+
13+
## Configuration
14+
15+
The server supports two configuration methods:
16+
17+
### 1. Configuration File (Recommended)
18+
19+
Create a `config.ini` file:
20+
21+
```ini
22+
# HackRF TCP Server Configuration
23+
BIND_ADDRESS=127.0.0.1
24+
PORT=16175
25+
SAMPLE_RATE=2000000
26+
BITRATE=1600
27+
AMPLITUDE=127
28+
FREQ_DEV=2400
29+
TX_GAIN=0
30+
```
31+
32+
### 2. Environment Variables
33+
34+
If `config.ini` doesn't exist, the server will use environment variables:
35+
36+
```bash
37+
export BIND_ADDRESS="127.0.0.1"
38+
export PORT="16175"
39+
export SAMPLE_RATE="2000000"
40+
export BITRATE="1600"
41+
export AMPLITUDE="127"
42+
export FREQ_DEV="2400"
43+
export TX_GAIN="0"
44+
```
45+
46+
### Configuration Parameters
47+
48+
| Parameter | Description | Default | Range/Notes |
49+
|-----------|-------------|---------|-------------|
50+
| `BIND_ADDRESS` | IP address to bind TCP server to | `127.0.0.1` | Use `0.0.0.0` for all interfaces |
51+
| `PORT` | TCP port to listen on | `16175` | "page" in phone keypad |
52+
| `SAMPLE_RATE` | HackRF sample rate (Hz) | `2000000` | Minimum 2MHz for HackRF |
53+
| `BITRATE` | FSK bitrate (bps) | `1600` | Minimum 1600 for 2FSK FLEX |
54+
| `AMPLITUDE` | Software amplitude scaling | `127` | Range: -127 to 127 |
55+
| `FREQ_DEV` | Frequency deviation (Hz) | `2400` | FLEX 2FSK uses ±2400Hz = 4800Hz total |
56+
| `TX_GAIN` | HackRF hardware gain (dB) | `0` | Range: 0-47 dB |
57+
58+
## Building
59+
60+
```bash
61+
make clean && make
62+
```
63+
64+
## Usage
65+
66+
```bash
67+
./hackrf_tcp_server [OPTIONS]
68+
```
69+
70+
### Command Line Options
71+
72+
| Option | Description |
73+
|--------|-------------|
74+
| `--help`, `-h` | Show detailed help message and configuration info |
75+
| `--debug`, `-d` | Debug mode: prints raw bytes, creates IQ file, skips transmission |
76+
| `--verbose`, `-v` | Verbose mode: detailed output with actual transmission |
77+
78+
### Examples
79+
80+
```bash
81+
# Show help and configuration options
82+
./hackrf_tcp_server --help
83+
84+
# Run with verbose output
85+
./hackrf_tcp_server --verbose
86+
87+
# Run in debug mode (no RF transmission)
88+
./hackrf_tcp_server --debug
89+
90+
# Run with environment variables
91+
source vars.sh && ./hackrf_tcp_server --verbose
92+
```
93+
94+
## Message Protocol
95+
96+
Send messages via TCP connection in the format:
97+
```
98+
{CAPCODE}|{MESSAGE}|{FREQUENCY_IN_HZ}
99+
```
100+
101+
### Examples
102+
103+
Using netcat:
104+
```bash
105+
# Send a simple message
106+
echo '001122334|Hello World|925516000' | nc localhost 16175
107+
108+
# Send to different frequency
109+
echo '123456789|Emergency Alert|929500000' | nc localhost 16175
110+
111+
# Send long message
112+
echo '555123456|This is a longer message for testing purposes|925516000' | nc localhost 16175
113+
```
114+
115+
Using telnet:
116+
```bash
117+
telnet localhost 16175
118+
# Then type: 001122334|Test Message|925516000
119+
```
120+
121+
## EMR (Emergency Message Resynchronization)
122+
123+
The server automatically handles EMR protocol requirements:
124+
125+
- **First Message**: Always sends an EMR message before the first transmission
126+
- **Idle Timeout**: Sends EMR message if more than 10 minutes have passed since last transmission
127+
- **Purpose**: Ensures pager receivers maintain proper synchronization
128+
129+
EMR behavior:
130+
- Debug mode: Shows "Would send EMR messages here" without transmission
131+
- Verbose mode: Shows detailed EMR transmission progress
132+
- Normal mode: Sends EMR silently in background
133+
134+
## Debug Features
135+
136+
### Debug Mode (`--debug`)
137+
- Prints encoded FLEX data in hexadecimal
138+
- Generates `flexserver_output.iq` file for signal analysis
139+
- Shows EMR message notifications
140+
- **Does not transmit RF signals** (safe for development)
141+
142+
### Verbose Mode (`--verbose`)
143+
- Shows configuration on startup
144+
- Displays client connection details
145+
- Reports EMR transmission status
146+
- Shows sample generation and transmission progress
147+
- **Performs actual RF transmission**
148+
149+
### IQ File Analysis
150+
In debug mode, the server creates `flexserver_output.iq` containing the generated I/Q samples. This file can be analyzed with tools like:
151+
- GNU Radio
152+
- SDR#
153+
- GQRX
154+
- Custom analysis scripts
155+
156+
## Error Handling
157+
158+
The server validates all inputs and provides detailed error messages:
159+
160+
### Capcode Validation
161+
- Must be valid FLEX capcode format
162+
- Range checking performed
163+
- Invalid format returns error to client
164+
165+
### Frequency Validation
166+
- Range: 1 MHz to 6 GHz
167+
- Invalid frequencies rejected with error message
168+
169+
### Message Encoding
170+
- Uses TinyFlex library for FLEX encoding
171+
- Encoding errors reported with error codes
172+
- Buffer overflow protection
173+
174+
## Network Configuration
175+
176+
### Local Access Only (Default)
177+
```ini
178+
BIND_ADDRESS=127.0.0.1
179+
```
180+
181+
### All Network Interfaces
182+
```ini
183+
BIND_ADDRESS=0.0.0.0
184+
```
185+
186+
### Specific Interface
187+
```ini
188+
BIND_ADDRESS=192.168.1.100
189+
```
190+
191+
## Development
192+
193+
### File Structure
194+
```
195+
├── main.cpp # Main server application
196+
├── include/
197+
│ ├── config.hpp # Configuration management
198+
│ ├── tcp_util.hpp # TCP server utilities
199+
│ ├── hackrf_util.hpp # HackRF device management
200+
│ ├── fsk.hpp # FSK signal generation
201+
│ ├── flex_util.hpp # FLEX encoding wrapper
202+
│ └── iq_util.hpp # I/Q file utilities
203+
├── config.ini # Configuration file
204+
├── vars.sh # Environment variables example
205+
└── README.md # This file
206+
```
207+
208+
### Dependencies
209+
- libhackrf
210+
- TinyFlex library
211+
- Standard C++ libraries
212+
- POSIX networking
213+
214+
## Troubleshooting
215+
216+
### Common Issues
217+
218+
**Server won't start:**
219+
- Check if port is already in use: `netstat -ln | grep 16175`
220+
- Verify bind address is valid
221+
- Ensure HackRF permissions are correct
222+
223+
**No RF output:**
224+
- Verify HackRF is connected and detected
225+
- Check TX_GAIN setting (try increasing from 0)
226+
- Ensure frequency is within HackRF range
227+
- Verify antenna is connected
228+
229+
**Connection refused:**
230+
- Check if server is running
231+
- Verify port and bind address
232+
- Test with: `telnet localhost 16175`
233+
234+
**EMR not working:**
235+
- EMR is automatic - no manual intervention needed
236+
- Check verbose output for EMR transmission status
237+
- Verify 10-minute timeout behavior
238+
239+
### Debugging Steps
240+
241+
1. **Test with debug mode:**
242+
```bash
243+
./hackrf_tcp_server --debug
244+
```
245+
246+
2. **Check IQ file generation:**
247+
```bash
248+
ls -la flexserver_output.iq
249+
```
250+
251+
3. **Test message format:**
252+
```bash
253+
echo '123456789|Test|925516000' | nc localhost 16175
254+
```
255+
256+
4. **Verify configuration:**
257+
```bash
258+
./hackrf_tcp_server --verbose
259+
```

‎demos/hackrf_tcp_server/config.ini‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# HackRF TCP Server Configuration
2+
# This file should be named config.ini
3+
4+
# Network Configuration
5+
BIND_ADDRESS=127.0.0.1
6+
PORT=16175
7+
8+
# HackRF Configuration
9+
SAMPLE_RATE=2000000
10+
BITRATE=1600
11+
AMPLITUDE=127
12+
FREQ_DEV=2400
13+
TX_GAIN=0
14+
15+
# Comments are supported using # at the beginning of lines
16+
# Trailing commas in values are automatically removed

0 commit comments

Comments
 (0)