[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.
2011-12-27 18:07:28 +01:00 · 2011-12-27 18:07:28 +01:00 · cf18386310
parent 5ffeafb857
commit cf18386310
5 changed files with 142 additions and 100 deletions
--- a/1
+++ b/1
@ -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.
--- a/owlps-positioning/cfg/owlps-positioning.conf
+++ b/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
-# 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
+[positioning.radar]
+# This subsection contains the options related to the RADAR algorithm
+# and derivated.

-# 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
+# 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.
+#average-reference-points = 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
+# 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.
+#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).
--- a/owlps-positioning/src/radar.cc
+++ b/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 =
--- a/owlps-positioning/src/stock.cc
+++ b/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() ;

--- a/owlps-positioning/src/userinterface.cc
+++ b/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.")
-  ("version,V", "Print version information.")
-  ("config-file,f", po::value<string>()
-   ->default_value(DEFAULT_CONFIG_FILE_NAME),
+  ("help,h",
+   "Print help.")
+  ("version,V",
+   "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> >()
-   ->composing(),
+  ("data-input.ap-medium",
+   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> >()
-   ->composing(),
+  ("data-input.mobile-medium",
+   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> >()
-   ->composing(),
+  ("data-input.topology-medium",
+   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> >()
-   ->composing(),
+  ("data-input.reference-points-medium",
+   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>()
-   ->default_value(OWL_DEFAULT_AGGREGATION_PORT),
+  ("input.udp-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,"
-   " FRBHMBasic, InterlinkNetworks, RADAR.")
-  ("positioning.area-start", po::value<string>(),
+   " this option more than once (but at least once). Allowed: Real,"
+   " FBCM, FRBHMBasic, InterlinkNetworks, RADAR.")
+  ("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"
-   " declared in the APs' configuration file) to the APs' list"
-   " (default is false, for security purposes).")
-  ("positioning.update-ap-coordinates-online",
+   "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.radar.ignore-ap-reference-points",
   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.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.")
+   "With the RADAR algorithm, try to avoid selecting the reference"
+   " points which are coordinates of an AP.")
  ;

  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(),
-   "Medium to which the results will be wrote. You can specify"
+  ("output.medium,O",
+   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>()
-   ->default_value(OWL_DEFAULT_RESULT_PORT),
+  ("output.udp-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>()
-   ->default_value(DEFAULT_TCPEVAAL_HOST),
+  ("output.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>()
-   ->default_value(DEFAULT_TCPEVAAL_PORT),
+  ("output.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.")
  ;