Telnet Remote Control
=====================

ODR-DabMux can be configured to set up a simple telnet remote control that can
be used to modify some parameters without restarting the multiplexer. The same
functionality available through telnet is also available over a ZeroMQ REQ/REP
socket, to make automation easier.

The server only listens on localhost for security reasons. Remote access should
be done using a VPN or SSH port forwarding.

The principle is that parts of ODR-DabMux which have modifiable parameters
register themselves as remote-controllable modules, and also register
parameters. Each parameter has a value, that can be read/written using the
get/set commands.

The interface is quite simple, and supports the following commands:

    > help
    list
      * Lists the modules that are loaded and their parameters
    show MODULE
      * Lists all parameters and their values from module MODULE
    get MODULE PARAMETER
      * Gets the value for the specified PARAMETER from module MODULE
    set MODULE PARAMETER VALUE
      * Sets the value for the PARAMETER ofr module MODULE
    quit
      * Terminate this session


Example
=======

In this example, there is one service whose unique id (set in the configuration
file) is 'srv-fb', one subchannel with uid 'sub-fb' and one component 'comp-fb'.

The command 'list' will show all exported parameters, and a small description:

    > list
    srv-fb
            label : Label and shortlabel [label,short]
    sub-fb
            buffer : Size of the input buffer [aac superframes]
            enable : If the input is enabled. Set to zero to empty the buffer.
    comp-fb
            label : Label and shortlabel [label,short]

The indication in square brackets can help you understand the format of the
values, or the units used. e.g. for AAC subchannels, the 'buffer' parameter
has values that are counted in number of AAC superframes. It is implicit that a
number is meant.

In contrast to this, the 'label' parameters of both services and components take
a "label,short-label" pair, separated by a comma.

Binary values accept the value 0 as false, and 1 as true.


Remarks concerning specific modules
===================================

ZMQ input
---------
The ZMQ input (both for MPEG and AAC+) export a 'buffer' parameter which
defines how many frames must be in the buffer *before* the input starts
streaming.

If you increase the size of the buffer, it will not fill up by itself (unless
there is a clock drift between the mux and the encoder).

In order to force the buffer to fill up, disable the input by setting 'enable'
to 0, and, once the buffer is empty, re-enable it. It will fill to the desired
value.

Labels (Components and Services)
--------------------------------
The restrictions on short-labels, namely that they can only consist of letters
appearing in the labels, and that they must be maximum 8 characters long, are
verified by the 'label' parameters.

If you try to set an invalid label/short-label combination, you will get an
error, and the label is unchanged:

example:
    > set comp-fb label Programme1,prog1
    comp-fb short label prog1 is not subset of label 'Programme1'

example:
    > set comp-fb label Programme1,Programme
    comp-fb short label Programme is too long (max 8 characters)

Announcements
-------------
Announcements can be triggered by the remote control in two ways. For a
specific announcement, its active parameter can be toggled which will
immediately signal it accordingly. Or the start time or stop time can be set to
trigger signalling changes in the future.

Direct setting:
    > set my_announcement active 1
    ok

Deferred setting:

The "start_in" and a "stop_in" parameters both accept a value in milliseconds.
They can either be set, and when you read them back you will see the timeout go
down to zero; or they can be "not set" if you never set them or if the timeout
expired. It is also possible to set both "start_in" and "stop_in" to trigger
both a start and stop in the future.

The timeout expiry will then influence the "active" parameter internally, ensuring
that the "active" parameter always represents the current state of the
signalling.

    > set my_announcement start_in 10000
    ok

    > show my_announcement
    active: 0
    start_in: 7313
    stop_in: Not set

    > show my_announcement
    active: 0
    start_in: 1244
    stop_in: Not set

    > show my_announcement
    active: 1
    start_in: Not set
    stop_in: Not set