.. _settings-device:

********************
Settings Device
********************

.. index:: devices; settings

Overview
====================
The settings device allows users to access the configuration of the
Dia system through the channel database of the system.  This allows
run-time viewing and modification of the configuration.

Currently, this device is best used to interrogate the state of the
system.  Many pieces of the system do not support on-the-fly settings
changes, and may not immediately reconfigure, or operate well after a
settings change is performed.  If that is the case, it may be
necessary to restart the system before the settings changes made
through the settings device take proper effect.

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

A typical settings device configuration block looks like this::

    - name: settings
      driver: devices.settings_device:SettingsDevice

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

The settings device has no additional configuration parameters of its own.

Channels
====================

Gettable/Settable channels
---------------------------
format
    Selects the settings serializer used to present the data.  The
    required serializer must have been part of the generated dia.zip.
    Typical values are ``pyr`` or ``yaml``.  Loaded values for a
    particular configuration can be accessed through the
    ``serializers`` channel.

binding
    Selects a peephole into the configuration tree of the system.
    This is a period-separated list that specifies a traversal of the
    settings tree. Read the `Usage`_ section below for some examples.

pending_settings
    Settings values that have yet to be applied to the system as
    viewed from the current ``binding``.

filename
    The name of the file to use when the settings are stored by a set
    to the ``save_file`` channel.

Gettable-only channels
----------------------

serializers
    A list of the serializers that the currently running settings
    device can provide.

running_settings
    The currently active and applied settings at the ``binding``
    location

application_result
    Indication of the success of the previous ``apply``.  This will be
    a dictionary of dictionaries that reports the success or failure
    of the operation in the format selected by ``format``.  The top
    level key will be a particular binding location to report.  The
    value of that will be a set of three keys:

    accepted
        The settings modification succeeded.

    rejected
        The modification failed.

    notfound
        A required setting was not found.

Settable-only channels
----------------------

apply
    Causes any settings changes made to ``pending_settings`` to be
    applied back to the running system.

save_file
    Causes the current ``running_settings`` to be written to the file
    specified by ``filename``.  Any comments or special non-meaningful
    formatting of the original settings file will not be preserved.
    When running the Dia subsequently, you will need to specify this
    new file name to run with its settings.

Usage
====================

Exercising the settings device through the console presentation:

View the device::

 Welcome to the iDigi Device Integration Application CLI.
 =>> channel_dump settings.

 Device instance: settings                                

    Channel                  Value              Unit     Timestamp          
    ------------------------ ------------------ -------- -------------------
    application_result                                   1969-12-31 18:00:00
    apply                    (N/A)                                          
    binding                                              1969-12-31 18:00:00
    filename                 /home/travisl/repo          2009-10-09 17:08:37
    format                   yaml                        2009-10-09 17:08:37
    pending_settings         (N/A)                                          
    running_settings         (N/A)                                          
    save_file                (N/A)                                          
    serializers              yaml                        2009-10-09 17:08:37

.. warning::
    If your dump lists something other than ``yaml`` for ``format``
    above, please perform this command before following along::

     =>> channel_set settings.format yaml

    You can perform settings device operations in any of the
    serialization formats, but need to conform to the conventions of
    that format.  This example uses YAML.

Select a more restricted binding::

 =>> channel_set settings.binding devices.template.settings
         settings.binding: devices.template.settings () @ 2009-10-09 17:10:19
 =>>

View settings at this location::

 =>> channel_get settings.pending_settings
         settings.pending_settings: 
 {count_init: 0, update_rate: 1.0}
  () @ 2009-10-09 17:10:19
 =>>

Change the settings::

 =>> channel_set settings.pending_settings '{count_init: 1000, update_rate: 5.0}'
         settings.pending_settings: 
 {count_init: 1000, update_rate: 5.0}
  () @ 2009-10-09 17:11:11
 =>> channel_set settings.apply 1
         settings.apply: (value unavailable) ((unit unavailable)) @ (time unavailable)
 =>> channel_get settings.application_result
         settings.application_result: 
 devices.template.settings:
   accepted: {count_init: 1000, update_rate: 5.0}
   notfound: {}
   rejected: {}
  () @ 2009-10-09 17:12:53
 =>> 

Success! Let's save that result to a file::

 =>> channel_set settings.filename test.yml
         settings.filename: test.yml () @ 2009-10-09 17:09:07
 =>> channel_set settings.save_file 1
         settings.save_file: (value unavailable) ((unit unavailable)) @ (time unavailable)
 =>>

Try something that won't succeed::

 =>> channel_set settings.pending_settings '{count_init: -1, update_rate: 5.0}'  
         settings.pending_settings: 
 {count_init: -1, update_rate: 5.0}
  () @ 2009-10-09 17:22:16
 =>> channel_set settings.apply 1                                              
         settings.apply: (value unavailable) ((unit unavailable)) @ (time unavailable)
 =>> channel_get settings.application_result                                   
         settings.application_result: 
 devices.template.settings:
   accepted: {count_init: null, update_rate: 5.0}
   notfound: {}
   rejected: {count_init: '''-1'' fails verification function'}
  () @ 2009-10-09 17:22:24
 =>> 

