2013-06-23 19:26:12 +02:00
|
|
|
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":
|
2013-07-26 01:11:03 +02:00
|
|
|
%!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)"
|
2013-06-23 19:26:12 +02:00
|
|
|
%%%
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
+ 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.
|
|
|
|
|
2014-02-18 16:22:35 +01:00
|
|
|
You can do something similar for OwlPS UDP-to-HTTP.
|
|
|
|
|
2013-06-23 19:26:12 +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
|
|
|
|
http://code.lm7.fr/p/owlps/source/tree/master/COPYRIGHT.t2t
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
= See also =
|
|
|
|
|
|
|
|
owlps.t2t, owlps-architecture.t2t, owlps-positionerd.t2t
|