diff --git a/TODO b/TODO index 7f99165..52e402e 100644 --- a/TODO +++ b/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. diff --git a/owlps-positioning/cfg/owlps-positioning.conf b/owlps-positioning/cfg/owlps-positioning.conf index bdeb4a4..43f7199 100644 --- 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). diff --git a/owlps-positioning/src/radar.cc b/owlps-positioning/src/radar.cc index 9c33539..58acbc8 100644 --- 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 = diff --git a/owlps-positioning/src/stock.cc b/owlps-positioning/src/stock.cc index 7516e24..a1f8567 100644 --- 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::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::const_iterator i = calibration_requests.begin() ; diff --git a/owlps-positioning/src/userinterface.cc b/owlps-positioning/src/userinterface.cc index 2bcbbfc..5cf3725 100644 --- 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() - ->default_value(DEFAULT_CONFIG_FILE_NAME), + ("help,h", + "Print help.") + ("version,V", + "Print version information.") + ("config-file,f", + po::value()->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 >() - ->composing(), + ("data-input.ap-medium", + po::value< vector >()->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(), + ("data-input.ap-csv-file", + po::value(), "CSV file to use for access points input (when" " data-input.ap-medium = CSV).") - ("data-input.mobile-medium", po::value< vector >() - ->composing(), + ("data-input.mobile-medium", + po::value< vector >()->composing(), "Medium from which mobiles are read. You can specify this" " option more than once. Allowed: CSV.") - ("data-input.mobile-csv-file", po::value(), + ("data-input.mobile-csv-file", + po::value(), "CSV file to use for mobiles input (when" " data-input.mobile-medium = CSV).") - ("data-input.topology-medium", po::value< vector >() - ->composing(), + ("data-input.topology-medium", + po::value< vector >()->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(), + ("data-input.areas-csv-file", + po::value(), "CSV file to use for topology input (when" " data-input.topology-medium = CSV).") - ("data-input.waypoints-csv-file", po::value(), + ("data-input.waypoints-csv-file", + po::value(), "CSV file to use for waypoints input (when" " data-input.topology-medium = CSV).") - ("data-input.reference-points-medium", po::value< vector >() - ->composing(), + ("data-input.reference-points-medium", + po::value< vector >()->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(), + ("data-input.reference-points-csv-file", + po::value(), "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(), + ("input.medium,I", + po::value(), "Medium from which requests are read. Allowed: CSV, UDP.") - ("input.csv-file", po::value(), + ("input.csv-file", + po::value(), "CSV file to use for input (when input.medium = CSV).") - ("input.udp-port", po::value() - ->default_value(OWL_DEFAULT_AGGREGATION_PORT), + ("input.udp-port", + po::value()->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 >()->composing(), + ("log.medium,L", + po::value< vector >()->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(), + ("log.csv-file", + po::value(), "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 >()->composing(), + ("positioning.algorithm,a", + po::value< vector >()->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(), + " this option more than once (but at least once). Allowed: Real," + " FBCM, FRBHMBasic, InterlinkNetworks, RADAR.") + ("positioning.accept-new-mobiles", + po::value()->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()->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()->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(), "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(), + ("positioning.area-stop", + po::value(), "Coordinates of the last point of the deployment area" " (string format: \"X;Y;Z\").") - ("positioning.radar-average-reference-points", - po::value()->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()->default_value(false), "Generate reference points from the (auto)calibration requests" " received.") ("positioning.generated-meshing-grain-x", - po::value()->default_value(0.5), + po::value()->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()->default_value(0.5), + po::value()->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()->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()->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()->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()->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()->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 >()->composing(), - "Medium to which the results will be wrote. You can specify" + ("output.medium,O", + po::value< vector >()->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(), + ("output.csv-file", + po::value(), "CSV file to use for output (when output.medium = CSV).") - ("output.udp-host", po::value(), + ("output.udp-host", + po::value(), "Host to which the UDP data is sent (when output.medium = UDP).") - ("output.udp-port", po::value() - ->default_value(OWL_DEFAULT_RESULT_PORT), + ("output.udp-port", + po::value()->default_value(OWL_DEFAULT_RESULT_PORT), "Port on which the UDP data is sent (when output.medium = UDP).") - ("output.tcpevaal-host", po::value() - ->default_value(DEFAULT_TCPEVAAL_HOST), + ("output.tcpevaal-host", + po::value()->default_value(DEFAULT_TCPEVAAL_HOST), "Host to which the TCP data is sent (when output.medium = TCPEvAAL).") - ("output.tcpevaal-port", po::value() - ->default_value(DEFAULT_TCPEVAAL_PORT), + ("output.tcpevaal-port", + po::value()->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()->default_value(true), + ("flush-output-files", + po::value()->default_value(true), "Flush output text files after each line.") ;