From 5d7c68fe2fd7a75435ff6ea9e437baf51afcec3f Mon Sep 17 00:00:00 2001 From: Matteo Cypriani Date: Sun, 23 Jun 2013 13:26:12 -0400 Subject: [PATCH] [doc] Add owlps-deployment.t2t --- TODO.t2t | 1 - doc/CMakeLists.txt | 1 + doc/owlps-deployment.t2t | 223 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 224 insertions(+), 1 deletion(-) create mode 100644 doc/owlps-deployment.t2t diff --git a/TODO.t2t b/TODO.t2t index ceb9505..35d7ed7 100644 --- a/TODO.t2t +++ b/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) diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index c6be2aa..039e323 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -54,6 +54,7 @@ endfunction() add_manpage(owlps 7) add_manpage(owlps-architecture 7) +add_manpage(owlps-deployment 7) add_manpage(owlps-client 1) diff --git a/doc/owlps-deployment.t2t b/doc/owlps-deployment.t2t new file mode 100644 index 0000000..46245a2 --- /dev/null +++ b/doc/owlps-deployment.t2t @@ -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