[doc] Add owlps-deployment.t2t
This commit is contained in:
parent
f4980d003e
commit
5d7c68fe2f
1
TODO.t2t
1
TODO.t2t
|
@ -9,7 +9,6 @@ Work to do in OwlPS
|
|||
|
||||
- Topics to write on:
|
||||
- Architecture
|
||||
- Deployment
|
||||
- General user manual (common command-line options, etc.)
|
||||
- Per module user manual (manpages)
|
||||
|
||||
|
|
|
@ -54,6 +54,7 @@ endfunction()
|
|||
|
||||
add_manpage(owlps 7)
|
||||
add_manpage(owlps-architecture 7)
|
||||
add_manpage(owlps-deployment 7)
|
||||
add_manpage(owlps-client 1)
|
||||
|
||||
|
||||
|
|
|
@ -0,0 +1,223 @@
|
|||
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.
|
||||
|
||||
|
||||
|
||||
|
||||
= 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
|
Loading…
Reference in New Issue