sdrangel/sdrgui/readme.md

Main Window interface

Multi device support

Starting with version 2 SDRangel supports running several sampling devices simultaneously. Each concurrent device is associated to a slot with a set of tabbed windows in the UI. These tabs are marked R0, R1, R2...

The slots are arranged in a stacked fashion so that when a new device is added with the Acquisition -> Add device set menu a new slot is allocated in the last position and when a devcie is removed with the Acquisition -> Remove last device set menu the slot in the last position is deleted. Slot 0 (R0) receiver slot is created at initialization and cannot be deleted with the menu. The letter "R" in the tab names indicates that the slot is for a receiver (source) device while "T" designates a tramsmitter (sink) device.

The tabbed windows are:

• Sampling devices (1)
• Sampling devices control (2)
• Spectrum display control (3)
• Channels (4)
• Spectrum from device (5)

The combination of a sampling device and its associated channels is called a "device set".

The sampling devices tab (1) acts as a master and when one of its tabs is selected all other tabs are selected accordingly i.e. all R0s, all R1s, etc... in tabs (2), (3), (4) and (5)

In each slave tab group (2), (3), (4) and (5) an individual tab corresponding to one device can be selected without affecting the selection of the other tabs. This way you can sneak peek into another spectrum or channel goup without affecting the display of other tabbed windows.

Interface details

1. Main menu

The following items are presented hierarchically from left to right:

• File:
  • Exit (shortcut Ctl-Q): Exit the program
• View:
  • Fullscreen (Shortcut F11): Toggle full screen mode
• Device sets:
  • Add source device set: adds a new source (receiver) type device set to the device set stack (last position)
  • Add sink device set: adds a new sink (transmitter) type device set to the device set stack (last position)
  • Remove last device set: removes the last device set from the device set stack
• Window: presents the list of dockable windows. Check to make it visible. Uncheck to hide. These windows are:
  • Sampling devices control: control of which sampling devices is used and add channels
  • Sampling devices: the sampling devices UIs
  • Spectrum display: the main spectrum displays (output from the sampling devices)
  • Presets: the saved presets
  • Commands: the defined commands
  • Channels: the channels active for each device
• Preferences:
  • Audio: opens a dialog to choose the audio output device (see 1.1 below for details)
  • Logging: opens a dialog to choose logging options (see 1.2 below for details)
  • DV Serial: if you have one or more AMBE3000 serial devices for AMBE digital voice check to connect them. If unchecked DV decoding will resort to mbelib if available else no audio will be produced for AMBE digital voice
  • My Position: opens a dialog to enter your station ("My Position") coordinates in decimal degrees with north latitudes positive and east longitudes positive. This is used whenever positional data is to be displayed (APRS, DPRS, ...). For it now only works with D-Star $$CRC frames. See DSD demod plugin for details on how to decode Digital Voice modes.
• Help:
  • Loaded Plugins: shows details about the loaded plugins (see 1.3 below for details)
  • About: current version and blah blah.

1.1. Preferences - Audio

Audio output preferences:

In the "Audio Output" tab of the audio preferences dialog you can choose which device is used for audio output. This choice is global for the application and is persistent. If the device is not available anymore at a later stage it reverts to the default devuce (first row).

Audio input preferences:

In the "Audio Input" tab of the dialog you can choose the device used for audio input in a similar way as you do for the output device.

In addition you can adjust the global volume using the dial knob at the bottom. Audio input behaves slightly differently than audio output and when the audio engine is started the volume is forced to a value that by default is maximum (1.0). This is not always desirable and using this control you can set it at a lower level (0.00 to 1.00 in 0.01 steps).

Eventually select "OK" to confirm the settings or "Cancel" to dismiss without change.

1.2. Logging preferences

Log message will appear as follows:

12.11.2017 15:03:37.864 (D) DownChannelizer::applyConfiguration in= 300000 , req= 375000 , out= 300000 , fc= 0
----------------------- --- ----------------------------------------------------------------------------------
(1)                     (2) (3)

