- 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 »

# Getting Started

## Introduction

Welcome to the iDigi Device Integration Application Getting Started guide. This document will lead you through setting up and executing the iDigi Device Integration Application (“iDigi Dia”). The iDigi Dia is used to create remote monitoring and sensor network applications. It is written in the Python language, it is fully extensible and you may easily add your own code and modules. The Dia can be executed in a PC environment for training and prototyping, then can be migrated to a supported Digi device.

The following activities are described in this guide:

> - Setting up Python 2.4 on your personal computer.
> - Executing and understanding your first Dia application on your PC.
> - Copying and executing this same application to your Digi device.
> - Adding an XBee device driver instance and redeploying your application.

This guide will make the assumption that we are operating on a Microsoft Windows environment; however, one can develop an application using the Dia on just about any personal computing environment where Python is supported.

Note

The iDigi Dia has now been integrated into the Digi ESP for Python, an integrated development environment (IDE) built on Eclipse. This environment includes a complete Dia installation and extends the Dia with a Smart Project Editor, and integrates creating, building, editing, and debugging Dia projects within a single graphical user interface.

Note

The path delimiter used in this document is the ‘/’ character.

## General Work-flow Summary

The general work flow for writing an application is the following:

> 1. Design Phase:

>    > 1. Decide which devices (e.g. XBee devices, serial devices, etc.) data will be acquired from.
>    > 2. Decide how this data will be presented to users and other applications (e.g. via a web page, by the command line interface, by posting XML documents to a web server, etc.)

> 2. Implementation Phase:

>    > 1. Select existing device drivers from the device driver library (in src/devices) or extend the library to include new custom devices by writing your own code.
>    > 2. Select existing data presentations from the presentation library (in src/presentations) or extend the library to include new custom presentations by writing your own code.
>    > 3. Configure the framework by writing your own YML file (often stored in the cfg/ directory).

> 3. Deployment & Testing Phase:

>    > 1. Execute make.py on your YML configuration file to create a bin/dia.zip which contains the source, configuration, and dependencies for your project.

>    > 2. Upload dia.py and bin/dia.zip to your Digi device.

>    > 3. Reboot your iDigi Device (if it has previously been running a Python application).

>    > 4. Telnet to your iDigi Device and execute your application::

>    >        #> python dia.py your_configuration.yml

>    > 5. Test and debug your application!

## Getting Started

### Installing Python 2.4

The Python programming language needs to be installed on your personal computer in order to be able to use the iDigi Dia. Digi products use Python version 2.4.3 and therefore the version of Python installed on your computer must be from the Python 2.4 series. Ideally, Python version 2.4.3 should be used.

Note

If you are an expert, then you may have multiple major versions of Python installed on your system at any one time. This may cause problems; for instance, an installation of Python 2.4 has limited problems coexisting with an installation of Python 2.5 or 3.0. If you do have multiple versions of Python installed, take care to know which version of Python is being executed when running the iDigi Dia. If you are having difficulty, make sure to consult your system PATH variable, etc.

However, the average Windows user will find it easiest to delete all versions of Python and only install Python 2.4.3, which is available at the Python website: http://www.python.org/download/releases/2.4.3/

Note

From iDigi Dia 1.3 onward, to run it on a PC you must install pywin previously. Please, install pywin for Python 2.4. It may be downloaded from this link: http://sourceforge.net/projects/pywin32/files/

### Opening a Command Prompt and Running the Dia

Open a Microsoft Windows command prompt (cmd.exe) and change directory folders to the place in which you have unpacked the dia archive.

In this directory folder you should see the following files and directories in addition to some other entities:

> - bin/
> - cfg/
> - dia.py
> - doc/
> - lib/
> - src/

The “dia.py” script is the script that is responsible for starting the iDigi Dia. It is able to run both on the PC environment and on the Digi device. Here we will execute it on our PC:

    C:\Users\Joe\Source\digi_dia>dia.py

If this fails it may be because python.exe is not in the system path. We may either add it to the PATH (via the Advanced Systems Settings dialog of the Windows Control Panels “System” settings) or we may specify the full path to Python:

    C:\Users\Joe\Source\digi_dia>C:\Python24\python.exe dia.py

