rtl_tcp SDR for RTL-SDR Documentation and README 1. App Description rtl_tcp SDR is an iOS app that allows using an RTL-SDR USB peripheral as a Software Defined Radio (SDR), via an rtl_tcp server. iOS devices do not currently support the direct connection of USB peripherals such as an RTL-SDR. Thus, 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 iOS device. The Raspberry Pi acts, essentially, as a USB port adapter for your iOS device. 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 iOS 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. 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. 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, or cellular networks with extremely high data caps. It may be necessary to run your rtl_tcp server (especially if it's a Mac) 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 iOS device. 3. Using the iOS 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 iOS device - Tap the "hamburger" icon at the upper left to display the menu - 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 (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) - Tap the “Set” button just above the numeric keyboard - 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 fill 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 - URL generation There is a URL generation web page here: http://www.hotpaw.com/rhn/hotpaw/urltest01.html (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 - A hardware connection may be possible if you do not want to use WiFi. An iOS device can be connected though an Apple Lightning Camera adapter to a multi-port USB hub (powered), which can be connected to an Apple USB Ethernet adapter, which can be connected, via an ethernet cross-over cable, to a Raspberry Pi 3 or other micro-server, which (finally!) can be connected to an RTL-SDR USB peripheral. - 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 iOS 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. Disclaimer: This iOS 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!) Do not use this app to transmit or receive radio signals unless it is legal in your legal jurisdiction, and/or you have an appropriate government radio license. ---- 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 Algorithm - New Squelch enabled by turning on Noise Reduction Version 1.4.6 - Bug fix release Version 1.4.4 - Improved Voiceover accessibility labeling - Added 2.5Msps RTL-SDR sample rate support - Added audio routing option - Bug fixes Version 1.4.3 - Bug fix release Version 1.4.2 - Bug fix release, 2X spectrum height option Version 1.4.1 - Bug fix release, added VFO A/B button, frequency markers 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.2 - Improved CW filtering (b08) Version 1.3.1 - macOS Catalina Catalyst port Version 1.2.8 - Minor update to iPad layout Version 1.2.6 - Bug fixes for iOS 13 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 the iOS 12 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 ----