Previous page (Basics) <------- Back to index -------> Next page (Recording)


GUI description

The main window

This window controls the data acquisition and general program behavior. It's a small one, subdivided in tabs. The variable fields in window have green color, while fixed texts and pushbuttons are yellow.

After program startup (unless a configuration file has been chosen at command prompt via the -s option) the program configures itself following the settings present in default.rts.

The first time the program is invoked - when that file doesn't exist yet - it takes the hardcoded (factory) settings and creates default.rts in the working directory.

That file is updated following the changes you made before exiting the program. The user can save these settings in a dedicated file by the means of “Save As” pushbutton. That file can be retrieved later from GUI by clicking the Open button or by specifying it as argument for -s command line option.

Some installation-dependent parameters, like GNUplot path and the daily events count, are recorded in a local configuration file (The registry under Windows, or .config files under Linux) in order to allow the portability of .rts files between different stations.


Pushbuttons

There are six pushbuttons at window's top:

While at bottom there are the two pushbuttons Start and Stop to start and stop the data acquisition thread. Below them, the small status bar shows the acquisition status or warnings or errors.

Even if Start has been pressed, the user can still operate on main window's controls except for those located in the Device tab. Some of the modifications take effect immediately while others will take effect only after acquisition stop and restart.

Note: Depending of the acquisition mode and other parameters chosen, the acquisition could stop many seconds after pressing the Stop button, this because the programs avoids to truncate the data files while capturing events and postpones the stop after all data files are closed. Despite this, pressing Quit the program exits immediately regardless the acquisition status.

After pressing Quit, if the current configuration differs against the configuration file rts loaded, a small dialog box prompts to keep or not our changes in that file. The prompt doesn't appear if no rts file has been loaded first, the default configuration is always updated silently.

exit_prompt


Device tab

The Device tab allows to control the samples acquisition parameters.

Once started, on main window all the available input sources are detected and made available through the device selector, on the device tab. This detection happens once when the program starts. Further dongles plugged afterwards won't be recognized. There are three types of devices currently supported:

devtab

By default, the device selected is the test device if no SDRs neither dongle servers are found.

dev_sel_close

Other devices appear in the drop-down list after clicking the listbox button at right side and can be selected.

dev_sel_open

When a configuration file is specified with -s option the selected device will be the one in use when that configuration file has been saved, or again test patterns if that device is not found. This happens - for instance - when the configuration file used comes from a different station with a different kind of dongle, having a different device identification string (like Generic RTL.... or similar). In this case, a warning is displayed:

dev_mismatch

then - after clicking OK - a new dongle will be listed in the drop-down, replacing the missing one.

Different simultaneous Echoes instances can open different dongles. The remaining controls in device tab operate on an opened device. Some fields could be hidden depending of the nature of the selected device.

Antenna

High level SDR devices allow to select between different antennas in order to get the best gain when working on different bands. In this case, Echoes shows the Antenna selector box, that in other cases is not visible.

Sample rate range

Some SDRs allow you to select a sample rate within precise ranges. RTL-SDR, for example, provides two ranges: 225k to 300k and 900k to 3200k. Then this selector allows you to select the desired range in which with the Sample rate control the user can select the value of the sample rate. In case there is only one available range, this control will be hidden. Other devices do not provide ranges, because they require predetermined sample rate values. The Audio device is one of them and the user can select one of the allowed sample rates with this control.

Sample rate

With this control the sample rate can be selected in 1Hz steps. By default, the control is initialized with the highest possible sample rate allowed by device. For the devices requiring predetermined sample rate values, the sample rate is chosen with the control Sample rate range, and this control will be hidden.

Band filter range and bandwidth

These controls appear when the SDR is equipped with RF filters for different bands. The first control selects a bandpass filter for a particular range, while the second finely adjusts its bandwidth. If the device does not provide such filters, these controls remain hidden.

Tuning range

This control appears when SDR provides non-contiguous ranges of tunable frequencies. By selecting an interval, the tuning selection with Tune group will be allowed only within that interval.

Tune group