We should then see the following program output:

    Determining platform type... PC host environment assumed.

    iDigi Device Integration Application Version 1.3.8
    Using settings file: dia.yml
    Core: initial garbage collection of 0 objects.
    Core: post-settings garbage collection of 28 objects.
    Starting Scheduler...
    Starting Channel Manager...
    Starting Device Driver Manager...
    Starting Presentation Manager...
    Web Presentation (web0): using port 8001 and BaseHTTPServer
    XMLRPC(xmlrpc): starting server on port 8080
    Starting Services Manager...
    Core services started.

Note

cfg/dia.yml is the default configuration file.

If you see this output without any fatal errors or exceptions, you have successfully run the iDigi Dia! Now, let us see how we may interact with the framework.

### Connecting to the Dia Command Line Interface

In the default cfg/dia.yml, an instance of the Dia command line interface (“CLI”) presentation is enabled on TCP port 4146. We can connect to this command line interface using a standard telnet client such as Microsoft Window’s telnet.exe or PuTTY. Connecting to the CLI presentation allows us to interact with the Dia’s channels and settings. Connect your telnet client to the host “localhost”, using port 4146. In Windows XP, this can be done from a command line by typing “telnet.exe localhost 4146”.

Note

Windows Vista and Windows 7 have telnet disabled by default, in which case this command will fail. To enable it (in Windows 7), bring up the “Programs and Features” section of the Control Panel, and check “Telnet Client” under “Turn Windows Features on or off”.

Once we connect to the Dia, we are first presented with the following welcome message and prompt:

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

The first thing to do is to type “help” at the command prompt in order to see what commands we can execute:

    =>> help

        Documented commands (type help <topic>):
        ========================================
        channel_dump     channel_set  logger_iterate  logger_prev    q
        channel_get      exit         logger_list     logger_rewind  quit
        channel_info     help         logger_next     logger_seek
        channel_refresh  logger_dump  logger_pos      logger_set

Note

If we make a mistake while typing, pressing CTRL-H will backspace.

Typing “help” followed by the name of a command will give us additional information on that command:

    =>> help channel_dump
    Dump the channel values for all devices.

    Syntax:
        channel_dump [prefix]

If we type “channel_dump” at the prompt we will receive the values of all channels for all devices on the Dia system:

    =>> channel_dump

    Device instance: template

       Channel                      Value      Unit     Timestamp
       ---------------------------- ---------- -------- -------------------
       adder_reg1                   0.0                 2010-06-16 11:17:32
       adder_reg2                   0.0                 2010-06-16 11:17:32
       adder_total                  0.0                 2010-06-16 11:17:32
       counter                      993                 2010-06-16 11:34:09
       counter_reset                (N/A)
       global_reset                 (N/A)

    Device instance: template_transforms

       Channel                      Value      Unit     Timestamp
       ---------------------------- ---------- -------- -------------------
       count_by_two                 1986                 2010-06-16 11:34:09

A “device instance” is a device driver which has been loaded into the system. Each of the channels under each device represents a property of that device. Channel properties have a value, a unit, and a timestamp. Channel property values may be get (read), set (wroFte), queried for info, requested to be refreshed, or some combination of all four. We can use the Dia CLI to get the value of a channel:

    =>> channel_get template.counter
            template.counter: 1086 () @ 2010-06-16 11:35:43
    =>> channel_get template.counter
            template.counter: 1091 () @ 2010-06-16 11:35:48
    =>> channel_get template.counter
            template.counter: 1092 () @ 2010-06-16 11:35:49

Note

We can access command line history by pressing the up and down arrows on the keyboard.

The template device driver is a demonstration device. Part of its demonstration functionality is that it implements a simple counter. Above, we can clearly see this counter incrementing.

