Controlling gqrx from a remote host

Starting with version 2.3 gqrx can be controlled remotely using a simple TCP connection. Currently, the remote control functionality is limited to setting and reading a few parameters but more handles might be added in the future.

Remote control buttons

You will notice two new buttons in the toolbar. One starts and stops the TCP server, the other one brings up a modal dialog window with the remote control options. In case the toolbar is hidden you can access these two functions through the Tools menu.

By default gqrx is configured to accept connections from the localhost on port 7356. You can test it by starting the server and then initiating a telnet session:

$ telnet localhost 7356
Connected to localhost.
Escape character is '^]'.

You can now send commands to gqrx. Supported commands include:

 f - Get frequency [Hz]
 F - Set frequency [Hz]
 m - Get demodulator mode
 M - Set demodulator mode (OFF, RAW, AM, FM, WFM, WFM_ST,
 l STRENGTH - Get signal strength [dBFS]
 l SQL - Get squelch threshold [dBFS]
 L SQL <sql> - Set squelch threshold to <sql> [dBFS]
 u RECORD - Get status of audio recorder
 U RECORD <status> - Set status of audio recorder to <status>
 c - Close connection
 AOS - Acquisition of signal (AOS) event, start audio recording
 LOS - Loss of signal (LOS) event, stop audio recording
 \dump_state - Dump state (only usable for compatibility)

For an up to date list of commands see the remote-control.txt file in the source tree or under the Help menu.

Gqrx replies with:

 RPRT 0 - Command successful
 RPRT 1 - Command failed

As an example consider the following session:

F 123456789
Connection closed by foreign host.

The frequency is entered and reported back in Hz.

You might recognize both the commands and the “RPRT 0” reply from gqrx to be the same as used by the hamlib rigctld protocol. Indeed the command syntax used for this interface is the same as the one used by rigctld and this is not a coincidence. Using this protocol allows gqrx to work together with existing applications that support this interface.

One of these applications is my gpredict satellite tracker. In gpredict you can configure an “RX only” device with the proper network settings and you are ready to track satellites with Doppler shift correction.

Gpredict radio configuration for gqrx

Since this is a rather insecure connection, gqrx will only accept connections from the local host by default. You can change both the network port and the allowed hosts in the remote control preferences dialog window show below.

Remote control settings

When adding a new host you must type in the IP address – the current implementation will not work with host names. To edit an entry in the list double click on the row and edit. To delete one or more items from the list, select the items and click on the “Del” button.

Please understand that there is no encryption or authentication involved and you should only use this feature behind a firewall. If you wish to use it on a global network you must tunnel the telnet traffic through SSH and/or another host that adds at least authentication.

The AOS and LOS commands are specific to gqrx and gpredict. I needed to find a quick way to trigger audio recordings based on satellite events. The AOS event is triggered when the satellite comes above the horizon. The LOS event is triggered when the satellite goes below the horizon.

As of writing, only the development version of gpredict is capable of sending the AOS and LOS events.

That’s basically all you can do for now. As a final remark, you might notice that gqrx tries to handle new frequency settings by adjusting the channel filter offset rather than requesting a new PLL frequency. The latter may cause glitches on some devices so for smooth Doppler tuning it much preferred to adjust the frequency using the software filter.

Document updates

2016/05/08 — Updated list of commands.

2014/01/21 — Add l, M and m commands.

Author: Alexandru Csete

Embedded software engineer in the satcom industry during the day. Radio amateur and SDR hacker during the night.

  • Chris

    Hello Alex, just installed gqrx on a fresh ubuntu system here and I think the ppa install route doesn’t include these new additions – can you confirm? 73s Chris

    • That’s correct. I am about to update the snapshots PPA but it always takes several days to have things built. This time I also chose to upgrade GNU Radio and that takes a long time to build.

      • Chris

        Yeah, I understand! Thanks!

  • Tim Hewitt

    Looking forward to v2.3 as I use gqrx for Noaa apt so keen to see the intergration with gpredict. Tim

  • Tim Hewitt

    Thanks Alex for the upgrade, trying with gpredict.

  • Madious Cameel

    Any plans of adding signal strength reporting to this? If I could get the signal strength after tuning I could easily write a basic scanner application!

    From what I see on the mailing lists I’m not alone in hungering for a gqrx scanner.

    • Before I go crazy adding all sorts of parameters I must know whether this interface is useful. As you can see there has been very little feedback about this. It seems people only give feedback when they have something to complain about or they want something new added.

      • Madious Cameel

        As the developer of a few OSS projects I understand completely. Don’t let it get you down, you’re doing great work and your software is top notch!

        If you ever do add this functionality I’ll write a scanner/freq manager as soon as I notice and then people will bother me for features too..

        • Ok, I’ll add mode, filter and signal strength.

      • me

        It is in use, by me :-). using the remote manually for now via nc
        (and rlwrap). can you please add more options (for example to change
        mode would be totally awesome!)? thanks! love the software!

    • You can now read the signal strength using the “l” command (l for level). Mode and filter will require a bit more work.

    • I have also added M and m for setting and reading the mode. See updated post for mode strings.

  • Rafael Marmelo

    This is an amazing feature!

    Please check out my gqrx-remote project:

    It connects to gqrx using this remote control interface and allows you to manage your bookmarks.

    • Rafael,
      Thanks for creating and sharing this. I need to start a page listing the applications that use the remote control interface.

  • king

    Hello Alex,thank you for your software ! This software interests me so much and it reveals a new world to me. However, this software could not work well with the bladeRF . Moreover, we could not receive the test signals(based on bladeRF and your software) sometime and the amplitude of the signals we have received is rather low. I hope you could give me some advises on the setting of paraments in your software and looking forward to your reply.

  • Ron Liekens

    Can Gqrx work on a Raspberry Pi with a FCDpro+? Like to make a server with these two items.

    • Hi Ron,
      Gqrx is too heavy to run well on the Raspberry Pi and while you may find other SDR packages that do, I don’t think the Raspoberry Pi wouldn’t be my first choice for such a server. I’d rather use a board with dedicated Ethernet.

  • apogsasis

    This is really cool, I started playing with using MIDI to control GQRX in a performance setting

  • Jason J

    Is there a way to use wildcards in the allowed hosts? I tried and it didn’t seem to work. Also when I explicitly put in an IP address and try to telnet in, it seems to accept the connection and then immediately close it. It works on localhost however. Is there something I’m doing wrong?

  • samlachance

    Just wanted to chime in an say that this management over TCP is great. I was able to use it to pass information to a usb connected arduino with lcd screen so I can monitor the frequency and signal strength without pulling up the window! Great work!

  • Andy Webster

    Great feature, thank you so much Alexandru. It’s probably worth making a note on this page at what version does gpredict provide the AOS/LOS output… I struggled for a while using the gpredict version from the Ubuntu repo until I finally came across another article on the web pointing me at the git version, installed that, AOS and LOS check boxes appeared the configuration and everything started working.

    Thanks again, 73
    Andy G7UHN

    • Hi Andy,

      Good idea. I have added a note stating that only the development version of gpredict knows about the AOS and LOS signals.

  • I can connect, but on telnet screen, alwais RPRT 1.
    Where is my error?

  • Helbet Robert Mihai

    Hi there! There are any possibilities to send IQ data from HackRF somewhrere in the Internet?