[Positioning] Review CLI options descriptions

Fix some typos and reorganise the command-line options' descriptions.
Rename positioning.radar-* --> positioning.radar.*
Same in the sample configuration file.

TODO

@@ -135,7 +135,6 @@
 - User interface
    ° When reading the APs, add them to the mobiles' list (or another
    way to be able to have a single entry for an AP).
-   ° Review the option names & descriptions.
    ° Add option positioning.self-calibrate (or autocalibrate), to
    activate automatically the options needed by the autocalibration.
    ° Improve --verbose (and/or debug level): print the options, etc.

owlps-positioning/cfg/owlps-positioning.conf

@@ -5,6 +5,8 @@
 #flush-output-files = true
 
 [data-input]
+# The options in this section are related to the data that are read
+# when the program starts.
 
 # Description of the machines running the listeners.
 ap-medium = CSV
@@ -26,6 +28,9 @@ waypoints-csv-file = cfg/waypoints.csv
 reference-points-csv-file = csv/reference_points.csv
 
 [input]
+# The following options are related to the input of the requests
+# (positioning requests and (auto-)calibration requests) from the
+# aggregator.
 
 #medium = CSV
 csv-file = csv/input.csv
@@ -34,13 +39,19 @@ csv-file = csv/input.csv
 #udp-port = 9902
 
 [log]
+# The following options allow to log the requests received from the
+# aggregator.
 
+# Uncomment the following line to completely disable logging (has
+# precedence over the other logging options):
 #medium = none
 
 medium = CSV
 csv-file = /tmp/owlps-positioning.log
 
 [positioning]
+# The options in this section are related to the way the requests are
+# handled and the results are computed.
 
 # Uncomment lines to activate one or more algorithm.
 #algorithm = Real
@@ -49,6 +60,26 @@ csv-file = /tmp/owlps-positioning.log
 #algorithm = RADAR
 #algorithm = FRBHMBasic
 
+# This option allows to create a new mobile when a request is sent by
+# a mobile which is not currently in the mobiles' list (i.e. not
+# declared in the mobiles' configuration file). If unset, the requests
+# sent by unknown mobiles will be dropped.
+# It is unactivated by default, mainly to avoid interferent devices.
+#accept-new-mobiles = false
+
+# This option allows to create a new AP when a request is captured by an
+# AP which is not currently in the APs' list (i.e. not declared in the
+# APs' configuration file), or when a self-calibration request is sent
+# by an unknown AP.
+# It is unactivated by default for the sake of security.
+#accept-new-aps = false
+
+# When receiving a calibration or autocalibration request from an AP,
+# containing the transmiter's coordinates, memorise the new AP's
+# coordinates.
+# This is unactivated by default for the sake of security.
+#update-ap-coordinates-online = false
+
 # Coordinates of the deployment area.
 # This is used to delimit the area in which reference points are
 # generated (when generate-reference-points is activated), and also
@@ -60,19 +91,6 @@ csv-file = /tmp/owlps-positioning.log
 #area-start = -2;-2;0
 #area-stop = 20;30;6
 
-# With the RADAR algorithm, for a given positioning request, average
-# all the calibration requests associated with a reference point before
-# to compute the SS distance. The default is false, i.e the positioning
-# request is compared directly to each calibration request.
-#radar-average-reference-points = false
-
-# With the RADAR algorithm, do not select reference points on which an
-# AP is sit, as far as possible (i.e. if there are reference points
-# where no AP sits). This is useful if you are using autocalibration
-# and want to select only the generated reference points.
-# The default is false.
-#radar-ignore-ap-reference-points = false
-
 # Generate reference points from the (auto)calibration requests
 # received.
 #generate-reference-points = false
@@ -99,27 +117,25 @@ csv-file = /tmp/owlps-positioning.log
 # serve the positioning process, not to use it.
 #position-calibration-requests = false
 
-# This option allows to create a new AP when a request is captured by an
+[positioning.radar]
-# AP which is not currently in the APs' list (i.e. not declared in the
+# This subsection contains the options related to the RADAR algorithm
-# APs' configuration file), or when a self-calibration request is sent
+# and derivated.
-# by an unknown AP.
-# It is unactivated by default for the sake of security.
-#accept-new-aps = false
 
-# This option allows to create a new mobile when a request is sent by
+# For a given positioning request, average all the calibration requests
-# a mobile which is not currently in the mobiles' list (i.e. not
+# associated with a reference point before to compute the SS distance.
-# declared in the mobiles' configuration file). If unset, the requests
+# The default is false, i.e. the positioning request is compared
-# sent by unknown mobiles will be dropped.
+# directly to each calibration request.
-# It is unactivated by default, mainly to avoid interferent devices.
+#average-reference-points = false
-#accept-new-mobiles = false
 