The template device also implements a simple adder. An adder is a simple logic device that takes two input values, adds them together, and produces a logical output containing the new sum value. Let us interact with the template drivers adder by using the “channel_set”, “channel_dump”, and “channel_get” commands:

    =>> channel_dump template.

    Device instance: template

       Channel                      Value      Unit     Timestamp
       ---------------------------- ---------- -------- -------------------
       adder_reg1                   0.0                 2010-06-16 11:17:32
       adder_reg2                   0.0                 2010-06-16 11:17:32
       adder_total                  0.0                 2010-06-16 11:17:32
       counter                      1235                2010-06-16 11:38:13
       counter_reset                (N/A)
       global_reset                 (N/A)

    Device instance: template_transforms

       Channel                      Value      Unit     Timestamp
       ---------------------------- ---------- -------- -------------------
       count_by_two                 2470                 2010-06-16 11:38:13

    =>> channel_set template.adder_reg1 42.0
            template.adder_reg1: 42.0 ((unit unavailable)) @ (time unavailable)
    =>> channel_dump template

    Device instance: template

       Channel                      Value      Unit     Timestamp
       ---------------------------- ---------- -------- -------------------
       adder_reg1                   42.0                2010-06-16 11:40:09
       adder_reg2                   0.0                 2010-06-16 11:17:32
       adder_total                  42.0                2010-06-16 11:40:09
       counter                      1409                2010-06-16 11:41:08
       counter_reset                (N/A)
       global_reset                 (N/A)

    Device instance: template_transforms

       Channel                      Value      Unit     Timestamp
       ---------------------------- ---------- -------- -------------------
       count_by_two                 2818                2010-06-16 11:38:13

    =>> channel_set template.adder_reg2 58.0
            template.adder_reg2: 58.0 ((unit unavailable)) @ (time unavailable)
    =>> channel_dump template.

    Device instance: template

       Channel                      Value      Unit     Timestamp
       ---------------------------- ---------- -------- -------------------
       adder_reg1                   42.0                2010-06-16 11:40:09
       adder_reg2                   58.0                2010-06-16 11:42:15
       adder_total                  100.0               2010-06-16 11:42:15
       counter                      1516                2010-06-16 11:42:55
       counter_reset                (N/A)
       global_reset                 (N/A)

    Device instance: template_transforms

       Channel                      Value      Unit     Timestamp
       ---------------------------- ---------- -------- -------------------
       count_by_two                 3032                2010-06-16 11:42:55

    =>> channel_get template.adder_total
            template.adder_total: 100.0 () @ 2010-06-16 11:42:15

Note

The CLI supports auto-completion. Try pressing the TAB key when typing a command name or command argument!

Here we have used the “channel_set” command to manipulate the values of “template.adder_reg1” and “template.adder_reg2” and we have read back the new sum value from “template.adder_total” using both the “channel_dump” and “channel_get” commands.

In the above examples we have interacted with a single driver; however, drivers may interact with one another. One common driver-to-driver interaction is by using the transforms device driver. The transforms device driver takes sample values from one or more channels and applies an expression (similar to a formula in a spreadsheet application) to calculate a new value.

The transforms driver is useful for performing unit conversions (for example, converting Fahrenheit into Centigrade), calculating areas and volumes (such as length multiplied by width multiplied by height), or even for sums and simple averages. In our example template configuration we observe that our transforms driver instance named “template_transforms” contains a channel property named “count_by_two” which multiplies the value of “template.counter” by two. Examine the following:

    =>> channel_dump

    Device instance: template

       Channel                      Value      Unit     Timestamp
       ---------------------------- ---------- -------- -------------------
       adder_reg1                   42.0                2008-11-05 12:13:48
       adder_reg2                   58.0                2008-11-05 12:15:03
       adder_total                  100.0               2008-11-05 12:15:03
       counter                      2733                2008-11-05 12:34:34
       counter_reset                (N/A)
       global_reset                 (N/A)

    Device instance: template_transforms

       Channel                      Value      Unit     Timestamp
       ---------------------------- ---------- -------- -------------------
       count_by_two                 5466                2008-11-05 12:34:34

    =>> channel_get template.counter
            template.counter: 2740
    =>> channel_get template_transforms.count_by_two
            template_transforms.count_by_two: 5482

Note

When the second “channel_get” was performed to retrieve the value of “template_transforms.count_by_two” the value of “template.counter” had already incremented to 2741.

### Seeing the Data in Another Way: The Web Presentation

