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
Trying 127.0.0.1...
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,
     WFM_ST_OIRT, LSB, USB, CW, CWL, CWU)
 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
RPRT 0
f
123456789
c
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.