Echelon i.LON 100 SOAP/XML Interface

The Echelon i.LON 100 is a Internet gateway for the LON⁵⁰ fieldbus and provides a SOAP Web Service-based interface for data access and configuration. The SOAP protocol of the device is not based on any standards, it uses a proprietary protocol developed by Echelon. The i.LON 100 was one of the first fieldbus gateways that implemented a Web Service-based interface.

Echelon already provides various tools that can be used to configure and access the i.LON 100, such as a configuration tool, distributed with the device or a LON specific tool called ``LonMaker''. However, it is also possible to access the gateway with custom Web Service-based applications. Echelon provides WSDL files that can be used by developer tools and offer a complete programming reference. Further information can be found in [ILON04].

The i.LON 100 provides access to fieldbus devices with so-called ``data points''⁵¹ which contain the actual value and some data point specific properties, such as its data type and format. Data points have names which follow a naming convention that is used throughout various LON specific tools, such as LonMaker.

The gateway implements the following functions that can be used to directly access data points:

DataPointRead:

This function implements reading the current value of a specific data point. Listing 15 depicts parts of an example request/response SOAP for querying the status of a light switch.

language=XML

Line 1,2 illustrate the request message, which consists of the name of the data point and an optional field name in case the value is a data structure. The result message contains the value of the data point and its properties, such as the time when the value was read, the unit or the alarm status.

DataPointWrite:

The write function enables writing the value of a data point. The SOAP request message has to contain the data point name and may contain the following special parameters:

Priority:

The i.LON 100 implements a simple priority system for writing values to datapoints by defining priority levels⁵² which are stored in a property of a data point. A write operation is only performed, if the priority is the same or higher than the priority level stored in the data point. In case the priority level of the write access is higher than the stored priority, the data point property is overwritten with the higher priority level. This way important or time critical write operations may gain precedence over others. The device also implements a special function to reset the priority level of a data point to recover write access of functions with lower priority.

Propagate:

In case of writing to structures, there may be situations where the structure must not be successively written to the fieldbus node. Therefore a write operation may specify the parameter ``Propagate'' which inhibits a propagation of the written value to the fieldbus network. This way, the values of the structure may be written one after another and may be propagated to the fieldbus node in an atomic operation.

Apart from these specific functions that can be used to directly access Data Points, the i.LON 100 implements so-called ``applications'' that provide a set of functions for specific purposes. Figure 24 provides an overview.

Figure 24: i.LON 100 applications and functions

These applications are configured with XML files that are uploaded to the gateway embedded in SOAP messages⁵³. Applications consist of items, such as data points, events, alarms or data logs and can be referenced by a specific identification number, called ``index'' or by its unique name. Every application has the following four basic functions which read or modify the XML configuration files:

1. List:

This function can be used for listing or browsing items, such as alarms, data points or events which are already defined in the i.LON 100 configuration files. The returned SOAP message will contain item properties, such as the index number and name of the item, its description or its last update time.

2. Get:

The configuration of items may be retrieved with this function. The request message has to contain the index number or name of the item and may contain also references to multiple items.

3. Set:

This is the counterpart of the ``Get'' function and manages writing of configuration data. Multiple item configurations may be written at once. The ``Set'' function is used to create new items and to overwrite the configuration of existing items.

4. Delete:

This function deletes items, such as certain data logs, data points or alarms.

These functions differ from the above ``DataPointRead/Write'' functions as the SOAP message is only used for transporting XML code. The SOAP body of request messages consists of the special element <Data> which then contains an encoded XML⁵⁴ file as shown in Listing 16.

language=XML

The above functions are meant to be ``symmetric'', which means that the output of one function may be used as an input to another. For example, a data point or alarm item may be cloned by feeding the output of a ``Get'' request to a subsequent ``Set'' command.

As shown in Figure 24, the i.LON 100 implements various applications for the following purposes:

Data point management:

The most important application of the i.LON 100 is the so-called ``Data Server''. It can be used to create, manage, delete and access data points. Apart from the four basic functions, as shown above, the Data Server provides the functions ``Read'', ``Write'' and ``ResetPriority'' that are very similar to the functions ``DataPointRead/Write''. However, the Data Server functions provide more functionality, such as reading and writing multiple data points at once, or reading values from data points that fulfill certain criteria.

Data logging:

The i.LON 100 implements so-called ``Data Loggers'' that can be configured to monitor and store changes of data point values. The data logs itself can be downloaded with the ``Read'' function⁵⁵ and can be erased with the function ``Clear''. The Data Logger enables storage and access of historical data but may also be configured so that it stores values in a circular buffer, which means that the oldest values are subsequently overwritten by newer ones.

Alarming:

The gateway implements alarming by two applications: the ``AlarmGenerator'' that generates alarms such as when certain limits of data point values are exceeded and the ``AlarmNotifier'' that logs alarm conditions, sends notifications via SMTP or updates specific data points.

Event Scheduling:

The i.LON 100 implements two applications, called ``EventScheduler'' and ``EventCalendar'' that can be used for periodic updates of data points. The EventScheduler provides means for creating day-based schedules, such as switching on a light every Monday at 8:00am. The EventCalendar may then be used to create exceptions for these day-based schedules. This way even complex scheduling applications may be implemented.

Type Translating:

The Type Translator can be utilized to translate values of data points with a specific variable type into another type. This can be useful when comparing data points of incompatible types. The i.LON 100 also enables the creation of custom rule sets that can be stored and utilized by the Type Translator.

The i.LON 100 does not provide strong security measures. The device limits access by implementing HTTP basic authentication and a common password protection when it is accessed via FTP. Encryption techniques, such as SSL and authenticity checks like signatures are not supported. This limits the field of application of the i.LON 100 to already secured intranets - a direct connectivity to the Internet would pose many security threats.