aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMatthias P. Braendli <matthias.braendli@mpb.li>2017-12-30 10:24:36 +0100
committerMatthias P. Braendli <matthias.braendli@mpb.li>2017-12-30 10:24:36 +0100
commit1dadf3b7856940911724d02613085d57535da474 (patch)
treef62544c7b2354a1ed684abce0920cebed057a66d
parentc56f572c1026a774bcec768821e64ac31354ceff (diff)
downloaddabmod-1dadf3b7856940911724d02613085d57535da474.tar.gz
dabmod-1dadf3b7856940911724d02613085d57535da474.tar.bz2
dabmod-1dadf3b7856940911724d02613085d57535da474.zip
Document RC in a separate file
-rw-r--r--README.md3
-rw-r--r--doc/README-RC.md58
-rw-r--r--doc/example.ini30
3 files changed, 62 insertions, 29 deletions
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