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
