The Owl Positioning System deployment guide
OwlPS {{OWLPS_VERSION}}
June 2013


%%%
% Man title & section:
%!postproc(man): "^(\.TH.*) 1 "  ".TH owlps-deployment 7 "
% Fix .TH, add NAME section and TABLE OF CONTENTS title:
%!postproc(man): "^(\.TH.*)$"  "\1 OwlPS\ User\ Manual\n.SH NAME\nowlps-deployment - The Owl Positioning System deployment guide\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-architecture)\.t2t" "//\1//(7)"
%!preproc(man): "(owlps-[^ ]*)\.t2t" "//\1//(1)"
%!preproc(man): "(owlps[^ ]*\.h)" "//\1//(3)"
%%%




+ Introduction +

This page is aimed at helping one to deploy and use OwlPS. Prior to
reading it, you should have a good understanding of what OwlPS is and
does: cf. owlps.t2t and owlps-architecture.t2t.




+ Choosing the hardware +

OwlPS is written in C and C++ and targets UNIX-like environment. It is
mainly written and tested on GNU/Linux platforms, although all the
modules should build and run painlessly on any UNIX.

The Aggregator and Positioner modules can be run on any PC and for an
experimental setup consisting of a handful of capture points and a
couple of clients, even a quite modest machine will be enough. To give
an example, in a real deployment with 5 capture points and 2 mobile
terminals, an Asus EeePC 701 (Intel Celeron M 900 MHz, 2 Gio RAM) was
able to run owlps-aggregator, owlps-positioner, owlps-udp-to-http and an
instance of the Mozilla Firefox web browser showing the coordinates of
the mobiles on a map. Of course, for a bigger deployment you will have
to conduct tests to dimension the hardware adequately.

The Client module is very lightweight and can virtually run on any
Wi-Fi-enabled hardware able to start an operating system and run C
programs. Furthermore, the code is simple enough that it is easy to
rewrite a version dedicated to one platform; for example an experimental
Android client (written in Java) has been developed pretty easily
(unfortunately it is not in a publishable shape and nobody is taking
care of it right now).

