Document RC in a separate file

1 files changed, 58 insertions, 0 deletions

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]