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

---
 doc/README-RC.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/example.ini  | 30 ++---------------------------
 2 files changed, 60 insertions(+), 28 deletions(-)
 create mode 100644 doc/README-RC.md

(limited to 'doc')

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