diff options
| -rw-r--r-- | README.md | 3 | ||||
| -rw-r--r-- | doc/README-RC.md | 58 | ||||
| -rw-r--r-- | doc/example.ini | 30 |
3 files changed, 62 insertions, 29 deletions
@@ -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 |