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 http://code.lm7.fr/p/owlps/source/tree/master/COPYRIGHT.t2t = See also = owlps.t2t, owlps-architecture.t2t, owlps-positionerd.t2t