From 0fc84a548f5ff9fc812424a5e2d93576acb37e4d Mon Sep 17 00:00:00 2001
From: Matteo Cypriani <mcy@lm7.fr>
Date: Fri, 11 Jan 2013 17:26:00 -0500
Subject: [PATCH] [doc] Add -client (unfinished)

---
 doc/Makefile         |   8 ++-
 doc/owlps-client.t2t | 137 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 143 insertions(+), 2 deletions(-)
 create mode 100644 doc/owlps-client.t2t

diff --git a/doc/Makefile b/doc/Makefile
index 573c38b..ac06bd6 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -1,6 +1,10 @@
 all: \
 	owlps.7 \
-	owlps-architecture.7
+	owlps-architecture.7 \
+	owlps-client.1
+
+%.1: %.man
+	mv $< $@
 
 %.7: %.man
 	mv $< $@
@@ -9,4 +13,4 @@ all: \
 	./preproc-man.sh $< | txt2tags --infile=- --outfile=$@ -t man
 
 clean:
-	rm -f *~ *.html *.man *.7
+	rm -f *~ *.html *.man *.7 *.1
diff --git a/doc/owlps-client.t2t b/doc/owlps-client.t2t
new file mode 100644
index 0000000..ef0f99a
--- /dev/null
+++ b/doc/owlps-client.t2t
@@ -0,0 +1,137 @@
+Owl Positioning System Client
+OwlPS {{OWLPS_VERSION}}
+11 January 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 positioning requests"
+% 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)"
+%%%
+
+
+
+
+= Synopsis =
+
+**owlps-client** **-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** **-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 =
+
+FIXME
+
+
+
+
+= 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.
+: **-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