Previous page (Installation) <------- Back to index -------> Next page (GUI)


Basics

Launching from GUI

Warning: the SDR device must be plugged in before invoking the program because it won't be recognized if plugged in later.

When clicking on Echoes desktop icon, the program starts 'naked', without additional command line arguments, using the default parameters. The program opens two windows, the main window and the waterfall window. The picture below has been taken on a Windows machine so it shows a third window too, the console window.

echoes_running

  1. The Main window (left side) contains the controls related to tuning, acquisition, data recording and report generation.

  2. The Waterfall window (right side) contains the real-time graphical output of the program: a waterfall diagram with colors scale and tuning ruler, an Instantaneous power graph under a Power history graph at its right and zoom/offset sliders on frequency and power. The waterfall scrolls downward. Echoes works exclusively with UTC time; all the time references present in the logs and in the waterfall are in UTC.

  3. The Console window (in background) opens automatically under Windows to display some status messages and warnings generated by Soapy library. Moreover, this window can display also the program log (echoes.log) when Echoes is started with -v option. Under Linux, the same behavior is achieved by launching the program from a terminal shell session.

Now, before continuing the GUI description, let's talk a little about the command line options first.


Launching from a shell

Under Windows, open a command prompt CMD.EXE window, change the current directory to:

C:\program files\GABB\echoes

this because the installer doesn't insert that directory in user's path, so you must find the executable before starting it with the following command:

echoes --help  <Enter>

Under Linux the command is the same, but it's not required to change the directory first, since Echoes is installed in a directory included in $PATH ( /usr/bin ).

The above command recalls the command line help, listing all the available options when starting Echoes : --help is one of these.

cmdhelp

Generally speaking, none of these options are mandatory to start Echoes with GUI, by clicking its icon on the desktop, but someday you could need to use them in a script or a batch file.


-c

The -c option starts Echoes without a GUI (console UI). The configuration used is the default one, (default.rts) unless another configuration file has been specified with the parameter

-s <config_file>

The acquisition starts immediately. This operating mode is suited for headless, stand-alone stations. Being no GUI active, the snapshots can't be generated; but if Generate GNUplot has been enabled in the chosen configuration file, each event will generate a data file that can later be open with GNUplot. The configuration files can be easily edited with a text editor or can be created with Echoes itself by opening the program in GUI mode, set the desired parameters then save the new configuration with a name different than default.

Linux only: What said above, is valid for Linux too, when invoking Echoes -c from an X-terminal window. The -c option prevents Echoes to display windows, but a running X server is still mandatory to run it.

A Linux system could nevertheless be started in multiuser mode without graphics at all. On systems supporting systemd you can set that mode with the command:

systemctl set-default multi-user.target

By appending the command

/usr/bin/console_echoes -c ...etc... 

at the end of the file /etc/rc.d/boot.local , Echoes will start automatically as a service at next reboot, without need of user login. Its textual output can be watched by the means of the command

journalctl -f | grep echoes .

console_echoes is simply an alias for echoes executable file. When called with that name, Echoes recognizes you want to exclude totally the graphical support and will run even without an X server running.


-d

The -d option activates the dumb mode: the program reads the IQ samples from the local USB dongle and forwards them to a remote UDP client without process neither store data locally. This option includes -c . Please note that sending samples via UDP is always enabled, even while running in GUI mode. The streaming starts if another Echoes instance asks to get samples from this instance. In this way is possible to run multiple instances on the same machine with different speeds and capture settings.


-l

The GUI language is chosen automatically depending of the operating system localization settings. Currently, the only alternative to the hardcoded language (English) is Italian, so the Italian language will be displayed automatically on Italian PCs. If you desire to override the default behavior and load a precise translation file (the extension .qm is implicit) it can be specified with the option -l.


-n < level>

Echoes can produce lot of debugging text output that can be read in the echoes.log file, under the default working directory. This file is re-created from scratch each time Echoes is launched. By setting the -n 0 option, the creation of this file will be inhibited, saving some CPU time and disk resources. Higher numbers (up to 5, with default 3) increase output verbosity and decrease the program performances.

Under Linux, echoes.log is never created because the text output is sent to syslog to be collected in the system journal. Echoes messages can be showed with the command:

journalctl |grep echoes

-s <config_file>