The most critical elements in terms of hardware are the capture points.
Firstly, OwlPS Listener is pretty much untested on non-Linux platforms,
so if you are willing to use a BSD system as underlying OS for the
capture points, you can expect to have a couple of bugs to fix in the
process (or maybe it will work out of the box, but you're warned).
Secondly, the driver used for the capture points' Wi-Fi chipsets must
provide the radiotap headers; you can verify easily if it is the case
by doing a capture on the Wi-Fi interface (for example using tcpdump)
and then analysing the capture file (for example with Wireshark) and
see if the radiotap header is present before the IEEE 802.11 header. On
Linux, all the drivers using the (not so) new mac80211 stack should be
radiotap-enabled. As several capture points are required, the devices
used should ideally be cheap and have a low power consumption; Wi-Fi
routers are often a good choice, and OwlPS Listener is mainly tested on
routers which run the [OpenWrt Linux distribution http://openwrt.org/].
The chosen hardware should provide enough storage space to install the
libraries needed to run OwlPS Listener; on OpenWrt, 8 Mio of total
storage space should be enough. The memory footprint and computational
power should not be a problem in most cases.




+ Network setup +

Setting up the network is an important step. The following paragraphs
raise important problematics related to the network deployment.

First of all, the mobile terminal must be able to transmit UDP data on
the Wi-Fi network, and therefore has to be connected to a BSS (that is,
being either connected to an access point or to an ad hoc cell). The
destination host of the positioning requests //must// also be connected
to the same BSS: when trying to transmit to an inexistent host, the ARP
requests will fail to resolve the IP address and therefore the actual
data packets will not be transmitted. However, the destination host
doesn't have to actually interpret the packets, what imports is that the
capture points receive them. When connected to an access point, the
easiest way is to set the destination host to the access point's IP; if
you prefer, you can also set a default route on the mobile terminal, the
gateway being an existing machine on the network (for example the access
point), and set the destination host to any IP that is not in the local
network.

When using the autocalibration, the same rule applies to the capture
points, which must be able to transfer autocalibration requests on the
radio network. It is not a problem on small deployments where all the
hosts are in coverage, but can be tricky in bigger installations; in
such a case, you will need to set the destination host of each capture
point depending on its position in the deployment area; in general the
destination host will be another capture point in coverage.

The second important point is that the capture points must be able to
send the requests they capture to the aggregation server. In a small
deployment, it is possible to set up an ad hoc network (or even a
managed network) to connect the Aggregator to the capture points, but
keep in mind the following points:

+ All the capture points must be in coverage with the Aggregator.

+ The radio channel will be easily overloaded, especially with a number
  of capture points, because each capture point will transmit a packet
  to the Aggregator for each request captured from a mobile terminal. If
  the autocalibration is used, each capture point will itself transmit
  packets which will be retransmitted by each other capture point in
  coverage. If an access point is used instead of an ad hoc network, the
  load is doubled since the access point retransmits every packet
  addressed to a host in the same cell. If you plan to use such a
  wireless deployment, you should do an evaluation of the number of
  packets that will transit on the network every second and adjust the
  transmission delays (time between two positioning requests, time
  between two autocalibration requests, time between two packets of the
  same request). A good indicator of the network load is the number of
  retry packets captured (in verbose mode, OwlPS Listener will print a
  message for each retry positioning request packet captured).


The safest way is of course to deploy in a wired network: the radio
network won't be overloaded and it will mostly avoid packet losses
between the infrastructure elements.




+ Positioning techniques +

The positioning techniques that can be employed mainly depend on OwlPS
Positioner and are documented in owlps-positionerd.t2t. The techniques
used can be changed even after the deployment of the system, only the
positioning server will need to be restarted. However, you have to make
an important choice: using or not using the self-calibration mechanism.
You can also decide to activate the autocalibration on the capture
points and to control whether or not it is used simply by switching it
on or off on the Aggregator: if it's off on the Aggregator, the latter
will not send autocalibration orders, and therefore no autocalibration
requests will be transmitted by the capture points.




+ Configuration +

The configuration of OwlPS Positioner is done through a few
configuration file; an example ``owlps-positioner.conf`` file is
provided with the distribution and, along with owlps-positionerd.t2t,
should provide enough information to guide you. Other example files are
provided to show how to describe the topology and the devices. Please
keep in mind that OwlPS Positioner is a complex piece of software and
that you should read its documentation and the example configuration
file thoroughly to be sure to make the right choices.

OwlPS Aggregator can also be configured with a configuration file, but
its options are simple enough that you can also use command-line
parameters to tweak it. If you wish to use a configuration file, you can
generate one with the ``-G`` switch, possibly along with other options.
For instance, if you wish to change the aggregate timeout to 300 ms and
to set the verbose level to 3, you can use:

``` owlps-aggregatord -t300 -vvv -G >owlps-aggregator.conf

The ``owlps-aggregator.conf`` file will contain all the default options,
except for ``aggregate_timeout`` and ``verbose``. Also, keep in mind
that the default configuration file will be read even when using the
``-G`` switch, so if such a file exists the generated file may not
contain the default values.

The same applies for OwlPS Listener if it was compiled with support of
configuration files (cf. the ``INSTALL.t2t`` file shipped with this
distribution). If it wasn't, you will have to use command-line options
to set the parameters you need.

OwlPS Client doesn't support configuration files, but its options are
simple enough to be set on the command-line. If you are always using the
same set of options, you can simply write a minimal shell script that
will call the program with the desired options. The most important
options to choose are the number of packets per request (``-n``), the
delay between two packets (``-t``), the delay between two requests when
using the so-called “flood mode” (``-F``), and obviously the destination
host. Here is an example of script that will call the program to send
requests of 18 packets separated by 33 ms to the IP ``192.168.0.254``,
with a delay of 1 s between two requests (the default when using
``-F``):

```
    #!/bin/sh
    exec owlps-client -i 192.168.0.254 -n18 -t33 -F "$@"
```

The final ``"$@"`` parameter of the script allows you to call this
script with parameters to set additional options or modify the ones you
specified in the script.

You can do something similar for OwlPS UDP-to-HTTP.




= 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-positionerd.t2t