The tuning frequency can be selected with the buttons with resolution of 1kHz. To set a finer-grained tuning frequency, right-click on the digits and enter the frequency in the edit box. There is no need to type the thousands separators, they will be added afterwards.

RF Gain

This control adjusts the RF gain as percentage of the maximum gain provided by the SDR. By checking the AGC box, you leave the device to choose the best gain, and the percentage inserted is ignored. By default the AGC is unchecked.

Error compensation

Enter a value only in case the frequency values on waterfall look shifted versus a reference signal. A precise well known fixed frequency carrier can help to verify the accuracy of the frequency scale. Shifts can be compensated by entering a value in ppm, that can be negative or positive and have 2 decimals precision. The integer part is managed by hardware, while the fractional part is used to apply a transparent offset correction to the waterfall for a finer centering.

Note: when acquisition is running, all controls in the Device tab are disabled.


FFT tab

The second tab FFT encloses the controls that have effect on spectrogram quality.

FFTtab

Downsampler

This control allows to reduce the sample rate of the samples acquired by the SDR before processing them with FFT. The Downsampling frequency drop-down lists up to 5 values, automatically generated by recursively divide by two the sample rate frequency or - if the SDR provides band filters - the bandwidth. So, for instance, with a sample rate of 3 MHz, the allowed values will be 3 MHz, 1,5 MHz, 750 kHz, 375 kHz, 187500 Hz.

The Downsampling bypass box, if checked, disables the Downsampling frequency drop-down and forwards the acquired samples directly to FFT.

Window

This control applies an additional algorithm to the FFT output that aims to a better separation between the spectrogram output points and reduce the noise level (N). There are 10 kinds of windows available, the default is Rectangle meaning no window at all.

Resolution

The FFT resolution can be selected with the two +/- buttons. The FFT transforms the input signal in time domain to a number of points (or bins) in frequency domain that is a power of two; the buttons increment or decrement this power, and the resulting number of FFT points is showed at right, just below the value in Hz.

Since this value depends of the sample rate chosen

(Hz = SR/points)

that value will be likely a non-integer frequency.

The smallest is the resolution step, the lower is the noise level (N) and the higher is the time to spend to get samples from the dongle. The default resolution is 4096 points (781.25 Hz with SR=3.2 MHz)


Output tab

The third tab Output includes the controls that have effect on data files generation.

With the acquired data, Echoes produces four kinds of files:

Outtab

After this premise, let's continue describing the Output tab controls:

Refresh interval required

This control sets the waterfall update cadence timer (aka tick). The default value is 100 mS, this means that when Start is pressed, an internal timer every 100 mS awakes the output controller to display all the scans the radio produced in meantime and updates the output files. Since Echoes has no real time claims, it normally occurs that the required refresh interval does not correspond to the effective scrolling speed. If the program takes more than 100mS to draw a scan, the following tick will be lost, so the waterfall will be updated 200 mS later instead of 100. This is the reason why I called it required interval. The effective Measured interval is available some seconds after acquisition start and its value appears immediately under the Refresh interval required control. It's advisable to keep the interval request few mS under the measured one, in order to optimize the program's CPU load.

Acquisition mode

The most important parameter to set is Acquisition mode because it has effect on the whole program behavior and the contents of generated files. Moreover, depending of the mode chosen, some controls can become ineffective. This is not the case of the Refresh interval required seen above.

Note: In Continuous and Periodic modes the statistic CSV file tends to grow a lot; in a single day it can reach several tenths of MB with 100mS interval.

Plot type

This control specifies in which way we want to represent the dump files:

2Dplot

3Dplot

2Dpower

In the following image, the two power graphs, the GUI's and the plotted one are compared on the same event. The screenshot has ben mirrored in order to display the time axis direction congruent.

2DpowerCompared

Delay before shot

This control delays the shot triggering by some amount of seconds after the event detection. The delay is specified as percentage of the screenshot / dump coverage. In this way, even if dumps coverage is different than screenshot coverage, the echo will appear in the same position on both.

