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_ip [ **-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_ip [ **-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 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.




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




= Options =

: **-h**
  Print help message.
: **-V**
  Print version information.
: **-v**
  Turn on verbose mode (default).
: **-q**
  Do not print informational messages and some (less important)
  warnings.
: **-i** //dest_ip//
  Destination IP address of the localisation request.
: **-p** //dest_port//
  Destination port of the localisation request (default: 9900).
: **-t** //delay//
  Time between each packet transmission in milliseconds (default: 25 ms
  for a normal request, 50 ms for a calibration request).
: **-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).
: **-N** //nb_requests//
  With -F, stop after //nb_requests// requests transmitted instead of
  looping indefinitely.
: **-D**
  Daemon mode. Useful only in flood mode.
: **-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.




= See also =

owlps.t2t, owlps-architecture.t2t