If we refer to Opening a Command Prompt and Running the Dia above, we can see a line from the program output that reads:

    Web Presentation (web0): using port 8001 and BaseHTTPServer

In the configuration file (“cfg/dia.yml”) the web presentations driver loads with the “page” setting set to “idigi_dia.html” By default, when the web presentation loads on a PC (i.e. non-Digi) environment it will start its own web-server on port 8001. This port setting can be overwritten. If a web browser is opened on the PC running the Dia and given the following URL, an HTML form containing the current devices and channels will be rendered for the user:

    http://localhost:8001/idigi_dia.html

### Deploying the Device Integration Application on a iDigi Device

Loading the iDigi Dia onto an iDigi Device is easy. As described in Opening a Command Prompt and Running the Dia above, open a command prompt window and navigate to the directory folder where the iDigi Dia has been installed and at the prompt type the following:

    C:\Users\Joe\Source\dia>python make.py cfg\dia.yml

Note

If python.exe is not in your environment’s PATH you will have to change “python” to be `C:\Python24\python.exe` in the above.

When the make.py script executes it will analyze the current project and generate a file named “dia.zip” in the “bin/” directory of the Digi Dia installation folder. This archive contains only the Python libraries necessary for running the Dia on the target Digi platform at a savings of system non-volatile flash storage.

In the above example we used the file name “dia.yml”. However, the make.py script will accept any valid Dia YML file for analysis.

The output that printed to the command window when running make.py should resemble the following:

    Project make started.
    Analyzing files...
    Compiling files...
    Zipping files...
    Finished writing archive 'C:\<...path...>\bin\dia.zip'
    Transforming settings file 'cfg\dia.yml' to 'pyr' format...
    Adding transformed settings as 'dia.pyr' to 'C:\<...path...>\bin\dia.zip' ...
    Project make completed successfully.

Note

If you have Python 2.4 installed in a non-standard directory, you may have to edit the make.py script in a text editor and change the value of the PYTHON_LIB variable to be the location of your Python 2.4 installation’s library path.

After building the archive, the next task is to load the archive and the initial loader script “dia.py” onto the target Digi device. In order to do this, open a web-browser and connect to the Web User Interface of the iDigi Device, by typing the device’s IP into the address bar. At the far left, there is a heading labeled “Applications” and underneath this heading there is a link labeled “Python”. Click on this “Python” link.

You will be presented with a listing of files as well as an upload form. Use the form to upload “dia.py” and “bin/dia.zip” to the device. There are two things to note at this point:

The first is that the configuration file “dia.yml” has been built into the dia.zip file. It does not need to be loaded to the device.

The second item of note is that if configuration changes are made, the “dia.zip” file will have to be rebuilt using the “make.py” script and re-loaded onto the device. The “dia.py” script does not change and it does not need to be reloaded. The “dia.py” script may only change if you change it via local edits (for debugging purposes, etc.) or if you receive a new release of the Device Integration Application from Digi.

### Running the iDigi Dia on the iDigi Device

Now that the Dia Framework has been loaded on the Digi device we may start our iDigi Dia application. Connect to the Digi device’s command line interface using a telnet client to the IP address of the Digi device with the default port (TCP port 23).:

Note

C:>telnet.exe 10.8.113.64

You should see a prompt that looks like:

    #>

In order to start the iDigi Dia application type the following:

    #> python dia.py

If you wish to use a separately uploaded yml configuration file (i.e. on the device filesystem, outside of dia.zip), you must also specify the filename to be used:

    #> python dia.py dia.yml

You should see the following output printed to the terminal:

    Determining platform type...Digi Python environment found.

    Attempting to read "dia.pyr" in "WEB/python/dia.zip" ...
    iDigi Device Integration Application Version 1.3.8
    Using settings file: dia.pyr
    Core: initial garbage collection of 0 objects.
    Core: post-settings garbage collection of 10 objects.
    Starting Scheduler...
    Starting Channel Manager...
    Starting Device Driver Manager...
    Starting Presentation Manager...
    Web Presentation (web0): using port 8001 and BaseHTTPServer
    XMLRPC(xmlrpc): starting server on port 8080
    Starting Services Manager...
    Core services started.