• 1: Timestamp in dd.MM.yyyy hh:mm:ss.zzz format
• 2: Message level: (D): debug, (I): info, (W): warning, (C): critical, (F): fatal
• 3: Message text

1.2.1. Console log minimum message level

This sets the minimum message level for a message do be displayed on the console:

• Debug: all messages with QtDebug level and above
• Info: all messages with QtInfo level and above
• Warning: all messages with QtWarning level and above
• Error: all messages with QtCritical level and above. Includes QtFatal.

1.2.2. File log minimum message level

This sets the minimum message level for a message do be logged to file:

• Debug: all messages with QtDebug level and above
• Info: all messages with QtInfo level and above
• Warning: all messages with QtWarning level and above
• Error: all messages with QtCritical level and above. Includes QtFatal.

1.2.3. File log enable

Use the checkbox to enable (check) or disable (uncheck) the dual logging to file

1.2.4. Log file selection

Use this button to open a file dialog to choose or create a new log file. There is a 2s delay before a file change is effective.

1.2.5. Log file name

The full path of the log file appears here

1.2.6. Confirm changes

Use the "OK" button to validate all changes

1.2.7. Dismiss changes

Use the "Cancel" button to dismiss all changes

1.3. Loaded plugins display

When clicking on Help -> Loaded Plugins from the main menu bar a dialog box appears that shows information about the plugins loaded in SDRangel:

Name

Plugin display name. Tells briefly what this plugin is about.

Version

Starting with SDRangel version 2.0.0 this is the SDRangel version when the plugin was last updated.

GPL

Tells if the plugin is under GPL license.

Expansion

The plugin entry can be expanded or collapsed using the caret on the left. When expanded it shows more information about the copyright of the author and locations on the web where the plugin can be found. In all cases this is just here.

OK button

Click here when done to dismiss the dialog.

2. Sampling devices

This is where the plugin GUI specific to the device is displayed. Control of one device is done from here. The common controls are:

2.1. Start or stop acquisition

• When a play icon (▶) is displayed with a grey background the device is not operational
• When a play icon (▶) is displayed with a blue background the device is ready to start
• When a stop icon (■) is displayed with a green background the device is currently running
• When a play icon (▶) is displayed with a red background there is an error and a popup displays the error message. An Error typically occurs when you try to start the same device in more than one tab.

2.2. Record I/Q

This is the I/Q from device record toggle. When a red background is displayed the recording is currently active. The name of the file created is test_n.sdriq where n is the slot number.

The format is S16LE I/Q samples. Thus there are 4 bytes per sample. I and Q values are 16 bit signed integers. The file starts with a context header containing information about center frequency, sample rate and timestamp of the start of the recording. This header has a length which is a multiple of a sample size (normally 24 bytes thus 6 samples). Thus this file can be used as a raw I/Q file with S16LE samples tolerating a glitch at the start corresponding to the 6 "random" samples.

You can also zap the 24 bytes header with this Linux command: tail -c +25 myfile.sdriq > myfile.raw

To convert in another format you may use the sox utility. For example to convert to 32 bit (float) complex samples do: sox -r 48k −b 16 −e signed-integer -c 2 myfile.raw -e float -c 2 myfilec.raw

Note that you have to specify the sampling rate and use .raw for the file extensions.

2.3. Device sampling rate

This is the sampling rate in kS/s of the I/Q stream extracted from the device after possible decimation. The main spectrum display corresponds to this sampling rate.

2.4. Center frequency

This is the current center frequency in kHz with dot separated thousands (MHz, GHz). On devices for which frequency can be directly controlled (i.e. all except File Source and SDRdaemon) you can use the thumbwheels to set the frequency. Thumwheels move with the mouse wheel when hovering over a digit.

When left clicking on a digit a cursor is set on it and you can also use the arrows to move the corresponding thumbwheel.

When right clicking on a digit the digits on the right are all set to zero. This effectively does a ceil rounding at the current position.

Additional inputs

Most devices will also present an interface to control automatic DC removal and I/Q imbalance and also a control of the LO correction in ppm.

• Example1:
• Example2:

3. Sampling devices control

