Owl Positioning System: a Wi-Fi-based, infrastructure-centred indoor positioning system. http://owlps.pu-pm.univ-fcomte.fr/
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

226 lines

  1. The Owl Positioning System deployment guide
  3. June 2013
  4. %%%
  5. % Man title & section:
  6. %!postproc(man): "^(\.TH.*) 1 " ".TH owlps-deployment 7 "
  7. % Fix .TH, add NAME section and TABLE OF CONTENTS title:
  8. %!postproc(man): "^(\.TH.*)$" "\1 OwlPS\ User\ Manual\n.SH NAME\nowlps-deployment - The Owl Positioning System deployment guide\n\n.SH TABLE OF CONTENTS"
  9. % Add the table of contents:
  10. %!options(man): --toc
  11. % Man "links":
  12. %!preproc(man): "(owlps)\.t2t" "//\1//(7)"
  13. %!preproc(man): "(owlps-architecture)\.t2t" "//\1//(7)"
  14. %!preproc(man): "(owlps-[^ ]*)\.t2t" "//\1//(1)"
  15. %!preproc(man): "(owlps[^ ]*\.h)" "//\1//(3)"
  16. %%%
  17. + Introduction +
  18. This page is aimed at helping one to deploy and use OwlPS. Prior to
  19. reading it, you should have a good understanding of what OwlPS is and
  20. does: cf. owlps.t2t and owlps-architecture.t2t.
  21. + Choosing the hardware +
  22. OwlPS is written in C and C++ and targets UNIX-like environment. It is
  23. mainly written and tested on GNU/Linux platforms, although all the
  24. modules should build and run painlessly on any UNIX.
  25. The Aggregator and Positioner modules can be run on any PC and for an
  26. experimental setup consisting of a handful of capture points and a
  27. couple of clients, even a quite modest machine will be enough. To give
  28. an example, in a real deployment with 5 capture points and 2 mobile
  29. terminals, an Asus EeePC 701 (Intel Celeron M 900 MHz, 2 Gio RAM) was
  30. able to run owlps-aggregator, owlps-positioner, owlps-udp-to-http and an
  31. instance of the Mozilla Firefox web browser showing the coordinates of
  32. the mobiles on a map. Of course, for a bigger deployment you will have
  33. to conduct tests to dimension the hardware adequately.
  34. The Client module is very lightweight and can virtually run on any
  35. Wi-Fi-enabled hardware able to start an operating system and run C
  36. programs. Furthermore, the code is simple enough that it is easy to
  37. rewrite a version dedicated to one platform; for example an experimental
  38. Android client (written in Java) has been developed pretty easily
  39. (unfortunately it is not in a publishable shape and nobody is taking
  40. care of it right now).
  41. The most critical elements in terms of hardware are the capture points.
  42. Firstly, OwlPS Listener is pretty much untested on non-Linux platforms,
  43. so if you are willing to use a BSD system as underlying OS for the
  44. capture points, you can expect to have a couple of bugs to fix in the
  45. process (or maybe it will work out of the box, but you're warned).
  46. Secondly, the driver used for the capture points' Wi-Fi chipsets must
  47. provide the radiotap headers; you can verify easily if it is the case
  48. by doing a capture on the Wi-Fi interface (for example using tcpdump)
  49. and then analysing the capture file (for example with Wireshark) and
  50. see if the radiotap header is present before the IEEE 802.11 header. On
  51. Linux, all the drivers using the (not so) new mac80211 stack should be
  52. radiotap-enabled. As several capture points are required, the devices
  53. used should ideally be cheap and have a low power consumption; Wi-Fi
  54. routers are often a good choice, and OwlPS Listener is mainly tested on
  55. routers which run the [OpenWrt Linux distribution http://openwrt.org/].
  56. The chosen hardware should provide enough storage space to install the
  57. libraries needed to run OwlPS Listener; on OpenWrt, 8 Mio of total
  58. storage space should be enough. The memory footprint and computational
  59. power should not be a problem in most cases.
  60. + Network setup +
  61. Setting up the network is an important step. The following paragraphs
  62. raise important problematics related to the network deployment.
  63. First of all, the mobile terminal must be able to transmit UDP data on
  64. the Wi-Fi network, and therefore has to be connected to a BSS (that is,
  65. being either connected to an access point or to an ad hoc cell). The
  66. destination host of the positioning requests //must// also be connected
  67. to the same BSS: when trying to transmit to an inexistent host, the ARP
  68. requests will fail to resolve the IP address and therefore the actual
  69. data packets will not be transmitted. However, the destination host
  70. doesn't have to actually interpret the packets, what imports is that the
  71. capture points receive them. When connected to an access point, the
  72. easiest way is to set the destination host to the access point's IP; if
  73. you prefer, you can also set a default route on the mobile terminal, the
  74. gateway being an existing machine on the network (for example the access
  75. point), and set the destination host to any IP that is not in the local
  76. network.
  77. When using the autocalibration, the same rule applies to the capture
  78. points, which must be able to transfer autocalibration requests on the
  79. radio network. It is not a problem on small deployments where all the
  80. hosts are in coverage, but can be tricky in bigger installations; in
  81. such a case, you will need to set the destination host of each capture
  82. point depending on its position in the deployment area; in general the
  83. destination host will be another capture point in coverage.
  84. The second important point is that the capture points must be able to
  85. send the requests they capture to the aggregation server. In a small
  86. deployment, it is possible to set up an ad hoc network (or even a
  87. managed network) to connect the Aggregator to the capture points, but
  88. keep in mind the following points:
  89. + All the capture points must be in coverage with the Aggregator.
  90. + The radio channel will be easily overloaded, especially with a number
  91. of capture points, because each capture point will transmit a packet
  92. to the Aggregator for each request captured from a mobile terminal. If
  93. the autocalibration is used, each capture point will itself transmit
  94. packets which will be retransmitted by each other capture point in
  95. coverage. If an access point is used instead of an ad hoc network, the
  96. load is doubled since the access point retransmits every packet
  97. addressed to a host in the same cell. If you plan to use such a
  98. wireless deployment, you should do an evaluation of the number of
  99. packets that will transit on the network every second and adjust the
  100. transmission delays (time between two positioning requests, time
  101. between two autocalibration requests, time between two packets of the
  102. same request). A good indicator of the network load is the number of
  103. retry packets captured (in verbose mode, OwlPS Listener will print a
  104. message for each retry positioning request packet captured).
  105. The safest way is of course to deploy in a wired network: the radio
  106. network won't be overloaded and it will mostly avoid packet losses
  107. between the infrastructure elements.
  108. + Positioning techniques +
  109. The positioning techniques that can be employed mainly depend on OwlPS
  110. Positioner and are documented in owlps-positionerd.t2t. The techniques
  111. used can be changed even after the deployment of the system, only the
  112. positioning server will need to be restarted. However, you have to make
  113. an important choice: using or not using the self-calibration mechanism.
  114. You can also decide to activate the autocalibration on the capture
  115. points and to control whether or not it is used simply by switching it
  116. on or off on the Aggregator: if it's off on the Aggregator, the latter
  117. will not send autocalibration orders, and therefore no autocalibration
  118. requests will be transmitted by the capture points.
  119. + Configuration +
  120. The configuration of OwlPS Positioner is done through a few
  121. configuration file; an example ``owlps-positioner.conf`` file is
  122. provided with the distribution and, along with owlps-positionerd.t2t,
  123. should provide enough information to guide you. Other example files are
  124. provided to show how to describe the topology and the devices. Please
  125. keep in mind that OwlPS Positioner is a complex piece of software and
  126. that you should read its documentation and the example configuration
  127. file thoroughly to be sure to make the right choices.
  128. OwlPS Aggregator can also be configured with a configuration file, but
  129. its options are simple enough that you can also use command-line
  130. parameters to tweak it. If you wish to use a configuration file, you can
  131. generate one with the ``-G`` switch, possibly along with other options.
  132. For instance, if you wish to change the aggregate timeout to 300 ms and
  133. to set the verbose level to 3, you can use:
  134. ``` owlps-aggregatord -t300 -vvv -G >owlps-aggregator.conf
  135. The ``owlps-aggregator.conf`` file will contain all the default options,
  136. except for ``aggregate_timeout`` and ``verbose``. Also, keep in mind
  137. that the default configuration file will be read even when using the
  138. ``-G`` switch, so if such a file exists the generated file may not
  139. contain the default values.
  140. The same applies for OwlPS Listener if it was compiled with support of
  141. configuration files (cf. the ``INSTALL.t2t`` file shipped with this
  142. distribution). If it wasn't, you will have to use command-line options
  143. to set the parameters you need.
  144. OwlPS Client doesn't support configuration files, but its options are
  145. simple enough to be set on the command-line. If you are always using the
  146. same set of options, you can simply write a minimal shell script that
  147. will call the program with the desired options. The most important
  148. options to choose are the number of packets per request (``-n``), the
  149. delay between two packets (``-t``), the delay between two requests when
  150. using the so-called “flood mode” (``-F``), and obviously the destination
  151. host. Here is an example of script that will call the program to send
  152. requests of 18 packets separated by 33 ms to the IP ````,
  153. with a delay of 1 s between two requests (the default when using
  154. ``-F``):
  155. ```
  156. #!/bin/sh
  157. exec owlps-client -i -n18 -t33 -F "$@"
  158. ```
  159. The final ``"$@"`` parameter of the script allows you to call this
  160. script with parameters to set additional options or modify the ones you
  161. specified in the script.
  162. You can do something similar for OwlPS UDP-to-HTTP.
  163. = Copying =
  164. This documentation is part of the Owl Positioning System (OwlPS)
  165. project. It is subject to the copyright notice and license terms
  166. in the COPYRIGHT.t2t file found in the top-level directory of the
  167. OwlPS distribution and at
  168. http://code.lm7.fr/p/owlps/source/tree/master/COPYRIGHT.t2t
  169. = See also =
  170. owlps.t2t, owlps-architecture.t2t, owlps-positionerd.t2t