For instance, if screenshot coverage is 30 sec and the dump is 60 sec long, setting a delay of 50% the screenshot will be taken 15 seconds after the peak, while the dump will occur after 30 seconds.

Stop after

Here you can set the number of shots to be captured before stopping acquisition automatically. The default number is zero, because the default mode is Continuous and it takes no shots; in Periodic or Automatic modes this number can be set high, for instance 9999.

Since in Automatic mode the event counter is zeroed at every midnight UTC, it is very unlikely that 9999 will be reached, so the acquisition won't never stop. In Periodic mode instead it will, sooner or later.

In Continuous mode, if this number is set higher than zero, the acquisition won't start, and the status bar at main window's bottom will show the warning

Please set shots=0 and upThreshold=0
Data dump coverage

The scan data used to drive the waterfall are saved in a circular buffer. The size of this buffer, expressed in seconds can be set with this control.

In Periodic mode, when the required number of seconds has been reached, all the data are dumped in a DAT file.

In Automatic mode, the dump file is created only if there is a detected pending event, otherwise the scans remains in the buffer until they reach the maximum age to be silently deleted. Even if a dump has been created, the scans dumped in the file aren't deleted before being aged, because there could be two or more events close in time that trigger further dumps. So, the same scan can appear in more than one dump file.

In Continuous mode this control is ignored.

Upper and lower peak thresholds and their behavior

The event capturing feature available in Automatic mode is based on two thresholds, Peak lower threshold and Peak upper threshold.

An event starts when the reference data value exceeds the lower threshold; at this moment the event counter is incremented and the first of the three rows is added to the statistic CSV buffer (Raise stage).

When the reference data value exceeds the upper threshold, the second row is added to the buffer (Peak stage). This row is continuously updated until the monitored data reaches the highest value.

When the reference data value falls under the lower threshold, the third row is added to the buffer (Fall stage), the event terminates and the three rows are appended to the statistic CSV file.

A reference data is the statistic CSV column that triggers an event. The statistic CSV columns are described in Recording section, but only three of them can be selected with the Thresholds behavior control.

Whatever reference is chosen, it applies on both thresholds.

Averaged scans for N calculation

The instantaneous noise level is obtained by averaging the power of all points in a scan. This value could significantly vary between consecutive scans, for this reason the N value is the result of a mobile average of the instantaneous noise of the last n scans. With this control the n value can be specified. The bigger is this number, the flatter will be the cyan noise line on the power history graph. This is also the number of scans averaged to calculate the average S-N and average S values reported in statistic CSV.

Peak detection range

In order to limit the detection of false positives, the S value is calculated considering a frequency range narrower than the entire scan portion displayed on waterfall. This range is expressed as percentage of the waterfall's width and is represented on frequency ruler with two blue triangular arrows.

range

These arrows can be dragged with the mouse. By dragging one, the other will follow specularly.

Join events closer than

This control specifies the minimum time distance between consecutive events in order to be considered the same event, the default is 1000 mS, a zero value means no joins.


Reporting tab

When the program runs in Automatic mode, every night at 00:00 UTC the acquisition is stopped and the postprocessing thread starts. This thread moves all the data files generated during the expired day (screenshots and dumps) into an archive subdirectory hierarchy, classifying them by day and kind of events: overdense, underdense or fake (false positives).

reporttab

The postprocessing thread generates and maintains a daily report file. This is a CSV file containing, for each day archived, the count - divided by hour - for each type of event (Underdense, Overdense or Fake) and the daily totals. If the file already exists in the archive, the daily counts are appended to that file.

Report coverage and Report contents groups

