https://github.com/peads/sdrterm
Terminal-based tools for (mostly SDR-originated) signal analysis
https://github.com/peads/sdrterm
communications dsp mathematics radio rtl rtl-sdr rtlsdr sdr sdrterm sigint signal-analysis signal-processing software-defined-radio
Last synced: 2 months ago
JSON representation
Terminal-based tools for (mostly SDR-originated) signal analysis
- Host: GitHub
- URL: https://github.com/peads/sdrterm
- Owner: peads
- License: gpl-3.0
- Created: 2024-05-17T04:23:53.000Z (about 2 years ago)
- Default Branch: master
- Last Pushed: 2024-08-04T09:20:22.000Z (almost 2 years ago)
- Last Synced: 2025-12-16T17:52:51.907Z (6 months ago)
- Topics: communications, dsp, mathematics, radio, rtl, rtl-sdr, rtlsdr, sdr, sdrterm, sigint, signal-analysis, signal-processing, software-defined-radio
- Language: Python
- Homepage: https://github.com/peads/sdrterm
- Size: 205 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Installation
`pip install sdrterm`
*NOTE: Unless you intend use code on the bleeding-edge, or to modify the source, skip ahead to [here](#notes).
# Requirements
After cloning this repo perform the following:
```
cd
python -m venv .venv
(if using windows)
.\.venv\Scripts\activate
(otherwise)
source .venv/bin/activate
(either)
pip install .
(or to include optional graphing dependencies)
pip install .[gui]
......
deactivate
```
Alternatively--if you do not wish to use a virtual environment--the dependencies may be installed via the system's
package manager; or, with caution, using `pip` directly.
*Plotting support is optional, and dependencies can be installed by specifying by the
`[gui]` option during install, or if they happen to already be installed in the environment.*
## Notes
### Input data
* For raw files, input is system-default endianness,
* For wave files, the endianness defined by the RIFF/X header
* For tcp connections, data is expected to be big-endian
* Endianness can be inverted using the `-X` flag
* When necessary to specify the input datatype (`-e` flag), the selections map exactly to the "integer" and "float" types listed [here](https://docs.python.org/3/library/struct.html#format-characters)
### Ouput data
* Standard mode outputs doubles (float64) with system-default endianness and alignment
* Multiple VFO mode (`--simo` flag) output is always big-endian doubles
### Misc
* Be aware that piping binary (i.e. non-text) data between processes in Powershell is only natively-supported
in Powershell v7.4+ (https://stackoverflow.com/a/68696757/8372013), which you may have
to install separately from the default version included with your copy of Windows.
*N.B. this does not affect modes that use sockets for IO.*
# Examples
## sdrterm.py
### Read input from wave file
`python -m sdrterm -i file.wav --omega-out=5k --decimation=64 --center-frequency="15k" --plot=spec --correct-iq -o out.bin`
#### General explanation of options
* Input source: wave file
* Input data type: determined by RIFF/X header metadata
* Sample rate: determined by RIFF/X header metadata ($fs$ $S \over s$)
* Output lp: 5 kHz
* Decimation factor: $64 \implies$ $fs \over 64$ $S \over s$
* Offset from tuned frequency: +15 kHz
* Plot(s): Spectrum Analyzer
* IQ correction: enabled
* Output destination: out.bin
### Read input from socket, and pipe output to stdout
`python -m sdrterm -i : -eh -r1024k -w5k -d64 -c"-30k" --plot=water | ...`
#### General explanation of options
*N.B. sampling rate and datatype must be specified for raw input*
* Input source: TCP socket at \ on \
* Input data type: 16-bit, signed integer
* Sample rate: $1024k$ $S \over s$
* Output lp: 5 kHz
* Decimation factor: $64 \implies$ $1024k \over 64$ $= 16k$ $S \over s$
* Offset from tuned frequency: -30 kHz
* Plot(s): Waterfall
* Output destination: stdout
### Select multiple frequencies to process from data input via a socket and output them via separate sockets
#### See [exmaple_simo.sh](example_simo.sh) for a complete example
*More examples can be found in the shell scripts in the root of this repo.*
```
Usage: sdrterm.py [OPTIONS]
╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --fs -r NUMBER Sampling frequency in k/M/Samples per sec │
│ --center-frequency -c NUMBER Offset from tuned frequency in k/M/Hz [default: 0] │
│ --input -i TEXT Input device [default: (stdin)] │
│ --output -o TEXT Output device [default: (stdout)] │
│ --plot TEXT 1D-Comma-separated value of plot type(s) [default: None] │
│ --demodulation -m [fm|am|re|im] Demodulation type [default: fm] │
│ --tuned-frequency -t NUMBER Tuned frequency in k/M/Hz [default: 0] │
│ --vfos TEXT 1D-Comma-separated value of offsets from tuned frequency to process in addition to tuned frequency in k/M/Hz [default: None] │
│ --decimation -d INTEGER RANGE [x>=2] Decimation factor [default: 2] │
│ --encoding -e [b|B|h|H|i|I|f|d] Binary encoding (ignored if wav file) [default: None] │
│ --omega-out -w NUMBER Output cutoff frequency in k/M/Hz [default: 12500] │
│ --correct-iq --no-correct-iq Toggle iq correction [default: no-correct-iq] │
│ --simo --no-simo Enable using sockets to output data processed from multiple channels specified by the vfos option. N.B. unlike normal mode, which uses the │
│ system-default endianness for output, the sockets output network-default, big-endian doubles. [Implies: --vfos ] │
│ [default: no-simo] │
│ --verbose -v INTEGER Toggle verbose output. Repetition increases verbosity (e.g. -vv, or -v -v) [default: 0] │
│ --smooth-output INTEGER Provide length of polynomial for smoothing output with Savitzky–Golay filter. A larger polynomial implies more aggressive filtering. │
│ [default: (0 => no filtering)] │
│ --vfo-host TEXT Address on which to listen for vfo client connections [default: localhost] │
│ --swap-input-endianness -X Swap input endianness [default: (False => system-default, or as defined in RIFF header)] │
│ --normalize-input --no-normalize-input Normalize input data. [default: no-normalize-input] │
│ --help Show this message and exit. │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```
## rtltcp.py
#### rtl_tcp running on server on \
`python -m rtltcp `
```
Usage: rtltcp.py [OPTIONS] HOST PORT
╭─ Arguments ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ * host TEXT Address of remote rtl_tcp server [default: None] [required] │
│ * port INTEGER Port of remote rtl_tcp server [default: None] [required] │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --server-host TEXT Port of local distribution server [default: localhost] │
│ --verbose -v INTEGER Toggle verbose output. Repetition increases verbosity (e.g. -vv, or -v -v) [default: 0] │
│ --help Show this message and exit. │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```
## sdrcontrol.py [EXPERIMENTAL]
*Due to the experimental nature of this interface, do not hesitate to report suspected bugs.*
*N.B. if you'd like to be sure of your wave file's sampling rate beforehand,
you can use a tool like `mediainfo` available via most POSIX-like systems' package managers.
Also, basic information about the input file, and other settings are output in JSON format at beginning
of sdrterm's operation. e.g.,*
```
{
"bandwidth": 12500,
"centerFreq": -25000,
"tunedFreq": 0,
"omegaOut": 5000,
"smooth": 0,
"vfos": "15000,-15000",
"host": "localhost",
"encoding": "uint8",
"fs": 1024000,
"decimatedFs": 16000
}
```