This is where the sampling device for one device set is selected and the channel plugins are instantiated.

3.1. Currently sampling device name

This label shows the human readable sampling device name

3.2. Open sampling device change dialog

Use this push button to open the device selection dialog to change the sampling device. This dialog will open:

3.2.1. Device selection combo

Use this combo box to select the device. Only available devices will appear in the list. For devices having more than one channel (ex: LimeSDR) the channel number will appear next to the device sequence number inside the brackets. Ex: LimeSDR[0:1] 0009060B00473419 designates the second Rx (Rx #1) of the first encountered LimeSDR which serial number is 0009060B00473419.

3.2.2. Device selection confirmation

Use the OK button to confirm your choice and exit the dialog

3.2.3. Device selection cancellation

Use the Cancel button to exit the dialog without any change

3.3. Reload currently selected device

This button activates a close/open sequence to recycle the device. It may be useful when the device is not streaming anymore or in an attempt to clear possible errors. Make sure the streaming is stopeed first.

3.4. Channel selector

Use this combo box to select a channel plugin to create a new channel

3.5. Add a new channel

Use this push button to add a new channel with the selected plugin

4. Spectrum display control

These are the controls of the main spectrum display in (7). Please refer to the spectrum display documentation (TBD) for details.

5. Presets and commands

The presets and commands tree view are by default stacked in tabbs. The following sections describe the presets section 5A) and commands (section 5B) views successively

5A. Presets

This is a tree view of the saved presets. Presets record the channels setup and a copy of the settings of each sample source that has been used when saving this preset. Thus you can use the same channel arrangement with various devices having their particular setup.

5A.1. Preset selection

You select a preset or a preset group by clicking on its line in the tree view. All actions (6) will be done relative to this preset or preset group.

5A.2. Group

You can organize your presets into groups. Groups can be collapsed or expanded by using the caret icon on the left.

5A.3. Center frequency

The center frequency used in this preset is displayed here.

5A.4. Rx/Tx indicator

"R" is displayed for a Rx device set and "T" for a Tx device set

5A.5. Preset name

You can give a name to your preset. Names need not to be unique.

5A.6. Preset control or actions

The controls are located as icons at the bottom of the window:

5A.6.1. New preset

Click on this icon to create a new preset with the current values in the selected sample device tab (Main window: 2).

5A.6.2. Update preset

Click on this icon to create a update the selected preset with the current values in the selected sample device tab (Main window: 2). Please note that this does not save the preset immediately on disk to save presets immediately you need to use the save button (4).

5A.6.3. Edit preset

Opens a new window where you can change the group name and description.

• for group items you can rename the group or merge all group presets into an existing group by selecting this existing group
• for preset items you can:
  • move the preset to another existing group by selecting this existing group
  • assign this preset to a new group by typing in this new group
  • change the description

5A.6.4. Save presets

Presets are saved to disk automatically at exit time you can however request to save them immediately using this icon.

5A.6.5. Export preset

Using the previous icon presets are saved globally in a system dependent place. Using this icon you can export a specific preset in a single file that can be imported on another machine possibly with a different O/S. The preset binary data (BLOB) is saved in Base-64 format.

5A.6.6. Import preset

This is the opposite of the previous operation. This will create a new preset in the selected group or the same group as the preset being selected.

5A.6.7. Delete preset

• on a preset item: deletes the selected preset.
• on a preset group: deletes the group and all its presets.

5A.6.8. Load preset

Applies the selected preset to the current device set (source and channel plugins).

5B. Commands

This is a tree view of the saved commands. Commands describe the path to an executable file, its arguments a possible link to a keystroke event that triggers the execution. Similarly to presets commands can be arranged into groups and have a description short text.

Typically an "executable file" is a script (Python, shell, whatever...) or can be a compiled program (c, c++, java, whatever...) that interacts with SDRangel using its web REST API. When called from within SDRangel they can act as "macros" allowing to perform actions automatically.

Of course any binary that resides in your system can be used that way like /bin/ls or /bin/date although these two are of anedoctical interest...

5B.1. Command selection

