From 3780d3ff6d1b1f477899919ae942bc2858de48dc Mon Sep 17 00:00:00 2001
From: Matteo Cypriani <mcy@lm7.fr>
Date: Fri, 11 Jan 2013 16:47:17 -0500
Subject: [PATCH] [doc] Add -architecture

---
 doc/Makefile               |  4 +-
 doc/owlps-architecture.t2t | 88 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 91 insertions(+), 1 deletion(-)
 create mode 100644 doc/owlps-architecture.t2t

diff --git a/doc/Makefile b/doc/Makefile
index 8a0349f..573c38b 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -1,4 +1,6 @@
-all: owlps.7
+all: \
+	owlps.7 \
+	owlps-architecture.7
 
 %.7: %.man
 	mv $< $@
diff --git a/doc/owlps-architecture.t2t b/doc/owlps-architecture.t2t
new file mode 100644
index 0000000..e908de9
--- /dev/null
+++ b/doc/owlps-architecture.t2t
@@ -0,0 +1,88 @@
+The Owl Positioning System's Architecture
+OwlPS {{OWLPS_VERSION}}
+11 January 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-architecture - The Owl Positioning System's Architecture\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-deployment)\.t2t" "**\1**(7)"
+%!preproc(man): "(owlps-[^ ]*)\.t2t" "**\1**(1)"
+%!preproc(man): "(owlps-[^ ]*\.h)" "**\1**(3)"
+%%%
+
+
+
+
++ Architecture and protocol overview +
+
+OwlPS' architecture is composed of several modules, which communicate
+through a four-step protocol, from the positioning request transmitted
+by the mobile terminal to the treatment of the position computed by the
+positioning server:
++ positioning request transmission,
++ signal strength measurement,
++ aggregation of the measurements corresponding to the request,
++ position computation.
+
+
+Each step of this protocol corresponds to a different module:
+
+: **The mobile terminals**
+  A mobile terminal can be any Wi-Fi-enabled device, such as a laptop, a
+  smartphone, a PDA, a hand-held gaming console, etc. The mobile
+  terminals transmit positioning requests which consist in a bunch of
+  UDP packets, thanks to the //OwlPS Client// module – see
+  owlps-client.t2t.
+
+: **The capture points** (CPs)
+  Capture points capture the packets transiting on the radio network and
+  filter them, in order to extract the positioning requests transmitted
+  by the mobile terminals. From each request, they extract the main
+  information needed to compute the mobile terminal's position, i.e. the
+  signal strength, and send the information to the aggregation server.
+  They run the //OwlPS Listener// module; a capture point can be any
+  device with a Wi-Fi interface whose driver offers a support for
+  //Radiotap// – see owlps-listener.t2t.
+
+: **The aggregation server**
+  The aggregation server collects all the information from the capture
+  points, aggregates them (according to the mobile terminal's MAC
+  address and the request timestamp, that together form a unique
+  identifier), and forwards them to the positioning server. This is done
+  by the //OwlPS Aggregator// module, which can run on a fairly modest
+  hardware – see owlps-aggregator.t2t.
+
+: **The positioning server**
+  The positioning server, or computation server, takes as an input the
+  data from the aggregation server, and outputs the computed positions,
+  thanks to the //OwlPS Positioner// module, described in detail in
+  owlps-positioner.t2t.
+
+
+
+
++ Coordinate system +
+
+OwlPS uses a coordinate system relative to the deployment area. The
+coordinates can be negative, and the origin can be set to any point,
+according to the constraint of the deployment area. As a convention, we
+generally set the origin at the South-West corner of the area, in order
+to avoid negative coordinates, but that is not a requirement.
+
+All the coordinates are in metres, and it is also mandatory that all the
+distance measurements provided in the positioning server's configuration
+be in metres – see owlps-positioner.t2t.
+
+
+
+
+= See also =
+
+owlps.t2t, owlps-client.t2t, owlps-listener.t2t, owlps-aggregator.t2t,
+owlps-positioner.t2t