.. _console:

********************
Console
********************

.. index:: presentations; console

Overview
====================

The console presentation provides a standard CLI (Command Line Interface) method of accessing the Dia.  


Configuration
====================

A typical console configuration block looks like this::

  # Create a new console instance on TCP port 4146.  It can be connected
  # two by using any telnet client.
  - name: console0
    driver: presentations.console.console:Console
    settings:
        type: tcp
        port: 4146

Settings
--------------------

type (optional, default: tcp)
    The two supported types are *tcp* and *serial*.

port (optional, default: 4146)
    If type is set to 'tcp', this value specifies the TCP port
    number to be used for the console presentation.

device (optional, default: com/0)
    If type is set to 'serial', this is the serial port device
    name that will be used.

baudrate (optional, default: 115200)
    If type is set to 'serial', this is the baud rate that will
    be used.

Usage
====================
You may type the following commands at the ``=>>`` prompt.  The
presentation also supports tab-completion of all commands and many
commands also provide tab completion of their arguments as well.  A
command history is available with the arrow keys.

Commands
--------------------
General Commands
++++++++++++++++++++

exit, quit, q
    Close and shut down the connection to the console, cleaning up any
    resources used. 

help
    With no arguments, *help* will list commands with help
    information.  *help* with an argument will access the internal
    documentation of the specified command.


Channel Database
++++++++++++++++++++
channel_dump [``prefix``]
    Dump all of the channel data for channels  beginning with the
    string ``prefix``. If no prefix is specified, dump data for all channels.

channel_get ``channel_name``
    Retrieve the current stored sample for the channel specified by
    ``channel_name``. 

channel_info ``channel_name``
    Get channel meta-information from a given channel.  Currently this
    returns two lists: A list of permissions for the channel, and
    channel options.  See :ref:`channels` for legal values.

channel_refresh ``channel_name``
    Request that a refresh be performed on a given channel.

channel_set ``channel name`` ``value`` [``unit``]
    Set ``channel name`` with the given ``value`` and optional ``unit``.  

Logging 
++++++++++++++++++++
logger_dump [``prefix``]
    Dumps the currently active logger DB channel state like ``channel_dump``.

logger_iterate ``start`` [``end``]
    Iterate between two points in the active logger and print logging
    events as they are encountered.  Logging events are reported from
    a 'start' to 'end' inclusively.  If 'end' is omitted, the log will
    continue seeking to the last record.

logger_list
    List all configured loggers in the system.  A single logger from
    this list is used with the logger_set command.

logger_next
    Advance the current logger database instance to the next record.

logger_pos
    Report the record number of the current log position.

logger_prev
    Obtain the previous record from current position.

logger_rewind
    Seek to the earliest event currently in the log.

logger_seek ``offset`` ``whence`` [``record_number``]
    Seek the current logger to position.

    ``offset`` is an integer

    ``whence`` is given as a string and may be of the following values:
        set: 
            seek ``offset`` records from the earliest record in the log
        cur: 
            seek ``offset`` records from the current record in the log
        end: 
            seek ``offset`` records from the last record in the log
        rec: 
            seek to an absolute record number given by ``record_number``
            and then seek ``offset`` records from that mark.

    ``record_number`` is an absolute record number which only applies when
    ``whence`` is rec.


logger_set ``logger_name``
    Select ``logger_name`` to be the currently active logger whose
    context the other logging commands will modify.