You select a command or a command group by clicking on its line in the tree view. All actions (6) will be done relative to this command or command group.

5B.2. Group

You can organize your commands into groups. Groups can be collapsed or expanded by using the caret icon on the left.

5B.3. Description

Short description of a command.

5B.4. Key binding indicator

• -: no key binding
• P: key press binding
• R: key release binding

5B.5. Key binding sequence

This is a descriptive text of the key sequence that is used for the key binding.

5B.6. Command control or actions

The controls are located as icons at the bottom of the window:

5B.6.1. Create new command

Click on this icon to create a new command. This opens an edit dialog see the edit section (5B.6.3) for the details of the edit dialog.

5B.6.2. Duplicate command

Click on this icon to duplicate the currently selected command (inactive on groups). Later you can edit the details of the copy with the edit dialog (see 5B.6.3 next)

5B.6.3. Edit command or command group

Command groups

With this dialog you can rename a group using the text box or if you select an existing group with the combo this will merge the contents of the group with the existing group

Commands

You can edit the details of the command with this dialog.

5B.6.3.1. Edit group

You can select an existing group with the combo or create a new one for this command using the text edit box

5B.6.3.2. Edit description

You can edit the description using this text box. The description will appear in the tree view.

5B.6.3.3. Executable file selection

Clicking on this button wil open a file dialog to select the executable file that will be run with this command. The file selection dialog has predefined file pattern selections:

• * for All files
• *.py for Pyhon files
• *.sh or *.bat for shell or batch files
• *.bin or *.exe for binary files

5B.6.3.4. Executable file path

This is the full path of the selected executable file.

5B.6.3.5. Command line arguments

Use the text box to edit the arguments given to the executable file as in program arguments.

You can use special codes to insert information specific to the application context:

• %1: the address of the web REST API
• %2: the port of the web REST API
• %3: the currently selected device set index

5B.6.3.6. Key binding

Use this checkbox to enable or disable the command execution binding to a key or combination of keys press or release event

5B.6.3.7. Key binding capture

Use this button to capture the key or key combination that will be used for the key binding. After pushing this button just type in the key or key combination.

5B.6.3.8. Key binding display

This shows the key or combination of keys used for the key binding.

5B.6.3.9. Release key binding

Use this checkbox to bind the key or combination of keys to the key release event. If unchecked the binding will be associated to the key press event.

5B.6.3.10. Confirm changes

Use the "OK" button to confirm the changes.

5B.6.3.11. Cancel changes

Use the "Cancel" button to cancel the changes.

5B.6.4. Run command or groups of commands

This will run the currently selected command. If the selection is a group it will run all commands of the group starting them in the displayed order. Please note that commands are run in independant processes and therefore all launched commands in the group will run concurrently.

5B.6.5. View last command run details

This dialog will show the results of the last run including the output (merged stdout and stderr).

5B.6.5.1. Process status

When the process is not running the stop icon (■) is displayed. The backgroumd color indicate different states:

• no color (same as backround): the process has never run during this session
• red: the process ended with error
• green: the process ended successfully. This does not mean that there was no programmatic error.

When the process is running the play icon (▶) is displayed with an orange background.

5B.6.5.2. Refresh data

Pushing this button will update the data displayed with the latest status. Please note that the log is displayed only when the process is terminated.

5B.6.5.3. Start time

This is the timestamp of process start. It is filled with dots ... if the process has never started during this session.

5B.6.5.4. End time

This is the timestamp of process end. It is filled with dots ... if the process has never terminated during this session.

5B.6.5.3. PID

This is the process PID. It is 0 if the process has never run during this session.

5B.6.5.6. Process kill

Use this button to kill (send SIGKILL) the running process. It has no effect if the process is not runing.

5B.6.5.7. Command line

This shows the actual command line that was used to start the process

5B.6.5.8. Error status

This is the translation of QProcess::ProcessError. Possible values are:

• ...: the process has never run during this session
• Failed to start: the process could not start. For example the executable file has no execution rights actually
• Crashed: the process ended with crash. This is the status when you killed the process
• Timed out: the last waitFor...() function timed out.
• Write error: an error occurred when attempting to write to the process. For example, the process may not be running, or it may have closed its input channel.
• Read error: an error occurred when attempting to read from the process. For example, the process may not be running.
• Unknown error: an unknown error occurred.

5B.6.5.9. Exit code

This is the program exit code. When the process crashes this is the signal by which the process end was caused. For example if you kill the process with button (6) it sends the process a SIGKILL (code 9) and therefore the value is 9.

5B.6.5.10. Exit status

There are only two possibilities: either the program exits normally but possibly with a non zero exit code or it ends with a crash.

5B.6.5.11. Process log

This is the log of the process (merged stdout and stderr). Please note that it is updated only on program termination.

5B.6.5.12. Exit

By pushing the "Close" button the process output window is closed.

5B.6.6. Save commands

This will save the commands immediately. The commands will be automatically saved when the applicaiton exits normally.

5B.6.7. Delete commands or group of commands

This will delete the currently selected command or if selection is a group this will delete all commands in the group.

5B.6.8. Activate keyboard binding

Use this button to activate the keyboard binding. This requires that the focus is set to the main window. On a few occasions the main window looses focus and the button gets unselected. Just click again on this button to reactivate the keyboard binding. Note that you need to have this button selected (its background should be lit in beige/orange) for the key binding to be effective.

6. Channels

This area shows the control GUIs of the channels curently active for the device. When the preset is saved (as default at exit time or as a saved preset) the GUIs are ordered by increasing frequency. If presets share the same frequenccy they are ordered by their internal ID name. Thus new channel GUIs will appear ordered only when reloaded.

Details about the GUIs can be found in the channel plugins documentation which consits of a readme.md file in each of the channel plugins folder (done partially).

With these channels: AM demod, BFM demod, DSD demod, NFM demod, UDP source, UDP sink some common basic settings can be set with a popup dialog. This dialog is opened by clicking on the small grey square on the top left of the channel window. The settings are as follows:

6.1: Window title

Changes the channel window title

6.2: Channel color

Changes the color of the window title bar and spectrum overlay. To change the color click on the color square to open a color chooser dialog. The hex rgb value is displayed next to the color square.

6.3: Frequency scale display type

When the mouse is over the channel window or over the central line in the spectrum a channel parameter is displayed on the frequency scale. This parameter can be:

• Freq: channel absolute center frequency
• Title: channel window title
• AdSnd: UDP address and send port
• AdRcv: UDP address and receive port

6.4,5,6: UDP address (4) receive port (5) and send port (6)

Some channels can exchange data over UDP. Depending on the channel the data is the following:

Channel	Data sent	Type	Data received	Type	Address
AM demod	Audio	Mono	N/A	N/A	Remote
BFM demod	Audio	Stereo	N/A	N/A	Remote
DSD demod	Audio	Stereo	N/A	N/A	Remote
NFM demod	Audio	Mono	N/A	N/A	Remote
SSB demod	Audio	Mono	N/A	N/A	Remote
WFM demod	Audio	Mono	N/A	N/A	Remote
UDP source	Audio, I/Q	Mono, Stereo	Audio	Mono	Remote
UDP sink	N/A	N/A	Audio, I/Q	Mono, Stereo	Local

Data type is S16LE 1 channel (Mono) or 2 channels (Stereo or I/Q)

6.7: Validate and exit dialog

Validates the data (saves it in the channel marker object) and exits the dialog

6.8: Cancel changes and exit dialog

Do not make any changes and exit dialog

7. Spectrum from device

This shows the spectrum in the passband returned from the sampling device possibly after decimation. The actual sample rate is shown in the device control at the left of the frequency display (2.3)

The spectrum display is cotrolled by the display control (4).

8. Status

8.1. SDRangel version

Self explanatory

8.2. Qt version

Qt version with which this copy of SDRangel was compiled.

8.3. Architecture

Codename of the CPU architecture in which SDRangel is running.

8.4. Operating system

Pretty print of the operating system in which SDRangel is running.

8.5. Local date and time

Local time timestamp according to system clock