-# When receiving a calibration or autocalibration request from an AP,
+# Do not select reference points on which an AP is sit, as far as
-# containing the transmiter's coordinates, memorise the new AP's
+# possible (i.e. if there are reference points where no AP sits).
-# coordinates.
+# This is useful if you are using autocalibration and want to select
-# This is unactivated by default for the sake of security.
+# only the generated reference points.
-#update-ap-coordinates-online = false
+# The default is false.
+#ignore-ap-reference-points = false
 
 [output]
+# The following options are related to the output of the results.
 
 # This is the default output if none is specified.
 #medium = Terminal
@@ -132,6 +148,9 @@ csv-file = /tmp/owlps-positioning.out
 #udp-host =
 #udp-port = 9910
 
+# The TCPEvAAL output follows the specification of EvAAL 2011 to
+# communicate with the SocketAdapter program developped by the
+# organizers.
 # Note: you can use only one algorithm when using the TCPEvAAL output.
 #medium = TCPEvAAL
 # Currently, the host must be an IP address (not a DNS name).

owlps-positioning/src/radar.cc

@@ -7,7 +7,7 @@
 const ReferencePoint& RADAR::select_point(const Request &request)
 {
   if (Configuration::bool_value(
-        "positioning.radar-average-reference-points"))
+        "positioning.radar.average-reference-points"))
     return Stock::closest_reference_point(request) ;
 
   const CalibrationRequest &cr =

owlps-positioning/src/stock.cc

@@ -383,7 +383,7 @@ closest_reference_point(const Request &request)
       " list is empty!") ;
 
   bool ignore_aps = Configuration::bool_value(
-                      "positioning.radar-ignore-ap-reference-points") ;
+                      "positioning.radar.ignore-ap-reference-points") ;
   unordered_set<ReferencePoint>::const_iterator i =
     reference_points.begin() ;
 
@@ -664,7 +664,7 @@ closest_calibration_request(const Request &request)
       " requests' list is empty!") ;
 
   bool ignore_aps = Configuration::bool_value(
-                      "positioning.radar-ignore-ap-reference-points") ;
+                      "positioning.radar.ignore-ap-reference-points") ;
   unordered_set<CalibrationRequest>::const_iterator i =
     calibration_requests.begin() ;
 

owlps-positioning/src/userinterface.cc

@@ -14,9 +14,14 @@ namespace po = boost::program_options ;
 
 /* *** Default value definitions *** */
 
+/* General options */
 #define DEFAULT_CONFIG_FILE_NAME \
   "/usr/local/etc/owlps/owlps-positioning.conf"
 
+/* Positioning options */
+#define DEFAULT_MESHING_GRAIN 0.5
+
+/* Output options */
 #define DEFAULT_TCPEVAAL_HOST "127.0.0.1"
 #define DEFAULT_TCPEVAAL_PORT 4444
 
