rtl_tcp SDR for RTL-SDR Documentation and README 1. App Description rtl_tcp SDR is an app that allows using an RTL-SDR USB peripheral as a Software Defined Radio (SDR), via an rtl_tcp server. The use of this app requires network access to a server, such as a Raspberry Pi (or Mac or PC), with an RTL-SDR unit plugged into its USB port, and running the rtl_tcp protocol at an TCP/IP network address accessible from your Mac. The rtl_tcp SDR iOS app can also connect directly to a Hermes Lite 2 if you know its IP address, no additional server required. RTL-SDR USB peripheral devices were originally developed for receiving DVB-T digital television, a broadcast standard used in Europe and other countries. But experimenters found out that the raw I/Q data stream can be accessed, allowing these devices to provide data for SDR (Software Defined Radio) applications. RTL-SDR USB peripheral devices are manufactured by multiple vendors. They can be tuned over a range of approximately 25 to 1700 MHz, and sometimes higher, depending on the tuner IC chip inside the particular device. Some models (RTL-SDR V.3) additionally allow tuning between 500 kHz and 14 MHz, using direct sampling. The rtl_tcp SDR app can connect to an rtl_tcp server over the network, set the RTL-SDR tuner frequency, receive raw I/Q samples of RF signals, and filter, demodulate, and display the RF spectrum. For AM and FM (mono) signals, you can also listen to the demodulated audio. The rtl_tcp SDR iOS app requires either a local or remote rtl_tcp server or similar raw IQ rtl_tcp compatible server This app can connect to rtl_tcp for RTL-SDR devices, hfp_tcp for the Airspy HF+ and HF+ Discovery, rsp_tcp for SDRPlay RSP devices, and lmm_tcp for the LimeSDR Mini. This app is NOT compatible with various vendor supplied servers that do not use the rtl_tcp protocol. However this app can connect directly to a Hermes Lite 2 if you know its IP address, no additional server required. Note that no support is provided by the app or app developer for building or installing any of these rtl_tcp or other tcp servers required to use this app either on your Mac, or on a Raspberry Pi or other remote server. Please see GitHub for repositories containing source code for various suitable rtl_tcp, hfp_tcp, or equivalent servers. Note that the rtl_tcp protocol requires a reliable and very high bandwidth network, often at a much higher data rate than typical streaming video. Only use rtl_tcp over sufficiently provisioned hi-speed WiFi networks. It may be necessary to run your rtl_tcp server cabled to a wired network, rather connected via WiFi. 2. Requirements to use this app: - have an RTL-SDR USB peripheral device, or similar device that has an rtl_tcp compatible server, - be able to run an rtl_tcp server on a computer such as a Raspberry Pi, Mac or PC into which the RTL-SDR is plugged-in, - know the IP address or host name of your server - be on a network at which your server can be reached from your Mac 3. Using the rtl_tcp SDR app: (A) Configuring the rtl_tcp server address - Start rtl_tcp on your server (Raspberry, Mac or PC) - Note the host name or IP address of your rtl_tcp server - Note the port number that your server is using, if not 1234 - Launch the app on your Mac - Select Server Settings from the menu - Tap the "Set IP” button - Enter the IP address of your rtl_tcp server and hit OK - If your network supports hostnames, you might be able to use a hostname, such as "raspberrypi.local" instead of a numeric IP address - Optional: configure the IP Port if different from 1234 - Tap “rtl_tcp SDR” at the top to go back to the main view - If you run the rtl_tcp server on the same Mac as this app, then you can connect using localhost, or the IP address 127.0.0.1 (B) Configuring the radio frequency and demodulation mode - Tap the top frequency text field - Use the keyboard to enter a frequency in Hz (Or use a number with a decimal point to enter MHz) - Select a Sample Rate from the left-side menu - Tap the main view to hide the menu - Select a modulation mode from AM/NFM/WFM/LSB/SSB - Broadcast FM radio (mono only) is usually WFM - VHF voice (amateur radio, marine weather, etc.) is NFM (C) Starting and running - Tap the Start/Stop button - An error box will show up if the app cannot connect to the server - On success, the spectrum and waterfall should start animating - Below the Stop button is a audio and network monitor bar graph. - the green/red bar monitors demodulation audio level - red indicated clipping - the blue bar indicates network activity - If the blue bar often stays below roughly center, that means your network may be too slow for the chosen sample rate. - The Audio Gain slider controls the demodulated audio level - Note that, once started, audio will continue during a locked screen (This is called background audio.) - The SDR Gain slider below controls the RTL-SDR front-end gain - The AGC Switch enables RTL2832U automatic gain, but its use is not recommended - An Audio Spectrum switch can toggle the spectrum from RF to audio - A Squelch control in is the left-side menu - Tap the Start/Stop button again to disconnect from the server (D) Operating spectrum or waterfall tuning - You can Swipe left or right on the spectrum to tune up or down - An empty area will appear opposite the direction of the swipe - Tap the empty spectrum area to re-tune the RTL-SDR - This will refill the spectrum after the RTL-SDR retunes - For fine tuning you can Zoom, or use fine tuning buttons - Tap on the Zoom button to change Zoom levels - There are 2 levels of zoom, plus full width for the sample rate - You can combine a zoom level with panning for fine tuning - Tap on the waterfall display to show/hide fine tuning buttons - You can also fine tune by starting a swipe downwards - The lower the swipe downward the finer the tuning gradations - Swipe left or right at this lower level to fine tune - When Zoomed-in, the f0 Scroll switch enables a wider frequency range of tuning by swiping, at the cost of a distorted waterfall - You can also type a frequency into the top field and hit "Set" - A frequency value without punctuation defaults to Hz - Enter a frequency in MHz by using a decimal point (E) Configuring a station preset - To use the 5 frequency Presets - Enter a frequency value in the top field - Press "Set" to enter the frequency - Select the demodulation mode - Press and Hold on a Preset for 3 seconds or longer (F) Custom URL Scheme Support A custom url scheme allows controlling some aspects of an app from a URL link contained in a text message, email, web page, contact URL, or a Siri Shortcut. - The rtl_tcp SDR app supports the custom url scheme "hotpaw-sdr" - Example tuneto urls tune to an NFM station on 162.5 MHz hotpaw-sdr://tuneto?f=162.4&mode=nfm tune to KQED FM at 88.5 MHz hotpaw-sdr://tuneto?name=KQED&f=88.5&mode=fm - Example server urls configure the IP address and port number for an rtl_tcp server hotpaw-sdr://server?ip=127.0.0.1&port=1234 hotpaw-sdr://server?host=raspberrypi.local&port=1234 (G) Other options - In LSB/USB mode, an optional CW filter can be enabled from the left menu - Tune about 650 Hz above(LSB) or below(USB) the carrier to listen to CW - The default CW audio bandwidth is about 400 Hz, centered at 650 Hz - Upconverter support is on the Options page (125 MHz default) - There is also an option for RTL-SDR’s that support Direct Sampling - Only select this mode for frequencies below 12 MHz - There is an option for setting a PPM value (parts-per-million, -200 to 200), if you know the frequency offset or drift of your particlular RTL-SDR oscillator - The hfp_tcp and rsp_tcp servers supports 16-bit IQ samples for a higher dynamic range - First enable this feature on the hfp or rsp_tcp server command line - Then select HF+ or rsp in the Server Settings - You record and play IQ files Select the file to record or play while streaming is Stopped To Play a file, the file extension must be ".data", ".dat", or ".bin" Clear Play mode by selecting any Preset, or Cancel during Play selection - Use with the Hermes Lite 2 SDR Transceiver: The hl2 mode, for use with the Hermes Lite 2 SDR (HL2), supports 2 modes of connection: TCP for use with the hl2_tcp server, and UDP for a direct network connection using Metis OpenHPSDR Protocol 1. A UDP connection to an HL2 requires obtaining and entering the HL2's IP address. A UDP direct network connection works best over a wired ethernet connection between the device and the HL2. A WiFi connection is NOT recommended. The python utility hermeslite.py is this github repository: https://github.com/softerhardware/Hermes-Lite2/tree/master/software/hermeslite hermeslite.py be run on a Mac or Pi to Discover a Hermes Lite 2's IP address. Your legal jurisdiction may require a radio license in order to operate a radio transmitter. In HL2 UDP mode, the custom url (with no spaces) : hotpaw-sdr : / / options?callsign=YOUR_RADIO_CALLSIGN will enable some CW and SSB transmit options. (Hint: Do not copy & paste the above URL as it contails spaces.) (H) SDR IQ data servers - Some General information on the history of the use of RTL-SDR devices is here: https://osmocom.org/projects/rtl-sdr/wiki/Rtl-sdr - Some instructions on the building and installation of rtl_tcp and hfp_tcp servers on various platforms (Mac and Linux) can be found inside this document: http://www.transitiontechnologyventures.com/sdr-receiver/instructions - Servers for the Airspy HF+, HF+ Discovery, the Hermes Lite 2, the LimeSDR Mini, and SDRPlay RSP devices are also available for experimentation. See: https://github.com/hotpaw2/hfp_tcp https://github.com/hotpaw2/hl2_tcp https://github.com/SDRplay/RSPTCPServer and: https://github.com/hotpaw2/lmm_tcp for beta test server source code. ---- Notes: Hotpaw Productions provides absolutely no support for installing any of the software that a Raspberry Pi, or other server, requires to use this app. Please do not download this app unless you are familiar with software defined radio, have an RTL-SDR, and have already installed and tested rtl_tcp on your Raspberry Pi, or other server. The user interface of this app is designed to fit on an iPhone’s display (even if there is more display room available when the app is installed on an iPad). This app, including all DSP filters and demodulators, is written entirely in Swift 4. There are no plans to support any other SDR or DSP modes that are written or documented in C/C#/C++. The original idea for this app was conceived at the 2016 iOS DevCamp (the original iPhone DevCamp) in San Jose, while trying to figure how to use Apple's Swift programming language to prove the breadth of its capabilities for real-time numeric and signal processing. ---- ---- For support, see the HotPaw Home Page: http://www.nicholson.com/rhn/hotpaw/ ---- DISCLAIMER There is no warranty that this document is accurate or correct. Do not use this app to receive radio signals unless it is legal within your legal jurisdiction, and/or you have an appropriate government radio license. Disclaimer: This SDR app is distributed in the hope that it might be useful, but WITHOUT ANY WARRANTY OF ANY KIND; not even the implied warranty of MERCHANTABILITY or FITNESS for ANY PARTICULAR PURPOSE. (There will be bugs!) ---- Version 1.5.1 - Improved audio limiter/AGC - Improve CW decoder (HL2 only) - Control Layout bug fixes Version 1.4.9 - Bug fix for A<>B toggle - New Noise Reduction - New Squelch enabled by turning Noise Reduction on Version 1.4.6 - Bug fix release - Fixed IQ record/save menu function - Improved S-meter calibration Version 1.4.4 - Improved Voiceover accessibility labeling - Added 2.5Msps RTL-SDR sample rate support - Added audio routing option - Bug fixes (b407,4) Version 1.4.3 - Bug fix release Version 1.4.2 - Bug fix release, 2X spectrum height option Version 1.4.1 - Added A/B VFO, trackpad panning, frequency labels Version 1.3.9 - Bug fix release Version 1.3.7 - Added support for the Hermes Lite 2 SDR transceiver Version 1.3.6 - Bug fix for squelch and audio quality Version 1.3.5 - Bug fixes and performance improvements Version 1.3.4 - Dark Mode Version 1.3.3 - Improved CW filter Version 1.3.2 - Bug fixes, improved audio filters - Added sample rates for Airspy HF+ and HF+ Discovery Version 1.2.9 - macOS Catalina Catalyst port Version 1.2.8 - Minor update to iPad layout Version 1.2.6 - Bug fixes for Dark Mode Version 1.2.5 - Bug fix for a problem setting higher RTL-SDR sample rates Version 1.2.4 - Updated support for hfp_tcp and new HF+ Discovery sample rates Version 1.2.3 - Bug fixes for CW enable/disable and filter bandwidth - Bug fixes for spectrum display - Other appearance and reliability improvements (b303) Version 1.2.2 - Improvements to spectrum zoom - Bug fixes for audio level and frequency configuration Version 1.2.1 - Added a Dark Mode option (set in the Options view) - Added a URL scheme to control tuning and server selection - Updated for Network.framework and Swift 5 - Bug fix for spectrum zoom gesture - Bug fix for AM squelch and CW filter gain - Bug fixes for frequency and sample rate selection issues Version 1.0.7 - Improved complex-modulated SSB and CW filters - Improved audio filtering - Added fine tuning buttons (tap on spectrograph to enable/hide) - Added an SSB and CW audio bandwidth indicator - Added support for SDRPlay rsp_tcp 16-bit mode - Fixed an HF+ sample rate bug - Preselects now save squelch setting - Fixed bug in spectrum and waterfall zoom in - Pinch and Zoom now allowed for zooming waterfall Version 1.0.6 - Bug fix for Upconverter settings - Allow comma in EU numeric keyboard frequency entry - Improvements to SSB demodulation Version 1.0.5 - initial App Store release Version 1.0.4xx - TestFlight beta-test releases Support: rhn-support @ hotpaw . com mailto:rhn-support@hotpaw.com Resources: rtl_tcp source code & library support: https://github.com/osmocom/rtl-sdr UC Berkeley notes on rtl_tcp installation: https://inst.eecs.berkeley.edu/~ee123/sp15/rtl_sdr_install.html HF+ TCP server: https://gist.github.com/hotpaw2/8c720c324ac0794aa7bf98c505eb61d5 Airspy HF+ library code: https://github.com/airspy/airspyhf SDRPlay RSP TCP server: https://github.com/SDRplay/RSPTCPServer https://www.sdrplay.com/docs/SDRplay_RSP_TCP_Server_Guide.pdf Biquad filter parameters: http://www.musicdsp.org/files/Audio-EQ-Cookbook.txt THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Credits: Multiple helpful bug reports: TestFlight volunteer test groups 1 & 2 Proofreading and Swift 2 code for GCD dispatch_once: Barry P. Medoff, WB2ISS Portions Copyright (c) 2007-2008 CSIRO Portions Copyright (c) 2007-2009 Xiph.Org Foundation Portions Copyright (c) 2017 Mozilla Portions Copyright (c) 2018 Gregor Richards Portions Copyright by Jean-Marc Valin Frameworks and Library routines Copyright © Apple, Inc. Copyright © 2016,2018,2020-2023 HotPaw Productions and Ronald Nicholson, Jr All Rights Reserved ----