owlps/doc/owlps-client.t2t

170 lines
6.8 KiB
Plaintext
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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