# pyrtlsdr
A Python wrapper for librtlsdr (a driver for Realtek RTL2832U based SDR's)
[](https://pypi.org/project/pyrtlsdr)   [](https://coveralls.io/github/pyrtlsdr/pyrtlsdr)
# Description
pyrtlsdr is a simple Python interface to devices supported by the RTL-SDR project, which turns certain USB DVB-T dongles
employing the Realtek RTL2832U chipset into low-cost, general purpose software-defined radio receivers. It wraps many of the
functions in the [librtlsdr library](https://github.com/librtlsdr/librtlsdr) including asynchronous read support
and also provides a more Pythonic API.
# Links
* Documentation:
* https://pyrtlsdr.readthedocs.io/
* Releases:
* https://pypi.org/project/pyrtlsdr/
* Source code and project home:
* https://github.com/pyrtlsdr/pyrtlsdr
* Releases for `librtlsdr`:
* https://github.com/librtlsdr/librtlsdr/releases
# Installation
pyrtlsdr can be installed by downloading the source files and running `python setup.py install`, or using [pip](https://pip.pypa.io/en/stable/) and
`pip install pyrtlsdr`.
## Full installation (recommended)
**New in version 0.3.0**
On most platforms, the `librtlsdr` binaries may be also installed with the [pyrtlsdrlib](https://github.com/pyrtlsdr/pyrtlsdrlib) package. This new feature should *drastically* simplify the installation process (especially for Windows).
This can be done by installing `pyrtlsdrlib` separately (via pip) or for simplicity, both can be installed at once via:
```bash
pip install pyrtlsdr[lib]
```
If errors are encountered with the `pyrtlsdrlib` integration (during installation or package import),
you may want to ensure you have the latest versions of both:
```bash
pip install --upgrade pyrtlsdr[lib]
```
# Usage
All functions in librtlsdr are accessible via librtlsdr.py and a Pythonic interface is available in rtlsdr.py (recommended).
Some documentation can be found in docstrings in the latter file.
## Examples
### Simple way to read and print some samples:
```python
from rtlsdr import RtlSdr
sdr = RtlSdr()
# configure device
sdr.sample_rate = 2.048e6 # Hz
sdr.center_freq = 70e6 # Hz
sdr.freq_correction = 60 # PPM
sdr.gain = 'auto'
print(sdr.read_samples(512))
```
### Plotting the PSD with matplotlib:
```python
from pylab import *
from rtlsdr import *
sdr = RtlSdr()
# configure device
sdr.sample_rate = 2.4e6
sdr.center_freq = 95e6
sdr.gain = 4
samples = sdr.read_samples(256*1024)
sdr.close()
# use matplotlib to estimate and plot the PSD
psd(samples, NFFT=1024, Fs=sdr.sample_rate/1e6, Fc=sdr.center_freq/1e6)
xlabel('Frequency (MHz)')
ylabel('Relative power (dB)')
show()
```
### Resulting Plot:
See the files 'demo_waterfall.py' and 'test.py' for more examples.
## Handling multiple devices:
*(added in v2.5.6)*
```python
from rtlsdr import RtlSdr
# Get a list of detected device serial numbers (str)
serial_numbers = RtlSdr.get_device_serial_addresses()
# Find the device index for a given serial number
device_index = RtlSdr.get_device_index_by_serial('00000001')
sdr = RtlSdr(device_index)
# Or pass the serial number directly:
sdr = RtlSdr(serial_number='00000001')
```
### Note
Most devices by default have the same serial number: '0000001'. This can be set
to a custom value by using the [rtl_eeprom][rtl_eeprom] utility packaged with `librtlsdr`.
[rtl_eeprom]: https://manpages.ubuntu.com/manpages/trusty/man1/rtl_eeprom.1.html
# Experimental features
Two new submodules are available for testing: **rtlsdraio**, which adds native Python 3 asynchronous support (asyncio module), and **rtlsdrtcp** which adds a TCP server/client for accessing a device over the network. See the respective modules in the rtlsdr folder for more details and feel free to test and report any bugs!
## rtlsdraio
Note that the rtlsdraio module is automatically imported and adds `stream()` and `stop()` methods to the normal `RtlSdr` class. It also requires the new `async`/`await` syntax introduced in Python 3.5+.
The syntax is basically:
```python
import asyncio
from rtlsdr import RtlSdr
async def streaming():
sdr = RtlSdr()
async for samples in sdr.stream():
# do something with samples
# ...
# to stop streaming:
await sdr.stop()
# done
sdr.close()
loop = asyncio.get_event_loop()
loop.run_until_complete(streaming())
```
## rtlsdrtcp
The `RtlSdrTcpServer` class is meant to be connected physically to an SDR dongle and communicate with an instance of `RtlSdrTcpClient`. The client is intended to function as closely as possible to the base RtlSdr class (as if it had a physical dongle attached to it).
Both of these classes have the same arguments as the base `RtlSdr` class with the addition of `hostname` and `port`:
```python
server = RtlSdrTcpServer(hostname='192.168.1.100', port=12345)
server.run_forever()
# Will listen for clients until Ctrl-C is pressed
```
```python
# On another machine (typically)
client = RtlSdrTcpClient(hostname='192.168.1.100', port=12345)
client.center_freq = 2e6
data = client.read_samples()
```
## TCP Client Mode
On platforms where the `librtlsdr` library cannot be installed/compiled, it is possible to import the `RtlSdrTcpClient` only by setting the environment variable `"RTLSDR_CLIENT_MODE"` to `"true"`. If this is set, no other modules will be available.
*Feature added in v0.2.4*
# Dependencies
* Windows/Linux/OSX
* Python 2.7.x/3.3+
* [librtlsdr](https://github.com/librtlsdr/librtlsdr/releases)
* **Optional**: NumPy (wraps samples in a more convenient form)
matplotlib is also useful for plotting data. The librtlsdr binaries (rtlsdr.dll in Windows and librtlsdr.so in Linux)
should be in the pyrtlsdr directory, or a system path. Note that these binaries may have additional dependencies.
# Todo
There are a few remaining functions in librtlsdr that haven't been wrapped yet. It's a simple process if there's an additional
function you need to add support for, and please send a pull request if you'd like to share your changes.
# Troubleshooting
* Some operating systems (Linux, OS X) seem to result in libusb buffer issues when performing small reads. Try reading 1024
(or higher powers of two) samples at a time if you have problems.
## librtlsdr import errors
First try upgrading `pyrtlsdr` and using the `pyrtlsdrlib` helper package described above.
* In cases where that isn't feasible:
* **Windows**: Make sure all the librtlsdr DLL files (librtlsdr.dll, libusb-1.0.dll) are in your system path, or the same folder
as this README file. Also make sure you have all of *their* dependencies (e.g. libgcc_s_dw2-1.dll or possibly the Visual Studio runtime files). If rtl_sdr.exe
works, then you should be okay. Also note that you can't mix the 64 bit version of Python with 32 bit builds of librtlsdr, and vice versa.
* **Linux**: Make sure your LD_LIBRARY_PATH environment variable contains the directory where the librtlsdr.so.0 library is located. You can do this in a shell with (for example): `export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib`. See [this issue](https://github.com/roger-/pyrtlsdr/issues/7) for more details.
# License
All of the code contained here is licensed by the GNU General Public License v3.
# Credit
Credit to dbasden for his earlier wrapper [python-librtlsdr](https://github.com/dbasden/python-librtlsdr) and all the
contributors on GitHub.
Copyright (C) 2013 by Roger <https://github.com/pyrtlsdr/pyrtlsdr>
Raw data
{
"_id": null,
"home_page": "https://github.com/pyrtlsdr/pyrtlsdr",
"name": "pyrtlsdr",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "radio librtlsdr rtlsdr sdr",
"author": "roger",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/13/82/d74c78b7b68d2b741f3973fbc0a56c3c676d5fac055b76e61083e3fd19ba/pyrtlsdr-0.3.0.tar.gz",
"platform": "any",
"description": "# pyrtlsdr\nA Python wrapper for librtlsdr (a driver for Realtek RTL2832U based SDR's)\n\n[](https://pypi.org/project/pyrtlsdr)   [](https://coveralls.io/github/pyrtlsdr/pyrtlsdr)\n\n# Description\n\npyrtlsdr is a simple Python interface to devices supported by the RTL-SDR project, which turns certain USB DVB-T dongles\nemploying the Realtek RTL2832U chipset into low-cost, general purpose software-defined radio receivers. It wraps many of the\nfunctions in the [librtlsdr library](https://github.com/librtlsdr/librtlsdr) including asynchronous read support\nand also provides a more Pythonic API.\n\n# Links\n\n* Documentation:\n * https://pyrtlsdr.readthedocs.io/\n* Releases:\n * https://pypi.org/project/pyrtlsdr/\n* Source code and project home:\n * https://github.com/pyrtlsdr/pyrtlsdr\n* Releases for `librtlsdr`:\n * https://github.com/librtlsdr/librtlsdr/releases\n\n# Installation\n\npyrtlsdr can be installed by downloading the source files and running `python setup.py install`, or using [pip](https://pip.pypa.io/en/stable/) and\n`pip install pyrtlsdr`.\n\n## Full installation (recommended)\n\n**New in version 0.3.0**\n\nOn most platforms, the `librtlsdr` binaries may be also installed with the [pyrtlsdrlib](https://github.com/pyrtlsdr/pyrtlsdrlib) package. This new feature should *drastically* simplify the installation process (especially for Windows).\n\nThis can be done by installing `pyrtlsdrlib` separately (via pip) or for simplicity, both can be installed at once via:\n\n```bash\npip install pyrtlsdr[lib]\n```\n\nIf errors are encountered with the `pyrtlsdrlib` integration (during installation or package import),\nyou may want to ensure you have the latest versions of both:\n\n```bash\npip install --upgrade pyrtlsdr[lib]\n```\n\n# Usage\n\nAll functions in librtlsdr are accessible via librtlsdr.py and a Pythonic interface is available in rtlsdr.py (recommended).\nSome documentation can be found in docstrings in the latter file.\n\n## Examples\n\n### Simple way to read and print some samples:\n\n```python\nfrom rtlsdr import RtlSdr\n\nsdr = RtlSdr()\n\n# configure device\nsdr.sample_rate = 2.048e6 # Hz\nsdr.center_freq = 70e6 # Hz\nsdr.freq_correction = 60 # PPM\nsdr.gain = 'auto'\n\nprint(sdr.read_samples(512))\n```\n\n### Plotting the PSD with matplotlib:\n\n```python\nfrom pylab import *\nfrom rtlsdr import *\n\nsdr = RtlSdr()\n\n# configure device\nsdr.sample_rate = 2.4e6\nsdr.center_freq = 95e6\nsdr.gain = 4\n\nsamples = sdr.read_samples(256*1024)\nsdr.close()\n\n# use matplotlib to estimate and plot the PSD\npsd(samples, NFFT=1024, Fs=sdr.sample_rate/1e6, Fc=sdr.center_freq/1e6)\nxlabel('Frequency (MHz)')\nylabel('Relative power (dB)')\n\nshow()\n```\n\n### Resulting Plot:\n![](https://i.imgur.com/hFhg8.png \"Resulting Plot\")\n\nSee the files 'demo_waterfall.py' and 'test.py' for more examples.\n\n## Handling multiple devices:\n*(added in v2.5.6)*\n```python\nfrom rtlsdr import RtlSdr\n\n# Get a list of detected device serial numbers (str)\nserial_numbers = RtlSdr.get_device_serial_addresses()\n\n# Find the device index for a given serial number\ndevice_index = RtlSdr.get_device_index_by_serial('00000001')\n\nsdr = RtlSdr(device_index)\n\n\n# Or pass the serial number directly:\nsdr = RtlSdr(serial_number='00000001')\n```\n\n### Note\nMost devices by default have the same serial number: '0000001'. This can be set\nto a custom value by using the [rtl_eeprom][rtl_eeprom] utility packaged with `librtlsdr`.\n\n[rtl_eeprom]: https://manpages.ubuntu.com/manpages/trusty/man1/rtl_eeprom.1.html\n\n# Experimental features\n\nTwo new submodules are available for testing: **rtlsdraio**, which adds native Python 3 asynchronous support (asyncio module), and **rtlsdrtcp** which adds a TCP server/client for accessing a device over the network. See the respective modules in the rtlsdr folder for more details and feel free to test and report any bugs!\n\n## rtlsdraio\nNote that the rtlsdraio module is automatically imported and adds `stream()` and `stop()` methods to the normal `RtlSdr` class. It also requires the new `async`/`await` syntax introduced in Python 3.5+.\n\nThe syntax is basically:\n\n```python\nimport asyncio\nfrom rtlsdr import RtlSdr\n\nasync def streaming():\n sdr = RtlSdr()\n\n async for samples in sdr.stream():\n # do something with samples\n # ...\n\n # to stop streaming:\n await sdr.stop()\n\n # done\n sdr.close()\n\nloop = asyncio.get_event_loop()\nloop.run_until_complete(streaming())\n```\n\n## rtlsdrtcp\nThe `RtlSdrTcpServer` class is meant to be connected physically to an SDR dongle and communicate with an instance of `RtlSdrTcpClient`. The client is intended to function as closely as possible to the base RtlSdr class (as if it had a physical dongle attached to it).\n\nBoth of these classes have the same arguments as the base `RtlSdr` class with the addition of `hostname` and `port`:\n```python\nserver = RtlSdrTcpServer(hostname='192.168.1.100', port=12345)\nserver.run_forever()\n# Will listen for clients until Ctrl-C is pressed\n```\n```python\n# On another machine (typically)\nclient = RtlSdrTcpClient(hostname='192.168.1.100', port=12345)\nclient.center_freq = 2e6\ndata = client.read_samples()\n```\n\n## TCP Client Mode\nOn platforms where the `librtlsdr` library cannot be installed/compiled, it is possible to import the `RtlSdrTcpClient` only by setting the environment variable `\"RTLSDR_CLIENT_MODE\"` to `\"true\"`. If this is set, no other modules will be available.\n\n*Feature added in v0.2.4*\n\n\n# Dependencies\n\n* Windows/Linux/OSX\n* Python 2.7.x/3.3+\n* [librtlsdr](https://github.com/librtlsdr/librtlsdr/releases)\n* **Optional**: NumPy (wraps samples in a more convenient form)\n\nmatplotlib is also useful for plotting data. The librtlsdr binaries (rtlsdr.dll in Windows and librtlsdr.so in Linux)\nshould be in the pyrtlsdr directory, or a system path. Note that these binaries may have additional dependencies.\n\n# Todo\n\nThere are a few remaining functions in librtlsdr that haven't been wrapped yet. It's a simple process if there's an additional\nfunction you need to add support for, and please send a pull request if you'd like to share your changes.\n\n# Troubleshooting\n\n* Some operating systems (Linux, OS X) seem to result in libusb buffer issues when performing small reads. Try reading 1024\n(or higher powers of two) samples at a time if you have problems.\n\n## librtlsdr import errors\n\nFirst try upgrading `pyrtlsdr` and using the `pyrtlsdrlib` helper package described above.\n\n* In cases where that isn't feasible:\n * **Windows**: Make sure all the librtlsdr DLL files (librtlsdr.dll, libusb-1.0.dll) are in your system path, or the same folder\nas this README file. Also make sure you have all of *their* dependencies (e.g. libgcc_s_dw2-1.dll or possibly the Visual Studio runtime files). If rtl_sdr.exe\nworks, then you should be okay. Also note that you can't mix the 64 bit version of Python with 32 bit builds of librtlsdr, and vice versa.\n * **Linux**: Make sure your LD_LIBRARY_PATH environment variable contains the directory where the librtlsdr.so.0 library is located. You can do this in a shell with (for example): `export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib`. See [this issue](https://github.com/roger-/pyrtlsdr/issues/7) for more details.\n\n# License\n\nAll of the code contained here is licensed by the GNU General Public License v3.\n\n# Credit\n\nCredit to dbasden for his earlier wrapper [python-librtlsdr](https://github.com/dbasden/python-librtlsdr) and all the\ncontributors on GitHub.\n\nCopyright (C) 2013 by Roger <https://github.com/pyrtlsdr/pyrtlsdr>\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "A Python wrapper for librtlsdr (a driver for Realtek RTL2832U based SDR's)",
"version": "0.3.0",
"project_urls": {
"Documentation": "https://pyrtlsdr.readthedocs.io/",
"Homepage": "https://github.com/pyrtlsdr/pyrtlsdr",
"Source": "https://github.com/pyrtlsdr/pyrtlsdr"
},
"split_keywords": [
"radio",
"librtlsdr",
"rtlsdr",
"sdr"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5aa6618ffd03652253ddd6455a9334e56332b9d5f6afa55197710a533dd91c28",
"md5": "a02a4f33b5d62f4a77ede89c535b09e8",
"sha256": "4967df42eb89e6bd70602337ae355c9b1231eb1d517fd8cc30f7b862fd1392f6"
},
"downloads": -1,
"filename": "pyrtlsdr-0.3.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "a02a4f33b5d62f4a77ede89c535b09e8",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 26064,
"upload_time": "2023-08-02T19:25:09",
"upload_time_iso_8601": "2023-08-02T19:25:09.952237Z",
"url": "https://files.pythonhosted.org/packages/5a/a6/618ffd03652253ddd6455a9334e56332b9d5f6afa55197710a533dd91c28/pyrtlsdr-0.3.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1382d74c78b7b68d2b741f3973fbc0a56c3c676d5fac055b76e61083e3fd19ba",
"md5": "71bc0285b09fd2f4c4c4456e2d5bac0e",
"sha256": "fb3e583ba073b861e8e0bc5e62f66f07365e9147f5d36491de4ad62f23e45362"
},
"downloads": -1,
"filename": "pyrtlsdr-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "71bc0285b09fd2f4c4c4456e2d5bac0e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 29209,
"upload_time": "2023-08-02T19:25:11",
"upload_time_iso_8601": "2023-08-02T19:25:11.683912Z",
"url": "https://files.pythonhosted.org/packages/13/82/d74c78b7b68d2b741f3973fbc0a56c3c676d5fac055b76e61083e3fd19ba/pyrtlsdr-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-02 19:25:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pyrtlsdr",
"github_project": "pyrtlsdr",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "pyrtlsdr"
}
JSON
