GQRX::Remote - Control Gqrx using the Remote Control protocol
use GQRX::Remote; # Initialize a $remote and connect to the local server my $remote = GQRX::Remote->new(); $remote->connect(); # Set up some options $remote->set_demodulator_mode('AM'); $remote->set_frequency(44000000); # 44,000 kHz # Retrieve the signal strength my $strength = $remote->get_signal_strength();
The GQRX::Remote module provides a Perl interface to the remote control protocol of the Gqrx software defined radio program. Using this, programs can communicate with a Gqrx instance over a socket connection.
To begin using this module, create a remote object:
my $remote = GQRX::Remote->new();
This object provides the interface for using and managing a connection to Gqrx.
my $remote = GQRX::Remote->new(exit_on_error => 1);
When exit_on_error is enabled, any errors encountered are considered fatal and will cause a die to be executed. This is useful when writing simple scripts, where errors would cause the execution to fail anyway. It is for convenience and can save a programmer a little time. While this might make sense for some scripts, applications generally should not use it, and instead perform proper error checking and handling.
exit_on_error
die
If the module is initialized with the exit_on_error option, all errors will results in a die() call with the error message. Otherwise, calls that fail will return a value of undef when a failure occurs.
undef
In these situations, the error message is retrievable by calling $remote->error(). This returns a string containing the error message.
$remote->error()
# Example handling of an error if (! defined $remote->get_signal_strength()) { print "get_signal_strength() failed with error: " . $remote->error(); }
This module connects to a Gqrx instance at a defined IP address and port. By default, this is the localhost (127.0.0.1) and port 7356.
localhost
127.0.0.1
7356
# Connect to 127.0.0.1:7356 $remote->connect(); # If the server isn't local and on the default port, these # may be overridden $remote->connect(host => '192.168.1.100', port => 4242);
After successfully connecting, a 1 will be returned. In the case of a failure, a 0 will be returned, and an error will be set. If exit_on_error is enabled, failures will exit, but otherwise they should be captured and handled.
0
if (! $remote->connect()) { # Connection failed }
# To get the frequency: $frequency = $remote->get_frequency(); # To set the frequency: $remote->set_frequency(4400000); # 44,000 kHz
All frequency values are in hertz.
On success the set_frequency() call returns 1. On failure, either call will return undef.
set_frequency()
# To get the demodulator_mode: $demodulator_mode = $remote->get_demodulator_mode(); # To set the demodulator_mode: $remote->set_demodulator_mode('WFM');
Any demodulator mode supported by Gqrx should work. At the current time this includes: AM, FM, WFM, WFM_ST, WFM_ST_OIRT, LSB, USB, CW, CWL, CWU.
On success the set_demodulator_mode() call returns 1. On failure, either call will return undef.
set_demodulator_mode()
# Retrieve the signal strength $remote->get_signal_strength();
On success, this returns the signal strength. On failure, it will return undef.
# To get the squelch_threshold: $squelch_threshold = $remote->get_squelch_threshold(); # To set the squelch_threshold: $remote->set_squelch_threshold(-23.1);
On success the set_squelch_threshold() call returns 1. On failure, either call will return undef.
set_squelch_threshold()
# Start recording $remote->start_recording(); # Stop recording $remote->stop_recording();
These calls can be used to automatically recording of audio in Gqrx. On success they return 1, and on failure undef.
$remote->set_recorder_status(1); $remote->set_recorder_status(0); $remote->get_recorder_status();
The API documentation lists the protocol for getting and setting recorder status. As of Gqrx 2.5.3 these requests always fail. The implementation has been included to provide for complete support of the documented protocol.
Recording audio files can be still be achieved via the start_recording() and stop_recording() calls.
start_recording()
stop_recording()
On success set_recorder_status() returns 1. On failure, either call will return undef.
set_recorder_status()
* GQRX::Remote on GitHub:
https://github.com/DougHaber/gqrx-remote
* Example script for collecting signal strength data: (included in distribution)
https://github.com/DougHaber/gqrx-remote/blob/master/example
* Gqrx:
http://gqrx.dk/
* Gqrx remote control protocol documentation:
http://gqrx.dk/doc/remote-control
Original author & current maintainer: Doug Haber <dhaber@node99.net>
Either the Perl Artistic Licence http://dev.perl.org/licenses/artistic.html or the GPL http://www.opensource.org/licenses/gpl-license.php
Copyright (c) 2016 Douglas Haber
All rights reserved. This is free software. You may distribute under the terms of either the GNU General Public License or the Artistic License.
To install GQRX::Remote, copy and paste the appropriate command in to your terminal.
cpanm
cpanm GQRX::Remote
CPAN shell
perl -MCPAN -e shell install GQRX::Remote
For more information on module installation, please visit the detailed CPAN module installation guide.