Once the Dia has started, we may connect a telnet client to port 4146 and see our data just as we had when the Dia was running locally on our PC:

    >telnet.exe 10.8.113.64 4146

    Connected to 10.8.113.64.
    Escape character is '^]'.
    Welcome to the iDigi Device Integration Application CLI.
    =>> channel_dump

        Device instance: template

           Channel                      Value      Unit     Timestamp
           ---------------------------- ---------- -------- -------------------
           adder_reg1                   0.0                 2008-11-05 18:28:57
           adder_reg2                   0.0                 2008-11-05 18:28:57
           adder_total                  0.0                 2008-11-05 18:28:57
           counter                      701                 2008-11-05 18:41:00
           counter_reset                (N/A)
           global_reset                 (N/A)

        Device instance: template_transforms

           Channel                      Value      Unit     Timestamp
           ---------------------------- ---------- -------- -------------------
           count_by_two                 1402                2008-11-05 18:41:00

        =>>

And we can connect using a web browser to the following address and receive a web representation of the same channel data:

    http://<the IP address of your Digi device>/idigi_dia.html

Note

When the web presentation is run on the Digi device, it does not use its own port number by default.

If you should wish to terminate the application and load a new version of the application on the gateway, the gateway must first be rebooted. In order to do this, disconnect from your telnet session and open a new session to the Digi device. At the prompt type the following:

    #> boot action=reset

This may also be abbreviated:

    #> bo a=r

### Using the Device Integration Application with a Wireless Device

The real power of the Device Integration Application is in device and data presentation abstraction. This power may be leveraged with wireless devices quite easily. The ConnectPort X series of wireless gateways from Digi incorporate a wireless XBee module for connectivity to many different types of wireless networks.

The iDigi Dia contains an abstraction model for communicating with wireless devices. The abstraction is expressed in what is known as the XBee Driver Stack for the iDigi Dia.

The XBee Driver Stack is divided into two items:

> 1. The XBee Device Manager
> 2. XBee device driver implementations.

A single instance of the XBee Device Manager is required when using one or more XBee device drivers on the Dia. The XBee Device Driver Manager is responsible for multiplexing data communications and managing node configurations. Each XBee device driver will use this single instance of the XBee Device Driver in turn to communicate with the wireless network.

A demonstration configuration file is included with the iDigi Dia to illustrate how to use the Dia to communicate with a wireless network. The configuration file includes the necessary statements to load an instance of the XBee Device Manager and an XBee device driver for a wirelessly connected XBee XBIB development board. The configuration file is located in the file demos/getting_started/digi_dia_xbib.yml

We will use this configuration file to communicate to communicate to a wireless device using the iDigi Dia. One of the first activities we need to do is to edit the digi_dia_xbib.yml configuration file to contain the proper address of the XBee module installed in the XBIB development board. In order to determine this address, we must first either read the address from the sticker at the bottom of the module or use the ConnectPort user interface to discover the address on our own.

If we use a web-browser and connect to the IP address of the Digi device, we may click on a link under the “Configuration” heading labeled either “XBee Network” or “Mesh Network” (depending on the Digi device firmware version). If we click on the “Refresh” button, the list of discovered devices will update and it will resemble the following:

> Node ID | Network Address | Extended Address | Node Type
> --- | --- | --- | ---
> COORD | [0000]! | 00:13:a2:00:40:34:02:30! | coordinator
> ... |  |  |
> DEVBRD | [ef69]! | 00:13:a2:00:30:0a:4a:b5! | router

Note

The Node ID labels in the above example had be previously set using the web user interface of the Digi device.

The “Extended Address” of each node is static and unchanging. This value, “00:13:a2:00:30:0a:4a:b5!” in the above example is what we will update the “extended_address” setting of the xbib0 instance in the digi_dia_xbib.yml configuration file.

Please identify the extended address value of your module and make a note of it. Open the demos/getting_started/digi_dia_xbib.yml file in a text editor of your choice and modify the following line to contain the value of your XBee module’s address:

    extended_address: "00:13:a2:00:40:0a:4a:b5!"

Once this change has been made, save the file and quit your text editor.

