********************
Dia Concepts
********************

The core concept of the Dia is the *channel database*.  Device drivers
provide sample data to the channels in the channel database, and
presentations access the channel database for communication to the
user or to move data out of the gateway.

Channel Database
====================

The channel database is the central abstraction around which the Dia
is built.  Primarily, devices publish sample data into channels in the
database, presentations consume data from the channel database.  This
provides a natural base view of data in the system.

.. _channels:

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

Each channel is an accessible discrete element in the channel
database.  Each channel can be accessed by presentations according to
a set of permissions.  The behavior of the channel in the system is
modified by certain options that may be set on the channel.

Permissions
--------------------
Current permissions are:

get
    The sample in the channel may be read by presentations.  The
    device driver which provides the channel may always access its value.

set
    Presentations may set the sample value. 

refresh
    When a channel has the *refresh* permissions, presentations are
    allowed to perform a *refresh* operation which requests that the
    device driver providing the channel obtain a new value for the
    channel.

.. _channel-options:

Options
--------------------
auto timestamp
    A channel with the *auto timestamp* option will add a timestamp
    value of the current system time to any *sample* object that is
    published to that channel, if that channel has not already been
    provided a timestamp by the driver.

do not log
   A channel with the *do not log* option will not have their samples
   logged by loggers in the system.  

Samples
====================
A *sample* in the system represents a value gathered by the system and
placed into a channel in the channel database.  Samples consist of
three elements:

value
    The acquired value provided by the device driver.

unit
    The reported *value*'s unit of measure. (e.g meters, Fahrenheit,
    Volts)

timestamp
    The time when the driver reports that the value was acquired. Many
    drivers populate data immediately to the channel database, in that
    case they can use the *auto timestamp* option.

Configuration File
====================

Dia settings are stored in a single configuration file on the system.
Most of the time, these settings are specified by the user using the
YAML markup language in a **dia.yml** file.  These settings are
transformed into a native Python representation and stored in a
**dia.pyr** file within the **dia.zip**.

When starting up the Dia without specifying a configuration file, the
one that is used by default is the one in the zip file. However, if
you have a file on the system with the same name, outside the zip
file, such as **dia.pyr**, it uses that instead.

For example, the dia.zip file contains a dia.pyr file, while the
filesystem looks like this:

* dia.py
* dia.zip
* dia.pyr

If the Dia is started, the dia.pyr on the filesystem is used. If you
remove the dia.pyr from that location, the Dia selects the
configuration file located in the zip file.

