Introduction to the Owl Positioning System
OwlPS {{OWLPS_VERSION}}
June 2013


%%%
% Man title & section:
%!postproc(man): "^(\.TH.*) 1 "  ".TH owlps 7 "
% Fix .TH, add NAME section and TABLE OF CONTENTS title:
%!postproc(man): "^(\.TH.*)$"  "\1 OwlPS\ User\ Manual\n.SH NAME\nowlps - Introduction to the Owl Positioning System\n\n.SH TABLE OF CONTENTS"
% Add the table of contents:
%!options(man): --toc
% Man "links":
%!preproc(man): "(owlps-architecture)\.t2t" "//\1//(7)"
%!preproc(man): "(owlps-deployment)\.t2t" "//\1//(7)"
%!preproc(man): "(owlps-[^ ]*)\.t2t" "//\1//(1)"
%!preproc(man): "(owlps[^ ]*\.h)" "//\1//(3)"
%%%




+ What is OwlPS? +

**OwlPS** (//Owl Positioning System//) is a positioning (localization)
system based on the IEEE 802.11 radio network (Wi-Fi), targeting mainly
indoor environments. It is developed and tested primarily on GNU/Linux,
but it should work on BSD platforms as well. Originally developed at the
University of Franche-Comté (Université de Franche-Comté, France), it is
released under the terms of the CeCILL free software license (GNU
GPL-compatible).

OwlPS uses an infrastructure-centred architecture, which means the
infrastructure does the measurements and computes the mobile terminals'
positions, rather than the terminals computing their own positions (as
it is the case for instance with the GPS). The infrastructure is
composed by several capture points that run //OwlPS Listener//, an
aggregation server running //OwlPS Aggregator//, and a computation
server running //OwlPS Positioner//. The role of each of these modules
is detailed in the documentation's part dedicated to the system's
architecture.

OwlPS implements various positioning techniques and algorithms based on
the radio signal strength (trilateration, signal strength
fingerprinting, and hybrid techniques). //OwlPS Listener// uses the
Radiotap header of the network packets to extract the RSS value. It
would be possible to extend the system to work with the TOF (Time of
Flight, i.e. the signal propagation time), but that is out of scope for
now (unless someone is willing to contribute).

OwlPS features a self-calibration (or autocalibration) mechanism for
signal strength fingerprinting-based algorithms, that avoids the
time-consuming manual fingerprinting phase and allows taking into
account dynamic changes of the environment (human, climatic, etc.) when
computing the location of mobile terminals.




+ Contribute +

If you would like to contribute to OwlPS, you can:

- use it, test it, and report suggestions and bugs on the forge:
  https://code.lm7.fr/mcy/owlps/issues

- get the latest development code, add functionalities and send me pull
  requests by email or on the forge:
  https://code.lm7.fr/mcy/owlps/pulls

  You can get improvement ideas from the ``TODO.t2t`` file.




+ Releases +


++ Timeline ++

There is no precise timeline for OwlPS, but the file ``TODO.t2t`` lists
a bunch of things that should be addressed at some point. A development
point release is made after some work has been done, usually mainly on a
particular topic. Usually such a release represents between 30 and 90
commits.

A stable release is made when a major goal has been reached and the
interfaces stabilised. For research purposes, it is probably better to
use the last development point release or even the last source version
from the Git repository, especially if you are willing to contribute by
integrating your changes in the main repository.


++ Version numbers ++

Releases are numbered according to the format //M.m.r//, where //M// is
the major version number, //m// is the minor one, and //r// is the
revision number.

Development point release are numbered with an odd minor version number
and a mandatory revision number starting at 0, for example:
- v0.9.0
- v1.1.2
- v1.3.3


A stable release is numbered with an even minor version number; the
revision number is not mandatory, but it is allowed. For example:
- v0.8
- v1.0
- v1.2
- v1.2.1 (this one doesn't exist for real!)


++ Cross-version compatibility ++

The communication protocol between the elements of the system is
guaranteed to stay the same across revisions of a given stable branch
(e.g. mixing modules of versions 1.2, 1.2.1 and 1.2.2 would be
possible). In development branches, the protocol can evolve from one
point release to the next (e.g.  mixing modules of versions 1.3.0 and
1.3.1 may not be possible). Changes in communication protocols,
libraries' APIs, file formats, etc., are documented in the ``CHANGELOG``
file.




+ Documentation summary +

++ Architecture and other considerations ++

- owlps-architecture.t2t
- owlps-deployment.t2t


++ Commands' user manuals ++

- owlps-client.t2t
- owlps-listenerd.t2t
- owlps-aggregatord.t2t
- owlps-positionerd.t2t


++ Developing with OwlPS libraries ++

- owlps.h (Doxygen-generated documentation)
- owlps-client.h (Doxygen-generated documentation)
- owlps-resultreader.h (Doxygen-generated documentation)




+ Online ressources +

- Official OwlPS' web page:
  http://owlps.pu-pm.univ-fcomte.fr/

- Project manager (source code, bug reports, documentation):
  https://code.lm7.fr/mcy/owlps

- Experimentations using OwlPS:
  https://code.lm7.fr/mcy/owlps-experiments




= 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
https://code.lm7.fr/mcy/owlps/src/master/COPYRIGHT.t2t
