Owl Positioning System Client
OwlPS {{OWLPS_VERSION}}
June 2013


%%%
% Man title & section:
%!postproc(man): "^(\.TH.*) 1 "  ".TH owlps-client 1 "
% Fix .TH, add NAME section and TABLE OF CONTENTS title:
%!postproc(man): "^(\.TH.*)$"  "\1 OwlPS\ User\ Manual\n.SH NAME\nowlps-client - send OwlPS positioning requests"
% 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-client** [ **-v** | **-q** ] **-i** //dest_host// [ **-p** //dest_port// ] [ **-I** //iface// ]
             [ **-t** //delay// ] [ **-n** //nb_packets// ] [ **-s** //packet_size// ]
             [ **-F** [ //[+]delay// ] [ **-N** //nb_requests// ] [ **-D** ] ] [ **-l** [ //port// ] ]

**owlps-client** [ **-v** | **-q** ] **-i** dest_host [ **-p** //dest_port// ] [ **-I** //iface// ]
             [ **-t** //delay// ] [ **-n** //nb_packets// ] [ **-s** //packet_size// ]
             [ **-F** [ //delay// ] [ **-N** //nb_requests// ] [ **-D** ] ] //direction x y z//




= Description =

**OwlPS Client** is the reference client for OwlPS, i.e. the program run
by the mobile terminals to send one or more positioning requests. With
the second invocation form, that is when the user provides the direction
(orientation) and the coordinates of the mobile terminal,
//owlps-client// will send calibration requests instead of positioning
requests, which can be registered (using OwlPS Aggregator, see
owlps-aggregatord.t2t) to create a manual calibration database.




= 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 and some (less important)
  warnings.
: **-i** //dest_host//
  Name or IP address of the destination host of the localisation
  request.
: **-p** //dest_port//
  Destination port of the localisation request (default: 9900).
: **-t** //delay//
  Time between two packet transmissions in milliseconds. The default is
  25 ms for normal requests and 50 ms for calibration requests.
: **-n** //nb_packets//
  Number of packet transmitted for the request (default: 10 for a normal
  request, 20 for a calibration request).
: **-s** //packet_size//
  Data size of the transmitted packets. The minimal value is the size of
  the request's data fields; if //packet_size// is less than this size,
  it is ignored. Note that this size does not take into account the
  headers, so the whole 802.11 frame will be bigger.
: **-I** //iface//
  Name of the network interface used to transmit the request (e.g.
  “eth2”). If this option is absent, the interface is selected
  automatically. You must be root to use this option.
: **-F** [ //[+]delay// ]
  “Flood mode”: loop indefinitely, sending a new request every //delay//
  milliseconds (default: 1000 ms). If //delay// is smaller than the
  transmission time of a request (cf. **-n** and **-t** options), it is
  ignored and the next request is transmitted right away. If //delay//
  is prefixed with a //+// sign, it is cumulative to the transmission
  time, i.e. it is the delay between the end of a request's transmission
  and the start of the next request's transmission; by default,
  //delay// is the time between the start of the transmissions of both
  requests.
: **-N** //nb_requests//
  With **-F**, stop after //nb_requests// requests transmitted instead
  of looping indefinitely.
: **-D**
  Daemon mode (fork to the background). Useful only in flood mode (cf.
  **-F** option).
: **-l** [ //port// ]
  Wait for the computed position and display it. The optional argument
  //port// allows to specify the listening port (default: 9910).
  Available only if the program was compiled with the compilation-time
  option ENABLE_RECEIVE_POSITION.




= Positioning request =

The positioning request sent by OwlPS Client is a simple buffer
represented as the following:

```
              Byte: |  1  |  2  |  3  |  4  |  5  |  6  |  7  |  8  |
        +-----------+-----+-----+-----+-----+-----+-----+-----+-----+
        | Offset: 0 |  T  |  Pkt ID   |  Nb pkts  |                 |
        +-----------+-----+-----+-----+-----+-----+                 |
        |         8 |                                               |
        +-----------+                                               |
        |        16 |           Request time (seconds)              |
        +-----------+                                               |
        |        24 |                                               |
        +-----------                              +-----+-----+-----+
        |        32 |                             |                 |
        +-----------+-----+-----+-----+-----+-----+                 |
        |        40 |                                               |
        +-----------+                                               |
        |        48 |         Request time (nanoseconds)            |
        +-----------+                                               |
        |        56 |                                               |
        +-----------+                             +-----+-----+-----+
        |        64 |                             |  D  |     X     |
        +-----------+-----+-----+-----+-----+-----+-----+-----+-----+
        |        72 | X (cont.) |           Y           |     Z     |
        +-----------+-----+-----+-----+-----+-----+-----+-----+-----+
        |        80 | Z (cont.) |                                   |
        +-----------+-----+-----+        Padding                    +
        |       ... |                                               |
        +-----------+           +-----+-----+-----+-----+-----+-----+
        |      1448 |           |
        +-----------+-----+-----+
```

Where:
- **T** is the request type;
- **Pkt ID** is the current packet's number;
- **Nb pkts** is the number of packets sent for this request;
- **Request time (seconds)** and **Request time (nanoseconds)** are the
  two fields of an //owl_timestamp// structure – see owlps.h;
- **D**, **X**, **Y** and **Z** are calibration information present only
  for calibration requests:
  - **D** is the direction (orientation) of the mobile,
  - **X**, **Y** and **Z** are the coordinates of the mobile;
- **Padding** are optional extra bytes added at the end of the packet,
  for a maximal size of 1450 bytes.




= 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-architecture.t2t