The GUI settings can be saved in user defined rts files. This can be done by pressing the Save As pushbutton on the main window and specifying a path and a file name. The rts extension will be added by default. These files can be reloaded in future sessions by specifying the -s option followed by a rts file path.


-r

By default, each time it starts, Echoes looks for a default configuration file in the working directory called default.rts. This file is updated with the actual parameters set in the GUI when quitting the program. In this way, the program's settings remains persistent between consecutive invocations. The -r option can be set when you desire to reset the parameters to the hard coded settings (-s will be ignored in this case). The same result can be achieved by deleting default.rts .


-v

The debug messages dumped in echoes.log can be watched in real time on the console/terminal window by specifying the -v option. In this way, the messages will be printed on stderr too.


-w <working_dir_path>

The default working directory ( echoes/ ) is normally created under the user's home directory, but another working directory can be specified with the -w option. In this directory will be stored the files generated by the program (logs, screenshots, data files, configurations, reports).


Getting started catching events

These hands-on instructions are suited to use GRAVES radar as source, but it can be adapted on other sources adjusting the tuning frequency accordingly. These settings can be find in TEST_PERIODIC.rts file. On Windows, you can find it into the program's folder, while on Linux the test rts files are located under /usr/share/packages/echoes. While opening this file, Echoes will ask you to select another device. This because the rts file stores the device used when it has been created, and your device is likely different from mine. So choose another plugged SDR in the device selector.

  1. In Device tab, set the minimum sample rate (226000), Tune frequency about 10khz away from 143.050.000, let's say 143.040.000 or 134.060.000 and maximum gain 49

  2. In FFT, check downsampler bypass and set resolution to 32768 or higher (the higher you set, the slower will be the waterfall)

  3. In Output tab, set PERIODIC mode, set 100ms of refresh interval , set a nonzero value as Stop after, say 1000, both thresholds to zero and dump data coverage set to 30sec (no matter if you use GNUplot or not, in periodic mode this field indicates the time between sequential shots).

  4. In waterfall window, set Freq. zoom at about 10khz and Freq.offset to +/-10khz depending of your tune frequency, to reach the Central frequency of 143.050.000.

  5. In waterfall window, set the power zoom to 1x in order to see all the 4 enabled tracks (S, N, difference S-N and average difference) in the power history graph. Note that thresholds are not showed in periodic mode.

  6. Start the acquisition and wait about a minute to read the waterfall coverage on waterfall window.

  7. Stop the acquisition and set the number of seconds of waterfall coverage in Output tab, dump data coverage.

  8. Restart acquisition. In this way the program will produce sequential screenshots. If data dump coverage is 30s it means 120 shots per hour. If you run it for at least a couple of hours you should be able to catch at least some sporadic events and see their data in the upper right corner of the waterfall window: The peak S and noise N levels, their instantaneous difference and average difference. These data will be useful later to configure the program to run in AUTOMATIC mode.

  9. Now stop the acquisition and set acquisition mode AUTOMATIC in Output tab.

  10. Set a big number in Stop after like 9999 or so, in order to cover an entire day avoiding acquisition stop.

  11. Set the thresholds mode differential.

  12. Set the Upper threshold level. A starting value for this threshold can be figured out by looking the echoes captured in periodic mode: a. Check the difference S-N value reached in each event, the highest dBfs value reached by orange track, and write them down, (for instance let's say 30, 32, 29, 31, 30, 28, 30 dBfs). b. Write also the average difference values - the brown track. It should be almost equal for all your echoes (for instance 7, 7, 8, 8, 8, 7, 7) c. Take the lowest difference value (28 dBfs), and the highest average difference (8 dBfs). d. Take the average of these two values, then add the highest average difference and set the result as upper threshold:

     ((28 - 8) / 2 + 8 = 18 dBfs)
    
  13. For lower threshold, set a value some dBfs above the highest average difference (lets' say 10..12 dBfs). Beware that a value too low could generate never ending events; in this case you'll see a CAPTURING label on waterfall window's lower side that never disappears.

  14. Start the acquisition. If enabled, in preferences tab, a "ping" sound will notify about each capture. The above settings can be find in TEST_AUTO_GRAVES.rts, obviously the thresholds should be adapted to match the measures made following the above steps.

  15. The captured data can be find in a subfolder echoes/ under the user's home folder. They will be archived each midnight UTC in a subfolder having the same name of the rts file.


Previous page (Installation) <------- Back to index -------> Next page (GUI)