Device user arguments: updated documentation

plugins/samplesink/soapysdroutput/readme.md

@@ -22,6 +22,12 @@ This works similarly to LimeSDR USB or BladeRF 2.0 micro
 
 The binary distributions provide only the SoapySDR base library. It is your responsibility to install SoapySDR in your system with the SoapySDR plugins suitable for your hardware.
 
+<h2>User arguments</h2>
+
+Occasionally some devices may require to have the user specifying keyword parameters in order to open the device correctly. Most noticeably the Red Pitaya (driver `redpitaya`) needs the IP address of the board specified as a `addr=x.x.x.x` key value pair as it does not get scanned automatically.
+
+In such a case you will use the device user arguments (Preferences -> Devices -> User arguments) with the dialog as described [here](../../../sdrgui/deviceuserargs.md)
+
 <h2>SoapySDR API implementation</h2>
 
 Not all parts are implemented. Currently the following have been left out:

plugins/samplesource/soapysdrinput/readme.md

@@ -22,6 +22,12 @@ This works similarly to LimeSDR USB or BladeRF 2.0 micro
 
 The binary distributions provide only the SoapySDR base library. It is your responsibility to install SoapySDR in your system with the SoapySDR plugins suitable for your hardware.
 
+<h2>User arguments</h2>
+
+Occasionally some devices may require to have the user specifying keyword parameters in order to open the device correctly. Most noticeably the Red Pitaya (driver `redpitaya`) needs the IP address of the board specified as a `addr=x.x.x.x` key value pair as it does not get scanned automatically.
+
+In such a case you will use the device user arguments (Preferences -> Devices -> User arguments) with the dialog as described [here](../../../sdrgui/deviceuserargs.md)
+
 <h2>SoapySDR API implementation</h2>
 
 Not all parts are implemented. Currently the following have been left out:

sdrbase/device/deviceuserargs.h

@@ -24,7 +24,7 @@
 
 #include "export.h"
 
-struct DEVICES_API DeviceUserArgs
+struct SDRBASE_API DeviceUserArgs
 {
 public:
     struct Args {

sdrgui/deviceuserargs.md

@@ -0,0 +1,45 @@
+<h1>Devices user arguments management</h1>
+
+The user can give arguments in the form of a string related to a specific device that appears in the list of enumerated device. At the moment these arguments are related to a specific hardware and its sequence in enumeration. For example `LimeSDR,0` for the first Lime SDR, `LimeSDR,1` for the second Lime SDR ...
+
+THe corresponding plugin can make use of this user string in any way it finds useful. At present this is used only by the SoapySDR input/output plugins to override the `kwargs` (keyword arguments) at device open time (the `driver` argument is preserved as defined in the enumeration)
+
+The following dialog is used to specify these arguments:
+
+![Device user arguments dialog](../doc/img/MainWindow_user_args.png)
+
+<h2>1 Available devices list</h2>
+
+This is the list of available devices reported by the initial enumeration. There are 3 columns:
+
+  - **HwID**: This is the "hardware ID". It represents a type of device like `HackRF` or `TestSource`
+  - **Seq**: The device sequence in enumeration starting at 0. You may have more that one device of the same type in the system
+  - **Description**: A descriptive string stored by the enumeration process to help identify which device is which
+
+<h2>2 Import device button</h2>
+
+Use this button to import the selected device in the panel above (1) to the panel below (3) that lists the user arguments by device and sequence. You can only import a device which hardware ID and sequence is not already in the panel below.
+
+<h2>3 User arguments</h2>
+
+This is the list of arguments given by the user and attached to a specific device given its hardware ID and sequence. There are 3 columns:
+
+  - **HwID**: This is the "hardware ID". It represents a type of device like `HackRF` or `TestSource`
+  - **Seq**: The device sequence in enumeration starting at 0. You may have more that one device of the same type in the system
+  - **Arg string**: The user argument string. It can be of any form and not necessarily in the `key1=value1, key2=value2` form. It is up to the corresponding plugin to interpret the string and to make use of its information.
+
+<h2>4 Delete button</h2>
+
+Use this button to delete the arguments currently selected in the above panel (3)
+
+<h2>5 Edit arguments</h2>
+
+Use this line editor to change the arguments currently selected in the above panel (3). The text will be commited when the focus is lost.
+
+<h2>6 Cancel button</h2>
+
+The changes made to the argument list are temporary. You can use this button to dismiss the changes and close the dialog.
+
+<h2>7 OK (confirmation) button</h2>
+
+The changes made to the argument list are only temporary. You can use this button to commit the changes and close the dialog.

sdrgui/readme.md

@@ -50,6 +50,8 @@ The following items are presented hierarchically from left to right:
     - _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](../plugins/channelrx/demoddsd/readme.md) for details on how to decode Digital Voice modes.
+    - _Devices_: section to deal with devices settings
+      - _User arguments_: opens a dialog to let the user give arguments specific to a device and its instance (sequence) in the system
   - Help:
     - _Loaded Plugins_: shows details about the loaded plugins (see 1.3 below for details)
     - _About_: current version and blah blah.
@@ -58,7 +60,7 @@ The following items are presented hierarchically from left to right:
 
 See the audio management documentation [here](audio.md).
 
-<h4>1.2. Logging preferences</h4>
+<h4>1.2. Preferences - Logging</h4>
 
 ![Main Window logging preferences](../doc/img/MainWindow_logging.png)
 
@@ -112,8 +114,11 @@ Use the "OK" button to validate all changes
 
 Use the "Cancel" button to dismiss all changes
 
+<h4>1.3 Preferences - Devices - User arguments</h4>
 
-<h4>1.3. Loaded plugins display</h4>
+See the devuces user arguments management documentation [here](deviceuserargs.md).
+
+<h4>1.4. Help - Loaded plugins display</h4>
 
 When clicking on Help -> Loaded Plugins from the main menu bar a dialog box appears that shows information about the plugins loaded in SDRangel: