goestuner

README

GOESTuner

goestuner is a simple CLI tool that can be used to help orient your parabolic dish with one of the GOES satellites. Think of it as a simple 'signal strength meter' for GOES/HRIT satellites, with large signal strength bars that are easier to see on a screen in sunlight.

Dependencies

• SoapySDR and any required module (e.g. SoapyRTLTCP for RTL_TCP)
• libsathelper: See here for build and installation instructions
• libcorrect: See above
• Go version 1.18+

Supported SDRs

So far this tool has only been verified as working with the SDRs listed below, but theoretically, it should work for any SDR that SoapySDR supports, and any SDR that supports complex samples. I do not have the resources to test every SDR under the sun, so if anyone is able to test this with other SDR's supported by SoapySDR, please let me know so they can be added to the list of supported radios!

• RTL-SDR Blog v3
• rtl_tcp (via the SoapyRTLTCP module)

Installation

Raspberry Pi (Debian 13)

Install dependencies:

• sudo apt install libsoapysdr-dev cmake build-essential
• Build libsathelper:
  • git clone https://github.com/opensatelliteproject/libsathelper
  • cd libsathelper
  • make libcorrect
  • sudo make libcorrect-install
  • make
  • sudo make install

Once the dependencies are satisfied, you can simply install goestuner with go install:

go install github.com/jrwynneiii/goestuner@latest

Fedora 42+

Install dependencies:

• sudo dnf install gcc g++ make cmake soapy-rtlsdr SoapySDR-devel SoapySDR
• Build libsathelper:
  • git clone https://github.com/opensatelliteproject/libsathelper
  • cd libsathelper
  • Apply patch to allow libsathelper to be built with modern GCC
    • wget https://raw.githubusercontent.com/JRWynneIII/goestuner/refs/heads/main/libsathelper.patch ; git apply libsathelper.patch
  • make libcorrect
  • sudo make libcorrect-install
  • make
  • sudo make install

Once the dependencies are satisfied, you can simply install goestuner with go install:

go install github.com/jrwynneiii/goestuner@latest

Before running goestuner, you will need to copy or generate a configuration file. The preferred method to configure goestuner is to use the built-in configuration tool. Simply run goestuner config with your SDR attached, and fill out the appropriate information (see here for more info on the configuration tool).

An example configuration file is provided in this repo as config.hcl. Modify and copy this file to either /etc/config.hcl, ~/.config/goestuner/config.hcl, or have a config.hcl in your current working directory where you run this tool. See Manually configuring GOESTuner for more information.

Usage

Usage: goestuner <command> [flags]

Flags:
  -h, --help           Show context-sensitive help.
      --conf=STRING    Set path to a config file (Default: [./config.hcl, ~/.config/goestuner/config.hcl, /etc/goestuner/config.hcl])
      --verbose        Prints debug output by default

Commands:
  probe [flags]
    List the available radios and SoapySDR configuration

  tune [flags]
    Starts the TUI and connects to the SDR

  config [flags]
    Opens the configuration file creator

Run "goestuner <command> --help" for more information on a command.

• config: Opens the configuration TUI and queries any available SoapySDR compatible devices and modules and prepopulates the config with the most common settings
• probe: Queries SoapySDR to list the available SDRs and their respctive settings (NOTE: Does not show anything for rtl_tcp devices)
• tune: Starts the HRIT demodulator/decoder and TUI. Please note, that while the demodulator/HRIT decoder isn't perfect, it may take up to 30 seconds for goestuner to get a lock on the signal, and start decoding packets. This is normal.

Keyboard Shortcuts

• p: Pauses the TUI; processing is still ongoing in the background. This can be useful for reading the log output, if it becomes too verbose or too fast.
• q: Stops the application gracefully and exits
• f: Flushes the processing stack and resets everything to default values. This is useful if using rtl_tcp, since it can introduce a delay between when the antenna is moved, and that is reflected in the sampling (This delay can be caused by any number of reasons, including poor network connection between the rtl_tcp server and the SoapySDR client)

Configuration

Automatically configuring GOESTuner

GOESTuner includes autogeneration of a configuration file through the config command. Simply run goestuner config (or goestuner --conf /path/to/conf.hcl config to set a non-default location for the generated config file), and the configuration TUI will open, and goestuner will query all available SoapySDR compatible devices and modules that are available on your system. Simply fill out the form, and select the Generate Configuration File to save your changes.

The most common configuration options are already prepopulated for you. To get up and running quickly, simply just select the driver (for example: rtlsdr) in the Driver drop down list, and select your device in the Device drop down, then hit Generate.

If the librtltcpSupport SoapySDR module is available, then the configuration tool will automatically add this as an available option. NOTE: This does not apply to SoapyRemote!

To configure goestuner to use rtl-tcp, select the rtltcp option in the Driver drop down, and modify the Address and Port fields, then select Generate.

Manually configuring GOESTuner

The goestuner config file uses the HashiCorp Configuration Language DSL. Included as config.hcl, the example configuration file should be enough to get you started. Most values will never need to be changed, except for the radio {} block. This contains the configuration that is used to tell SoapySDR which radio to use. Included in the config file is an example for an RTL-SDR dongle, and one for accessing an SDR over rtl_tcp.

Additionally, goestuner has the ability to read configuration from environment variables. The same example configuration as is set in config.hcl is replicated in config.sh. Simply modify this file and run source /path/to/config.sh ; goestuner tune to utilize this feature

Radio

For example, if you have an RTL-SDR connected directly via USB, your radio {} block should look something like this:

radio {
  driver = "rtlsdr"
  device_index = 0
  gain = 5
  frequency = 1694100000
  sample_rate = 2048000
  sample_type = "complex64"
  decimation = 1
}

If you only have 1 dongle attached, this should work right out of the box. Otherwise, specify the device_index for the radio you would like to use.

Alternatively, if you'd like to connect goestuner to an rtl_tcp server, simply change the driver to "rtltcp", and add the address parameter (e.g. address = "192.168.0.100:1234")

TUI

A few tunables are exposed to allow cusomization of the TUI. These parameters are listed in the tui {} block in the config file.

• refresh_ms = 500: Sets the refresh rate of the signal meters and packet/decoder stats to half a second (value is in milliseconds)
• rs_threshold_warn_pct = 20: Defines the percentage value that the "Reed-Solomon Corrections" meter turns yellow
• rs_threshold_crit_pct = 25: Defines the percentage value that the "Reed-Solomon Corrections" meter turns red
• vit_threshold_warn_pct = 10: Defines the percentage value that the "Viterbi Error Rate" meter turns yellow
• vit_threshold_crit_pct = 15: Defines the percentage value that the "Viterbi Error Rate" meter turns red
• enable_log_output = true: Disables the log output in the bottom box, and makes the signal meters larger. Helpful if the meters are still too small to see on a laptop screen in the sunlight

Additionally, if you would like to turn off the frequency plot (since this can be CPU intensive, since FFTs can be pretty beefy), set xrit.do_fft = false

Acknowledgements:

I'd like to thank the Open Satellite Project for creating libsathelper, and SatHelperApp; these two projects were extremely helpful in the development of the demodulator and decoder, and served, not only as a good reference point for development of goestuner, but as a wonderful reference for learning various concepts about SDR and xRIT programming.