From 1dadf3b7856940911724d02613085d57535da474 Mon Sep 17 00:00:00 2001
From: "Matthias P. Braendli" <matthias.braendli@mpb.li>
Date: Sat, 30 Dec 2017 10:24:36 +0100
Subject: Document RC in a separate file

---
 README.md        |  3 ++-
 doc/README-RC.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/example.ini  | 30 ++---------------------------
 3 files changed, 62 insertions(+), 29 deletions(-)
 create mode 100644 doc/README-RC.md

diff --git a/README.md b/README.md
index 4711028..b0b4635 100644
--- a/README.md
+++ b/README.md
@@ -29,7 +29,8 @@ Features
 - Logging: log to file, to syslog
 - ETI sources: ETI-over-TCP, file (Raw, Framed and Streamed) and ZeroMQ
 - A Telnet and ZeroMQ remote-control that can be used to change
-  some parameters during runtime
+  some parameters during runtime and retrieve statistics.
+  See doc/README-RC.md for more information
 - ZeroMQ PUB and REP output.
 - Ongoing work about digital predistortion for PA linearisation.
   See dpd/README.md
diff --git a/doc/README-RC.md b/doc/README-RC.md
new file mode 100644
index 0000000..c0fe4a7
--- /dev/null
+++ b/doc/README-RC.md
@@ -0,0 +1,58 @@
+Remote Control Interface
+========================
+
+The RC interface allows you to change settings at runtime and to access some
+statistics. Two interfaces are available: Telnet and based on ZeroMQ.
+
+The Telnet interface is designed for human interaction. Once you have enabled
+the interface and set the port, use any telnet client to connect to the server
+to get the RC command line interface. Since this is totally unsecure telnet,
+the software will only listen on the local loopback interface. To get secure
+remote access, use SSH port forwarding.
+
+The ZeroMQ interface is designed for machine interaction, e.g. for usage in
+scripts or from third party tools. An example python script to connect to that
+interface is available in `doc/zmq-ctrl/zmq_remote.py`, and example C++ code is available in `doc/zmq-ctrl/cpp/`.
+
+Both interfaces may be enabled simultaneously.
+
+Statistics available
+--------------------
+
+The following statistics are presented through the RC:
+
+ * Value of TIST in `tist timestamp`
+ * UHD: number of underruns, overruns and frames transmitted
+ * SoapySDR: number of underruns and overruns
+ * OFDM Generator: CFR stats and MER after CFR (if CFR enabled) in `ofdm clip_stats`
+ * OFDM Generator: PAPR before and after CFR in `ofdm papr`
+
+More statistics are likely to be added in the future, and we are always open
+for suggestions.
+
+
+ZMQ RC Protocol
+---------------
+
+ODR-DabMod binds a zmq rep socket so clients must connect
+using either req or dealer socket.
+[] denotes message part as zmq multi-part message are used for delimitation.
+All message parts are utf-8 encoded strings and match the Telnet command set.
+Messages to be sent as literal strings are denoted with "" below.
+
+The following commands are supported:
+
+    REQ: ["ping"]
+    REP: ["ok"]
+
+    REQ: ["list"]
+    REP: ["ok"][module name][module name]...
+
+    REQ: ["show"][module name]
+    REP: ["ok"][parameter: value][parameter: value]...
+
+    REQ: ["get"][module name][parameter]
+    REP: [value] _OR_ ["fail"][error description]
+
+    REQ: ["set"][module name][parameter][value]
+    REP: ["ok"] _OR_ ["fail"][error description]
diff --git a/doc/example.ini b/doc/example.ini
index b3faffd..d04c1a7 100644
--- a/doc/example.ini
+++ b/doc/example.ini
@@ -1,39 +1,13 @@
 ; Sample configuration file for ODR-DabMod
 
 [remotecontrol]
+; The RC feature is described in detail in doc/README-RC.md
+
 ; enable the telnet remote control on localhost:2121
-; Since this is totally unsecure telnet, the software
-; will only listen on the local loopback interface.
-; To get secure remote access, use SSH port forwarding
 telnet=1
 telnetport=2121
 
 ; Enable zmq remote control.
-; The zmq remote control is intended for machine-to-machine
-; integration. It may run in parallel with Telnet.
-;
-; Protocol:
-; ODR-DabMod binds a zmq rep socket so clients must connect
-; using either req or dealer socket.
-; [] denotes message part as zmq multi-part message are used for delimitation.
-; All message parts are utf-8 encoded strings and match the Telnet command set.
-; Messages to be sent as literal strings are denoted with "" below.
-;
-; The following commands are supported:
-; REQ: ["ping"]
-; REP: ["ok"]
-;
-; REQ: ["list"]
-; REP: ["ok"][module name][module name]...
-;
-; REQ: ["show"][module name]
-; REP: ["ok"][parameter: value][parameter: value]...
-;
-; REQ: ["get"][module name][parameter]
-; REP: [value] _OR_ ["fail"][error description]
-;
-; REQ: ["set"][module name][parameter][value]
-; REP: ["ok"] _OR_ ["fail"][error description]
 zmqctrl=1
 zmqctrlendpoint=tcp://127.0.0.1:9400
 
-- 
cgit v1.2.3