Owl Positioning System Aggregator OwlPS {{OWLPS_VERSION}} June 2013 %%% % Man title & section: %!postproc(man): "^(\.TH.*) 1 " ".TH owlps-aggregatord 1 " % Fix .TH, add NAME section and TABLE OF CONTENTS title: %!postproc(man): "^(\.TH.*)$" "\1 OwlPS\ User\ Manual\n.SH NAME\nowlps-aggregatord - aggregate OwlPS positioning requests" % Man "links": %!preproc(man): "(owlps)\.t2t" "//\1//(7)" %!preproc(man): "(owlps-architecture)\.t2t" "//\1//(7)" %!preproc(man): "(owlps-deployment)\.t2t" "//\1//(7)" %!preproc(man): "(owlps-[^ ]*)\.t2t" "//\1//(1)" %!preproc(man): "(owlps[^ ]*\.h)" "//\1//(3)" %%% = Synopsis = **owlps-aggregatord** [ **-f** //config_file// ] [ **-G** ] [ **-D** ] [ **-v**[**v**[**v**[**v**]] ] | **-q** ] [ **-o** //out_file// ] [ **-F** ] [ **-i** //positioner_host// ] [ **-p** //positioner_port// ] [ **-l** //listening_port// ] [ **-t** //aggregate_timeout// ] [ **-k** //keep_timeout// ] [ **-c** //check_interval// ] [ **-A** ] [ **-O** //autocalibration_order_port// ] [ **-H** //hello_port// ] [ **-K** //cp_keep_timeout// ] [ **-C** //ac_order_interval// ] = Description = **OwlPS Aggregator** receives captured requests from the capture points (OwlPS Listener, see owlps-listenerd.t2t), and assembles the different packets corresponding to the same request. The requests received are stored in a list in memory, which is checked periodically (cf. the **-c** option). The aggregated requests are written to a file (or the standard output, by default) in CSV format, and are sent through a UDP socket to the positioning server (OwlPS Positioner, see owlps-positionerd.t2t). Two timers are used, relatively to the time a packet for a given request is first seen: - When a new request arrives from a capture point, the “aggregation timer” is started. Until it reaches //aggregate_timeout// (**-t** option), the information of each captured request received from a capture point and corresponding to the same request is added in the same data structure. When the delay has passed, all the information of this request are written to the output file and to the UDP socket so that it can be treated by the positioning server. - Once the request is written, the “keep timer” is started. Until //keep_timeout// (**-k** option) is reached, the captured requests received from the capture points and corresponding to this request are ignored. This avoids the creation of a new request containing only one or a handful of packets if packets corresponding to an old request arrive with a delay (this can occur in case of network congestion). When the delay has passed, the request is deleted from the memory. This process is illustrated in the section “**Sequence diagram**” below. When using autocalibration, OwlPS Aggregator also acts as a scheduler for the transmission of the autocalibration requests. The capture points from which a //hello// message was received are registered and, if at least two capture points are known, autocalibration orders are transmitted to the known capture points in a round-robin (the **-C** option controls the delay between two order transmissions). When a capture point is seen for the first time, it is given the highest rank in the list so that it will be ordered to transmit an autocalibration request as soon as possible. When no //hello// message is received from a given capture point for some time, it is deleted and no more autocalibration orders are transmitted to it (this delay is defined by the **-K** option). = Options = == Main options == : **-h** Print help message and exit. : **-V** Print version information and exit. : **-f** //config_file// Use //config_file// instead of the default configuration file. This option is available only if the program was compiled with support of configuration files. : **-G** Dump the configuration on the standard output and exit. This is useful to generate a configuration file with default values, possibly modified from the current set of options. The configuration file (either the default one if it exists or specified with the **-f** option) is read and the options it contains will be taken into account. : **-D** Daemon mode (fork to the background). : **-v** Be verbose. You can use this option up to 4 times to increase the level of verbosity: - 0 = errors and important warnings - 1 = more warnings - 2 = useful information - 3 = a lot of information - 4 = display each captured packet corresponding to a request : **-q** Quiet mode (default): sets the verbose level to 0 (cf. verbose levels above). == Output options == : **-o** //out_file// Aggregated requests will be //appended// to this CSV file (default is "-", i.e. the standard output). : **-F** Do not flush the output file. : **-i** //positionner_host// Host name or IP address of the positioning server (default: localhost). : **-p** //positioner_port// Aggregated requests are transmitted to the positioning server on this port (default: 9902). == Aggregation options == : **-l** //listening_port// Listen for requests from the capture points on this port (default: 9901). : **-t** //aggregate_timeout// Requests are stored during //aggregate_timeout// milliseconds before to be grouped (default: 600 ms). : **-k** //keep_timeout// Aggregated requests are kept during //keep_timeout// milliseconds (default: 3000 ms). : **-c** //check_interval// Time between two checks of the stored requests, in milliseconds (default: 300 ms). == Autocalibration options == : **-A** Enable autocalibration (default: disabled). : **-O** //autocalibration_order_port// Port on which autocalibration orders are sent to the listeners (default: 9904). : **-H** //hello_port// Port on which autocalibration //hello// messages are received from the listeners (default: 9903). : **-K** //cp_keep_timeout// Inactive capture points are kept during //cp_keep_timeout// seconds (default: 35 s). : **-C** //ac_order_interval// Time (in milliseconds) between two transmissions of autocalibration orders to the stored capture points (default: 1000 ms). = CSV format = The text output is constituted of fields separated by semicolons (;). (We call it CSV format even though semicolons are used instead of commas.) The format can evolve from one version of OwlPS to another, this is why the first field of each line is the version of the format used. In the current version of the format, each line contains the following fields: - CSV format version = 1 - MAC address of the transmitter - request type - number of packets sent by the transmitter - timestamp (transmission time at the transmitter), under the form “seconds.nanoseconds” - X coordinate - Y coordinate - Z coordinate - direction (orientation) of the transmitter - one or more per-packet information made of the following fields: - MAC address of the capture point - packet ID - signal strength If unknown, the coordinates are set to “0.00” and the orientation to “0”. = Sequence diagram = This sequence diagram of the positioning process of OwlPS illustrates the two-timer mechanism of OwlPS Aggregator. In this example, the mobile terminal (Client) transmits a positioning request; a capture point (Listener) captures it and forwards it to the aggregation server (Aggregator) along with the measured signal strength (SS). When it receives this message, the aggregation server starts the aggregation timer; shortly after, it receives another message corresponding to the same request, which it stores along with the first message (“added”). Once the timeout is reached, the aggregation server forwards the information of both messages to the positioning server (Positioner) – which starts immediately to compute the mobile terminal's position – and starts the keep timer. While this timer is still running, it receives a new message corresponding to the same request; this time, the message is ignored. Would it receive again a new message corresponding to the same request after the timeout, it would however consider it as a new request and would start a new aggregation timer. Note that it doesn't matter whether or not the three messages come from different capture points. ``` ,------. ,--------. ,----------. ,----------. |Client| |Listener| |Aggregator| |Positioner| `--+---' `---+----' `----+-----' `----+-----' ,-. positioning ,-. | | | | -------------->| | | | | | request | | | | | | | | request + SS ,-. | | | | |--------------->| | ----. aggregation | | | | | | | | timer | | | | | | ,-.<---' | | | | | | |T| | | | | | | |T| | | | | | | |T| | | | | | request + SS | |T| ,------. | | | | |- - - - - - - ->| |T| |added \ | | | | | | |T| `-------' | | | | | | |T| | | | | | | |T|----. | | | | | | |T| | timeout | | | | | | `-'<---' | | | | | | | aggregated request ,-. | | | | | |---------------------->| | | | | | | | -----. | | | | | | | | | keep timer | | | | | | | ,-.<---' | | | | | | | |T| | | | | | | | |T| | | | | | | | |T| | | | | | | request + SS | |T| ,--------. | | | | | |- - - - - - - ->| |T| |ignored \ | | | | `-' | |T| `---------' | | | | | | |T| | | | | | | |T|----. | | | | | | |T| | timeout | | | | | `-^-'<---' | | | | | computed | | | | | <-----------------------------------------------------------| | `-' | position | `-' ,--+---. ,---+----. ,----+-----. ,-----+----. |Client| |Listener| |Aggregator| |Positioner| `------' `--------' `----------' `----------' ``` The PlantUML source file for this figure is provided along with the OwlPS distribution, in the ``doc/figures/`` directory. = Files = : //{{INSTALL_PREFIX}}/etc/owlps/owlps-aggregator.conf// Default configuration file. = Copying = This documentation is part of the Owl Positioning System (OwlPS) project. It is subject to the copyright notice and license terms in the COPYRIGHT.t2t file found in the top-level directory of the OwlPS distribution and at https://code.lm7.fr/mcy/owlps/src/master/COPYRIGHT.t2t = See also = owlps.t2t, owlps-architecture.t2t, owlps-deployment.t2t