Besides the daily report, that is simply a table, Echoes can generate a full report. It is a single HTML page divided in 7 sections that can be included or not in the report by checking the appropriate boxes:

  1. Include site infos: The Site infos button opens a form where information about your station can be entered. It's also possible to replace the Echoes logo with a customized one. With box checked, information and logo will be inserted in report.

  2. siteinfos

  3. Summary: inserts a table where the events numbers are split by kind (underdense, overdense, fake) in columns and by days on rows.

    summary

  4. Hourly count color tables: when checked, generates one or more RMOB's Colorgramme-like diagrams, where the daily counts are split by hour and expressed with a color scale where black means zero and red is the highest value in diagram. The figure below shows the Total without fakes where all the valid events recorded are counted; this diagram is always present if the box is checked. Then if overdense shots/plots has been checked, a second diagram is inserted where only overdense events are counted. Finally, a third diagram is inserted if underdense shots/plots has been checked.

    hourly

  5. Overdense shots: when checked, all the overdense events screenshots will be inserted in the report.

  6. Underdense shots: when checked, all the overdense events screenshots will be inserted in the report.

  7. Overdense plots: when checked, all the overdense events plots will be plotted in an image then inserted in the report.

  8. Underdense plots: when checked, all the overdense events plots will be plotted in an image then inserted in the report.

  9. Detailed data with each shot: when checked, all the information about each event will be included in tabular form. These are the information coming from the statistic CSV file where each event is recorded on three rows.

    details

Events filtering group

The controls in this group configure the events classification functionality. This argument is developed in more detail in Recording section.

Besides this lasting-based discrimination, there are also three experimental filters aimed to discriminate three different causes for false positives. These filters work by applying bare empiric rules on the event data collected in statistic CSV and are executed before the check of event lasting.

Note: being experimental, all the filter enabling checkboxes are checked by default but currently they depends of some hardcoded parameters that have been calculated under a determinate configuration (bandwidth, peak detection range, refresh interval, thresholds...); therefore it is very likely that changing the configuration will affect the functionality of these filters, in better or in worse.

Generate report

This button triggers the full report generation. The data included in the report are taken from the archive and cover the days range specified in Report coverage group. The report is generated if at least one of the days in the specified range are included in the archive. If the acquisition was active when the button was pressed, after some seconds of freezing the acquisition continues once the report has been generated.

Flatten archive

This button opens a dialog box prompting the user to specify an empty folder where the entire archive will be copied with no subfolders, with all files in the same folder. If such a folder does not exist, the dialog allows to create a new one before copying.

This feature was initially added for development purposes, but I also found it useful for composing a video by joining events captured over several days in a timeline; it's a much easier task to perform when all the images involved are in the same folder. The following video was produced in a Windows environment with the batch file make_video.bat present in the program folder Echoes:

Perseids 2021

It uses ImageMagick to compose the video, that must be installed on your system. Follow the instructions in the batch file to customize and use it.

Automatic report

This checkbox enables the automatic full report generation. If checked, every night after the midnight swap the Report coverage dates are checked. If the To date matches the day just terminated, the report generation starts.

If generation ends successfully, the coverage dates are incremented both by the same number of days. This means - for instance - that if From is set on a Monday and To on a Sunday, the report will be generated once a week the night between Sunday and Monday, and will cover the entire week.


Preferences tab

The last main window's tab is about user's preferences, a miscellaneous of controls that covers different aspects of the program that can be customized.

preftab

Show... checkboxes

Some people dislikes to see the measuring grids above the waterfall and the side graphs, so this tab allows to hide them by unchecking the related box. By default, all these box are checked.

Disable tooltips

This box is unchecked by default, allowing the display of the help messages that appear on every control when the mouse cursor hovers them. Once the user has become familiar with Echoes controls, they could result annoying, so they can be hidden by checking this box.

Erase shots and report files before start

When checked, all the screenshots, the plots and report files produced with the configuration file currently loaded, and present in the working directory, will be deleted at acquisition's start. This option is useful while experimenting with the parameters setup, but remember to uncheck it before saving the final setup on a new configuration file! By default is unchecked.

Erase old statistics before start

When checked, all statistic CSV files produced with the configuration file currently loaded, and present in the working directory, will be deleted at acquisition's start. This option is useful while experimenting with the parameters setup, but remember to uncheck it before saving the final setup on a new configuration file! By default is unchecked.

Enable event notification sound

Checked by default, it can be unchecked to avoid playing the notification sound ("ping") when a new event is detected.

