2013-08-01 19:26:34 +02:00
|
|
|
|
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** ]
|
2013-09-23 21:32:19 +02:00
|
|
|
|
[ **-i** //positioner_host// ]
|
2013-08-01 19:26:34 +02:00
|
|
|
|
[ **-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 =
|
|
|
|
|
|
2013-09-13 23:07:51 +02:00
|
|
|
|
**OwlPS Aggregator** receives captured requests from the capture points
|
2013-08-01 19:26:34 +02:00
|
|
|
|
(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.
|
|
|
|
|
|
|
|
|
|
|
2013-10-03 18:26:01 +02:00
|
|
|
|
This process is illustrated in the section “**Sequence diagram**” below.
|
|
|
|
|
|
|
|
|
|
|
2013-08-01 19:26:34 +02:00
|
|
|
|
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.
|
2013-09-23 21:32:19 +02:00
|
|
|
|
: **-i** //positionner_host//
|
|
|
|
|
Host name or IP address of the positioning server (default:
|
|
|
|
|
localhost).
|
2013-08-01 19:26:34 +02:00
|
|
|
|
: **-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
|
2014-10-31 16:24:51 +01:00
|
|
|
|
orders to the stored capture points (default: 1000 ms).
|
2013-08-01 19:26:34 +02:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2013-09-13 23:07:51 +02:00
|
|
|
|
= 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”.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2013-10-03 18:26:01 +02:00
|
|
|
|
= 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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2013-09-13 19:56:55 +02:00
|
|
|
|
= Files =
|
|
|
|
|
|
|
|
|
|
: //{{INSTALL_PREFIX}}/etc/owlps/owlps-aggregator.conf//
|
|
|
|
|
Default configuration file.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2013-08-01 19:26:34 +02:00
|
|
|
|
= 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
|
2016-11-03 05:10:34 +01:00
|
|
|
|
https://code.lm7.fr/mcy/owlps/src/master/COPYRIGHT.t2t
|
2013-08-01 19:26:34 +02:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
= See also =
|
|
|
|
|
|
|
|
|
|
owlps.t2t, owlps-architecture.t2t, owlps-deployment.t2t
|