@@ -76,12 +81,15 @@ void UserInterface::fill_options()
 void UserInterface::fill_cli_options()
 {
   cli_options->add_options()
-  ("help,h", "Print help.")
+  ("help,h",
-  ("version,V", "Print version information.")
+   "Print help.")
-  ("config-file,f", po::value<string>()
+  ("version,V",
-   ->default_value(DEFAULT_CONFIG_FILE_NAME),
+   "Print version information.")
+  ("config-file,f",
+   po::value<string>()->default_value(DEFAULT_CONFIG_FILE_NAME),
    "Alternative configuration file.")
-  ("verbose,v", "Verbose mode.")
+  ("verbose,v",
+   "Verbose mode.")
   ; // End of options
 }
 
@@ -102,35 +110,40 @@ void UserInterface::fill_data_input_options()
   po::options_description options("Data input options") ;
 
   options.add_options()
-  ("data-input.ap-medium", po::value< vector<string> >()
+  ("data-input.ap-medium",
-   ->composing(),
+   po::value< vector<string> >()->composing(),
    "Medium from which access points are read. You can specify this"
    " option more than once. Allowed: CSV.")
-  ("data-input.ap-csv-file", po::value<string>(),
+  ("data-input.ap-csv-file",
+   po::value<string>(),
    "CSV file to use for access points input (when"
    " data-input.ap-medium = CSV).")
-  ("data-input.mobile-medium", po::value< vector<string> >()
+  ("data-input.mobile-medium",
-   ->composing(),
+   po::value< vector<string> >()->composing(),
    "Medium from which mobiles are read. You can specify this"
    " option more than once. Allowed: CSV.")
-  ("data-input.mobile-csv-file", po::value<string>(),
+  ("data-input.mobile-csv-file",
+   po::value<string>(),
    "CSV file to use for mobiles input (when"
    " data-input.mobile-medium = CSV).")
-  ("data-input.topology-medium", po::value< vector<string> >()
+  ("data-input.topology-medium",
-   ->composing(),
+   po::value< vector<string> >()->composing(),
    "Medium from which topology (buildings, areas and waypoints) is"
    " read. You can specify this option more than once. Allowed: CSV.")
-  ("data-input.areas-csv-file", po::value<string>(),
+  ("data-input.areas-csv-file",
+   po::value<string>(),
    "CSV file to use for topology input (when"
    " data-input.topology-medium = CSV).")
-  ("data-input.waypoints-csv-file", po::value<string>(),
+  ("data-input.waypoints-csv-file",
+   po::value<string>(),
    "CSV file to use for waypoints input (when"
    " data-input.topology-medium = CSV).")
-  ("data-input.reference-points-medium", po::value< vector<string> >()
+  ("data-input.reference-points-medium",
-   ->composing(),
+   po::value< vector<string> >()->composing(),
    "Medium from which reference points are read. You can specify this"
    " option more than once. Allowed: CSV.")
-  ("data-input.reference-points-csv-file", po::value<string>(),
+  ("data-input.reference-points-csv-file",
+   po::value<string>(),
    "CSV file to use for reference points input (when"
    " data-input.reference-points-medium = CSV).")
   ;
@@ -144,12 +157,14 @@ void UserInterface::fill_input_options()
   po::options_description options("Input options") ;
 
   options.add_options()
-  ("input.medium,I", po::value<string>(),
+  ("input.medium,I",
+   po::value<string>(),
    "Medium from which requests are read. Allowed: CSV, UDP.")
-  ("input.csv-file", po::value<string>(),
+  ("input.csv-file",
+   po::value<string>(),
    "CSV file to use for input (when input.medium = CSV).")
-  ("input.udp-port", po::value<int>()
+  ("input.udp-port",
-   ->default_value(OWL_DEFAULT_AGGREGATION_PORT),
+   po::value<int>()->default_value(OWL_DEFAULT_AGGREGATION_PORT),
    "Port on which the UDP socket listens (when input.medium = UDP).")
   ;
 
@@ -162,11 +177,13 @@ void UserInterface::fill_log_options()
   po::options_description options("Log options") ;
 
   options.add_options()
-  ("log.medium,L", po::value< vector<string> >()->composing(),
+  ("log.medium,L",
+   po::value< vector<string> >()->composing(),
    "Medium to which the requests will be logged. You can specify"
    " this option more than once. Allowed: none, CSV. The `none`"
    " value completely disables logging.")
-  ("log.csv-file", po::value<string>(),
+  ("log.csv-file",
+   po::value<string>(),
    "CSV file to use for logging (when log.medium = CSV).")
   ;
 
@@ -179,42 +196,48 @@ void UserInterface::fill_positioning_options()
   po::options_description options("Positioning options") ;
 
   options.add_options()
-  ("positioning.algorithm,a", po::value< vector<string> >()->composing(),
+  ("positioning.algorithm,a",
+   po::value< vector<string> >()->composing(),
    "Algorithms used to compute positions. You can specify"
-   "this option more than once (but at least once). Allowed: Real, FBCM,"
+   " this option more than once (but at least once). Allowed: Real,"
-   " FRBHMBasic, InterlinkNetworks, RADAR.")
+   " FBCM, FRBHMBasic, InterlinkNetworks, RADAR.")
-  ("positioning.area-start", po::value<string>(),
+  ("positioning.accept-new-mobiles",
+   po::value<bool>()->default_value(false),
+   "When receiving requests, add unknown mobiles (mobiles which are not"
+   " declared in the mobiles' configuration file) to the mobiles' list.")
+  ("positioning.accept-new-aps",
+   po::value<bool>()->default_value(false),
+   "When receiving requests, add unknown APs (APs which are not"
+   " declared in the APs' configuration file) to the APs' list"
+   " (default is false, for security purposes).")
+  ("positioning.update-ap-coordinates-online",
+   po::value<bool>()->default_value(false),
+   "Allow AP's coordinates to be updated when a calibration request"
+   " with new coordinates is received from the AP (default is false,"
+   " for security purposes).")
+  ("positioning.area-start",
+   po::value<string>(),
    "Coordinates of the first point of the deployment area; this is"
    " used to delimit the area in which the MinMax multilateration"
    " method tests points and in which the reference points are"
    " generated, if the corresponding options are activated"
    " (string format: \"X;Y;Z\").")
-  ("positioning.area-stop", po::value<string>(),
+  ("positioning.area-stop",
+   po::value<string>(),
    "Coordinates of the last point of the deployment area"
    " (string format: \"X;Y;Z\").")
-  ("positioning.radar-average-reference-points",
-   po::value<bool>()->default_value(false),
-   "With the RADAR algorithm, for a given positioning request, average"
-   " all the calibration requests associated with a reference point"
-   " before to compute the SS distance."
-   " The default is false, i.e the positioning request is compared"
-   " directly to each calibration request.")
   ("positioning.generate-reference-points",
    po::value<bool>()->default_value(false),
    "Generate reference points from the (auto)calibration requests"
    " received.")
   ("positioning.generated-meshing-grain-x",
-   po::value<float>()->default_value(0.5),
+   po::value<float>()->default_value(DEFAULT_MESHING_GRAIN),
    "When generating reference points, this distance (in meters) will"
    " separate each point to the next in X.")
   ("positioning.generated-meshing-grain-y",
-   po::value<float>()->default_value(0.5),
+   po::value<float>()->default_value(DEFAULT_MESHING_GRAIN),
    "When generating reference points, this distance (in meters) will"
    " separate each point to the next in Y.")
-  ("positioning.radar-ignore-ap-reference-points",
-   po::value<bool>()->default_value(false),
-   "With the RADAR algorithm, try to avoid selecting the reference"
-   " points which are coordinates of an AP.")
   ("positioning.accept-new-calibration-requests",
    po::value<bool>()->default_value(false),
    "Add the calibration requests received during the run-time to"
@@ -228,20 +251,17 @@ void UserInterface::fill_positioning_options()
    " calibration requests to be positioned as normal requests."
    " The default is to add them to the calibration requests' list"
    " without position them.")
-  ("positioning.accept-new-aps",
+  ("positioning.radar.average-reference-points",
    po::value<bool>()->default_value(false),
-   "When receiving requests, add unknown APs (APs which are not"
+   "With the RADAR algorithm, for a given positioning request, average"
-   " declared in the APs' configuration file) to the APs' list"
+   " all the calibration requests associated with a reference point"
-   " (default is false, for security purposes).")
+   " before to compute the SS distance."
-  ("positioning.update-ap-coordinates-online",
+   " The default is false, i.e the positioning request is compared"
+   " directly to each calibration request.")
+  ("positioning.radar.ignore-ap-reference-points",
    po::value<bool>()->default_value(false),
-   "Allow AP's coordinates to be updated when a calibration request"
+   "With the RADAR algorithm, try to avoid selecting the reference"
-   " with new coordinates is received from the AP (default is false,"
+   " points which are coordinates of an AP.")
-   " for security purposes).")
-  ("positioning.accept-new-mobiles",
-   po::value<bool>()->default_value(false),
-   "When receiving requests, add unknown mobiles (mobiles which are not"
-   " declared in the mobiles' configuration file) to the mobiles' list.")
   ;
 
   file_options->add(options) ;
@@ -253,23 +273,26 @@ void UserInterface::fill_output_options()
   po::options_description options("Output options") ;
 
   options.add_options()
-  ("output.medium,O", po::value< vector<string> >()->composing(),
+  ("output.medium,O",
-   "Medium to which the results will be wrote. You can specify"
+   po::value< vector<string> >()->composing(),
+   "Medium to which the results will be written. You can specify"
    " this option more than once."
-   " Allowed: Terminal, CSV, UDP, TCPEvAAL."
+   " Allowed: Terminal, CSV, UDP, TCPEvAAL (EvAAL 2011 format)."
    " If this option is absent, the results are printed on the terminal.")
-  ("output.csv-file", po::value<string>(),
+  ("output.csv-file",
+   po::value<string>(),
    "CSV file to use for output (when output.medium = CSV).")
-  ("output.udp-host", po::value<string>(),
+  ("output.udp-host",
+   po::value<string>(),
    "Host to which the UDP data is sent (when output.medium = UDP).")
-  ("output.udp-port", po::value<int>()
+  ("output.udp-port",
-   ->default_value(OWL_DEFAULT_RESULT_PORT),
+   po::value<int>()->default_value(OWL_DEFAULT_RESULT_PORT),
    "Port on which the UDP data is sent (when output.medium = UDP).")
-  ("output.tcpevaal-host", po::value<string>()
+  ("output.tcpevaal-host",
-   ->default_value(DEFAULT_TCPEVAAL_HOST),
+   po::value<string>()->default_value(DEFAULT_TCPEVAAL_HOST),
    "Host to which the TCP data is sent (when output.medium = TCPEvAAL).")
-  ("output.tcpevaal-port", po::value<int>()
+  ("output.tcpevaal-port",
-   ->default_value(DEFAULT_TCPEVAAL_PORT),
+   po::value<int>()->default_value(DEFAULT_TCPEVAAL_PORT),
    "Port on which the TCP data is sent (when output.medium = TCPEvAAL).")
   ;
 
@@ -282,7 +305,8 @@ void UserInterface::fill_misc_options()
   po::options_description options("Miscellaneous options") ;
 
   options.add_options()
-  ("flush-output-files", po::value<bool>()->default_value(true),
+  ("flush-output-files",
+   po::value<bool>()->default_value(true),
    "Flush output text files after each line.")
   ;