.. _short_messaging_Presentation:

********************
Short Messaging
********************

.. index:: presentations; short_messaging

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

The Short Messaging presentation allows for the iDigi Dia to send short
messages about channel updates and channel alarms over SMS to iDigi. 

This is useful in situations where you might like to be sent an update
or an alarm when certain conditions on channel(s) occurs.

It is also useful in situations where the Device is not accessible because it
is in an area of the world where a regular network connection is not available.
For example, if the Device is on a ship in the middle of the ocean.

.. note:: In order to upload data to your iDigi account, your
          subscription must have SMS support added.  Speak to your
          iDigi sales representative.
 
Configuration
====================

A typical Short Messaging configuration block for SMS looks like this::

  - name: Short_Messaging_Service
    driver: presentations.short_messaging.short_messaging:ShortMessaging
    settings:
        SMS:
            settings:
                limit: 5
                limit_interval: hour
        clients:
            - name: iDigi
              settings:
                  transport: SMS
                  type: iDigi
            - name: Enduser_1
              settings:
                  transport: SMS
                  type: Enduser
                  number: 19525551234
                  command_access: True
                  update_message: "DIA Update.  Chan: %c  Val: %v %u  Time: %h"
                  alarm_message: "DIA Alarm!  Chan: %c  Val: %v %u  Time: %h"
            - name: Enduser_2
              settings:
                  transport: SMS
                  type: Enduser
                  number: 19525556789
                  command_access: True
                  update_message: "<update><chan>%c</chan><val>%v</val><unit>%u</unit><time>%h</time></update>"
                  alarm_message: "<alarm><chan>%c</chan><val>%v</val><unit>%u</unit><time>%h</time></alarm>"
        updates:
            - name: MassaM3_distance_update
              settings:
                  filter: "Massa*distance*"
                  clients: [ iDigi, Enduser_1, Enduser_2 ]
                  interval: 60
        alarms:
            - name: MassaM3_distance_alarm
              settings:
                  filter: "Massa*distance*"
                  clients: [ iDigi, Enduser_1, Enduser_2 ]
                  condition: "%c <= 10.0 or %c > 30.0"

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

There are 4 settings areas that need to be set up.

    SMS:

        limit:
            Sets the maximum limit of how many messages Dia will send in a
            given period of time.

        limit_interval:
            Sets the limit interval/period of time for the limit.

            Must be a string value comprised of one of the following:

                ``second``, ``minute``, ``hour``, ``day``, ``week``,
                ``month`` or ``year``

    clients:

        type:
            Sets the type of client.
            Currently the two supported types of are *iDigi* and *Enduser*.

        transport:
            Sets the type of transport this client should use.
            The only supported type is *SMS*.

        command_access: (required ONLY when 'transport' is set to *SMS* and the type of client is set to *Enduser*)
            Sets whether the client is allowed to send commands to
            this device or not.
            When set to False, the client effectively becomes a reporting
            only client.

            .. note::
                By default there are no commands defined for the Enduser.
                It is assumed that commands will be added based on the requirements that one might have to support other things beyond reporting samples values.
                Please view the Enduser source code in Enduser.py for more information.

        number: (required ONLY when 'transport' is set to *SMS* and the type of client is set to *Enduser*)
            The phone number to send data to.
            This setting is also used to determine whether we will
            accept commands when received from the given number.

        update_message: (required ONLY when 'transport' is set to *SMS* and the type of client is set to *Enduser*)

                Specifies the text format that should be used when an Update
                is sent.

                NOTE: There are shortcut escape sequences that can be used to indicate important variables in the text::

                    %c: Will output the channel name
                    %v: Will output the current channel value
                    %u: Will output the current channel units
                    %t: Will output the current channel timestamp
                    %h: Will output the current channel timestamp, in human-readable format

        alarm_message: (required ONLY when 'transport' is set to *SMS* and the type of client is set to *Enduser*)

                Specifies the text format that should be used when an Alarm
                is sent.

                NOTE: There are shortcut escape sequences that can be used to indicate important variables in the text::

                    %c: Will output the channel name
                    %v: Will output the current channel value
                    %u: Will output the current channel units
                    %t: Will output the current channel timestamp
                    %h: Will output the current channel timestamp, in human-readable format

    updates:

        filter:
            Sets the channel name filter to trigger on.
            This setting is a 'glob' style string, which allows for
            using the wildcard values of '*' and '?' to create filters.

            An example might be "Massa*distance*", which would be
            able to capture channel names like "Massa1.distance",
            "Massa2.distance" and "Massa3.distance" all in one filter.

        clients:
            Sets the client list that these updates should be sent to.

        interval:
            Sets the interval rate in which to update each client in the
            client list.


    alarms:

        filter:
            Sets the channel name filter to trigger on.
            This setting is a 'glob' style string, which allows for
            using the wildcard values of '*' and '?' to create filters.

            An example might be "Massa*distance*", which would be
            able to capture channel names like "Massa1.distance",
            "Massa2.distance" and "Massa3.distance" all in one filter.

        clients:
            Sets the client list that these updates should be sent to.

        condition:
            Sets the condition in which this alarm should be triggered.
            This value should be written as a Python expression that
            will be evaluated to either True of False.
            To substitute the channel's current value, use %c in your
            expression.

            A few examples are::

                "%c < 10.0"
                "%c < 10.0" or
                "%c > 30.0"
