NAME
GQRX::Remote - Control Gqrx using the Remote Control protocol
SYNOPSIS
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();DESCRIPTION
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.
INITIALIZATION
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.
ERROR HANDLING
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.
In these situations, the error message is retrievable by calling $remote->error(). This returns a string containing the error message.
# Example handling of an error
if (! defined $remote->get_signal_strength()) {
print "get_signal_strength() failed with error: " . $remote->error();
}CONNECTING TO A SERVER
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.
# 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.
if (! $remote->connect()) {
# Connection failed
}BASIC USAGE
FREQUENCY
# To get the frequency:
$frequency = $remote->get_frequency();
# To set the frequency:
$remote->set_frequency(44000000); # 44,000 kHzAll frequency values are in hertz.
On success the set_frequency() call returns 1. On failure, either call will return undef.
DEMODULATOR MODE
# 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.
SIGNAL STRENGTH
# Retrieve the signal strength
$remote->get_signal_strength();On success, this returns the signal strength. On failure, it will return undef.
SQUELCH THRESHOLD
# 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.
RECORDING
# 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.
RECORDER STATUS (experimental)
$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.
On success set_recorder_status() returns 1. On failure, either call will return undef.
SEE ALSO
* 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
AUTHOR
Original author & current maintainer: Doug Haber <dhaber@node99.net>
LICENSE
Either the Perl Artistic Licence http://dev.perl.org/licenses/artistic.html or the GPL http://www.opensource.org/licenses/gpl-license.php
COPYRIGHT
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.