From 73b71f279db92f79c1ea559e75e2ee452b0edaa5 Mon Sep 17 00:00:00 2001 From: Matteo Cypriani Date: Thu, 1 Aug 2013 13:26:34 -0400 Subject: [PATCH] [doc] Add owlps-aggregatord.t2t --- doc/CMakeLists.txt | 1 + doc/owlps-aggregatord.t2t | 184 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 185 insertions(+) create mode 100644 doc/owlps-aggregatord.t2t diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 2e59edb..9a63e5b 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -57,6 +57,7 @@ add_manpage(owlps-architecture 7) add_manpage(owlps-deployment 7) add_manpage(owlps-client 1) add_manpage(owlps-listenerd 1) +add_manpage(owlps-aggregatord 1) ### Doxygen-generated man pages ### diff --git a/doc/owlps-aggregatord.t2t b/doc/owlps-aggregatord.t2t new file mode 100644 index 0000000..9c19a81 --- /dev/null +++ b/doc/owlps-aggregatord.t2t @@ -0,0 +1,184 @@ +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_ip// ] + [ **-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. + + +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_ip// + IP address of the positioning server (default: 127.0.0.1). +: **-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 CPs (default: 1000 ms). + + + + += 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 +http://code.lm7.fr/p/owlps/source/tree/master/COPYRIGHT.t2t + + + + += See also = + +owlps.t2t, owlps-architecture.t2t, owlps-deployment.t2t