Enable acquisition fault notification sound

Checked by default, it can be unchecked to avoid playing the notification sound ("crash") when an acquisition fault occurs.

Use direct buffers when possible

Unchecked by default. When checked, it ask the program to get samples from SDR by using directly its data buffers instead of use the streaming interface, see also SoapySDR Direct Buffers.

Data lasting

Here can be specified the maximum age of the files stored in the archive to preserve disk space. Older files will be automatically deleted at acquisition's start. This applies only on the files generated with the configuration file currently loaded, leaving others untouched. The default value is 40 days and - depending if you decide to capture screenshots only or also dump files - this could mean a disk space between 20 to 100 GB indicatively.

Waterfall palette style

Allow to choose the B/W or color palette for waterfall. The default is B/W.

Pause captures if N exceeds...

In this control can be specified a threshold in dBfs. If the average noise N exceeds this threshold, the event captures are inhibited and on the waterfall's status bar appears the TOO NOISY message. The acquisition remains active to detect when N falls under the threshold but no events neither screenshots will be recorded. This is to prevent recording of false positives caused by unforeseen and strong disturbances.

dBfs scale offset and gain

The second value is a multiplier of each power of the FFT output point, while the first is added to the second. By calibrating these two constants with a reference signal source, Echoes can measure power in dBm.

UDP server address

Here can be specified the IP address of another machine running Echoes to recognize it as a dongle server device. It can still be the same machine, by specifying the localhost address (127.0.0.1). In this case, two Echoes instances must be running, one as dongle client (where localhost has been set) and the other as a dongle server connected to a physical dongle, where the UDP server address has been set to 0.0.0.0 that is the default value. This is the native Echoes way of sharing samples locally, it has nothing to do with SoapyRemote library. See also Advanced

UDP server port

Port number where a dongle server accepts connections from clients. The default is 1234.

Reserved storage

This is the space in gigabytes that must be left free on the disk hosting the working directory. When the space occupied by the working directory grows out, the acquisition is stopped automatically. The default value is zero (no limits).

Find GNUplot

This button appears when Echoes doesn't know where to find * GNUplot *. When the button is pressed, an * Open File * dialog opens to select the GNUplot executable file (generally * wgnuplot.exe * under Windows, or simply * gnuplot * under Linux).

Once the executable has been specified, it is stored in a local configuration file (in Windows it is the registry, in Linux it is the * ~ / .config * folder). It will not be saved in the * rts * configuration because this is a machine specific setting. From the next restart of the program, this button will no longer be shown.

Status bar

It's a small place at bottom of main window where status messages are displayed.


The waterfall window

This window shows the output of FFT processing, split in three diagrams.

waterfall

Waterfall spectrogram

At the center is the Waterfall spectrogram, with the time axis in Y and frequency in X, scrolling downwards.

If in a time interval set as update interval the radio thread is able to extract more scans, the scan displayed will be the result of an integration of the scans received.

This integrated scan is good for recording on dump files and for statistic purposes but isn't yet ready for displaying on the waterfall, because the waterfall pane's horizontal width almost never matches the FFT resolution set; often it's smaller but could even be bigger, depending of the combination of Downsampling frequency, FFT resolution, Freq. zoom and Freq. offset set.

So, the power represented by each pixel could be the result of the averaging of many FFT points, or could be the direct FFT point value and even replied for more pixels.

For instance, if the waterfall pane is 1024 pixel wide and FFT resolution is set to 4096 points, each pixel shows the average of four points.

This compaction algorithm is for visualization purposes only. Values saved in statistical CSV and GNUplot dump files only deal with integrated scans values.

While scrolling, horizontal time tick marks are plotted with a cyan color, and the relative UTC time is printed at the left side. These ticks can be hidden by unchecking the relative boxes in main window's preferences tab.

By left-clicking with the mouse on any point of the waterfall, a tooltip box shows the frequency and UTC time at the moment of clicking. Obviously if the acquisition is active, that point will continue to scroll downwards: clicking won't stop the acquisition.

Brightness and contrast

