The Owl Positioning System's Architecture
OwlPS {{OWLPS_VERSION}}
June 2013

%%%
% Man title & section:
%!postproc(man): "^(\.TH.*) 1 "  ".TH owlps 7 "
% Fix .TH, add NAME section and TABLE OF CONTENTS title:
%!postproc(man): "^(\.TH.*)$"  "\1 OwlPS\ User\ Manual\n.SH NAME\nowlps-architecture - The Owl Positioning System's Architecture\n\n.SH TABLE OF CONTENTS"
% Add the table of contents:
%!options(man): --toc
% Man "links":
%!preproc(man): "(owlps)\.t2t" "//\1//(7)"
%!preproc(man): "(owlps-deployment)\.t2t" "//\1//(7)"
%!preproc(man): "(owlps-[^ ]*)\.t2t" "//\1//(1)"
%!preproc(man): "(owlps-[^ ]*\.h)" "//\1//(3)"
%%%




+ Architecture and protocol overview +

OwlPS' architecture is composed of several modules, which communicate
through a four-step protocol, from the positioning request transmitted
by the mobile terminal to the treatment of the position computed by the
positioning server:
+ positioning request transmission,
+ signal strength measurement,
+ aggregation of the measurements corresponding to the request,
+ position computation.


Each step of this protocol corresponds to a different module:

: **The mobile terminals**
  A mobile terminal can be any Wi-Fi-enabled device, such as a laptop, a
  smartphone, a PDA, a hand-held gaming console, etc. The mobile
  terminals transmit positioning requests which consist in a bunch of
  UDP packets, thanks to the //OwlPS Client// module – see
  owlps-client.t2t.

: **The capture points** (CPs)
  Capture points capture the packets transiting on the radio network and
  filter them, in order to extract the positioning requests transmitted
  by the mobile terminals. From each request, they extract the main
  information needed to compute the mobile terminal's position, i.e. the
  signal strength, and send the information to the aggregation server.
  They run the //OwlPS Listener// module; a capture point can be any
  device with a Wi-Fi interface whose driver offers a support for
  //Radiotap// – see owlps-listenerd.t2t.

: **The aggregation server**
  The aggregation server collects all the information from the capture
  points, aggregates them (according to the mobile terminal's MAC
  address and the request timestamp, that together form a unique
  identifier), and forwards them to the positioning server. This is done
  by the //OwlPS Aggregator// module, which can run on a fairly modest
  hardware – see owlps-aggregatord.t2t.

: **The positioning server**
  The positioning server, or computation server, takes as an input the
  data from the aggregation server, and outputs the computed positions,
  thanks to the //OwlPS Positioner// module, described in detail in
  owlps-positionerd.t2t. These results can be sent to the mobile
  terminal or treated otherwise, for instance by a program such as OwlPS
  UDP-to-HTTP (cf. owlps-udp-to-http.t2t).


The figure below summarises this process:

```
      +--------------+     positioning request      +----------------+
      | OwlPS Client | ---------------------------> | OwlPS Listener |
      +--------------+                              +----------------+
              ^                                             |
              |                                             |
              |                                             | captured
     computed |                                             | request
     position |                                             |
              |                                             |
              |                                             V
    +------------------+     aggregated request    +------------------+
    | OwlPS Positioner | <------------------------ | OwlPS Aggregator |
    +------------------+                           +------------------+
```




+ Autocalibration +

With the self-calibration mechanism on, the capture points will play the
role of pseudo-clients and send so-called autocalibration requests,
which are very similar to the positioning requests sent by the mobile
terminals. The transmission of the autocalibration requests is scheduled
by the Aggregator, which sends an //autocalibration order// to each
capture point, in a round-robin. When it receives such an order, the
Listener transmits an autocalibration request. For this to work, the
Listener transmits a //hello// packet from time to time to the
Aggregator, which allows the latter to maintain a list of currently
active capture points. If no //hello// packet is received from a given
capture point for some time, it is deleted from the list and the
Aggregator doesn't send it any more autocalibration orders; this delay
is an option of the Aggregator, cf. owlps-aggregator.t2t.




+ Coordinate system +

OwlPS uses a coordinate system relative to the deployment area. The
coordinates can be negative, and the origin can be set to any point,
according to the constraint of the deployment area. As a convention, we
generally set the origin at the South-West corner of the area, in order
to avoid negative coordinates, but that is not a requirement.

All the coordinates are in metres, and it is also mandatory that all the
distance measurements provided in the positioning server's configuration
be in metres – see owlps-positionerd.t2t.




= 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-client.t2t, owlps-listenerd.t2t, owlps-aggregatord.t2t,
owlps-positionerd.t2t