- iDigi Dia Home
- User
  - Getting Started
  - Dia Concepts
  - Devices
  - Loggers
  - Presentations
  - Services
  - Tracing
- Developer
  - Overview
  - Drivers
  - Loggers
  - Presentations
  - Services
  - Integrating Application
  - Tracing Manager
  - Debugging
  - Specific Considerations
  - API Reference

- Email
- Phone
- Contact us:

### Navigation

- index
- next |
- previous |
- iDigi Dia |
- User Documentation »
- Device Drivers »

# Settings Device

## 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
    =>>

### Navigation

- index
- next |
- previous |
- iDigi Dia |
- User Documentation »
- Device Drivers »