At waterfall's left is the color power scale that shows the correspondence between waterfall color and dBfs; it can be adjusted with the Brightness and Contrast sliders placed at window's bottom. The waterfall is in fact a flat representation of 3D data, since the dBfs values are represented by colors instead of points on a Z axis.

System information

The window's bottom shows some system information: the Latitude and Longitude entered in Site info dialog, the Automatic shots captured vs. the total required and the Current date/time UTC.

Note: due to a bug in Qt5, the date shows GMT instead of UTC, but it's still UTC.

There are also two labels that appear in particular circumstances:

Note: this label should appear temporarily. Once expired the number of seconds specified in Data dump coverage it must disappear. If it remains still, it means that the value set as Peak lower threshold is too low.

Power history

On the right, a scrolling graph called Power History displays - in cyan - the averaged power of each scan line called noise level (abbreviated N) and - in red - the maximum power detected within the peak detection range called signal level (abbreviated S). The graph scrolls at the same speed and direction as the waterfall. The orange track is the instantaneous S-N difference, while the brown track is its averaged value, obtained with a mobile averaging of the S-N values of the last n scans. n is the value of Averaged scans for N calc. control. There are two further values displayed by this graph: the upper and lower threshold for automatic acquisition mode, represented respectively in yellow and pale green. Due to their nature, the Power zoom control must be set to 1x in order to see all these five tracks simultaneously. If the graph gets cluttered, unneeded tracks can be hidden by clicking on their colored labels - that are in fact pushbuttons.

Instantaneous power

Below the waterfall is the Instantaneous power graph, where the power values are represented in Y and their frequencies in X. The dBfs scale is centered on N value, so only the Power offset slider has no effect on it.

Power zoom and offset sliders

The two sliders Power zoom and Power offset are placed at window's bottom right side. The first reduces/enlarges the power scale range while the second shifts the position of the traces along the power axis. Their value can be adjusted finely by clicking on the slider then typing on cursor keys.

Frequency zoom and offset sliders

Other two sliders Freq. zoom and Freq. offset, placed at window's top, define the frequency portion of the downsampled band displayed by waterfall and its side graphs.

By default Freq. zoom is set to 1.0X, so the waterfall shows the entire downsampled band set in main window's FFT tab. With this setting, the Freq. offset slider is locked in zero position. This slider gets unlocked when Freq. zoom is moved to any value different to 1.0X. In this way, the frequency range monitored for events can be shifted away from the tuned frequency, in case some DC component is present in the spectra (aka "spike artifact").

After any adjustment of downsampling frequency, tune, bandwidth or sample rate controls, the Freq. zoom and Freq. offset are restored to their default values (1.0x and zero).

Radio parameters

The waterfall window shows also some parameters related to radio receiving:

notches

Note: dragging the red arrow is a replacement for the eccentricity slider introduced in rel.0.33 and now removed.

Finally, in the up right corner, there are six instantaneous values displayed. As already said, their colored labels are in fact pushbuttons that toggle the relative track with the same color on Power history graph:

Manual shot

Immediately below the power sliders, there is the Manual shot pushbutton that triggers a screenshot when pressed. Manual screenshots are counted separately from automatic screenshots and follow a different naming convention. They are also not accompanied by any GNUplot data.

Frequency ruler and notches

By right-clicking on the frequency ruler, it's possible to place a notch filter on that frequency. A small pop-up window appears, to set the width of the blocked band in Hz. Its width can be adjusted with a slider or by typing. Once confirmed the value, a brown triangle appears, with a horizontal red line above it, to visualize the blocked band width. The triangle can be dragged leftwards / rightwards with the mouse.

notches

It's possible to add many filters, the unique condition is that they cannot overlap each other. The effect of notch filter is that, in the frequency range it covers, the waterfall will display the N value calculated in the last scan, in place of the real value produced by FFT. This effect applies also to all the data and plot files produced. The filter can be edited by right-clicking on the red arrow, and deleted by clicking the minus icon on the pop-up.


Previous page (Basics) <------- Back to index -------> Next page (Recording)