Owl Positioning System UDP-to-HTTP
OwlPS {{OWLPS_VERSION}}
September 2013


%%%
% Man title & section:
%!postproc(man): "^(\.TH.*) 1 "  ".TH owlps-udp-to-http 1 "
% Fix .TH, add NAME section and TABLE OF CONTENTS title:
%!postproc(man): "^(\.TH.*)$"  "\1 OwlPS\ User\ Manual\n.SH NAME\nowlps-udp-to-http - provide OwlPS results through HTTP"
% Man "links":
%!preproc(man): "(owlps)\.t2t" "//\1//(7)"
%!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)"
%%%




= Synopsis =

**owlps-udp-to-http** [ **-v** | **-q** ] [ **-l** //result_port// ] [ **-t** //http_port// ]




= Description =

**OwlPS UDP-to-HTTP** receives results from OwlPS Positioner on a UDP
socket and allows a client to retrieve them with the HTTP protocol. Only
the last result received for a given mobile terminal is memorised and
provided to the HTTP client. The UDP socket listens on //result_port//,
which default value is the default port to which OwlPS Positioner sends
the results. The TCP (HTTP) socket listens on //http_port//.

The client is expected to send an HTTP GET request, with a request
string as the first variable value (the variable's name does not
matter). For example, a correct request is detected if you load
http://localhost:8080/?request=ReadSimpleResults (assuming the host
running this program is localhost).

The HTTP requests currently implemented are listed in the “Request
types” section below.




= Options =

: **-h**
  Print help message and exit.
: **-V**
  Print version information and exit.
: **-v**
  Turn on verbose mode (default).
: **-q**
  Do not print informational messages.
: **-l** //result_port//
  Port on which the results are received (default: 9910).
: **-t** //http_port//
  Port on which the HTTP server listens (default: 8080).




= Request types =

== “ReadResults” request ==

Answer in case of error:
``` Results;NOK;Explanation

``Explanation`` is “NoResults” if no results were received from OwlPS
Positioner yet.

Normal answer:
``` Results;OK;Nb_results;Result_1;…;Result_n

With:
- ``Nb_results``: the number of results in the answer (number of mobile
  terminals).
- ``Result_i``: a result, following this format:
``` Mobile_MAC;Request_type;Request_timestamp;Nb_algo;Algo_1;…;Algo_n
- ``Nb_algo``: the number of algorithms in the result.
- ``Algo_i``: an algorithm, following this format:
``` Algorithm_name;X;Y;Z;Error;Area_name
- ``Error``: the distance from the true coordinates of the mobile, if
  known; -1 if unknown.
- ``Area_name``: the name of the area or room in which the mobile is
  (may be empty).


== “ReadSimpleResults” request ==

Answer in case of error:
``` SimpleResults;NOK;Explanation

Normal answer:
``` SimpleResults;OK;Nb_results;Result_1;…;Result_n

With:
- ``Nb_results``: the number of results in the answer (number of
  mobile terminals).
- ``Result_i``: a result, following this format:
``` Mobile_MAC;X;Y;Z;Area_name
- ``Area_name``: the name of the area or room in which the mobile is
  (may be empty).


== Unknown request ==

If a unknown request is received, the answer format is:
``` UnknownRequest;NOK




= 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




= See also =

owlps.t2t, owlps-positionerd.t2t