As we have done in previous sections, next we need to build the dia.zip binary and upload it to the Digi device. We will open a command prompt window, navigate to the place in which we have the Dia source files, and execute make.py on our configuration file:

    C:\Users\Joe\Source\dia.python make.py demos\getting_started\digi_dia_xbib.yml

Next, we will upload both the newly generated bin/dia.zip and the demos/getting_started/dia.yml configuration file to the Digi device. In order to do this, we will once again open a web-browser and connect to the Web User Interface of the iDigi Device. Beneath the heading labeled “Applications” a there is a link labeled “Python” Click on this “Python” link and use the form to upload both files.

Now that we have loaded our Digi device will all the necessary components we can connect to the command line with our telnet client and start the iDigi Dia with our new configuration file. After connecting to the device will we will the following prompt:

    #>

In order to start the iDigi Dia application type the following:

    #> python dia.py digi_dia_xbib.yml

Note

Observe that we are using “digi_dia_xbib.yml” instead of “dia.yml” as we have done in our previous examples!

We should see the following output:

    Determining platform type...Digi Python environment found.

    iDigi Device Integration Application Version 1.3.8
    Using settings file: WEB/python/dia.yml
    Starting Channel Manager...
    Starting Device Driver Manager...
    [ ... some XBee trace messages may appear here ... ]
    Starting Presentation Manager...
    Core services started.

Next, we may connect to the Dia command line by connecting our telnet client to port 4146 and performing a channel_dump:

    Trying 10.8.113.64...
    Connected to 10.8.113.64.
    Escape character is '^]'.
    Welcome to the iDigi Device Integration Application CLI.
    =>> channel_dump

    Device instance: template

      Channel                      Value      Unit     Timestamp
      ---------------------------- ---------- -------- -------------------
      adder_reg1                   0.0                 2008-11-10 17:50:26
      adder_reg2                   0.0                 2008-11-10 17:50:30
      adder_total                  0.0                 2008-11-10 17:50:26
      counter                      25                  2008-11-10 17:50:59
      counter_reset                (N/A)
      global_reset                 (N/A)

    Device instance: template_transforms

      Channel                      Value      Unit     Timestamp
      ---------------------------- ---------- -------- -------------------
      count_by_two                 50                  2008-11-10 17:50:59

    Device instance: xbib0

      Channel                      Value      Unit     Timestamp
      ---------------------------- ---------- -------- -------------------
      sw1                          True                2008-11-10 17:50:34
      sw2                          True                2008-11-10 17:50:36
      sw3                          True                2008-11-10 17:50:38
      sw4                          True                2008-11-10 17:50:38

    =>>

From the channel dump we can see the new device instance of the XBee XBIB device driver named “xbib0”. The driver contains four channels which are representative of the four momentary push buttons on the XBee XBIB development board. The four buttons on this development board will pull the logic level to ground when they are pressed and the value of the channel in the Dia will transition from “True” to “False”. In the above snapshot, all four buttons are in their open state.

In the below example, we are holding a button down while we dump the channels of the xbib0 device:

    =>> channel_dump xbib0

    Device instance: xbib0

      Channel                      Value      Unit     Timestamp
      ---------------------------- ---------- -------- -------------------
      sw1                          False               2008-11-10 17:51:28
      sw2                          True                2008-11-10 17:50:36
      sw3                          True                2008-11-10 17:50:38
      sw4                          True                2008-11-10 17:50:38

    =>>

Here we can see the xbib0.sw1 channel has transition from “True” to “False”.

We can enable more wireless devices by following the same pattern presented in this section:

> 1. Add configuration lines to a configuration file.
> 2. Re-generate dia.zip and upload it to the gateway.
> 3. Restart the iDigi Dia.

Settings for each driver may be found in the API reference for each driver’s source file. Either open the API reference documentation or use a text editor to read the documentation from each driver source file directly.

## Where to Go Next

### On-line Resources

See:

> - The Digi Web page
> - The iDigi Development Platform
> - The Digi ESP for Python (requires iDigi login)
> - The Digi Python Developer Resource Center
> - The Digi Python Development Wiki

### Navigation

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