Echelon i.LON 100 e2 User Manual

Download

i.LON

100 e2 Internet

Server Programmer’s

Reference

Version 1.1

™

@echelon

C o r p o r a t i o n

078-0250-01B

Echelon, LON, LONWORKS, NodeBuilder, LonTalk, Neuron, L

ONMARK, LNS, LonBuilder, LonUsers, BeAtHome, LonManager,

3120, 3150, LonPoint, Digital Home, L

i.LON, the Echelon logo, and the L

ONWORLD, ShortStack,

ONMARK logo are

registered trademarks of Echelon Corporation. LNS Powered by Echelon, LonMaker, LonLink, LonResponse, OpenLDV, LONews, Open Systems Alliance, Panoramix, Panoramix Powered by Echelon, L

ONMARK Powered by Echelon,

No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of Echelon Corporation.

Echelon Corporation 550 Meridian Ave San Jose, CA 95126, USA

Table Of Contents

1 Introduction to the i.LON 100 SOAP/XML Interface.............................................. 1-1

1.1 About This Document .................................................................................................... 1-1

1.2 Programming Samples .................................................................................................. 1-2

1.3 Getting Started .............................................................................................................. 1-2

1.4 i.LON 100 Version 1.1 SOAP/XML Interface Upgrades.............................................. 1-2

1.4.1 Modified SOAP Applications and Functions............................................................ 1-3

1.4.2 Changes to SOAP Message Formats ........................................................................ 1-6

2 SOAP Messages and the i.LON 100 WSDL File........................................................ 2-1

2.1 i.LON 100 WSDL File.................................................................................................... 2-1

2.2 Security........................................................................................................................... 2-1

2.3 Formats of SOAP Messages .......................................................................................... 2-2

2.3.1 Input Messages .......................................................................................................... 2-2

2.3.1.1 SOAP Envelope ................................................................................................. 2-2

2.3.1.2 SOAP Body ........................................................................................................ 2-3

2.3.2 Response Message ..................................................................................................... 2-4

2.3.2.1 SOAP Header .................................................................................................... 2-4

2.3.2.2 <Result> Parameter.......................................................................................... 2-5

2.3.3 SOAP Error Responses.............................................................................................. 2-5

2.4 Writing SOAP Applications........................................................................................... 2-6

3 Monitoring and Controlling Data Points with the SOAP/XML Interface......... 3-1

3.1 Overview of Data Points ................................................................................................ 3-1

3.2 About This Chapter........................................................................................................ 3-2

3.3 DataPointWrite .............................................................................................................. 3-3

3.3.1 Data Point Values and Priority Levels..................................................................... 3-5

3.4 DataPointRead ............................................................................................................... 3-7

3.5 DataPointResetPriority ............................................................................................... 3-10

3.6 Using the DataPoint Functions With Visual Basic .NET ......................................... 3-11

3.6.1 DataPointWrite........................................................................................................ 3-11

3.6.2 DataPointRead......................................................................................................... 3-11

3.6.3 DataPointResetPriority........................................................................................... 3-11

3.6.4 Programming Samples ............................................................................................ 3-12

4 i.LON 100 Applications and the SOAP/XML Interface........................................... 4-1

4.1 Overview of i.LON 100 Applications............................................................................. 4-1

4.2 i.LON 100 XML Configuration Files............................................................................. 4-2

4.3 i.LON 100 SOAP Functions........................................................................................... 4-3

4.3.1 <Data> Parameter ..................................................................................................... 4-5

4.3.1.1 Encoded XML and Standard XML................................................................... 4-6

4.4 i.LON 100 Resource Files .............................................................................................. 4-8

4.4.1 LonMark Standard Network Variable Type (SNVT) Device Resource Files......... 4-8

4.4.2 Standard Configuration Property Type (SCPT) Device Resource Files ................. 4-8

4.4.3 User Network Variable Type (UNVT) Device Resource Files ................................ 4-9

4.4.4 User Configuration Property Type (UCPT) Device Resource Files....................... 4-9

4.5 Data Formatting .......................................................................................................... 4-10

4.6 List, Get, Set and Delete Functions............................................................................ 4-11

4.6.1 List Functions .......................................................................................................... 4-11

4.6.2 Get Functions........................................................................................................... 4-11

4.6.3 Set Functions ........................................................................................................... 4-11

4.6.4 Delete Functions ...................................................................................................... 4-12

4.7 Performance Issues ...................................................................................................... 4-13

i.LON 100 Internet Server Programmer’s Reference i

4.8 Getting Started ............................................................................................................ 4-14

5 Data Server....................................................................................................................... 5-1

5.1 Data Server XML Files .................................................................................................. 5-4

5.1.1 DP_NVL.XML ............................................................................................................ 5-5

5.1.2 DP_NVC.XML............................................................................................................ 5-7

5.2 Creating and Modifying the Data Server XML Files................................................... 5-8

5.2.1 Data Server SOAP Interface..................................................................................... 5-8

5.2.1.1 DataServerList................................................................................................ 5-10

5.2.1.2 DataServerGet ................................................................................................ 5-12

5.2.1.3 DataServerSet ................................................................................................. 5-17

5.2.1.4 DataServerRead .............................................................................................. 5-19

5.2.1.5 DataServerWrite ............................................................................................. 5-24

5.2.1.6 DataServerResetPriority ................................................................................ 5-27

5.2.1.7 DataServerDelete............................................................................................ 5-28

6 Data Loggers ....................................................................................................................6-1

6.1 DataLogger.XML............................................................................................................ 6-1

6.2 Creating and Modifying the DataLogger.XML File..................................................... 6-4

6.2.1 DataLogger SOAP Interface ..................................................................................... 6-4

6.2.1.1 DataLoggerList ................................................................................................. 6-5

6.2.1.2 DataLoggerGet .................................................................................................. 6-6

6.2.1.3 DataLoggerSet................................................................................................. 6-10

6.2.1.4 DataLoggerRead ............................................................................................. 6-11

6.2.1.5 DataLoggerClear............................................................................................. 6-15

6.2.1.6 DataLoggerDelete ........................................................................................... 6-17

7 Alarm Generator ............................................................................................................. 7-1

7.1 AlarmGenerator.XML.................................................................................................... 7-2

7.2 Creating and Modifying the AlarmGenerator.XML File............................................. 7-3

7.2.1 Alarm Generator SOAP Interface............................................................................. 7-3

7.2.1.1 AlarmGeneratorList ......................................................................................... 7-4

7.2.1.2 AlarmGeneratorGet .......................................................................................... 7-5

7.2.1.3 AlarmGeneratorSet......................................................................................... 7-16

7.2.1.4 AlarmGeneratorDelete ................................................................................... 7-17

8 Alarm Notifier..................................................................................................................8-1

8.1 AlarmNotifier.XML........................................................................................................ 8-2

8.2 Creating and Modifying the AlarmNotifier.XML File................................................. 8-4

8.2.1 Alarm Notifier SOAP Interface................................................................................. 8-4

8.2.1.1 AlarmNotifierList ............................................................................................. 8-5

8.2.1.2 AlarmNotifierGet .............................................................................................. 8-6

8.2.1.3 AlarmNotifierSet............................................................................................. 8-19

8.2.1.4 AlarmNotifierRead.......................................................................................... 8-20

8.2.1.5 AlarmNotifierWrite......................................................................................... 8-26

8.2.1.6 AlarmNotifierClear ......................................................................................... 8-29

8.2.1.7 AlarmNotifierDelete ....................................................................................... 8-31

9 Analog Function Block ..................................................................................................9-1

9.1 AnalogFB.XML............................................................................................................... 9-1

9.2 Creating and Modifying the AnalogFB.XML File........................................................ 9-3

9.2.1 Analog Function Block SOAP Interface ................................................................... 9-3

9.2.1.1 AnalogFBList .................................................................................................... 9-4

9.2.1.2 AnalogFBGet ..................................................................................................... 9-5

9.2.1.3 AnalogFBSet.................................................................................................... 9-14

i.LON 100 Internet Server Programii mer’s Reference

9.2.1.4 AnalogFBDelete .............................................................................................. 9-15

10 Event Scheduler ............................................................................................................ 10-1

10.1 EventScheduler.XML................................................................................................... 10-2

10.2 Creating and Modifying the EventScheduler.XML File............................................ 10-4

10.2.1 Event Scheduler SOAP Interface ....................................................................... 10-4

10.2.1.1 EventSchedulerList ........................................................................................ 10-5

10.2.1.2 EventSchedulerGet......................................................................................... 10-6

10.2.1.3 EventSchedulerSet........................................................................................ 10-13

10.2.1.4 EventSchedulerDelete .................................................................................. 10-15

11 Event Calendar.............................................................................................................. 11-1

11.1 EventCalendar.XML .................................................................................................... 11-1

11.2 Creating and Modifying the EventCalendar.XML File ............................................. 11-3

11.2.1 Event Calendar SOAP Interface ........................................................................ 11-3

11.2.1.1 EventCalendarList.......................................................................................... 11-4

11.2.1.2 EventCalendarGet .......................................................................................... 11-5

11.2.1.3 EventCalendarSet......................................................................................... 11-12

11.2.1.4 EventCalendarDelete.................................................................................... 11-13

12 Type Translator............................................................................................................. 12-1

12.1 TypeTranslator.XML ................................................................................................... 12-1

12.2 Creating and Modifying the TypeTranslator.XML File ............................................ 12-3

12.2.1 Type Translator SOAP Interface........................................................................ 12-3

12.2.1.1 TypeTranslatorList......................................................................................... 12-4

12.2.1.2 TypeTranslatorGet.......................................................................................... 12-5

12.2.1.3 TypeTranslatorSet ........................................................................................ 12-12

12.2.1.4 TypeTranslatorDelete................................................................................... 12-13

13 Type Translator Rules .................................................................................................13-1

13.1 Type Translator Rule XML Files ................................................................................ 13-1

13.2 Creating and Modifying the Type Translator Rule XML Files................................. 13-3

13.2.1 Type Translator Rule SOAP Interface ............................................................... 13-3

13.2.1.1 TypeTranslatorRuleList ................................................................................. 13-4

13.2.1.2 TypeTranslatorRuleGet.................................................................................. 13-5

13.2.1.3 TypeTranslatorRuleSet ................................................................................ 13-12

13.2.1.4 TypeTranslatorRuleDelete........................................................................... 13-14

14 Using the SOAP Interface as a Web Service ..........................................................14-1

14.1 Referencing the WSDL File......................................................................................... 14-1

14.2 Programming Samples ................................................................................................ 14-3

14.2.1 Manually Creating the <Data> Parameter ....................................................... 14-3

14.2.2 Using an XMLDocument Object......................................................................... 14-4

14.2.2.1 Writing to a Data Point .................................................................................. 14-4

14.2.2.2 Reading Data Logs.......................................................................................... 14-6

14.2.3 Using DataSets.................................................................................................... 14-7

14.2.3.1 DataSets and XML Schemas.......................................................................... 14-8

14.2.3.2 Wrapping Elements ........................................................................................ 14-9

14.2.4 DataSets Programming Sample ....................................................................... 14-10

15 Manually Modifying an XML Configuration File.................................................. 15-1

15.1 Creating an XML File.................................................................................................. 15-1

15.2 Modifying an XML File................................................................................................ 15-1

15.3 Copying XML Files Between i.LON 100s................................................................... 15-2

i.LON 100 Internet Server Programmer’s Reference iii

1 Introduction to the i.LON 100 SOAP/XML Interface

The i.LON 100 contains a powerful microprocessor with a real-time, multi-tasking operating system that manages its various applications. These applications include alarming, scheduling, data logging and network variable type translation. Generally, you will configure these applications using the i.LON 100 Configuration Software, as described in the i.LON 100 Internet ServerUser’s Guide. The i.LON 100 Internet Server User’s Guide provides instructions to follow when configuring the i.LON 100 Configuration Software, as well as general information on the diffferent i.LON 100 applications, and guidelines to follow when using these applications.

You can also use the SOAP (Simple Object Access Protocol) / XML (Extensible Markup Language) interface provided with the i.LON 100 to configure and use these applications. XML is a universal format used to deliver data through structured documents over the Web. It allows developers to store data for any application in a standard, consistent way. SOAP is an interface that provides a mechanism for different applications and devices to communicate with each other over the Internet, regardless of platform, by sending SOAP messages to each other. SOAP relies on XML to define the format and contents of its messages.

The configuration of each i.LON 100 application is stored in an XML file. The i.LON 100 reads these files during its boot process, and sets the operating parameters of each application based on the configuration data contained in the XML file for that application.

The i.LON 100 includes a set of SOAP functions that you can use to create and manage the configuration of each application. Each time you invoke any of these functions, a SOAP message is sent to the i.LON 100. The content of the SOAP message is based on the input you supply to the function. The i.LON 100 reads the contents of the message, writes the contents of the message to the applicable XML file, and adjusts the operating parameters of its applications accordingly. All of this occurs while the i.LON 100 is operating.

It is important to note that the XML files described in this document store the configurations of the i.LON 100 applications. They do not store the data generated by these applications. The data generated by the i.LON 100 applications is stored in the flash memory of the i.LON

100.

However, this does not mean that application configuration is the only task you can perform with the i.LON 100 SOAP/XML interface. The SOAP/XML interface also includes functions you can use to access, read and analyze the data generated by the i.LON 100 applications. And so you can use the SOAP/XML interface not only to configure the various applications of the i.LON 100, but to monitor them as well.

1.1 About This Document

This document describes the XML files that store the configurations of the various i.LON 100 applications, and the SOAP functions you can use with each application. The SOAP interface provided with the i.LON 100 conforms to the SOAP 1.1 proposed Technical Recommendation:

http://www.w3.org/TR/2000/NOTE-SOAP-20000508

This document also describes how to configure the i.LON 100 applications by manually creating and modifying the XML configuration files. Once you have created the XML files, you can download them to the i.LON 100 via FTP. The i.LON 100 will read the downloaded files and adjust its operating parameters accordingly the next time it is rebooted.

i.LON 100 Internet Server Programmer’s Reference 1-1

You can create or modify the files using any XML editor or ASCII text editor. This document provides examples you can use when creating the XML configuration files for your i.LON 100, and instructions to follow when downloading these files to the i.LON 100. The XML files used by the i.LON 100 applications conform to the XML 1.0 Technical Recommendation:

http://www.w3.org/TR/2000/REC-xml-20001006

Echelon strongly recommends that you use the SOAP interface to configure the applications of your i.LON 100. The i.LON 100 performs error-checking on all data

written in a SOAP message, so that invalid data will not be written to any of the XML files. The i.LON 100 will not perform error-checking on any XML files downloaded to it via FTP, and so manually editing the XML files may cause errors during the boot process. Additionally, you can send SOAP messages to the i.LON 100 while it is operating, and the

i.LON 100 will update the XML files affected by the SOAP messages without requiring a

reboot.

You may find the information in this document that pertains to manually creating and managing XML files useful if you are using several i.LON 100s, and would like to use the same configuration on each one. In that case, you could configure one of the i.LON 100s, copy its XML files, and download them to the appropriate directories of the other i.LON 100s to obtain the same configuration in all of them. For more information on how to download XML configuration files, see Copying XML Files Between i.LON 100s on page 15-2.

1.2 Programming Samples

This document includes programming samples written in Microsoft Visual Basic .NET ® to illustrate concepts described in this manual. To make these samples more easily understood, they have been simplified. Error checking has been removed, and in some cases, the examples are only fragments that may not compile without errors or warnings.

1.3 Getting Started

You should review Chapter 2, SOAP Messages and the i.LON 100 WSDL File , before proceeding to the rest of this document and learning about the functions and applications of the SOAP/XML interface. Chapter 2 describes the WSDL file which defines the i.LON 100 SOAP/XML interface, and contains vital information you will need to know before referencing the WSDL file and using the various functions of the SOAP/XML interface. The final section of Chapter 2, Writing SOAP Applications, sets a roadmap you can follow when reading through the rest of the document.

If you are upgrading to version 1.1 of the SOAP/XML interface, it is also recommended that you review the next section, i.LON 100 Version 1.1 SOAP/XML Interface Upgrades, before proceeding. This section outlines the changes that have been made to the SOAP/XML interface for version 1.1.

1.4 i.LON 100 Version 1.1 SOAP/XML Interface Upgrades

This section provides an overview of the changes made to the SOAP/XML interface for version 1.1, and includes the following sections:

• Modified SOAP Applications and Functions

• Changes to SOAP Message Formats

You may find these changes advantageous when using version 1.1 of the SOAP/XML interface. You should also note that version 1.1 provides complete compatibility with version

i.LON 100 Internet Server Program1-2 mer’s Reference

1.0 of the SOAP/XML interface. An i.LON 100 using version 1.1 software will accept and respond to SOAP messages sent by applications written with version 1.0 of the SOAP/XML interface just as an i.LON 100 using version 1.0 software would.

1.4.1 Modified SOAP Applications and Functions

Table 1 lists the functions and properties that have been modified for version 1.1 of the SOAP/XML interface. Each function includes a brief explanation of how the function or property was modified for version 1.1. Detailed explanations of these modifications are included later in the document.

Table 1 i.LON 100 Version 1.1 SOAP/XML Interface Modifications

Function Description of Change For More

Information, See…

AlarmNotifierRead

The AlarmNotifierRead function now returns two additional properties in its output: <UCPTlastEvent> and <UCPTtotalCount>.

The <UCPTlastEvent> property indicates the last time an entry in the alarm log read by the function was modified or deleted. The <UCPTtotalCount> property indicates the total number of entries in the alarm log read by the function.

In addition, the AlarmNotifierRead function now allows the user to read from the end of the alarm log backwards, if the <UCPTstop> property is specified and the <UCPTstart> property is left empty in the input supplied to the function.

Further, when reading the Alarm History Log, the <UCPTstart> and <UCPTstop> input parameters now indicate a filter for log entry time. When reading the Alarm Summary Log, the <UCPTstart> and <UCPTstop> input parameters still indicate a filter for alarm time, as was the case in Version 1.0 of the SOAP/XML Interface. This change will affect the ordering of log entries returned when reading the Alarm History Log, because they will not be sorted by alarm time, as in version 1.0. Rather, they will appear in the order that each event was entered into the log.

AlarmNotifierRead on page 8-20

i.LON 100 Internet Server Programmer’s Reference 1-3

Function Description of Change For More

Information, See…

AlarmGeneratorGet

DataloggerGet

The i.LON 100 has been modified to handle the properties defining the hysteresis levels and offset limits used by each Alarm Generator differently for certain data types. This only applies if you use the AlarmGeneratorGet function to return the configuration of an Alarm Generator with input data points that use the following format descriptions:

SNVT_temp_f#US SNVT_temp_p#US SNVT_temp#US

In this case, the values of the hysteresis level and offset limit properties returned by the function will be displayed using the SNVT_temp_f#US_diff format description. This rule applies to all formats that use the #US specifier.

The i.LON 100 has been modified to handle the <UCPTlogMinDeltaValue> property, which defines the minuimum change in value that must occur for the data point update to be recorded by a Data Logger, differently for some data types. This only applies if you use the DataLoggerGet function to return the configuration of Data Logger with input data points that use the following format descriptions:

AlarmGeneratorGet on page 7-5.

DataLoggerGet on page 6-6

DataLoggerRead

SNVT_temp_f#US SNVT_temp_p#US SNVT_temp#US

In this case, the <UCPTlogMinDeltaValue> property returned by the function will be displayed using the SNVT_temp_f#US_diff format type. This rule applies to all formats that use the #US specifier.

The DataLoggerRead function now two additional properties in its output: <UCPTlastEvent> and <UCPTtotalCount>.

The <UCPTtotalCount> property indicates when the last time an entry in the data log read by the function was modified or deleted. The <UCPTtotalCount> property indicates the total number of entries in the data log read by the function.

In addition, the DataLoggerRead function now allows the user to read from the end of the data log backwards, if the the <UCPTstop> property is specified and the <UCPTstart> property is left empty in the input supplied to the function.

DataLoggerRead on page 6-11

1-4

i.LON 100 Internet Server Programmer’s Reference

Function Description of Change For More

Information, See…

DataServerRead

In version 1.0 of the i.LON 100 SOAP/XML interface, you could use the DataServerRead function to read the value of any data point, or group of data points. However, each data point had to be specified individually, by its name or index number. In version 1.1, you can specify a time stamp range in the input you supply to the DataServerRead function so that the i i.LON 100 only responds with data points whose last update occurred within the range. This allows your application to optimize throughput by only requesting data points whose value has changed since the last poll. The DataServerRead method also now accepts parameters to restrict the bus type (e.g. NVL or NVC) and total number of data points returned in the response message.

The <UCPTlifeTime> property defines how old the value of a data point can be before the Data Server retrieves a new data value from the driver when an application requests its value. If the property is set to 0, the values of the data points will be copied from the i.LON 100 Data Server when an application requests them, and no update will be requested from the applicable driver. If this parameter is set to a positive value, the i.LON 100 Data Server will poll the driver for the current value of a data point each time an application requests it, and the time interval defined by the property has expired. The interval resets each time the value of a data point is retrieved.

DataServerRead on page 5-19

DataServerRead

page 5-19

DataServerWrite

i.LON 100 Internet Server Programmer’s Reference 1-5

In version 1.0, you could set the <UCPTlifeTime> property by manually modifying it in the DP_NVL.XML or DP_NVE.XML configuration files. As of version 1.1, you can also temporarily override this value each time you call the DataServerRead function.

You can use the DataServerWrite function to update the value of one or more data points. The DataServerWrite function now returns a fault response message if the i.LON 100 encounters errors updating any of the data points specified in the input to the function. The response message contains an element for each data point it was unable to update that describes why the data point could not be updated.

DataServerWrite on page 5-24

1.4.2 Changes to SOAP Message Formats

The SOAP body that must be included in every message sent to the i.LON 100, and in every output message returned by the i.LON 100, has been updated in version 1.1. The namespace URI has been modified to reflect the new version number of the i.LON 100.

In addition, the SOAP header attached to response messages sent by the i.LON 100 will include the time the message was sent, the IP address of the i.LON 100 that sent the message, and the port number used to send the transmission. These changes are described in Chapter 2 of this document.

i.LON 100 Internet Server Program1-6 mer’s Reference

2 SOAP Messages and the i.LON 100 WSDL File

This chapter contains general information about the SOAP/XML interface you will need to know before using the SOAP functions described in this manual. It includes the following major topics:

• i.LON 100 WSDL File. An overview of the i.LON 100 WSDL file, which defines the SOAP/XML interface. When writing applications to use the SOAP interface, some tools can import this file and automatically build a class structure for sending and receiving each message.

• Security. An overview of the security features provided by the i.LON 100 for SOAP applications.

• Formats of SOAP Messages. As described in Chapter 1, a SOAP message is sent to the

i.LON 100 each time you invoke any of the functions described in this document. This

section describes the formats that must be used for all SOAP messages that are sent to and from the i.LON 100.

• Writing SOAP Applications. SOAP applications for the i.LON 100 can be divided into two general groups: those that are written to configure the various applications of the

i.LON 100, and those that are written to perform monitor and control tasks on the

network that the i.LON 100 is attached to. This section sets a road map for you to follow as you learn how to write each kind of application.

2.1 i.LON 100 WSDL File

Each i.LON 100 includes a WSDL (Web Service Description Language) file. This file defines the i.LON 100 SOAP/XML interface, and contains all the information an application will require to use the SOAP/XML interface. When writing applications to use the SOAP interface, some tools can import the WSDL file and automatically build a class structure for sending and receiving each message. The WSDL file is compatible with numerous programming development environments, such as Microsoft Visual Studio .NET ®.

See Chapter 14,

Using the SOAP Interface as a Web Service, for more detailed information the WSDL file. Chapter 14 contains step-by-step instructions you can follow when you reference the version

1.1 WSDL file with a Microsoft Visual Basic .NET project.

2.2 Security

You can add a basic level of security to the i.LON 100 SOAP/XML interface with the i.LON 100 Web Server Security and Parameters utility. Use this utility to add password protection to all web content served by the i.LON 100. Basic Access Authentication is the security mechanism used by the i.LON 100 web server for HTTP transactions. Basic Access Authentication is described by the IETF in RFC 2617:

http://www.ietf.org/rfc/rfc2617.txt

If you want all SOAP messages sent to your i.LON 100 to be authenticated, use the i.LON 100 Web Server Security and Parameters utility to password protect the i.LON 100 WSDL file at this path in the Web server: /WSDL/iLON100.WSDL.

A user name and password will then be required each time a SOAP message is sent to the

i.LON 100. Since SOAP uses HTTP as a transport, you can use the user name and password

pair for an entire HTTP session. As a result, you can use a single username and password to

i.LON 100 Internet Server Programmer’s Reference 2-1

authenticate access to Web pages that send or receive multiple SOAP messages. If a SOAP message is sent to the i.LON 100 that does not contain the correct user name and password, it will be ignored. For instructions on using the i.LON Web Server Security and Parameters utility, see Chapter 13 of the i.LON 100 Internet Server User‘s Guide.

To protect FTP access to the XML configuration files, the i.LON 100 requires a user name and password for every FTP session. This username and password default to “ilon”, and can be re-defined with the i.LON 100 Security Web Page. The i.LON 100 Internet Server User’s Guide describes how to use this page.

2.3 Formats of SOAP Messages

As described in Chapter 1, a SOAP message is sent to the i.LON 100 each time you invoke a SOAP function. The content of the SOAP message, and the effect it has on the i.LON 100, is based on the input you supply to the function. The i.LON 100 reads the contents of the message, and adjusts its operating parameters of its applications accordingly. It also returns a response message describing the status or configuration of the modified application.

This section describes the basic format of the SOAP messages that are sent to the i.LON 100 when you invoke any of the functions described in this manual. It also describes the formats of the response SOAP messages that are returned by these functions.

NOTE: All SOAP messages sent to and from the i.LON 100 must adhere to the UTF-8 encoding standard. This is indicated by the <?xml version="1.0" encoding="utf-8" ?> tag included in each SOAP messages, as shown in the following sections. However, this restriction is not enforced by the i.LON 100 software. As a result, the i.LON 100 will accept SOAP messages that do not adhere to the UTF-8 encoding standard without throwing an error, which may result in invalid configuration data being written to your i.LON 100. To avoid this, you should program your application to ensure that all SOAP messages adhere to the UTF-8 encoding standard. For more information on the UTF-8 encoding standard, see

http://www.ietf.org/rfc/rfc3629.txt.

2.3.1 Input Messages

The following represents the basic format of the SOAP messages that are sent to the i.LON 100 when you invoke any of the functions described in this manual. The sections following this sample describe each part of the SOAP message.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <echelon:FunctionName xmlns:echelon="http://wsdl.echelon.com/web_services_ns/ilon100/v1.1/message/"> <Data> Data </Data>

</echelon:FunctionName>

</SOAP-ENV:Body> </SOAP-ENV:Envelope>

2.3.1.1 SOAP Envelope

The SOAP envelope is the highest level of a SOAP message. The SOAP envelope for any message sent to the i.LON 100 must conform to the W3C SOAP 1.1 proposed Technical Recommendation:

i.LON 100 Internet Server Program2-2 mer’s Reference

http://www.w3.org/TR/2000/NOTE-SOAP-20000508/

The SOAP envelope portion of the sample input message shown above includes the following:

<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> ...

</SOAP-ENV:Envelope>

You will notice that the fourth line of this example includes the symbol “ the portion of the message known as the SOAP body would be. The SOAP body portion of the

message is described in the next section.

...” This is where

2.3.1.2 SOAP Body

The SOAP body contains general information about the SOAP message, and contains the data that is passed to the function as input. The SOAP body conforms to the W3C SOAP 1.1 proposed Technical Recommendation mentioned above.

The SOAP header portion of the sample input message shown above includes the following:

<SOAP-ENV:Body> <echelon:FunctionName

xmlns:echelon="http://wsdl.echelon.com/web_services_ns/ilon100/v1.1/message/">

</echelon:FunctionName>

</SOAP-ENV:Body>

The name of the function that was invoked is passed as part of the SOAP body, and is prefixed by the string “Echelon.” In order to use the features included in version 1.1,

the version1.1 namespace URI must be included as an attribute of the function name element. The i.LON 100 namespace URI for version 1.1 of the SOAP interface is:

http://wsdl.echelon.com/web_services_ns/ilon100/v1.1/

By passing this Namespace URI in the input messages, the tool transmits version and platform compatibility information to the target server. In this way, a version 1.1 i.LON 100 could accept a version 1.0 SOAP message, and recognize from the namespace that it is a version 1.0 SOAP message. It would then process the message as though it were a version 1.0

i.LON 100. As a result, all applications written for version 1.0 of the SOAP/XML

interface are compatible with version 1.1 of the SOAP/XML interface. The i.LON 100

will return the Namespace URI in all of the response messages it sends, so that a tool can use the Namespace identifier to check the version and platform of the SOAP interface.

2.3.1.2.1 <Data> Parameter

The <Data> parameter in the SOAP body is an essential part of the body of the SOAP message sent to the i.LON 100 when you call the functions described in this manual. The above example shows the string “Data” included in the <Data> parameter. This represents

the input that you must supply when you invoke any of the functions described in this manual.

The majority of the functions of the SOAP/XML interface require a string of XML as input. When the function is called, the SOAP message is generated, the XML is inserted in the <Data> parameter, and the message is sent. The description of each SOAP function in this

i.LON 100 Internet Server Programmer’s Reference 2-3

document includes a sample XML string you could supply as the <Data> parameter, and a description of how to build the XML string.

However, there are a few exceptions to this rule. The DataPointRead, DataPointWrite,

and DataPointResetPriority functions do not include a <Data> parameter as part of their input messgaes. They take a series of input parameters, each of which contains a

single value, as input. These input parameters are inserted in place of the <Data> parameter that is included in the SOAP body of all the other SOAP functions. This is described in more detail later in the document in Chapter 3, where the DataPoint functions are described.

2.3.2 Response Message

The following represents the basic format of the SOAP message returned by the i.LON 100 when you call any of the functions described in this document.

<?xml version="1.0" encoding="UTF-8" standalone="no"?> <SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header> <p:messageProperties xmlns:p="http://wsdl.echelon.com/web_services_ns/ilon100/v1.1/type"> <UCPTtimeStamp>2000-04-18T10:08:47.200-07:00</UCPTtimeStamp> <UCPTuniqueId>030000073782</UCPTuniqueId> <UCPTipAddress>172.25.137.100</UCPTipAddress> <UCPTport>80</UCPTport> </p:messageProperties> </SOAP-ENV:Header> <SOAP-ENV:Body> <echelon:FunctionNameResponse xmlns:echelon="http://wsdl.echelon.com/web_services_ns/ilon100/v1.1/message/"> <Result>Result</Result> </echelon:FunctionNameResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

There are two differences between the input messages sent to the i.LON 100, and those returned by the i.LON 100. The first is the inclusion of a SOAP header between the SOAP envelope and SOAP body. The second is the inclusion of the <Result> parameter contained within the SOAP body.

2.3.2.1 SOAP Header

The SOAP/XML interface has been modified in version 1.1 to include a SOAP header in all response messages. The SOAP header section of each response message is between the SOAP envelope and the SOAP body, and is shown below:

<SOAP-ENV:Header> <p:messageProperties xmlns:p="http://wsdl.echelon.com/web_services_ns/ilon100/v1.1/type"> <UCPTtimeStamp>2000-04-18T10:08:47.200-07:00</UCPTtimeStamp> <UCPTuniqueId>030000073782</UCPTuniqueId> <UCPTipAddress>172.25.137.100</UCPTipAddress> <UCPTport>80</UCPTport> </p:messageProperties> </SOAP-ENV:Header>

The SOAP Header contains general information about the message, and can be used to identify the i.LON 100 that sent it. This section is also tightly controlled by the W3C

i.LON 100 Internet Server Program2-4 mer’s Reference

standards mentioned in the previous section. Every element in a SOAP Header, and all immediate child elements must be namespace qualified. Therefore, each user defined element contains a namespace prefix and a path to the unique Echelon Namespace.

The SOAP Header consists of a complex type with four fields describing different properties of the message:

• <UCPTtimeStamp> This field contains a time stamp indicating when the message was sent.

• <UCPTuniqueId> This field contains the Neuron ID of the i.LON 100, which is the third Neuron ID in the i.LON 100s block of addresses.

• <UCPTipAddress> This field contains the IP address of the i.LON 100 that sent the SOAP message.

• <UCPTport> This field contains the HTTP port specifier for the i.LON 100 web server.

2.3.2.2 <Result> Parameter

Another difference between response messages sent by the i.LON 100, and input messages sent to the i.LON 100, is the <Result> element contained within the SOAP body. The above example shows the string “Result” included in the <Result> parameter. This represents the

information that will be returned you invoke any of the functions described in this manual.

The information that will be returned varies, depending on the function you are using. The description of each function included in this document includes a sample <Result> parameter that could be returned by the function, and information to help you interpret the contents of the <Result> parameter.

2.3.3 SOAP Error Responses

The following represents the basic format of the SOAP message returned by the i.LON 100 when the input you supply to the function causes an error.

<?xml version="1.0" encoding="UTF-8" standalone="no" ?> <SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <SOAP-ENV:Fault> <SOAP-ENV:faultcode>ErrorCode</SOAP-ENV:faultcode> <SOAP-ENV:faultstring>ErrorMessage</SOAP-ENV:faultstring> </SOAP-ENV:Fault> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

You will notice that the SOAP envelope of an error response contains an attribute called

<SOAP-ENV:faultcode>. This contains the error code returned by the function. The next

attribute is the <SOAP-ENV:faultstring> attribute. This represents the description of the error code returned by the function. The rest of the SOAP envelope and body is the same as those inlcuded in the input and response SOAP messages sent to and from the i.LON 100 (excluding the <Data> and <Result> parameters).

Table 2 lists the error codes and messages that the i.LON 100 SOAP interface may return.

Error Code Error Message

Table 2 SOAP Error Codes

i.LON 100 Internet Server Programmer’s Reference 2-5

Error Code Error Message

0 No Error

1 Unknown function call.

2 Parameter error. For example, the input you supplied to the function does not

contain valid data, or no data was supplied to the function.

3 XML/Parser Error.

4 Tag missing.

5 Index missing

6 Index not found

7 Index invalid

The index number you supplied to the function is greater than the maximum or less than the minimum allowed by the application. The allowable range of index numbers in the i.LON 100 is –32,768-32,767.

8 Can’t create. This error may occur when you attempt to create a data point.

9 Can’t delete. This error may occur when you attempt to delete a data point.

10 Can’t set. This error may occur when attempting to modify the configuration of an

existing item in the i.LON 100. For example, when attempting to write to the configuration of a data point.

11 Format Error

12 Command failed

13 The data point name referenced in the call to the function does not use the supplied

index number.

14 Data point name not found in the i.LON 100 Data Server.

15 No Data

16 Field name not found. This will occur when attempting to read, write or set a data

point that is structure, and you reference a structure field that does not exist.

2.4 Writing SOAP Applications

The majority of the SOAP functions and XML files described in this document will be useful to those who plan to use the SOAP/XML interface to configure the various applications of the

i.LON 100. To begin learning about the SOAP functions and XML files you can use to do so,

see Chapter 4, i.LON 100 Applications and the SOAP/XML Interface.

However, the SOAP/XML interface for the i.LON 100 also includes functions which allow you to write applications to monitor and control the data points you have created for your control network with L may be useful to anyone using the i.LON 100, including those who will only be using L

ONMAKER and the i.LON 100 Configuration Software to configure the i.LON 100’s

applications. For more information on these functions, see Chapter 3, Monitoring and

Controlling Data Points with the SOAP/XML Interface.

ONMAKER and the i.LON 100 Configuration Software. Applications like these

2-6

i.LON 100 Internet Server Programmer’s Reference

3 Monitoring and Controlling Data Points with the

SOAP/XML Interface

Any i.LON 100 user can make use of the SOAP/XML interface, even those who do not plan on using it to configure the applications of their i.LON 100. The SOAP interface includes functions that read and write the values of the data points defined on the i.LON 100. These functions do not affect the configuration of the i.LON 100 applications. You can use them to create applications to monitor and control data in the control network attached to your

i.LON 100.

This chapter provides an overview of data points, and the functions you can use to read and write their values. It also describes the syntax of each of these functions, and a programming sample written in Microsoft Visual Basic .NET that may assist you when using these functions.

NOTE: You can use the functions described in this chapter to read or write to the value of a single data point at a time. This may create unnecessary network traffic if you use it to read or write to a large number of data points over a short period of time. The Data Server SOAP interface includes functions you can use to read or write to multiple data points at a time. These functions are described in Chapter 5, Data Server. However, you should review Chapter 4, i.LON 100 Applications and the SOAP/XML Interface, before attempting to use any of the functions described in Chapter 5.

3.1 Overview of Data Points

The i.LON 100 uses the concept of a data point to map logical names to i.LON 100 system variables, network variables defined on the i.LON 100 LonTalk interface, and explicitly addressed network variables. Data points provide the i.LON 100 applications and Web server a generic, open way to handle any piece of information from any type of network, such as the current value of a network variable in an LNS managed network, or a network variable on a self-installed node in a closed LONWORKS system.

This document describes how to use two kinds of data points:

• NVL data points for network variables that are local to the i.LON 100

• NVC data points for i.LON 100 system variables that maintain constant values

The i.LON 100 Data Server handles all the details of each data point that the various applications require, such as how often the value of a data point should be polled, its default value, its heartbeat, its current status, and its value.

At the Data Server layer, all data points have the same set of properties, regardless of which network or device they are local to. This made possible by the drivers that exist for each separate data point type, which handle all communication between the i.LON 100 Data Server and the network each data point is local to. Each driver on the i.LON 100 must be configured using a standard network management tool for that particular point type.

For example, you could use an LNS-based network management tool to configure the NVL points on the i.LON 100. The abstraction layer between the drivers and the Data Server provides a mechanism for all i.LON 100 applications to use data points of all types and from all devices in the same way.

One of the most important properties stored in the Data Server for each data point is the <UCPTvalue> property. The <UCPTvalue> property contains the current value of the data

i.LON 100 Internet Server Programmer’s Reference 3-1

point. This property is updated by the Data Server in real time, and can be read or written to with the functions described in this chapter.

3.2 About This Chapter

This chapter describes the syntax of each of the functions you can use to read and write to the values of the data points in your network. It also includes code samples written in Microsoft Visual Basic .NET that may be useful when designing applications that use these functions.

NOTE: You can use the Data Point functions to read and write to the values of your data points. You must create data points and add them to the Data Server before using these functions. You can create NVL data points with LONMAKER. You can create NVC data points with the i.LON 100 Configuration Software, or with the SOAP interface.

For more information on the using the SOAP interface to create data points, see Chapter 5,

Data Server. You should review Chapter 4, i.LON 100 Applications and the SOAP/XML Interface, before using the SOAP interface to create data points. For more information on the

i.LON 100 Configuration Software, see the i.LON 100 Internet Server User’s Guide.

i.LON 100 Internet Server Program3-2 mer’s Reference

3.3 DataPointWrite

You can use the DataPointWrite function to write to the value of any data point in your network. You must reference the data point to be modified by the name (UCPTpointName) assigned to it in i.LON 100 Data Server in the input you supply to the function, as in the example below. The <UCPTpointName> of a data point is defined when it is created and added to the i.LON 100 Data Server. You can create data points with the i.LON 100 Configuration Software or with the DataServerSet function.

Chapter 5, Data Server, describes the DataServerSet function. However, you should review Chapter 4, i.LON 100 Applications and the SOAP/XML Interface, before attempting to use the function. For instructions on creating data points with the i.LON 100 Configuration Software, see the i.LON 100 Internet Server User‘s Guide.

If the specified data point is a structure, you can specify the field (UCPTfieldName) whose value should be written to by the function. Table 3 describes the rest of the parameters you will need to supply as input to this function.

You can only write to the value of one data point at a time with this function. However, you can use the DataServerWrite function to write to the values of multiple data points at once. Chapter 5, Data Server, describes the DataServerWrite function. However, you should review Chapter 4, i.LON 100 Applications and the SOAP/XML Interface, before attempting to use the function.

The sample below shows how the input parameters are filled into the SOAP message sent to the i.LON 100 when you call DataPointWrite. For programming samples writen in Microsoft Visual Basic .NET that call this function (and will fill in the SOAP message with the input data shown below), see Using the DataPoint Functions With Visual Basic .NET on page 3-11.

Input Parameters

Return Parameter

<UCPTpointName>NVL_nvo01Switch</UCPTpointName> <UCPTfieldName> <UCPTvalueDef>100.0</UCPTvalueDef> <UCPTpriority>25</UCPTpriority> <UCPTpropagate>1</UCPTpropagate>

<Result> <UCPTpointName>NVL_nvo01Switch</UCPTpointName> <UCPTfieldName>value</UCPTfieldName> </Result>

value</UCPTfieldName>

Table 3 describes the properties that you will need to supply as input when you call the DataPointWrite function. The function returns the name of the data point written to.

Table 3 DataPointWrite Input Properties

Property Description

i.LON 100 Internet Server Programmer’s Reference 3-3

Property Description

Enter the <UCPTpointName> of the data point to be written to. The name must begin with the following prefixes:

• NVL_ for an NVL data point

• NVC_ for an NVC data point

Note: The names assigned to NVL data points follow the naming convention NVL_[NAME], where [NAME] represents that progammatic name assigned to the NV when it was created with L

ONMAKER.

For example, if the progammatic name of the NV in L

ONMAKER

is nvo01Switch_001, the <UCPTpointName> would be NVL_nvo01Switch. You can determine the progammatic name of an NV in LONMAKER by right-clicking it and selecting

Properties.

Field name. This can be left empty if the data point is not a structure, or if an entire structure is to be written to.

NOTE: If this property is defined, the <UCPTvalueDef> property can only contain the actual value to be assigned to the data point, and not a pre-defined value definition.

Enter either the value definition (if the <UCPTfieldName> property is not filled in) or the actual value to be assigned to the data point. The format of the value entered must match the format type that the data point to be written to requires.

The value definition is a string representing a preset value. This value must match the format type the data point requires. You can create value definitions for a data point using the

i.LON 100 Configuration Software, or the DataServerSet SOAP

function.

Enter the priority level to be assigned to the data point. The priority level must be specified as an integer between 0 (highest priority) and 255 (lowest priority). In order for your application to update the value of a data point successfully, the priority selected must be of equal or higher priority than that used by the last application to write to the data point. If no priority level is defined, the default value of 255 will be used.

For a more detailed description of priority levels, see the next Data Point Values and Priority Levels on page 3-5.

3-4

i.LON 100 Internet Server Programmer’s Reference

Property Description

3.3.1 Data Point Values and Priority Levels

As described in the previous section, the DataPointWrite function requires you to specify a priority level when writing to a data point. In order to successfully update the value of the data point, you must specify a higher priority level than the one used by the last application to write to the data point.

For example, consider a scenario where a SOAP application uses the DataPointWrite function to write to the value of a data point called NVL_nvoValue. Assume that the last application to write to the value of NVL_nvoValue used priority level 75 when it updated the data point. In that case, the current application must use a priority value between 0 and 75 to successfully write a new value to the data point.

0 or 1. If you assign the default value 1 to the <UCPTpropagate> property, the change you make to the data point value will be propagated over the network. If you assign value 0 to this property, the change will be made in the i.LON 100 Data Server, but not over the network.

This may be useful if you are writing to different fields of a structure with separate calls to DataPointWrite, and do not want to update the structure over the network until all of its fields have been written to.

Data point priority levels allow you to give some applications precedence over others when more than one application might attempt to update the same data point. Table 4 depicts a series of events where various applications write to the value of a single data point. For each event, the priority level used is listed, as well as a description of whether or not the update was successful, and why. This should help you understand how you can use data point priority levels to determine which applications will be given precedence when updating the value of a data point.

Table 4 Data Point Priority Levels and Values

Event Priority Level

Assigned

Power-Up 255 The value of the data point is updated

successfully.

Event Scheduler Updates Data Point

Custom Application Invokes DataPointWrite

Event Scheduler Updates Data Point

240 The value of the data point is updated

successfully, as the priority used by the Event Scheduler is greater than that assigned to the data point during power-up.

240 The value of the data point is not updated

The value of the data point is updated successfully, as the priority used in the call to DataPointWrite is greater than that assigned to the data point by the Event Scheduler.

successfully, as the priority used by the Event Scheduler is less than that used by the last application to update the data point.

Result of Operation

i.LON 100 Internet Server Programmer’s Reference 3-5

Event Priority Level

Custom Application Invokes DataPointResetPriority

Result of Operation

Assigned

255 The custom application invokes the

DataPointResetPriority function to reset the priority level assigned to the data point. This does not result in a change in the data point’s value, but the priority level assigned to the data point is reset to 255, the lowest priority. At this point, all applications will be able to write to the data point.

For more information on the DataPointResetPriority function, see DataPointResetPriority on page 3-10.

Event Scheduler Updates Data Point

240 The Event Scheduler successfully updates the

value of the data point, as the priority level used here (240) is greater than that assigned to the data point by the DataPointResetPriority function.

3-6

i.LON 100 Internet Server Programmer’s Reference

3.4 DataPointRead

You can use the DataPointRead function to retrieve the current value assigned to a data point, as well as the values of several properties associated with the data point. You can use this function with any data point in your network.

You must reference the data point whose you value you want to read by its name (UCPTpointName) in the input you supply to the function, as in the example below. If the data point is a structure, you can specify the field whose value is to be retrieved by filling in the optional <UCPTfieldName> property.

You can only read the value of one data point at a time with this function. However, you can use the DataServerRead function to read the values of multiple data points at once. Chapter 5, Data Server, describes the DataServerRead function. However, you should review Chapter 4, i.LON 100 Applications and the SOAP/XML Interface, before attempting to use the function.

The sample below shows how the input parameters are filled into the SOAP message sent to the i.LON 100 when you call DataPointRead. For programming samples writen in Microsoft Visual Basic .NET that call this function (and will fill in the SOAP message with the input parameters shown below), see Using the DataPoint Functions With Visual Basic .NET on page 3-11.

Input Parameters

Return Parameters

Table 5 describes the properties that the DataPointRead function returns in the <Result> parameter. Note that the <UCPTpointName> and <UCPTfieldName> properties are also supplied as input in the <Data> parameter.

Property Description

<UCPTpointName>NVL_nvo03Switch</UCPTpointName> <UCPTfieldName>state</UCPTfieldName>

<Result> <UCPTpointName>NVL_nvo03Switch</UCPTpointName> <UCPTfieldName>state</UCPTfieldName> <UCPTlocation>MainBuilding\First Floor\Meetingroom\Light<UCPTlocation> < pd

UCPTpointU ateTime>2001-07-24T01:47:22.000+03:00</UCPTpointUpdateTime>

<UCPTunit></UCPTunit> <UCPTpointStat AL_NO_CONDITION</UCPTpointStatus> us> <UCPTpriority>250</UCPTpriority> <UCPTformatDescription>SNVT_switch<UCPTformatDescription> <UCPTbaseType>BT_STRUCT</UCPTbaseType> </Result>

Table 5 DataPointRead Output Properties

i.LON 100 Internet Server Programmer’s Reference 3-7

Property Description

Enter the <UCPTpointName> of the data point to be written to. The name must begin with the following prefixes:

• NVL_ for an NVL data point

• NVC_ for an NVC data point

Note: The names assigned to NVL data points follow the naming convention NVL_[NAME], where [NAME] represents that progammatic name assigned to the NV when it was created with L

ONMAKER.

For example, if the progammatic name of the NV in LONMAKER is nvo01Switch_001, the <UCPTpointName> would be NVL_nvo01Switch. You can determine the progammatic name of an NV in L

ONMAKER by right-clicking it and

selecting Properties.

The name of the data point field whose value is to be read. This property should be left empty if the data point is not a structure. If defined, the <UCPTvalueDef> property will not be included in the <Result> parameter.

An alphanumeric string of up to 128 characters that describes the location of the data point. This user-defined property is established when the data point is created. You could use it to organize your data points by physical location or device.

A timestamp indicating the last time the value of the data point was updated. This timestamp is expressed in local time, with an appended time zone indicator that indicates the difference between local time and Coordinated Universal Time (UTC). UTC is the current term for what was commonly referred to as Greenwich Meridian Time (GMT). Zero (0) hours UTC is midnight in Greenwich England, which lies on the zero longitudinal meridian. Universal time is based on a 24 hour clock, therefore, an afternoon hour such as 4 pm UTC would be expressed as 16:00 UTC. The timestamp uses the following format:

3-8

[YYYY-MM-DD]T[HH:MM:SS.MSS]+/-[HH:MM]

The first segment of the timestamp [YYYY-MM-DD] represents the date. The second segment (T[HH:MM:SS.MSS]) of the timestamp represents the local time, expressed in hours, minutes, seconds and milliseconds. The third segment (+/[HH:MM]) represents the difference between the local time listed in the second segment and UTC. This segment begins with a + or a -. The + indicates that the local time is ahead of UTC, the - indicates the local time is behind UTC. Consider the following example:

2002-08-13T10:24:37.111+02:00

This timestamp indicates a local date and time of 10:24 AM and 37.111 seconds, on August 13, 2002. Because the third part of the segment reads +02:00, we know the local time here is 2 hours ahead of UTC. The value currently assigned to the data point.

i.LON 100 Internet Server Programmer’s Reference

Property Description

The value definition being used by the data point. If the data point is not using a value definition, or if you defined the <UCPTfieldName> property in the input you supplied to the function, this field will appear blank.

Value definitions are user-defined strings that represent preset values the data point can be updated to. For example, the value assigned to a value definition called ON for a SNVT_switch data point might be “100.0 1.” You can create value definitions for a data point with the DataServerSet function, or with the i.LON 100 Configuration Software.

Unit type of the data point. This property is configured based on the network variable type of the data point.

The current status of the data point. This property is updated in real time by the Data Server, and can be used when setting up Alarm Generators and Alarm Notifiers with the i.LON 100. You can create Alarm Generators and Alarm Notifiers with the i.LON 100 Configuration Software, or with the SOAP interface. For information on using the SOAP interface to create Alarm Generators and Alarm Notifiers, see Chapters 7 and 8 of this document.

The priority level currently assigned to the data point. You can set the priority level of a data point with the DataPointWrite or DataPointResetPriority functions. For more information on priority levels, see Data Point Values and Priority Levels on page 3-5.

The format description of the data point. This determines many factors about the data point, including the type of values it takes, and its base type. This could be any standard (SNVT) format type included in the i.LON 100 resource files, or any user-defined (UNVT) format type included in resource files uploaded to the i.LON

100. For more information on the i.LON 100 resource files, see i.LON 100 Resource Files on page 4-8.

i.LON 100 Internet Server Programmer’s Reference 3-9

The SNVT format types included in the i.LON 100 resource files are also listed and described in the SNVT Master List, which can be downloaded as a PDF by selecting the Documentation link on Echelon’s Support Web site:

http://www.echelon.com/support

This read-only property is assigned to the data point automatically based on the data point’s <UCPTformatDescription>. It defines the base type of the data point, as defined in the base_type_t enumeration in the BAS_Controller resource files for the i.LON 100.

For more information on the i.LON 100 resource files, see i.LON 100 Resource Files on page 4-8.

3.5 DataPointResetPriority

You can use the DataPointResetPriority function to reset the priority level of a data point to 255, the lowest priority level. This would allow any application to write to the value of the data point.

You must reference the data point to be affected by its <UCPTpointName> in the input you supply to the function, as in the example below. In addition, you must specify a priority level of equal or higher priority than that currently assigned to the data point in the input you supply to the function. Only then will the priority level assigned to the data point be reset.

For example, if the priority level currently assigned to a data point is 30, then priority level specified in the input must be between 0 and 30. For a more detailed description of data point priority levels, see Data Point Values and Priority Levels on page 3-5.

NOTE: You can only reset the priority of one data point at a time with this function. However, you can use the DataServerResetPriority function to read the values of multiple data points at once. Chapter 5, Data Server, describes the DataServerResetPriority function. However, you should review Chapter 4, i.LON 100 Applications and the SOAP/XML Interface, before attempting to use the function.

The sample below shows how the input parameters are filled into the SOAP message sent to the i.LON 100 when you call DataPointResetPriority. For programming samples written in Microsoft Visual Basic .NET that call this function, and will fill in the SOAP message with the input data shown below, see Using the DataPoint Functions With Visual Basic .NET on page 3-11.

Input Parameters

Return Parameters

<UCPTpointName>NVL_nvo01Switch</UCPTpointName> <UCPTpriority>25</UCPTpriority>

<Result>NVL_nvo01Switch<Result>

i.LON 100 Internet Server Program3-10 mer’s Reference

3.6 Using the DataPoint Functions With Visual Basic .NET

You can call the DataPoint functions from development environments such as Microsoft Visual Basic .NET by referencing the i.LON 100 WSDL file. Chapter 14, Using the SOAP Interface as a Web Service, describes how to reference the i.LON 100 WSDL file in Microsoft Visual Basic .NET.

This chapter describes the syntax you will use when you call each of these functions, and provides a code sample written in Visual Basic .NET that invokes each of them.

3.6.1 DataPointWrite

Syntax: return=ilonWebReference.DataPointWrite(UCPTpointName As String, UCPTfieldName As String, UCPTvalue As String, UCPTpropagate As Integer, UCPTpriority As Integer)

Element Description

return DataPointWriteReturnType variable

ilonWebReference Instance of the i.LON 100 WSDL file Web service.

Input Parameters For descriptions of the individual input parameters

that you must supply to the function, see DataPointWrite on page 3-3.

Returns: The function returns an object containing two properties: the name of the data point written to (UCPTpointName), and the name of the field written to (UCPTfieldName).

3.6.2 DataPointRead

Syntax: return=ilonWebReference.DataPointRead(UCPTpointName As String, UCPTfieldName As String)

Element Description

return DataPointReadReturnType variable

ilonWebReference Instance of the i.LON 100 WSDL file Web service.

Input Parameters For descriptions of the input parameters that you

must supply to the function, see DataPointRead on page 3-7.

Returns: The function returns an object containing each of the properties described in Table 5 on page 3-7. Each property can be retrieved from this object individually by referencing the property name listed in Table 5, as shown in the programming sample later in this section.

3.6.3 DataPointResetPriority

Syntax: return=ilonWebReference.DataPointResetPriority(UCPTpointName As String, UCPTpriority As Integer)

Element Description

return String variable

ilonWebReference Instance of the i.LON 100 WSDL file Web service.

i.LON 100 Internet Server Programmer’s Reference 3-11

Input Parameters For descriptions of the input parameters that you

must supply to the function, see DataPointResetPriority on page 3-10.

Returns: The function returns a string containing the name of the data point reset by the function.

3.6.4 Programming Samples

The following programming sample, written in Microsoft Visual Basic .NET, invokes all three of the DataPoint functions. It uses the DataPointWrite function to write to the value of a data point called NVL_nvo01Switch. It then uses DataPointResetPriority to reset the priority level assigned to the data point, so that other applications can write to its value later.

Once the data point has been updated, the DataPointRead function is called. Each property included in the object returned by the function is then extracted and displayed in a text box.

Private Sub Button1_Click(ByVal sender As System.Object, ByVal e _ As System.EventArgs) Handles Button1.Click

'Create an instance of the i.LON 100 Web service, and return 'objects for the three functions to be called. The WSDL file 'defines a return type for DataPointRead and DataPointWrite. The 'DataPointResetPriority returns a string containing the name of the 'data point reset by the function.

Dim ilon As New WebReference1.iLON100() Dim retRead As New WebReference1.DataPointReadReturnType() Dim retWrite As New WebReference1.DataPointWriteReturnType() Dim retPriority As String

'Create variables to store the input for each function. Dim S As String Dim pointName As String Dim fieldName As String Dim value As String Dim propagate As String Dim priority As String

'Specify the IP location of the i.LON 100 by replacing the default ' “localhost” with the IP address of the i.LON 100.

S = ilon.Url ilon.Url = S.Replace("localhost", "10.5.0.50")

'Define the data point to be written to, and the value to assign 'it. In this case, the field name is left blank, as the data point 'the program is writing to is not a structure.

pointName = " NVL_nvo01Switch " fieldName = "" value = "0.0 0" propagate = "1" priority = "50"

i.LON 100 Internet Server Program3-12 mer’s Reference

'Call DataPointWrite, and then call DataPointResetPriority. Note 'that the priority 'level used in the call to 'DataPointResetPriority is less than that used in the call to 'DataPointWrite. This resets the priority assigned to 'NVL_nvo01Switch to 255, and allows all other applications to write 'to the data point. The propagate value used is in each call is 1, 'so that the change is updated over the network.

retWrite = ilon.DataPointWrite(pointName, fieldName, value, _ priority, propagate) priority = "45" ilon.DataPointResetPriority(pointName, priority)

'Call DataPointRead and display the properties contained in the 'object returned by the function in text boxes. Note that the names 'used to extract each property from the return object match the 'property names used in the sample SOAP parameters earlier in this 'chapter.

retRead = ilon.DataPointRead(pointName, fieldName) TextBox1.Text = retRead.UCPTbaseType TextBox2.Text = retRead.UCPTfieldName TextBox3.Text = retRead.UCPTformatDescription TextBox4.Text = retRead.UCPTlocation TextBox5.Text = retRead.UCPTpointName TextBox6.Text = retRead.UCPTpointStatus TextBox7.Text = retRead.UCPTpointUpdateTime TextBox8.Text = retRead.UCPTpriority TextBox9.Text = retRead.UCPTunit TextBox10.Text = retRead.UCPTvalue TextBox11.Text = retRead.UCPTvalueDef End Sub

i.LON 100 Internet Server Programmer’s Reference 3-13

4 i.LON 100 Applications and the SOAP/XML Interface

This chapter provides an overview of the applications supported by the i.LON 100, and of how you can use the SOAP/XML interface to configure these applications and use the data they generate. This chapter includes the following major sections:

• Overview of i.LON 100 Applications. This section provides a description of each of the applications that the i.LON 100 supports.

• i.LON 100 XML Configuration Files. The configuration of each i.LON 100 application is stored in an XML file. This section lists those XML files, and indicates where they are stored on the i.LON 100.

• i.LON 100 SOAP Functions. Each i.LON 100 application includes a set of SOAP functions that can be used to configure that application. This section lists and describes the functions provided for each application, and references where each function is described in more detail in this document. It also provides information you will require when constructing the input to be supplied to each function.

• i.LON 100 Resource Files. The i.LON 100 resource files contain information you will need when using the SOAP functions. This section describes how to use the resource files.

• List, Get, Set and Delete Functions. You will notice when reviewing the i.LON 100 SOAP Functions section that each application has separate List, Get, Set and Delete functions. Together, these functions form a symmetric interface, and you may find this symmetry very useful when programming your SOAP applications. This section describes how you might do so.

• Performance Issues. This section lists performance issues you should consider when using the SOAP/XML interface.

• Getting Started. This section provides a roadmap to follow when configuring the i.LON 100 applications. The most important part of this roadmap is that you must configure the i.LON 100 Data Server before configuring any other applications.

4.1 Overview of i.LON 100 Applications

You need to build the i.LON 100 Data Server and create the data points you need to manage your control network before using the SOAP/XML interface to configure your applications. Chapters 5 of this document describes data points, and how to build the i.LON 100 Data Server. Once you have built the Data Server, you can use the SOAP/XML interface to configure the following i.LON 100 applications:

• Data Logging – You can configure the i.LON 100 to record updates to the data points on your network by creating Data Loggers. Each Data Logger will have its own log file, which will contain an entries for each of the updates to the data points it is monitoring. These logs can be downloaded and read using the Internet File Transfer Protocol (FTP), or retrieved using a SOAP function called DataLoggerRead. Table 6 provides a brief description of DataLoggerRead and the other functions you can use to create and manage your Data Loggers. These functions are described in Chapter 6 of this document.

• Alarming – You can configure the i.LON 100 to trigger alarms based on the values and statuses of the data points in your control network. The i.LON 100 can be configured to update any data point in the L logs, or send out emails notifying recipients of the alarms and the conditions that

i.LON 100 Internet Server Programmer’s Reference 4-1

ONWORKS network, log the conditions to one or more data

triggered them. Alarms can be configured to shut off automatically when certain conditions are met, or they can be configured to require manual clearance. You will create Alarm Generators and Alarm Notifiers to manage these alarming tasks. Table 6 provides a brief description of the functions you can use to do so. These functions are described in detail in Chapters 7 and 8 of this document.

• Analog Function Blocks – You can use the Analog Function Block application to perform statistical operations on the values of any of the data points in your network. Table 6 provides a brief description of the functions you can use to do so. These functions are described in detail in Chapter 9 of this document.

• Scheduling – The i.LON 100 can be used to create daily and weekly schedules, as well as exception schedules and override schedules. These schedules can drive the inputs to data points bound to any L Calendars to manage these tasks. Table 6 provides a brief description of the functions you can use to do so. These functions are described in detail in Chapters 10 and 11 of this document.

• Type Translation – You can use the Type Translator application to translate data from one network variable data type to another. You will need to create Type Translators, and optionally Type Translator Rules, to translate your data. Table 6 provides a brief description of the functions you can use to do so. These functions are described in detail in Chapters 12 and 13 of this document.

ONWORKS device. You can create Event Schedulers and Event

4.2 i.LON 100 XML Configuration Files

As described in Chapter 1, the configurations of each i.LON 100 application is stored in an XML file. The i.LON 100 contains the following configuration files:

/root/config/software/AlarmGenerator.XML /root/config/software/AlarmNotifier.XML /root/config/software/AnalogFB.XML /root/config/software/EventCalendar.XML /root/config/software/EventScheduler.XML /root/config/software/DataLogger.XML /root/config/software/TypeTranslator.XML /root/config/software/DataServer/DP_NVL.XML /root/config/software/DataServer/DP_NVC.XML

NOTE: The /root/config/software directory includes a sub-directory called TranslatorRules, which contains several XML files you can use when configuring your Type Translators. It also contains a file called RNI.XML, which contains configuration data used by the i.LON 100 remote network interface (RNI). There is no SOAP interface for the RNI application, and you should not manually edit the RNI.XML file. You can configure the RNI application using the i.LON 100 configuration web pages. For more information on this, see the i.LON 100 Internet Server User’s Guide.

Each application inludes a Set function. You can use the Set function to create and write to the applicable XML file. The i.LON 100 will modify the XML file, and the operating parameters of the associated application, each time it receives a Set message. The next section, i.LON 100 SOAP Functions, lists the other functions that can be used with each application.

i.LON 100 Internet Server Program4-2 mer’s Reference

As an alternative to using SOAP, you can modify the files manually using an ASCII-text or XML editor, and then download them to the i.LON 100 via FTP. Echelon does not recommend this, as you will need to reboot the i.LON 100 for it to read the downloaded files, and the i.LON 100 will not perform error-checking on the downloaded XML files.

Chapters 5-13 of this document describe the content of each of the i.LON 100 XML configuration files, the applications they support, and the SOAP functions you can use to manage them in detail. Review the rest of this chapter before proceeding to any of

Chapters 5-13, as it provides background information you will need when you use the SOAP/XML interface.

4.3 i.LON 100 SOAP Functions

Each of the XML files listed in the previous section will contain elements and properties that define the configuration of an i.LON 100 application, and the configuration of the items or instances that have been added to that application. For example, the AlarmGenerator.XML file defines the global configuration properties associated with the Alarm Generator application, as well as the configuration of each Alarm Generator that you have added to the

i.LON 100.

Table 6 provides an overview of the the functions you can use to write to these XML files, build the i.LON 100 Data Server, configure the applications of your i.LON 100, and read the data that your applications generate. It is highly critical that you review the rest of this chapter before using these functions. This chapter provides background information on the SOAP interface you will need when reading the rest of this document.

Table 6 i.LON 100 SOAP Functions

Function Names Description

DataServerList DataServerGet DataServerSet DataServerDelete DataServerRead DataServerWrite DataServerResetPriority

Use the DataServerList function to return the index number, name, and location of each data point that you have added to the i.LON 100 Data Server. You can use the DataServerGet function to return the configuration of any of these data points.

Use the DataServerSet function to add data points to the i.LON 100 Data Server, or to update the configuration of the data points that are already in the Data Server.

Use the DataServerRead and DataServerWrite functions to read and write to the current values of any of the data points in the network. Use the DataPointResetPriority function to reset the priority of any of these data points. Use the DataServerDelete function to delete any data point.

For more information on these functions, see Data Server on page 5-1.

i.LON 100 Internet Server Programmer’s Reference 4-3

Function Names Description

DataloggerList DataloggerGet DataloggerSet DataLoggerRead DataLoggerClear DataloggerDelete

AlarmGeneratorList AlarmGeneratorGet AlarmGeneratorSet AlarmGeneratorDelete

AlarmNotifierList AlarmNotifierGet AlarmNotifierSet AlarmNotifierDelete AlarmNotifierRead AlarmNotifierWrite AlarmNotifierClear

Use the DataLoggerList function to return the index number, last update time, description, and functional block name of each Data Logger that you have added to the i.LON 100. You can use the DataLoggerGet function to return the configuration of any of these Data Loggers.

Use the DataLoggerSet function to add new Data Loggers to the i.LON 100, or to overwrite the configuration of existing Data Loggers. Use the DataLoggerDelete function to remove Data Loggers from the i.LON 100.

Use the DataLoggerRead function to read data from the log files generated by your Data Loggers. Use the DataLoggerClear function to remove data from the log files.

For more information on these functions, see Data Loggers on page 6-1.

Use the AlarmGeneratorList function to return the index number, last update time, description, and functional block name of each Alarm Generator that you have added to the i.LON 100. You can use the AlarmGeneratorGet function to return the configuration of any of these Alarm Generators.

Use the AlarmGeneratorSet function to add new Alarm Generators to the i.LON 100, or to overwrite the configuration of existing Alarm Generators. Use the AlarmGeneratorDelete function to remove Alarm Generators from the i.LON

100.

For more information on these functions, see Alarm Generator on page 7-1.

Use the AlarmNotifierList function to return the index number, last update time, description, and functional block name of each Alarm Notifier that you have added to the i.LON 100. You can use the AlarmNotifierGet function to return the configuration of any of these Alarm Notifiers.

Use the AlarmNotifierSet function to add new Alarm Notifiers to the i.LON 100, or to overwrite the configuration of existing Alarm Notifiers. Use the AlarmNotifierDelete function to remove Alarm Notifiers from the i.LON 100.

AnalogFBList AnalogFBGet AnalogFBSet AnalogFBDelete

4-4

Use the AlarmNotifierRead function to read the log files generated by your Alarm Notifiers. Use the AlarmNotifierWrite function to comment on and acknowledge the entries in the log files. Use the Alarm NotifierClear function to remove entries from the log files.

For more information on these functions, see Alarm Notifier on page 8-1.

Use the AnalogFBList function to return the index number, last update time, description, and functional block name of each Analog Function Block that you have added to the i.LON 100. You can use the AnalogFBGet function to return the configuration of any of these Analog Function Blocks.

Use the AnalogFBSet function to add new Analog Function Blocks to the i.LON 100, or to overwrite the configuration of existing Analog Function Blocks. Use the AnalogFBDelete function to remove Analog Function Blocks from the i.LON

100.

For more information on these functions, see Analog Function Block on page 9-1

i.LON 100 Internet Server Programmer’s Reference

Function Names Description

EventSchedulerList EventSchedulerGet EventSchedulerSet EventSchedulerDelete

EventCalendarList EventCalendarGet EventCalendarSet EventCalendarDelete

TypeTranslatorList TypeTranslatorGet TypeTranslatorSet TypeTranslatorDelete

Use the EventSchedulerList function to return the index number, last update time, description, and functional block name of each Event Scheduler that you have added to the i.LON 100. You can use the EventSchedulerGet function to return the configuration of any of these Event Schedulers.

Use the EventSchedulerSet function to add new Event Schedulers to the i.LON 100, or to overwrite the configuration of existing Event Schedulers. Use the EventSchedulerDelete function to remove Event Schedulers from the i.LON 100.

For more information on these functions, see Event Scheduler on page 10-1.

Use the EventCalendarList function to return the index number, last update time, description, and functional block name of each Event Calendar that you have added to the i.LON 100. You can use the EventCalendarGet function to return the configuration of any of these Event Calendars.

Use the EventCalendarSet function to add new Event Calendars to the i.LON 100, or to overwrite the configuration of existing Event Calendars. Use the EventCalendarDelete function to remove Event Calendars from the i.LON 100.

For more information on these functions, see Event Calendar on page 11-1.

Use the TypeTranslatorList function to return the index number, last update time, description, and functional block name of each Type Translator that you have added to the i.LON 100. You can use the TypeTranslatorGet function to return the configuration of any of these Type Translators.

Use the TypeTranslatorSet function to add new Type Translators to the i.LON 100, or to overwrite the configuration of existing Type Translators. Use the TypeTranslatorDelete function to remove Type Translators from the i.LON 100.

TypeTranslatorRuleList TypeTranslatorRuleGet TypeTranslatorRuleSet TypeTranslatorRuleDelete

4.3.1 <Data> Parameter

As described in Chapters 1 and 2 of this document, a SOAP message is sent to the i.LON 100 each time you invoke any of the functions listed in Table 6. The i.LON 100 reads the message, and adjusts its configuration or operating parameters based on its contents. An essential part of each SOAP message sent to the i.LON 100 is the <Data> parameter. The <Data> parameter contains the input that you must supply to the SOAP functions when you invoke them.

For more information on these functions, see Type Translator on page 12-1.

Use the TypeTranslatorRuleList function to return the index number, last update time, description, and functional block name of each Type Translator Rule that you have added to the i.LON 100. You can use the TypeTranslatorRuleGet function to return the configuration of any of these Type Translator Rules.

Use the TypeTranslatorRuleSet function to add new Type Translator Rules to the i.LON 100, or to overwrite the configuration of existing Type Translator Rules. Use the TypeTranslatorRuleDelete function to remove Type Translator Rules from the i.LON 100.

For more information on these functions, see Type Translator Rules on page 13-

i.LON 100 Internet Server Programmer’s Reference 4-5

This input is a string of encoded XML containing a list of objects, or the desired settings of any number of the configuration properties associated with the i.LON 100. The contents of the string vary by function. The string of encoded XML contained within the <Data>

parameter is the single parameter you will supply as input when calling the SOAP functions described in Chapters 5-13 of this document. This differs from the DataPoint

functions described in Chapter 3, as those functions take a series of parameters as input, instead of the singe <Data> parameter.

NOTE: Some programming environments will require you to include the <Data> parent element in the input you supply to each function. Others, such as Microsoft Visual Studio .NET, do not. They insert the <Data> parent element into the SOAP message automatically when the function is invoked, and as a result you are only required to supply the contents of the <Data> parameter (i.e. the XML string only) as input.

The properties and attributes that you must define in the XML string passed within the <Data> parameter when calling each SOAP function are described in Chapters 5-13 of this document. In addition, the i.LON 100 resource files contain format definitions and descriptions of all configuration properties and network variable used on the i.LON 100. This information will be necessary when determining the values to assign to each property within the XML string. For more information on the i.LON 100 resource files, see the next section, i.LON 100 Resource Files.

This document includes a sample <Data> parameter with sample values that you could supply to each function included in the SOAP interface. For ease of understanding, these samples are shown in standard XML format. However, all data contained within the <Data> parameter must be passed over the network in encoded XML format.

Some programming environments, such as Microsoft Visual Studio .NET, will accept the data to be included in the <Data> parameter in standard XML format, and convert it to encoded XML format before the SOAP message is sent to the i.LON 100. In this case, you can enter the data in standard XML format when coding your application.

Other programming environments will not automatically convert the data from standard XML to encoded XML. This requires you to supply the string to the function in encoded XML format when you program your application. The following sections describe the difference between encoded XML and standard XML.

NOTE: The input supplied to the DataPointRead, DataPointWrite, and DataPointResetPriority functions requires a different format. For more information, see Formats of SOAP Messages on page 2-2.

4.3.1.1 Encoded XML and Standard XML

The following sample shows a SOAP message in enocded XML format, as it would appear when transmitted over the network to the i.LON 100. The string inside the <Data> parameter is a valid XML structure in the encoded format discussed in the previous section. This prevents the encapsulated XML data from being interpreted as individual parameters in the SOAP message.

The encoding used in the i.LON 100 SOAP interface uses character escaping for the &, < and > characters as defined for XML 1.0 by the W3C in “Extensible Markup Language (XML) 1.0” (http://www.w3.org/TR/2000/REC-xml-20001006 as follows:

• < character is replaced by <

• > character is replaced by >

). The rules for this character escaping are

i.LON 100 Internet Server Program4-6 mer’s Reference

• & character is replaced by &

For both the <Data> and <Result> parameters (see next section), the SOAP application will handle the value as a string. This string can be directly decoded and manipulated by an XML parsing engine. All input strings passed over the network in the <Data> parameter must be valid, encoded XML, and all strings returned by the i.LON 100 within the <Result> parameter will be passed over the network as valid, encoded XML.

The following represents a sample <Data> parameter as it would appear when passed over the network. The contents of the <Data> parameter here are in encoded XML format:

<Data> <iLONApplication> <UCPTindexValue>3</UCPTindexValue> <UCPTpointName>NVL_nvo03Switch</UCPTpointName> </iLONApplication> </Data>

To make this message format more readable, the above example would appear in standard XML format in this document, as shown below. The sample below, and all of the sample messages in this manual for the Data Server, Data Logger, Alarm Generator, Alarm Notifier, Event Calendar, Event Scheduler, or Type Translator applications, are not written as the messages actually appear when transmitted over the network. It is important to note this when using the sample XML strings provided in this document.

<Data> <iLONApplication> <UCPTindex>3</UCPTindex> <UCPTpointName>NVL_nvo03Switch</UCPTpointName> </iLONApplication> </Data>

i.LON 100 Internet Server Programmer’s Reference 4-7

4.4 i.LON 100 Resource Files

There are many configuration properties you can configure using the SOAP functions described in this document. This document provides a general description of each property, and other information you will need when configuring each one, such as minimum and maximum values for scalar properties, and maximum string lengths for string properties. This information is also contained in the i.LON 100 resource files. In order to successfully send a SOAP message to the i.LON 100, all data in the message must be formatted as described in this document, and in the resource files.

The i.LON 100 resource files are added to the LNS resource file catalog by the i.LON 100 Configuration Software installation utility, but they also exist locally on the i.LON 100. In fact, like LNS, the i.LON 100 maintains a catalog of resource files to use when formatting data in SOAP messages, network variable updates, and web tag data from the i.LON 100 web server.

You can use the Node Builder Resource Editor, which is included on the i.LON 100 Installation CD, to create new resource files for your own custom data point types and formats. Note that when creating custom resource files on a PC, it is common to organize the files into subdirectories such as:

C:\LonWorks\Types\User\MyCompany\MyResourceFiles.*

However, when adding these files to the i.LON you must FTP them to the following location:

/root/lonworks/types/MyResourceFiles.*

You only need to FTP your own custom resource files to the i.LON. If the name of your file set is "MyResourceFiles", then you must copy every file which starts with the name "MyResourceFiles". After you have copied these files to the i.LON you must reboot to be able to use the new type definitions and formats. During boot the i.LON reads the resource files in this directory and updates its local catalog accordingly.

4.4.1 LonMark Standard Network Variable Type (SNVT) Device

Resource Files

SNVT device resource files describe the data structures within LonMark SNVTs, and the formats used to display SNVT data. On the i.LON 100, you can find these files in the directory /root/lonworks/types. They are named STANDARD.ENU, STANDARD.TYP, STANDARD.FMT, and STANDARD.FPT.

The default format for a SNVT is its native format, as described in STANDARD.FMT. When you add a data point to the i.LON 100, you will assign that data point a fotmat type. If a specific SNVT format is desired for a particular data point, the <UCPTformatDescription> of that data point must be set the name of that SNVT format. For example:

The <UCPTformatDescription> property is described in more detail in Chapter 5, Data Server. You can browse the entire SNVT device resource files online at

http://types.lonmark.org

4.4.2 Standard Configuration Property Type (SCPT) Device Resource

Files

This is a set of files that describes the data structures within SCPTs, and also describes the formats used to display SCPT data. On the i.LON 100, these files can be found in the

i.LON 100 Internet Server Program4-8 mer’s Reference

directory /root/lonworks/types, and are named STANDARD.ENU, STANDARD.TYP, STANDARD.FMT and STANDARD.FPT.

Many configuration properties that are used by the i.LON 100 applications are based on the SCPTs defined in these files. The information provided in this document, and in the SCPT resource files, will help you determine what values to assign to the SCPTs referenced by the

i.LON 100.

You can browse the entire SCPT device resource files online at http://types.lonmark.org.

4.4.3 User Network Variable Type (UNVT) Device Resource Files

Device manufacturers create UNVT device resource files to describe non-standard, manufacturer specific network variables. Using the same mechanisms as the standard resource files, these files describe how to format data from a particular manufacturer's device. On the i.LON 100, you can find all device resource files in the directory /root/lonworks/types.

To specify UNVT formats a fully qualified format name is required as follows:

#<progID>[<selector>].<format name>

In this syntax, the “#”, “[“, “]” and “.” characters are literal characters. A hex byte string (in the “RAW_HEX_PACKED” format described below) represents the program ID. The selector is a one-digit string. It represents a filter that indicates relevant parts of the program ID, and may be one of the following:

0 - Standard

1 - Device Class

2 - Device Class and Usage

3 - Manufacturer

4 - Manufacturer and Device Class

5 - Manufacturer, Device Class, and Device Subclass

6 - Manufacturer, Device Class, Device Subclass, and Device Model

The format name syntax is similar to that used for SNVT types, except that the type name starts with “UNVT” instead of “SNVT”. For example:

FORMAT:#800001128000000[4].UNVT_date_event

4.4.4 User Configuration Property Type (UCPT) Device Resource

Files

This is a set of files that describes the data structures within UCPTs and also describes the formats used to display UCPT data. On the i.LON 100, these files may be found in the directory /root/lonworks/types, and are named BAS_Controller.ENU, BAS_Controller.TYP, BAS_Controller.FMT and BAS_Controller.FPT.

Echelon added these UCPTs for configuration properties used by i.LON 100 applications that have no SCPT definition. You can browse the UCPT resource files online at

http://types.echelon.com.

i.LON 100 Internet Server Programmer’s Reference 4-9

4.5 Data Formatting

In order to keep the i.LON SOAP/XML interface neutral across regions, most of the rules for formatting data, which would normally be changeable in LNS, are not changeable on the

i.LON 100. The one exception is the support of measurement system locale which is new in

version 1.1. The following list describes the various regional settings used by the i.LON 100 SOAP / XML interface:

Decimal Symbol – Always period "."

Precision – Single floats always use 7 digits of precision, including digits before and after

the decimal point. Double floats always use 14 digits of precision. For the rest of the base types, precision is determined by the type definition

Digit Grouping Symbol – Always comma ","

Digit Grouping – Always in the form "123,456,789"

Negative Sign Symbol – Always the minus sign "-"

Negative Number Format – Always "-1.1"; negative symbol in front, and no space between

the symbol and the number

List Separators – If the format uses the localized list separator symbol verticle bar "|", the

i.LON 100 will replace it with comma ",". However, if you define a new type in the

NodeBuilder Resource Editor which is a structure, array or union, the default list separator is space " ". The localized list separator must be explicitly specified in the format.

Measurement System – The i.LON 100 does not use localization settings for measurement system. The measurement system used to display a formatted value is determined by the UCPTformatDescription property of the data point. For example, if you have a data point whose format is defined as SNVT_temp_f#US, then the UCPTvalue written to the DataServerRead SOAP message will be in Farenheit. If that data point is an input to the AlarmGenerator, then the format of a property which specifies a comparison value, a delta or an offset like UCPThighLimit2Offset will also be in US units when you read it with the AlarmGeneratorGet function. Furthermore, you must use US units when setting the property with the AlarmGeneratorSet function. You should note that the value stored in the XML file will always be in SI units so that XML files may be shared between i.LON 100s. The rule used by the applications is that the format of the primary data point for the application instance determines the format of measurement system dependent properties, like offsets, comparison values and deltas.

i.LON 100 Internet Server Program4-10 mer’s Reference

4.6 List, Get, Set and Delete Functions

The SOAP interface for each i.LON 100 application contains a List function, a Get function, a Set function, and a Delete function. Together, these functions make up a symmetric interface. You can use the response from the List command as the input to the Get command. You can use the response from the Get command as the input to the Set command. This section provides an overview of this feature, and describes how you can take advantage of it when using the SOAP interface.

NOTE: The SOAP interface for some applications contains additional SOAP functions you can use to manage your XML files. These functions are listed later in this chapter, and described in detail in Chapters 5-13.

4.6.1 List Functions

Use the List function to retrieve a list of all items created for an application. For example, the AlarmGeneratorList function returns a list containing the index number, description, last update time and functional block name of each Alarm Generator that you have added to the i.LON 100, with custom SOAP applications or with the i.LON 100 Configuration Software. Similarly, the DataLoggerList function returns a list containing the index number, last update time, description and functional block name of each Data Logger that you have added to the i.LON 100.

4.6.2 Get Functions

Use the Get function to retrieve the configuration of any items or instances that you have added to an application. For example, you would use the AlarmGeneratorGet function to retrieve the configuration of an Alarm Generator. Or, you would use DataLoggerGet to retrieve the configuration of a Data Logger. You must reference the item whose configuration is to be retrieved by its index number, which is defined when the item is created.

Now, consider a scenario where you have used the AlarmGeneratorList function to retrieve a list containing the index number of each Alarm Generator that has been added to the i.LON

100. You could use the list as the input for the AlarmGeneratorGet function. The

AlarmGeneratorGet function would return the configuration of all the items included in the list.

You can also use the Get function to retrieve the configuration of a single item, by supplying the index number assigned to the item when it was created as input.

4.6.3 Set Functions

You can use the Set function to write to each of the XML files described in the previous section. When you invoke the Set function for an application for the first time, the associated XML file will be created in the /root/config/software directory of the i.LON 100, if it has not already been created. All data defined in the input passed to the function will be added to the XML file. Following this, you can use the Set function to add more data to the XML file, or to overwrite existing data.

For example, the first time an application invokes the AlarmGeneratorSet function, the AlarmGenerator.XML file will be created in the /root/config/software directory of the i.LON 100 (if it has not already been created by another application). The file will contain an element for each Alarm Generator defined in the input passed to the function, as well as the global configuration properties defined in the input passed to the function.

i.LON 100 Internet Server Programmer’s Reference 4-11

After its initial invocation, you can use the AlarmGeneratorSet function to overwrite the values of the global properties defined for the Alarm Generator application. You can also use it to add new Alarm Generators to the XML file, or to overwrite the configuration of exisiting Alarm Generators.

Each time you create an Alarm Generator (or any item or instance of an i.LON 100 application) using the Set method, the item will be assigned an index number. You will use that index number to identify that Alarm Generator when writing to its configuration later, or when referencing it from other functions.

When using the Set function to create an item such as an Alarm Generator, you shoud consider using output supplied by the corresponding Get function as the basis for your input. The following procedure describes how you might do so using the Alarm Generator functions. You could use this algorithm when programming any of the i.LON 100 applications.

1) Invoke the AlarmGeneratorList function to generate a list of Alarm Generators that have

been added to the i.LON 100. This list includes the index number of each Alarm Generator.

2) Invoke the AlarmGeneratorGet function, using the list returned by the

AlarmGeneratorList function as the input. The function will return the configuration of each Alarm Generator included in the list output.

3) Review the output from step 2, and choose an Alarm Generator to serve as your “default”

Alarm Generator. The AlarmGeneratorGet output for this Alarm Generator will serve as the basis for the next Alarm Generator you create. Modify the values of each property in the string returned by AlarmGeneratorGet to match the configuration you want for the new Alarm Generator. This will be more efficient than building the input string for the Set function from scratch.

NOTE: You must increment the index number assigned to the Alarm Generator, or remove the index number property from the string created in this step, when using this algorithm. Otherwise, the next step of this procedure will overwrite the configuration of the default Alarm Generator you have chosen. Chapters 5-13 describe this in more detail.

4) Invoke the AlarmGeneratorSet function, using the modified string created in Step 3 as

input. The new item is successfully created, without recreating an input string that defines an entire Alarm Generator configuration from scratch, and with minimal risk of format errors. Chapters 5-13 will clarify the benefits of this algorithm.

4.6.4 Delete Functions

Use the Delete functions to delete items from an application. For example, use the AlarmGeneratorDelete function to delete an Alarm Generator. Or, use the DataServerDelete function to delete a data point.

You must reference the item to be deleted by its index number in the input you supply to the function.

i.LON 100 Internet Server Program4-12 mer’s Reference

4.7 Performance Issues

The i.LON 100 contains 32 MB of RAM, which allows for complicated application configurations and extensive network use. However, even with this amount of memory, it is still possible for very high levels of network traffic to the i.LON 100, especially using the SOAP interface, to eventually exhaust its memory. This could result in delays in network access of the i.LON 100, performance problems for the i.LON 100 applications, or in the worst case even a reboot of the i.LON 100.

If your i.LON 100 exhibits some of these symptoms, you should consider reducing the level of network traffic to it. The following numbers are guidelines that apply to the use of the i.LON 100’s SOAP interface. While they are not absolute limits or guarantees of performance, they may be helpful to follow when attempting to manage the i.LON 100’s network traffic load or troubleshoot a performance problem.

As a result, you should follow these guidelines when programming SOAP applications:

• Limit the number of data points referenced in a single Get or Read message to no more

than 100. For more information, see Chapter 5, Data Server.

• Limit the number of alarm log records read in a single message to no more than 100. For

more information on reading alarm log records, see AlarmNotifierRead on page 8-20.

• Limit the number of data log records read in a single message to no more than 150. For

more information on reading data log records, see DataLoggerRead on page 6-11.

• If the combined XML file sizes for a given application exceed 100 KB, don’t try to read all

the configuration data for that application in a single Get message. This could potentially happen with the Event Scheduler application if all of its functional blocks were used, or possibly with the Alarm Notifier application.

• Don’t send a request message larger than 100 KB. Some possible examples of this might

be defining more than 100 NVL points in the Data Server in a single message with DataServerSet, or writing to 40 Alarm Notifiers in a single message with AlarmNotifierSet.

• Limit the number of simultaneous SOAP clients to no more than the number of web

tasks specified in the WebParams.dat file on the i.LON 100. The default for this number is five.

i.LON 100 Internet Server Programmer’s Reference 4-13

4.8 Getting Started

Chapters 5-13 of this document provide more detailed information on the various applications of the i.LON 100, and describe the SOAP functions you can use to configure them. You should review Chapter 5 before attempting to program any of the i.LON 100 applications. This chapter introduces and describes the i.LON 100 Data Server, which manages the data points you will use to control your network. It describes each type of data point, and lists the different ways you can create these data points and add them to the Data Server.

Once you have created your data points and built the i.LON 100 Data Server, you will be able to reference those data points when configuring the various applications of the i.LON

100. Chapters 5-13 describe the applications of the i.LON 100, and the SOAP functions you

can use to configure each one.

i.LON 100 Internet Server Program4-14 mer’s Reference

5 Data Server

The i.LON 100 uses the concept of a data point to map logical names to i.LON 100 system variables, network variables defined on the i.LON 100 LonTalk interface, and explicitly addressed network variables. This paradigm can be extended to handle data from other types of control networks as drivers for these buses become available.

Data points provide the i.LON 100 applications and Web server with a generic, open way to handle any piece of information in any type of network, such as the current value of a network variable in an LNS-managed network, or an explicit message in a closed L system. This document describes how to use two kinds of data points:

• NVL data points for network variables that are local to the i.LON 100

• NVC data points for i.LON 100 system variables that maintain constant values

The i.LON 100 Data Server handles all the details of these data point that are required by the various applications of the i.LON 100, such as how often a data point should be polled, its default value, its heartbeat, its current status, and its current value.

At the DataServer layer, all data points have the same set of properties, regardless of the network or device each data point is local to. This is made possible by the drivers that exist for each data point type, which handle communication between the Data Server and the network each data point is local to.

Use a standard network management tool for the particular data point type to configure each driver on the i.LON 100. For example, you could use an LNS-based network management tool to configure the NVL points on the i.LON 100. This layer of abstraction between the drivers and the DataServer provides a mechanism for all i.LON 100 applications to use data points of all types in the same way.

ONWORKS

The Data Server also ensures that the configuration, status and value of each data point recognized by the tools you can use to configure the i.LON 100 remain synchronized with each other, and within the device each data point is local to. The tools you can use to configure the i.LON 100 include include custom SOAP applications, L

i.LON 100 Configuration Software. The following diagram shows the relationship between

the i.LON 100 Data Server and the different tools you can use to configure the i.LON 100 and its applications.

ONMAKER, and the

i.LON 100 Internet Server Programmer’s Reference 5-1

The various applications of the

i.LON 100 can be configured

using the i.LON 100

configuration software and

LONMAKER, as well as the

SOAP/XML interface:

Custom

Applications Using the i.LON 100 SOAP/XML

Interface

i.LON 100 Applications:

Alarm Notifier

Alarm Generator

Data Logger

Analog Function Block

Event Scheduler

Event Calendar Type Translator

Web Binder

The i.LON 100 applications poll

the Data Server for NVE and

MBus data point values and

information.

i.LON 100

Configuration

Software

LONMAKER

i.LON 100

NVE Data Points

NVE DRIVER

The NVE driver exists to manage

communication between the i.LON 100

Data Server and the various external

devices on the same network as the the

i.LON 100.

NVE Data Points

External Network

i.LON 100

Data Server

MBus Data Points

MBus DRIVER

The MBus driver exists to manage

communication between the i.LON 100

Data Server and the various meter devices

on the same network as the i.LON 100.

MBus Data Points

Meter

Devices

Two of the most important properties in the Data Server for any data point are the <UCPTpointStatus> and <UCPTvalue> properties. The <UCPTpointStatus> property represents the current status of the data point. The <UCPTvalue> property represents the current value of the data point. The Data Server updates these properties in real time, and they are very useful to many i.LON 100 applications.

For example, you could set up an Alarm Generator that will update the <UCPTpointStatus> of a data point to an alarm condition each time the <UCPTvalue> of that data point reaches a certain level. You could then set up an Alarm Notifier that will send out an alarm notification each time the <UCPTpointStatus> of the data point is updated to that condition. These applications are described in more detail later in this document.

A data point list is generated for each data point when it is created and added to the i.LON 100 Data Server. Once you have created the data points for your i.LON 100 and them to the Data Server, you can reference these data points when using i.LON 100 applications such as the Analog Function Block, Event Scheduler, Event Calendar, Type Translator, Alarm Generator, and Alarm Notifier. When any of these applications reference a data point, that application is added to the data point list for the data point, and the application will be

i.LON 100 Internet Server Program5-2 mer’s Reference

notified each time the data point is updated. In this fashion, each application has current access to all the network information pertaining to the data points it is using.

This chapter describes how to create data points and add them to the Data Server.

NOTE: Echelon recommends that you restrict all networks to a maximum of 800 data points.

i.LON 100 Internet Server Programmer’s Reference 5-3

5.1 Data Server XML Files

The /root/config/software/dataserver directory of your i.LON 100 contains several XML files that will store the configuration of the data points in your Data Server. Table 7 describes these XML files.

Table 7 Data Server XML Files

File Name Description

DP_NVL.XML When a local NV for the i.LON 100 is created using LONMAKER, a

corresponding NVL data point is automatically added to the Data Server. Its configuration can then be modified using the SOAP interface or the

i.LON 100 Configuration Software, and it can be referenced from the i.LON

100 applications.

The DP_NVL.XML file stores the configurations of the NVL data points in your Data Server. This file contains an entry for each static, dynamically created data point that has been added to the Data Server.

NOTE: NVL data point must always be created using LONMAKER.

DP_NVC.XML This file contains an entry for each NVC data point that has been added to

the Data Server. An NVC data point represents a network variable that maintains a constant value.

These data points can be created with the DataServerSet function, which is described later in this chapter, or with the i.LON 100 Configuration Software.

The following sections provide examples of each of these files. Guidelines and instructions to follow when modifying these files, manually or with the SOAP interface, follow the examples.

i.LON 100 Internet Server Program5-4 mer’s Reference

5.1.1 DP_NVL.XML

The DP_NVL.XML file is created automatically the first time the i.LON 100 boots. It will contain an <NVL> element for each static NV on the device. The properties contained within these elements define the configuration of an NVL data point, and are described later in this chapter. Each time you use L 100, an <NVL> element for the associated data point will be added to this file.

You can modify a data point's configuration after it has been added to the i.LON 100 by manually editing this XML file, or by using the DataServerSet function. The sections following the example XML files provide guidelines and instructions to follow when doing so.

The following represents a sample DP_NVL.XML file for an i.LON 100 with four NVL data points.

<DpNVL>

</DpNVL> <NVL>

<UCPTindex>0</UCPTindex> <UCPTpointName>NVL_nvoAlarmFlag2</UCPTpointName> iLON</UCPTlocation> <UCPTlocation> <UCPTdescription />

<UCPTformatDescription>SNVT_switch</UCPTformatDescription>

2</UCPTdpSize> <UCPTdpSize> <UCPTbaseType>BT_STRUCT</UCPTbaseType> <UCPTunit>% of full level state code</UCPTunit>

0.0</SCPTmaxSendTime> <SCPTmaxSendTime> <SCPTminSendTime>0.0</SCPTminSendTime> <SCPTmaxRcvTime>0.0</SCPTmaxRcvTime>

0.0 -1</UCPTdefOutput> <UCPTdefOutput>

</NVL> <NVL>

<UCPTindex>1</UCPTindex> <UCPTpointName>NVL_nviLevAlarm</UCPTpointName> <UCPTlocation>iLON</UCPTlocation> <UCPTdescription /> <UCPTformatDescription>SNVT_alarm</UCPTformatDescription> <UCPTdpSize>29</UCPTdpSize> <UCPTbaseType>BT_STRUCT</UCPTbaseType> <UCPTunit></UCPTunit> <SCPTmaxSendTime>0.0</SCPTmaxSendTime> <SCPTminSendTime>0.0</SCPTminSendTime> <SCPTmaxRcvTime>0.0</SCPTmaxRcvTime> <UCPTdefOutput>0 0 0 0 0 0 0 AL_NO_CONDITION PR_LEVEL_0 0

<0 0 0 0> 0/0/0/0:0:0:0 <0 0 0 0></UCPTdefOutput>

</NVL>

ONMAKER to create a dynamic network variable for the i.LON

i.LON 100 Internet Server Programmer’s Reference 5-5

<NVL>

<UCPTindex>2</UCPTindex> <UCPTpointName>NVL_nvoDlClear</UCPTpointName> <UCPTlocation>iLON</UCPTlocation> <UCPTdescription />

<UCPTformatDescription>SNVT_switch</UCPTformatDescription>

<UCPTdpSize>2</UCPTdpSize> <UCPTbaseType>BT_STRUCT</UCPTbaseType> % of full level state code</UCPTunit> <UCPTunit> <SCPTmaxSendTime>0.0</SCPTmaxSendTime> <SCPTminSendTime>0.0</SCPTminSendTime> <SCPTmaxRcvTime>0.0</SCPTmaxRcvTime> <UCPTdefOutput>0.0 -1</UCPTdefOutput>

</NVL> <NVL>

3</U<UCPTindex> CPTindex> <UCPTpointName>NVL_nviDeviceAlarm</UCPTpointName> <UCPTlocation>iLON</UCPTlocation>

UCPTdescription></UCPTdescription>

<UCPTformatDescription>UNVT_alarm_2</UCPTformatDescription>

<UCPTdpSize>31</UCPTdpSize> BT_STRUCT</UCPTbaseType> <UCPTbaseType> <UCPTunit /> <SCPTmaxSendTime>0.0</SCPTmaxSendTime> SCPTminSendTime 0.0</SCPTminSendTime> < > <SCPTmaxRcvTime>0.0</SCPTmaxRcvTime>

</NVL>

</iLONDataServer>

i.LON 100 Internet Server Program5-6 mer’s Reference

5.1.2 DP_NVC.XML

The DP_NVC.XML file contains a list of <NVC> elements, one for each NVC data point that you have added to the Data Server. An NVC data point represents an i.LON 100 system variable that maintains a constant value.

Each element defines the configuration of an associated NVC data point. The properties that must be defined within each <NVC> element define the configuration of an NVC data point, and are described later in this chapter.

The following represents a sample DP_NVC.XML file for an i.LON 100 with two NVC data points. You can add NVC data points to the Data Server using the DataServerSet function, or by manually editing the XML file. The sections following the example XML files provide instructions and guidelines to follow when doing so.

<?xml version="1.0" ?>

LONDataServer> <i

pNVC>

<UCPTlifeTime>0</UCPTlifeTime> </DpNVC> VC> <N

<UCPTpointName>NVC_nviConstant</UCPTpointName>

<UCPTdpSiz 2 UCPTdpSize> e> </

<UCPTdirection>DIR_IN</UCPTdirection> </NVC> VC> <N

<UCPTpointName>NVC_nviTemp</UCPTpointName>

</iLONDataServer>

Reference temperature</UCPTdescription>

i.LON 100 Internet Server Programmer’s Reference 5-7

5.2 Creating and Modifying the Data Server XML Files

The i.LON 100 generates all of the Data Server configuration files the first time it boots. The DP_NVL.XML file will contain an <NVL> element for each static NV on the device that has been created with LONMAKER. New NVL data points will be added to the DP_NVL.XML file automatically when more local NVs are created in LONMAKER. The DP_NVC.XML file will not contain any data point entries the first time the i.LON 100 boots.

You can use the DataServerSet function to add new NVC data points to the Data Server and to the DP_NVC.XMl file. You can also use DataServerSet to modify the configuration of existing NVL and NVC data points in the Data Server. The following section, Data Server SOAP Interface, describes how to use DataServerSet and the other SOAP functions provided for use with the Data Server.

You can manage the Data Server XML files manually using an XML text editor, and download them to the /root/config/software directory of the i.LON 100 via FTP. Echelon does not recommend this, as the i.LON 100 will require a reboot to read the configuration of the downloaded XML files. Additionally, the i.LON 100 performs error checking on all SOAP messages it receives before writing to the XML files. It will not perform error checking on any XML files you download via FTP, and so the application may not boot properly.

However, if you plan to create or modify any XML files manually, you should review the rest of this chapter first. This chapter describes the elements and properties in the Data Server configuration files that define each data point’s configuration. For instructions on creating or modifying an XML file manually, see Manually Modifying an XML Configuration File on page 15-1.

5.2.1 Data Server SOAP Interface

The SOAP interface for the Data Server application includes seven functions. Table 8 lists and describes these functions. For more information, see the sections following Table 8.

Table 8 Data Server SOAP Functions

Function Description

DataServerList Use this function to list the index number, name and location of

each data point that you have added to the Data Server. For more information, see DataServerList on page 5-10.

DataServerGet Use this function to return the configuration of a data point. For

more information, see DataServerGet on page 5-12.

DataServerSet Use this function to create an NVC data point and add it to the

Data Server, or to modify the configuration of an existing NVL or NVC data point. For more information, see DataServerSet on page 5-17.

DataServerRead Use this function to read the current value of a data point, or

group of data points, that has been added to the Data Server. For more information, see DataServerRead on page 5-19.

DataServerWrite Use this function to write to the value of a data point, or group of

data points. For more information, see DataServerWrite on page 5-24.

i.LON 100 Internet Server Program5-8 mer’s Reference

Function Description

DataServerResetPriority Use this function to reset the priority level assigned to a data

point. For more information, see DataServerResetPriority on page 5-25.

DataServerDelete Use this function to remove a data point from the Data Server.

For more information, see DataServerDelete on page 5-28.

i.LON 100 Internet Server Programmer’s Reference 5-9

5.2.1.1 DataServerList

Use the DataServerList function to retrieve a list of data points that you have added to the

i.LON 100 Data Server. The Data Server List function accepts an empty string as the

contents of its <Data> parameter. If you supply an empty string as the <Data> parameter, the list returned by the function will contain an entry for every data point in the Data Server.

Alternatively, you can specify a subset of data points to be listed by filling the properties described in Table 9 into the <Data> parameter you supply to the function.

Table 9 DataServerList Input Properties

Parameter Description

Enter the type of data point to be listed in the return string (NVL or NVC). Leave this property empty to display all data point types.

Optional. Enter a string of 16 comma-separated Boolean values. This string will be compared to the <UCPTsettings> string defined for each data point. If at least one set bit in this string matches the <UCPTsettings> string defined for a data point, then that data point will be included in the list returned by the function.

The <UCPTsettings> property for a data point is defined when it is added to the Data Server, and can be written to with the DataServerSet function, which is described later in this chapter.

Enter the index number of the first data point to be listed in the return string.

Enter the maximum number of data points to be included in the return string.

The example below requests that the function return a list of up to 50 NVL data points, starting with index number 0.

In this example, the function returns a <DpNVL> element at the beginning of the return string, because the <UCPTdataPointType> requested in the input is NVL. This contains global information about the data point type requested in the list. Or, if the property had been filled in as NVC, a <DpNVC> element would have been returned. Each of these elements includes the following child elements:

<SCPTobjMajVer> and <SCPTobjMinVer>. Child elements identifying the major and minor

•

version numbers of the firmware implementation the Data Server application is using.

• <UCPTlastUpdate>. A timestamp indicating the last time the Data Server was written to. This timestamp is expressed in UTC format, as per the ISO 8601 standard.

• <UCPTlifeTime>. This property defines how old (in seconds) the value of a data point of the specified type can be before the Data Server retrieves a new data value from the driver when an application requests the value of a given data point. If this parameter is set to 0, the values of the data points will be copied from the i.LON 100 Data Server when an application requests them, and no update will be requested from the driver. If this parameter is set to a positive value, the i.LON 100 Data Server will poll the driver for the current value of a data point each time an application requests it, and the time interval defined by the property has expired.

i.LON 100 Internet Server Program5-10 mer’s Reference

The interval resets each time the value of a data point is retrieved. By default this value is 0 for NVL data points, and 0 NVC data points. You can change this value by manually modifying it in the DP_NVL.XML or DP_NVC.XML configuration files. Note that you can also temporarily override this value each time you call the DataServerRead function. See the

DataServerRead function later in this chapter for

more information.

The <Result> parameter also includes an <NVL> element for each NVL data point that met the selection criteria defined in the input supplied to the function. Note that the function would return <NVC> element for each NVC data point that met the selection criteria defined in the function’s input. The next section, DataServerGet, describes the properties included in each of these elements.

You could use the list of data point elements returned by this function as input for the DataServerGet function. The function would then return the configuration of each data point included in the list.

<Data> Parameter

<Result> Parameter

<Data> <iLONDataServer> <UCPTdataPointType>NVL</UCPTdataPointType> <UCPTstartIndex>0</UCPTstartIndex> <UCPTcount>50</UCPTcount> </iLONDataServer> </Data> <Result> <iLONDataServer> <DpNVL> <SCPTobjMajVer>1</SCPTobjMajVer> <SCPTobjMinVer>1</SCPTobjMinVer> <UCPTlastUpdate>2002-06-24T16:03:58Z</UCPTlastUpdate> <UCPTlifeTime>0</UCPTlifeTime> </DpNVL> <NVL> <UCPTindex>0</UCPTindex> <UCPTpointName>NVL_nviRequest</UCPTpointName> <UCPTlocation>iLON100</UCPTlocation> </NVL> <NVL> <UCPTindex>1</UCPTindex> <UCPTpointName>NVL_nvoStatus</UCPTpointName> <UCPTlocation>iLON100</UCPTlocation> </NVL> <NVL> <UCPTindex>2</UCPTindex> <UCPTpointName>NVL_nviTimeSet</UCPTpointName> <UCPTlocation>iLON100</UCPTlocation> </NVL> <NVL> <UCPTindex>3</UCPTindex> <UCPTpointName>NVL_nviDateEvent</UCPTpointName> <UCPTlocation>iLON100</UCPTlocation> </NVL> </iLONDataServer> </Result>

i.LON 100 Internet Server Programmer’s Reference 5-11

<Data> Parameter

<Result> Parameter

5.2.1.2 DataServerGet

You can use the DataServerGet function to retrieve the configuration of any data point that you have added to the i.LON 100 Data Server. Each NVL data point to be returned must be identified by an <NVL> element within the <Data> parameter, and each NVC data point must be identified by an <NVC> element. You must reference the specific data point to be returned by its index number (UCPTindex) or its name (UCPTpointName) within each of these elements, as shown below.

You can request the configurations of any mixture of NVL or NVC data points in a single call to DataServerGet. The following example requests that the configuration of two data points be returned. One is referenced by its index number, and the other is referenced by its name. Note that the child element for each data point is called <NVL>: this would be <NVC> for an NVC data point.

NOTE: You should not attempt to retrieve the configuration of more than 100 data points with a single call to this function.

<Data> <iLONDataServer> <NVL> <UCPTindex>0</UCPTindex> </NVL> <NVL> <UCPTpointName>NVL_nvoSwitch</UCPTpointName> </NVL> </iLONDataServer> </Data>

<iLONDataServer> <NVL> <UCPTindex>0</UCPTindex> <UCPTpointName>NVL_nviRequest</UCPTpointName> <UCPTlocation>iLON100</UCPTlocation> <UCPTdescription>Node request message input</UCPTdescription> <UCPTformatDescription>SNVT_obj_request</UCPTformatDescription> <UCPTdpSize>3</UCPTdpSize> <UCPTbaseType>BT_STRUCT</UCPTbaseType> <UCPTunit></UCPTunit> <SCPTmaxSendTime>0.0</SCPTmaxSendTime> <SCPTminSendTime>0.0</SCPTminSendTime> <SCPTmaxRcvTime>0.0</SCPTmaxRcvTime> <UCPTdefOutput>0,RQ_NORMAL</UCPTdefOutput> <UCPTsettings>0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0</UCPTsettings> <UCPTdirection>DIR_IN</UCPTdirection> </NVL> <NVL> <UCPTindex>1</UCPTindex> <UCPTpointName>NVL_nvoSwitch</UCPTpointName> <UCPTlocation>MainBuilding\FirstFloor\Light</UCPTlocation> <UCPTdescription>Light switch Tdescription> </UCP <UCPTformatDescription>SNVT_switch</UCPTformatDescription> <UCPTdpSize>6</UCPTdpSize> <UCPTbaseType>BT_STRUCT</UCPTbaseType> <UCPTunit></UCPTunit> <SCPTmaxSendTime>0.0</SCPTmaxSendTime> <SCPTminSendTime>0.0</SCPTminSendTime> <SCPTmaxRcvTime>0.0</SCPTmaxRcvTime> <UCPTdefOutput>100.0 1</UCPTdefOutput> <UCPTsettings>0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0</UCPTsettings>

i.LON 100 Internet Server Program5-12 mer’s Reference

The DataServerGet function returns an element for each data point referenced in the <Data> parameter you supplied to the function. The properties included within each element are initially defined when the data point is added to the DataServer. You can write to them with the DataServerSet function. Table 10 describes these properties.

For more information on the DataServerSet function, see DataServerSet on page 5-17.

Table 10 DataServerGet Output properties

Property Description

The index number assigned to a data point must be in the range 0-32767. As mentioned earlier, you can use the DataServerSet function to create a new NVC data point, or to modify an existing NVL or NVC data point. If you do not specify an index number in the <Data> parameter you supply to DataServerSet, the function will create a new data point using the first available index number.

If you specify an index number that is already being used, the function will overwrite the configuration of the data point using that index number with the settings defined in the <Data> parameter.

The name of a data point can be a maximum of 31 characters long, and must begin with the following prefixes:

• NVL_ for an NVL data point

• NVC_ for an NVC data point

Once you have added a data point to the Data Server, you can not change its <UCPTpointName>. The <UCPTpointName> property for all data points must be unique, and must not contain any spaces.

Note: The names assigned to NVL data points in the Data Server follow the naming convention NVL_[NAME], where [NAME] represents the progammatic name assigned to the NV when it was created with LONMAKER. You can determine the progammatic name of a network variable in LONMAKER by right-clicking it and selecting Properties.

An alphanumeric string of up to 128 characters that describes the location of the data point. This field is user-defined, and may be useful when organizing your data points by physical location or device.

A description of the data point. This can be a maximum of 228 characters long.

i.LON 100 Internet Server Programmer’s Reference 5-13

Property Description

http://www.echelon.com/support

Unit text. This property is a string up to 228 characters long that describes the units the value of a data point is measured in. It should be filled in based on the network variable type assigned to the data point.

A default value will be assigned to this property, if a unit for the network variable type chosen for the data point exists in the

i.LON 100 resource files.

This read-only property is assigned to the data point automatically, and is based on the point’s <UCPTformatDescription>. It defines the base type of the data point, as defined in the base_type_t enumeration in the BAS_Controller resource files for the i.LON 100.

Read-only. The size of the data point. This is determined based on the <UCPTformatDescription> selected for the data point.

This property applies to output data points. It defines the maximum amount of time that may elapse before the data point is updated on the network, if it is set to a non-zero value.

For example, if a SNVT_temp value data point is changing by one degree every 10 seconds and this property is set to two seconds, the i.LON 100 will update the value of the data point on the network every two seconds, even though the value of the data point is not changing more than once every 10 seconds. The receiver can use this output as a heartbeat. The receiver will know something is wrong if he or she does not receive an update every two seconds.

5-14

i.LON 100 Internet Server Programmer’s Reference

Property Description

This property applies to output data points, and defines the minimum amount of time that may elapse between data point updates if it set to a non-zero value.

For example, if a SNVT_temp value data point is changing by one degree every half second and this value is set to two seconds, the data point will only be updated every two seconds with the latest value, even though the value changes more frequently than that.

NOTE: If a data point update occurs before this time period elapses, that update will not be propagated over the network, unless the <SCPTmaxSendTime> property is defined. In that case, the update would be propagated over the network after the <SCPTmaxSendTime> period expires. If <SCPTmaxSendTime> is not set, the update would be lost. As a result, it is recommended that you set the <SCPTmaxSendTime> property.

This property is used to control the maximum time that can elapse after an update to a bound network input, before another update occurs. If this period elapses without an update, the <UCPTpointStatus> of the data point will be updated to AL_OFFLINE. You could create an Alarm Notifier to trigger an alarm notification when this happens. For more information on Alarm Notifiers, see Chapter 8, Alarm Notifier.

The valid range for this property is any value between 0.0 sec and 6,553.4 seconds. Setting <SCPTmaxRcvTime> to the default value of 0.0 disables the receive failure mechanism.

Optional. The value to be assigned to this data point after a power-up of the device or during an override of the functional block.

For external data points and devices that operate as slaves, Echelon does not recommend that you define this property, as the value entered here will be sent to the external device after a power-on.

NOTE: You can use DataServerSet to change this value in the Data Server. However, you must program your application to enforce the new value, as the i.LON 100 will continue to enforce the default value taken from the resource files.

Optional. This value is initially taken from the i.LON 100 resource files, if it exists for the data point type selected. This value represents the minimum value the data point can be updated to.

NOTE: You can use DataServerSet to change this limit in the Data Server. However, you must program your application to enforce the new limit, as the i.LON 100 will continue to enforce the limit taken from the resource files.

i.LON 100 Internet Server Programmer’s Reference 5-15

Property Description

Optional. This value is initially taken from the i.LON 100 resource files, if it exists for the data point type selected. This value represents the maximum value the data point can be updated to.

Optional. The invalid value for the data point. If the data point is updated and equals this value, the <UCPTpointStatus> of the data point will be updated to the AL_VALUE_INVALID. You could create an Alarm Notifier to trigger an alarm notification when this happens. For more information on Alarm Notifiers, see Chapter 8, Alarm Notifier.

A default value for this property will be assigned based on the <UCPTformatDescription> selected.

A string of 16 comma-separated Boolean values. You could use these flags to determine access rights to the data point with your application.

You can optionally specify a <UCPTsetting> string when you call the DataServerList function. This string will be compared to this property for each data point. If any bits in either string match, DataServerList will include the data point in its output. If no bits match, it will not include the data point. You could use this feature to restrict which users can view and access to certain data points.

This element can be used to create a series of value definitions for the data point. Each value definition is defined by a usernamed attribute within the <UCPTvalueDef> element. These value definitions represent preset values that you can use to update the value of the data point when other i.LON 100 applications such as the Event Scheduler or the Alarm Notifier reference it.

The sample <Data> parameter shown in this section defines two preset value definitions for the data point: OnValue and OffValue.

NOTE: The values entered here must be in valid format, as defined by the network variable type assigned to the data point.

5-16

i.LON 100 Internet Server Programmer’s Reference

5.2.1.3 DataServerSet

Use the DataServerSet function to overwrite the configuration of an NVL or NVC data point, or to create an NVC data point and add it to the Data Server. Each NVL data point to be written to must be identified by an <NVL> element within the <Data> parameter, and each NVC data point must be identified by an <NVC> element. You must reference the specific data point to be written by its index number (UCPTindex) or its name (UCPTpointName) within each of these elements, as shown below.

The rest of properties that you must fill in within each data point element define the configuration of the data point within the Data Server. This set of properties is the same, whether you are creating a new data point or modifying an existing data point. The previous section, DataServerGet, describes each of these properties in detail.

It is important to realize that when you modify an existing data point with the DataServerSet function, any optional properties such as <UCTPminValue>, <UCPTmaxValue>, <UCPTdefOutput> and <UCPTinvalidValue> left out of the <Data> parameter will be erased. Old values will not be carried over, so you must fill in every property, or make sure that the data point is linked to a template defining the values any of these properties, when writing to an existing data point. Otherwise, these properties will be set to a null value.

The following example re-writes the configuration of a data point called NVL_nvo01Switch. Because this is an NVL data point, its new configuration is contained within an <NVL> element.

NOTE: You can create or write to multiple data points with a single call to DataServerSet. However, you should not attempt to create or write to more than 100 data points with a single call to this function. Additionally, to optimize the memory available to the i.LON 100, you should not have more than 800 data points in your network at any time.

i.LON 100 Internet Server Programmer’s Reference 5-17

<Data> Parameter

<Result> Parameter

<UCPTlocation>Light Kitchen</UCPTlocation> <UCPTdescription>Lamp Kitchen 230V; 100W</UCPTdescription> <UCPTformatDescription>SNVT_switch</UCPTformatDescription> <UCPTbaseType>BT_STRUCT</UCPTbaseType> <UCPTunit>State, % /UCPTunit> < <SCPTmaxSendTime>60</SCPTmaxSendTime>

<UCPTmaxValue>100.0 1 CPTmaxValue> </U

<OffValue>100.0 0 OffValue> </

</UCPTvalueDef> </NVL> </iLONDataServer> </Data>

i.LON 100 Internet Server Program5-18 mer’s Reference

5.2.1.4 DataServerRead

You can use the DataServerRead function to read the value and status of any data point that you have added to the Data Server. There are two ways to reference the data points whose values and statuses are to be returned:

• You can reference each data point to be read by its index number or name in the <Data> parameter you supply to the function. If the specified input data point is a structure, you can specify the field whose value is to be returned below. For more information on this, and a sample <Data> string, see the Requesting Data Points by Name and Index section later in this chapter.

• You can reference a group of data points to be returned by the data point type, and by the last time the data points were updated. For more information on this, and a sample <Data> string, see the Requesting Data Points by Type and Last Update Time section later in this chapter.

The DataServerRead function will return a list of elements, one for each data point referenced by the <Data> parameter you supplied to the function. Each of these elements contains the current values of a group of properties and attributes associated with the associated data point. This includes the value and the priority level currently assigned to the data point. This is described in more detail in the in the DataServerRead Output Properties section later in this chapter.

5.2.1.4.1 Requesting Data Points by Name and Index

You can reference the data points to be returned by their index numbers or names in the <Data> parameter you supply to the function. This may be useful if you only need to request information for a small number of data points. You should not attempt to read more than 100 data points with a single call to this function.

The following example <Data> parameter requests that information for three separate data points be returned. Note that the name of each element within the <Data> parameter must match the data point type (NVL, NVC) of the data point referenced within it. Table 12, which follows the example, describes the properties returned by the function for each data point.

The information contained in the <Result> parameter for each data point returned by the function is described in the section later in this chapter.

NOTE: This example includes the optional <UCPTlifeTime> property. This defines how old the value of a data point can be, in seconds, before the Data Server retrieves a new data value from the driver when an application requests its value. If the property is set to 0, the values of the data points will be copied from the i.LON 100 Data Server when an application requests them, and no update will be requested from the applicable driver. If this parameter is set to a positive value, the i.LON 100 Data Server will poll the driver for the current value of a data point each time an application requests it, and the time interval defined by the property has expired. You can temporarily override the value of the <UCPTlifeTime> property stored in the i.LON 100 Data Server by passing it in to the DataServerRead message. In doing so, you can determine whether or not the values of the data points you are reading will be polled for this message. This may be useful if you are creating an application to monitor a device such as a thermometer, and do not necessarily need a current value. Set the property to 0, or any value greater than the current poll rate, if you do not want the values of the data points polled for this message.

i.LON 100 Internet Server Programmer’s Reference 5-19

<Data> Parameter

<UCPTpointName>NVL_nvo03Switch</UCPTpointName>

</NVL> <NVL> <UCPTindex>9</UCPTindex> <UCPTfieldName>state</UCPTfieldName> </NVL> </iLONDataServer> </Data>

i.LON 100 Internet Server Program5-20 mer’s Reference

5.2.1.4.2 Requesting Data Points by Type and Last Update Time

You can also reference the data points to be returned by their data point type, and time of last update. This may be useful if you want to see which data points were updated during a certain time period, or if you want to read the values of all data points of a certain type.

Table 11 DataServerRead Input Properties

Property

Enter the type of data point you want to see information for. Enter NVL for NVL data points, or NVC for NVC data points. Leave this property empty to see all data point types in the <Result> parameter.

Use these fields to specify a range for the last update time to the data points that will be returned by the function. Both parameters are optional.

If you only specify a start time, the function will only return the data points whose value or status has been updated since the time specified. This is useful when an application only requires the latest updates of data points, and based on the activity of the data points requested, it can reduce the size of the response SOAP message.

If you specify a start and stop time only data points whose last update time is between this interval will be returned by the function. If you only specify a stop time only data points whose last update time occurs before the stop time will be returned by the function.

Description

If you do not enter a start or stop time, the function will return all data points requested, up to the count specified.

The <UCPTstart> and <UCPTstop> properties must be entered as timestamps in local time, with an appended time zone indicator that denotes the difference between local time and UTC. For more information on this format, see Local Times and Coordinated Universal Time on page 6-12.

The following example <Data> parameter requests that information for NVL data points updated in July of 2001 be returned. Because the <UCPTcount> property is set to 20, the function will include information for no more than 20 data points in the <Result> parameter.

Use this field to specify the maximum number of data point entries the function will return. If this property is not filled in, the function will return all data points requested, or data points whose last update occurred within the interval defined by the <UCPTstart> and <UCPTstop> properties.

NOTE: You should not attempt to read more than 100 data points with a single call to this function.

Optional. Use this property to determine whether the values of the data points requested in the <Data> parameter will be polled before they are returned. This is described in more detail earlier in the section.

The information contained in the <Result> parameter for each data point returned by the function is described in the next section of this chapter, DataServerRead Output Properties.

i.LON 100 Internet Server Programmer’s Reference 5-21

<Data> Parameter

5.2.1.4.3 DataServerRead Output Properties

The function returns an element for each data point referenced in the <Data> parameter you supplied to the function. Information for NVL data points will be included within an <NVL> element, and information for NVC data points will be included within an <NVC> data point.

<Result> Parameter

<NVL>

<UCPTpointName>NVL_nvo01Switch</UCPTpointName>

<UCPTvalue>0.0 0</UCPTvalue> <UCPTvalueDef>OffValue</UCPTvalueDef> <UCPTunit>% of full level,state code</UCPTunit> <UCPTpointStatus>AL_NO_CONDITION</UCPTpointStatus>

<NVL>

<UCPTpointName>NVL_nvo03Switch</UCPTpointName>

<UCPTvalue 33.0 0> </UCPTvalue> <UCPTunit>% of full level,state code</UCPTunit> <UCPTpointStatus>AL_NO_CONDITION</UCPTpointStatus>

<NVL>

<UCPTpointName>NVL_nvo02Switch</UCPTpointName> <UCPTfieldName>state</UCPTfieldName>

<UCPTvalue 1 lue> > </UCPTva <UCPTunit>state code </UCPTunit> <UCPTpointStatus>AL_NO_CONDITION</UCPTpointStatus> <UCPTpriority>250</UCPTpriority>

</NVL> </iLONDataServer> </Result>

The following table describes the properties that are included in each of <NVL> or <NVC> element.

Table 12 DataServerRead Output Properties

Property Description

The index number assigned to the data point.

The name of the data point.

i.LON 100 Internet Server Program5-22 mer’s Reference

Property Description

If the value of a field was requested in the <Data> parameter, this property contains the name of the field.

[YYYY-MM-DD]T[HH:MM:SS.MSS]+/-[HH:MM]

The first segment of the timestamp [YYYY-MM-DD] represents the date. The second segment (T[HH:MM:SS.MSS]) of the timestamp represents the local time, expressed in hours, minutes, seconds and milliseconds. The third segment (+/-[HH:MM]) represents the difference between the local time listed in the second segment and UTC. This segment begins with a + or a -. The + indicates that the local time is ahead of UTC, the - indicates the local time is behind UTC. Consider the following example:

2002-08-13T10:24:37.111+02:00

This timestamp indicates a local date and time of 10:24 AM and

37.111 seconds, on August 13, 2002. Because the third part of the segment reads +02:00, we know the local time here is 2 hours ahead of UTC.

The current value of the data point.

The value definition currently being used by the data point. Value definitions represent preset values. They can be created with the

i.LON 100 Configuration Software, or the DataServerSet function.

You can use these value definitions to update the value of the data point other i.LON 100 applications such as the Event Scheduler or the Alarm Notifier reference it.

Unit type. This property is configured based on the network variable type of the data point.

The current status of the data point. This can be used when setting up Alarm Generators and Alarm Notifiers with the i.LON

100. For more information on these applications, see Chapter 7, Alarm Generator, and Chapter 8, Alarm Notifier.

The priority level currently assigned to the data point (0-255). The priority level of a data point determines which applications have write access to it. You can modify the value of this property with the DataServerWrite or DataServerResetPriority functions.

For more information on priority levels, see Data Point Values and Priority Levels on page 3-5.

i.LON 100 Internet Server Programmer’s Reference 5-23

5.2.1.5 DataServerWrite

A data point's value and priority level are initially set when the data point is added to the Data Server. The value is set to the value established for the <UCPTdefOutput> property for the data point, and the priority defaults to the lowest priority level (255).

You can use the DataServerWrite function to update the value and priority of one or more data points at a time. Each NVL data point to be written to must be identified by an <NVL> element within the <Data> parameter, and each NVC data point must be identified by an <NVC> element. The rest of this section describes the information that must be filled in within each of these elements.

You must reference the specific data point to be written to by their index numbers (UCPTindex) or point names (UCPTpointName) within each of these elements.

If the data point is a structure, you can also specify the field whose value should be written to by the function by filling in the <UCPTfieldName> property. In this case, you may also want to fill in the <UCPTpropagate> property. If you assign the default value 1 to this property, the change you make to the data point will be propagated to the network. If you assign value 0 to this property, the change will be made in the i.LON 100 Data Server, but it will not be propagated over the LONWORKS network. This may be useful if you are writing to the different fields of a structure within a call to DataServerWrite, and do not want to update the structure over the network until all fields have been written by the function.

The priority level specified for each data point is set by the <UCPTpriority> property. This must be a higher priority than that used by the last application to write to the data point. If it is not, the data point will not be successfully updated. For more information on priority levels, see Data Point Values and Priority Levels on page 3-5.

You can write to the value of the data point using either a value definition (UCPTvalueDef), or an actual value (UCPTvalue). The example <Data> parameter below shows both of these options. You should not attempt to write to more than 100 data points with a single call to this function.

The following sample <Data> parameter writes to three data points. Note that the name of each element within the <Data> parameter must match the data point type (NVL or NVC) of the data point referenced within it.

<Data> Parameter

<Data> <iLONDataServer> <NVL> <UCPTpointName>NVL_nvo01Switch</UCPTpointName>

<UCPTvalueDef>OffValue</UCPTvalueDef> <UCPTpriority>25</UCPTpriority>

</NVL> <NVL> <UCPTindex>5</UCPTindex> <UCPTfieldName>state</UCPTfieldName> <UCPTvalue>1</UCPTvalue>

</NVL> </iLONDataServer> </Data>

i.LON 100 Internet Server Program5-24 mer’s Reference

<Result> Parameter

5.2.1.5.1 DataServerWrite Fault Responses

As of version 1.1, the i.LON 100 will return a detailed fault response message if it fails to update the value of any of the data points specified in the <Data> parameter. Consider a case where you specify input to update the values of 3 data points called NVL_myNetworkVar_1, NVL_myNetworkVar_2, and NVL_myNetworkVar_3. If the i.LON 100 is unable to update any one of the 3 data points for any reason, none of the data points will be updated, and a fault response message will be returned that indicates which data points the i.LON 100 was unable to update, and why.

The fault message will be returned using the same error reponse format as described in the SOAP Error Responses section in Chapter 2 of this document. However, the SOAP envelope will contain an additional element called the

ENV:faultstring>

data point that the i.LON 100 was unable to update.

<Result> <iLONDataServer> <NVL> <UCPTindex>8</UCPTindex> </NVL> <NVL> <UCPTindex>10</UCPTindex> <UCPTfieldName>state</UCPTfieldName> </NVL> </iLONDataServer> </Result>

<SOAP-ENV:detail> after the <SOAP-

element. The <SOAP-ENV:detail> will contain a child-element for each

In the following example, the i.LON 100 is unable to update the NVL_myNetworkVar_1 and NVL_myNetworkVar_2 data points element for each of these data points containing properties identifying the data point (UCPTindex, UCPTpointName, UCPTdataPointType) and the error code and description (faultcode and faulstring) that describes why the i.LON 100 was unable to update the data point. Remember that the value of the NVL_myNetworkVar_3 data point would not be updated by the funtion in this case, even though the new value passed to the function for the data point is valid.

<Data> Parameter

. The <SOAP-ENV:detail> element includes a child

<Data> <iLONDataServer> <NVL> <UCPTpointName>NVL_myNetworkVar_1</UCPTpointName> <UCPTvalue>500.0 1</UCPTvalue> </NVL> <NVL> <UCPTpointName NVL_myNetworkVar_2</UCPTpointName> > <UCPTvalueDef>AUTO</UCPTvalueDef> </NVL> <NVL> <UCPTpointName>NVL_myNetworkVar_3</UCPTpointName> <UCPTvalue>100.0 1</UCPTvalue> </NVL> </iLONDataServer> </Data>

i.LON 100 Internet Server Programmer’s Reference 5-25

<SOAP-ENV:detail> of Fault Response Message

5.2.1.5.2 DataServerWrite and the Web Binder Application

You can use the Web Binder application to create connections that allow direct data exchange over a TCP/IP network between two i.LON 100s, or between an i.LON 100 and any Web server that can communicate via SOAP messaging such as Apache or IIS. You can configure the Web Binder using the built-in Web pages included with the i.LON 100, as described in Chapter 1 of the i.LON 100 Internet Server User’s Guide: Using the i.LON 100 Web Pages to Configure Applications and to Monitor and Control Data Points document.

<SOAP-ENV:detail> <iLONDataServer/> <AoDP/> <DP/> <UCPTindex/>421</UCPTindex/> <UCPTdataPointType/>NVL</UCPTdataPointType/> <UCPTpointName/>NVL_myNetworkVar_1</UCPTpointName/> <faultcode/>11</faultcode/> <faultstring/>Value cannot be formatted</faultstring/> </DP/> <DP/> <UCPTindex/>422</UCPTindex/> <UCPTdataPointType/>NVL</UCPTdataPointType/> <UCPTpointName/>NVL_myNetworkVar_2</UCPTpointName/> <faultcode/>11</faultcode/> <faultstring/>Value cannot be formatted</faultstring/> </DP/> </AoDP/> </iLONDataServer/> </SOAP-ENV:detail>

Once the WebBinder has been configured, the i.LON 100 will send a DataServerWrite SOAP message for each update of a source data point to the destination server. Thus, to create an application on the Web server to receive WebBinder updates from the i.LON 100, you only need to implement the DataServerWrite method. You should note that an application which can receive the DataServerWrite message from the i.LON 100 differs from an application that would use all of the other methods described in this manual in that it must be a "serverside" application rather than a client application.

You can find an example if such a server-side WebBinder application on the i.LON 100 area of Echelon’s website at:

http://www.echelon.com/ilon

i.LON 100 Internet Server Program5-26 mer’s Reference

5.2.1.6 DataServerResetPriority

You can use the DataServerResetPriority function to reset the priority of a data point to 255, the lowest priority.

Each NVL data point to be reset must be identified by an <NVL> element within the <Data> parameter, and each NVC data point must be identified by an <NVC> element. You must reference the specific data point to be reset by its index number (UCPTindex) or its name (UCPTpointName) in each of these elements, as shown below.

The new priority level for each data point is established by the value of the <UCPTpriority> property. Priority levels can be numbered from 0 to 255, with 0 representing the highest priority and 255 representing the lowest priority. Once the priority level assigned to a data point has been reset to 255, all applications will be able to write to the value of that data point.

The priority level specified in the <Data> parameter must be a higher priority than the current priority assigned to the data point for it to be reset. For more information on priority levels, see Data Point Values and Priority Levels on page 3-5.

NOTE: You should not attempt to reset more than 100 data points with a single call to this function.

<Data> Parameter

<Result> Parameter

i.LON 100 Internet Server Programmer’s Reference 5-27

5.2.1.7 DataServerDelete

You can use the DataServerDelete function to remove a data point from the Data Server. Each NVL data point to be deleted must be identified by an <NVL> element within the <Data> parameter, and each NVC data point must be identified by an <NVC> element. You must reference the specific data point to be deleted by its index number (UCPTindex) or its name (UCPTname) in each of these elements, as shown below.

The deletion of NVL data points requires two steps. NVL data points must be deleted from LONMAKER before they are deleted with this function. When you delete a local NV using

ONMAKER, the status of the associated NVL data point in the Data Server will be set to

L AL_CONSTANT. In version 1.0 of the SOAP/XML interface, the index number of the associated NVL data point was also increased by 5000 to prevent errors from occurring when other applications attempt to reference the deleted data point before it is removed from the Data Server. In version 1.1, the incrementation of the index is no longer necessary.

NOTE: You should not attempt to delete more than 100 data points with a single call to this function.

<Data> Parameter

<Result> Parameter

i.LON 100 Internet Server Program5-28 mer’s Reference

6 Data Loggers

You can use Data Loggers to monitor activity on your network. Each Data Logger will record updates to a group of user-specified data points into a log file. The information recorded for each update includes the value and status that the data point was updated to.

Each i.LON 100 supports up to ten Data Loggers. The log files for each Data Logger are stored in the /root/Data directory of the i.LON 100 with the file name logX, where X represents the index number assigned to the Data Logger.

You can create two kinds of Data Loggers: historical Data Loggers, and circular Data Loggers. A historical Data Logger stops recording data point updates when its log file becomes full. A circular Data Logger removes the records for older updates when its log file is full, and new updates occur. The Data Logger can save either type of log file in an ASCII-text (.csv file extension) or binary (.dat file extension) format.

You can specify the minimum amount of time that must elapse, and the minimum change in value required, between log entries for each data point your Data Logger is monitoring. When an update to a data point is logged, a subsequent update for that data point will not be logged until the minimum time period specified for the data point has elapsed, and the minimum value change specified for the data point has been met. If an input data points is updated more than once before the minimum time period has elapsed after a log entry has been recorded, the older values will be discarded. Only the most recent update will be recorded by the Data Logger when the minimum time period elapses. This allows you to throttle the data entry into a log.

You can also define a threhold level for each Data Logger. The threshold level represents a percentage. When the Data Logger’s log file consumes this percentage of the memory space allocated to it, the Data Logger will enunciate that it is time to upload the log, and clear out some of the data. The Data Logger makes this enunciation by updating the Data Logger’s alarm data point (called NVL_nvoDlAlarm[X], where X represents the index number assigned to the Data Logger) to the status AL_ALM_CONDITION. This feature may be useful when working with historical Data Loggers, which are disabled when they become full. You could create an Alarm Notifier to trigger an alarm notification when a log becomes full. For more information on Alarm Notifiers, see Chapter 9 of this document.

You can access the data in a log file by manually opening the log file, or by using the DataLoggerRead SOAP function. You can clear data from a log using the DataLoggerClear function, or by sending an update to the data point NVL_nviDlClear[X], where X represents the index number of the Data Logger to be affected. This is described in more detail later in the chapter.

6.1 DataLogger.XML

The DataLogger.XML file stores the configurations of each Data Logger that you have added to the i.LON 100. Each Data Logger is signified by a <Log> element in the XML file. The configuration properties contained in each <Log> element define the configuration of a Data Logger, and are described later in this chapter.

You can create newData Loggers using the DataLoggerSet SOAP function, or by manually editing the DataLogger.XML file. The sections following this example provide instructions and guidelines to follow when doing so.

The following represents a sample DataLogger.XML file for an i.LON 100 with three defined Data Loggers.

i.LON 100 Internet Server Programmer’s Reference 6-1

<?xml version="1.0" ?>

LONDataLogger> <i

<Log>

<UCPTindex>0</UCPTindex> <UCPTlastUpdate>2002-02-12T14:36:51Z</UCPTlastUpdate> <UCPTdescription>Data Logger 0</UCPTdescription> LT_CIRCULAR</UCPTlogType> <UCPTlogType> <UCPTlogSize>100</UCPTlogSize> <UCPTlogFormat>LF_BINARY</UCPTlogFormat> <UCPTlogLevelAlarm>0.0</UCPTlogLevelAlarm>

<Point>

<UCPTindex>0</UCPTindex> NVL_nviWHTot1</UCPTpointName> <UCPTpointName> <UCPTlogMinDeltaTime>0.0</UCPTlogMinDeltaTime> <UCPTlogMinDeltaValue>0</UCPTlogMinDeltaValue> <UCPTpollRate>0</UCPTpollRate>

</Point> <Point>

<UCPTindex>1</UCPTindex> <UCPTpointName>NVL_nviWHTot2</UCPTpointName>

0</UCPTlogMinDeltaValue> <UCPTlogMinDeltaValue> <UCPTpollRate>0</UCPTpollRate>

</Point>

</Log>

<Log>

<UCPTindex>1</UCPTindex> 2002-02-12T14:41:15Z</UCPTlastUpdate> <UCPTlastUpdate> <UCPTdescription>Data Logger 1</UCPTdescription> <UCPTlogType>LT_HISTORICAL</UCPTlogType> 10 ogSize> <UCPTlogSize> </UCPTl <UCPTlogFormat>LF_TEXT</UCPTlogFormat> <UCPTlogLevelAlarm>30.0</UCPTlogLevelAlarm> <Point>

<UCPTindex>0</UCPTindex> <UCPTpointName>NVL_nviDLTemp_f</UCPTpointName> <UCPTlogMinDeltaTime>0.0</UCPTlogMinDeltaTime> <UCPTlogMinDeltaValue>0</UCPTlogMinDeltaValue> <UCPTpollRate>0</UCPTpollRate>

</Point> </Log> <Log>

<UCPTdescription>Data Logger 2</UCPTdescription>

<UCPTlogType>LT_HISTORICAL</UCPTlogType>

<Point>

<UCPTindex>0</UCPTindex> <UCPTpointName>NVL_AI_Analog</UCPTpointName> <UCPTlogMinDeltaTime>10.0</UCPTlogMinDeltaTime> <UCPTlogMinDeltaValue>0</UCPTlogMinDeltaValue> <UCPTpollRate>10</UCPTpollRate>

i.LON 100 Internet Server Program6-2 mer’s Reference

</Point>

<Point>

<UCPTindex>1</UCPTindex> <UCPTpointName>NVL_nviWeekend</UCPTpointName> <UCPTlogMinDeltaTime>10.0</UCPTlogMinDeltaTime> <UCPTlogMinDeltaValue>0</UCPTlogMinDeltaValue> <UCPTpollRate>10</UCPTpollRate>

</Point>

<Point>

<UCPTindex>2</UCPTindex> <UCPTpointName>NVL_nvoWeekday</UCPTpointName> <UCPTlogMinDeltaTime>10.0</UCPTlogMinDeltaTime> <UCPTlogMinDeltaValue>0</UCPTlogMinDeltaValue> <UCPTpollRate>10</UCPTpollRate>

</Point> </Log>

</iLONDataLogger>

i.LON 100 Internet Server Programmer’s Reference 6-3

6.2 Creating and Modifying the DataLogger.XML File

You can create and modify the DataLogger.XML file with the DataLoggerSet SOAP function. The following section, DataLogger SOAP Interface, describes how to use DataLoggerSet and the other SOAP functions provided for the Data Logger application.

Alternatively, you can create and modify the DataLogger.XML file manually and download it to the i.LON 100 via FTP. Echelon does not recommend this, as the i.LON 100 will require a reboot to read the configuration of the downloaded file. Additionally, the i.LON 100 performs error checking on all SOAP messages it receives before writing to the XML file. It will not perform error checking on any XML files you download via FTP, and thus the application may not boot properly.

However, if you plan to create and manage the DataLogger.XML file manually, you should review the rest of this chapter first, as it describes the elements and properties in the XML file that define each Data Logger’s configuration. For instructions on creating or modifying an XML file manually, see Manually Modifying an XML Configuration File on page 15-1.

6.2.1 DataLogger SOAP Interface

The SOAP interface for the Data Logger application includes six functions. Table 13 lists and describes these functions. For more information on each function, see the sections following Table 13.

Table 13 DataLogger SOAP Functions

Function Description

DataloggerList Use this function to generate a list of the Data Loggers that you have

added to the i.LON 100. For more information, see DataLoggerList on page 6-5.

DataloggerGet Use this function to retrieve the configuration of any Data Logger that

you have added to the i.LON 100. For more information, see DataLoggerGet on page 6-6.

DataloggerSet Use this function to create a new Data Logger, or to overwrite the

configuration of an existing Data Logger. For more information, see DataLoggerSet on page 6-10

DataloggerRead Use this function to read some, or all, of the log entries a Data Logger

has recorded. For more information, see DataLoggerRead on page 6-11.

DataloggerClear Use this function to remove some, or all, of the log entries a Data Logger

has recorded from its log file. For more information, see DataLoggerClear on page 6-15.

DataloggerDelete Use this function to delete a Data Logger. For more information, see

DataLoggerDelete on page 6-16.

i.LON 100 Internet Server Program6-4 mer’s Reference

6.2.1.1 DataLoggerList

Use the DataLoggerList function to retrieve a list of the Data Loggers that you have added to the i.LON 100. The DataLoggerList function takes an empty string as its <Data> parameter, as in the example below.

The function returns the major and minor version numbers of the firmware implementation that the Data Logger application is using in the <Result> parameter. The <Result> parameter also includes a <Log> element for each Data Logger that you have added to the

i.LON 100. The next section, DataLoggerGet, describes the properties included in each of

these elements.

You could use the list of <Log> elements returned by this function as input for the DataLoggerGet function. The DataLoggerGet function would then return the configuration of each Data Logger included in the list.

<Data> Parameter

<Result> Parameter

Empty String

<Result> <iLONDataLogger> <SCPTobjMajVer>1</SCPTobjMajVer> <SCPTobjMinVer>1</SCPTobjMinVer> <Log> <UCPTindex>0</UCPTindex> <UCPTlastUpdate>2002-12-21T12:31:00Z</UCPTlastUpdate> <UCPTdescription>Light first Floor</UCPTdescription>

<UCPTfbName>Data Logger- 0</UCPTfbName>

</Log> <Log> <UCPTindex>1</UCPTindex> <UCPTlastUpdate>2002-12-21T12:31:01Z</UCPTlastUpdate> <UCPTdescrip Energy data</UCPTdescription> tion> <UCPTfbName>Data Logger- 1</UCPTfbName> </Log> <Log> <UCPTindex>2</UCPTindex> <UCPTlastUpdate>2002-12-21T12:31:02Z</UCPTlastUpdate> <UCPTdescription>

Light second Floor</UCPTdescription>

<UCPTfbName>Data Logger- 2</UCPTfbName>

</Log> </iLONDataLogger> </Result>

i.LON 100 Internet Server Programmer’s Reference 6-5

6.2.1.2 DataLoggerGet

You can use the DataLoggerGet function to retrieve the configuration of any Data Logger that you have added to the i.LON 100. You must reference the Data Logger whose configuration is to be returned by its index number in the <Data> parameter you supply to the function, as in the example below.

<Data> Parameter

<Result> Parameter

<Result> <iLONDataLogger> <Log> <UCPTindex>0</UCPTindex> <UCPTlastUpdate>2002-02-12T14:36:51Z</UCPTlastUpdate> <UCPTdescrip Temperature monitor</UCPTdescription> tion> <UCPTfbName>Data Logger- 0</UCPTfbName> <UCPTlogType>LT_CIRCULAR</UCPTlogType> <UCPTlogSize>100</UCPTlogSize> <UCPTlogFormat>LF_BINARY</UCPTlogFormat> <UCPTlogLevelAlarm>0.0</UCPTlogLevelAlarm> <Point> <UCPTindex>0</UCPTindex> <UCPTpointName>NVL_nviWHTot1</UCPTpointName> <UCPTlogMinDeltaTime>0.0</UCPTlogMinDeltaTime> <UCPTlogMinDeltaValue>0</UCPTlogMinDeltaValue> <UCPTpollRate>0</UCPTpollRate> </Point> <Point> <UCPTindex>1</UCPTindex> <UCPTpointName>NVL_nviWHTot2</UCPTpointName> <UCPTlogMinDeltaTime>0.0</UCPTlogMinDeltaTime> <UCPTlogMinDeltaValue>0</UCPTlogMinDeltaValue> <UCPTpollRate>0</UCPTpollRate> </Point> </Log> </iLONDataLogger> </Result>

The function returns a <Log> element for each Data Logger referenced in the <Data> parameter you supplied to the function. The properties included in each element are initially defined when the Data Logger is created. You can write to them with the DataLoggerSet function. Table 14 describes these properties.

For more information on the DataLoggerSet function, see DataLoggerSet on page 6-10.

Table 14 DataLoggerGet Output Properties

Property Description

i.LON 100 Internet Server Program6-6 mer’s Reference

Property Description

The index number assigned to the Data Logger must be in the range of 0-32,767. As mentioned earlier, you can use the DataLoggerSet function to create a new Data Logger, or to modify an existing Data Logger. If you do not specify an index number in the <Data> parameter you supply to DataLoggerSet, the function will create a new Data Logger using the first available index number.

If you specify an index number that is already being used, the function will overwrite the configuration of the Data Logger using that index number with the settings defined in the <Data> parameter.

A timestamp indicating the last time the configuration of the Data Logger was updated. This timestamp uses the following format:

YYYY-MM-DDTHH:MM:SSZ

The first segment of the time stamp (YYYY-MM-DD) represents the date the configuration of the Data Logger was last updated. The second segment (THH:MM:SS) represents the time of day the configuration of the Data Logger was last updated, in UTC (Coordinated Universal Time).

UTC is the current term for what was commonly referred to as Greenwich Meridian Time (GMT). Zero (0) hours UTC is midnight in Greenwich England, which lies on the zero longitudinal meridian. Universal time is based on a 24 hour clock, therefore, an afternoon hour such as 4 pm UTC would expressed as 16:00 UTC. The Z appended to the timestamp indicates that it is in UTC.

For example, 2002-08-15T10:13:13Z indicates a UTC time of 10:13:13 AM on August 15, 2002.

The functional block name assigned to the Data Logger in LONMAKER. You can write to this property, but each time you use the i.LON 100 Configuration Software to view the Data Logger, it will be reset to match the functional block name defined in L

ONMAKER.

A user-defined description of the Data Logger. This can be a maximum of 228 characters long.

Either LT_HISTORICAL or LT_CIRCULAR. This indicates whether the log is a historical or circular. A historical data log stops recording data point updates when it is full. A circular data log removes older values when the log is full and it receives new updates.

The amount of memory allocated to the log file, in kilobytes. Enter an integer value here.

Please note that the total size of the log files for all Data Loggers (and Alarm Notifiers) on the i.LON 100 can not exceed the size of the flash memory stored in the i.LON 100. The i.LON 100 will stop writing to the log files when it only has 256 Kb of flash memory remaining.

Either LF_TEXT or LF_BINARY. This property indicates whether the log file the Data Logger uses will be an ASCII-text formatted CSV file (LF_TEXT), or use a proprietary binary format (LF_BINARY).

i.LON 100 Internet Server Programmer’s Reference 6-7

Property Description

<Point>

Enter a value between 0.0 and 100.0. The default value is 0.0. This value represents a percentage. When the volume of the Data Logger reaches this percentage, the status of the output data point for the Data Logger will be updated to the condition AL_ALM_CONDITION. The output data point for each Data Logger is called NVL_nvoDlLevAlarm[X], where X represents the index number assigned to the Data Logger. For example, if you enter 30.0 here, the data point would be updated when the log file has consumed 30% of the space allocated to it.

You could create an Alarm Notifier to trigger an alarm notification each time one of your Data Loggers reaches this level. For more information on this, see Chapter 9, Alarm Notifier.

You can determine the current log level of a Data Logger using the DataLoggerRead funtion, or by using the DataLoggerRead function to read the value field of the NVL_nviDlStatus[X] data point, where X represents the index number assigned to the Data Logger. The value assigned to the data point represents the percentage of the Data Logger’s log file that has been used.

You can clear out a log file using the DataLoggerClear function, or by updating the value assigned to NVL_nviDlClear[X], where X represents the index number assigned to the Data Logger. The value field you assign the data point when you update it reflects how much of the total log size will be cleared. For example, if your log is 50% full (out of 100kB), and you update the value of the data point to "30.0 1", then the application would go to the beginning of the log and clear out the first 30% of the log (in this case, 30K). You could use the DataServerWrite or DataPointWrite functions to update this data point’s value.

The data points the Data Logger will record updates for are defined by a list of <Point> elements.

When any of the data points defined by these elements are updated, the Data Logger will record the updates into its log file. There are several properties you need to configure within each <Point> element that determine when an update to that data point will be logged. For descriptions of these properties, see Table 15 below.

A Data Logger can record updates for as many data points as you want.

The data points a Data Logger monitors are defined by a list of <Point> elements. Table 15 describes the properties that should be defined within each <Point> element.

Table 15 DataLoggerGet <Point> Element Properties

Property Description

The name of the data point to be monitored by the Data Logger, as defined in the i.LON 100 Data Server.

The minimum amount of time, in seconds, that must pass between log entries for the data point. All updates will be logged if this value is 0.0, or not defined.

This property has a maximum value of 214,748,364.0 seconds. The default is 0.0 seconds.

6-8

i.LON 100 Internet Server Programmer’s Reference

Property Description

This property applies to scalar data points only. Specify the change in value required for an entry to the log to be made. For example, if this property is set to 30.0, the value of the data point being monitored must change by at least 30.0 during an update for the change to be recorded by the Data Logger. All updates are logged if this value is 0.0, or not defined.

This property has minimum and maximum floating point values of +/-3.402823466e+038.

NOTE: If the format type used by the data point being monitored is SNVT_temp_p#US or SNVT_temp#US, then the value of this property returned by the DataLoggerGet function will be displayed using the SNVT_temp_f#US_diff format type. This rule applies to all formats that use the #US specifier.

The poll rate for the Data Logger can be between 0 and 214,748,364.0 seconds. The Data Logger will check for updates to the data point at this interval. Echelon recommends that you set this to a value greater than or equal to the value specified for the <UCPTlogMinDeltaTime> property if you do not want to poll data before updates to the log are possible.

If you use the default poll rate of 0 seconds, the Data Logger will record each updates to the data points it is monitoring into the log, assuming that the time period defined by the <UCPTlogMinDeltaTime> property has elapsed and the change in value specified by the <UCPTlogMinDeltaValue> property has been met.

You should note that other i.LON 100 applications may cause the Data Server to poll this data point’s value as well. The poll rate specified by these applications should be compatible with each other. For example, if an Alarm Generator is polling a data point every 15 seconds, and the Data Logger is polling that data point every 10 seconds, then the Data Server will have to poll the value of the data point every five seconds to ensure that each application gets a current value for each poll.

It is important to note this as you set poll rates for various applications, as you may end up causing more polls than is efficient on your network. For example, if an Alarm Generator is polling a data point every 9 seconds and a Data Logger is polling a data point every 10 seconds, the Data Server would have to poll the data point every second to ensure that each application polls for a current value. This may create a significant amount of undesrired traffic.

i.LON 100 Internet Server Programmer’s Reference 6-9

6.2.1.3 DataLoggerSet

Use the DataLoggerSet function to create new Data Loggers, or to overwrite the configuration of existing Data Loggers. The Data Loggers to be created or written to are signified by a list of <Log> elements in the <Data> parameter. The properties you must define within each <Log> element are the same, whether you are creating a new Data Logger or modifying an existing Data Logger. The previous section, DataLoggerGet, describes these properties.

NOTE: When modifying an existing Data Logger, any optional properties left out of the input string will be erased. Old values will not be carried over, so you must fill in every property when writing to a Data Logger, even if you are not changing all of the values.

The first invocation of the DataLoggerSet function will generate the DataLogger.XML file in the /root/Config/Software directory of the i.LON 100, if the file does not already exist.

When creating or modifying a Data Logger with DataLoggerSet, you may want to use output from the DataLoggerGet function as the basis for your <Data> parameter. You would then only need to modify the values of each property to match the new configuration you want, as opposed to re-creating an entire string like the one shown below.

The following example creates a Data Logger that records all updates for two data points, one named NVL_nviWHTot1 and the other named NVL_nviWHTot2.

<Data> Parameter

<Result> Parameter

<Data> <iLONDataLogger> <Log> <UCPTdescription>Data Logger 1</UCPTdescription> <UCPTfbName></UCPTfbName> <UCPTlogType>LT_CIRCULAR</UCPTlogType> <UCPTlogSize>100 gSize> </UCPTlo <UCPTlogFormat>LF_BINARY</UCPTlogFormat> <UCPTlogLevelAlarm>0.0</UCPTlogLevelAlarm> <Point> <UCPTindex>0</UCPTindex> <UCPTpointName>NVL_nviWHTot1</UCPTpointName> <UCPTlogMinDeltaTime>0.0</UCPTlogMinDeltaTime> <UCPTlogMinDeltaValue>0</UCPTlogMinDeltaValue> <UCPTpollRate>0.0</UCPTpollRate> </Point> <Point> <UCPTindex>1</UCPTindex> <UCPTpointName>NVL_nviWHTot2</UCPTpointName> <UCPTlogMinDeltaTime>0.0</UCPTlogMinDeltaTime> <UCPTlogMinDeltaValue>0</UCPTlogMinDeltaValue> <UCPTpollRate>0</UCPTpollRate> </Point> </Log> </iLONDataLogger> </Data>

i.LON 100 Internet Server Program6-10 mer’s Reference

6.2.1.4 DataLoggerRead

Use the DataLoggerRead function to retrieve the entries in the log files generated by your Data Loggers. You can specify which log entries the function will return by filling the properties described in Table 16 into the <Data> parameter you supply to the function.

Table 16 DataLoggerRead Input Properties

Property Description

The index number of the Data Logger to return log entries for.

The name of the data point for which log entries are to be returned. If you do not fill in this property, the function will return log entries for all data points the Data Logger is monitoring.

Use this field to specify the maximum number of log entries the function will return. If you do not fill in this property, the function will return all log entries for the applicable data point (or data points) that were logged during the interval defined by the <UCPTstart> and <UCPTstop> properties.

NOTE: You should not attempt to read more than 150 log entries with a single call to this function.

Use these fields to specify a time interval for the log entries to be returned. You can specify a start and stop time, or just a stop time.

If you specify a start and stop time and the number of log entries during this interval exceeds the maximum defined by the <UCPTcount> property, the function will return the first group of log entries recorded during the interval.

If you only specify a start time, the function will return entries from the log starting at the start time until it reaches the end of the log file, or until it has returned the maximum number of entries (as defined by the <Count> property).

If you only specify a stop time and the number of log entries during this interval exceeds the maximum defined by the <UCPTcount> property, the function will return the group of entries from the stop time going backwards in the log until the maximum number of log entries have been returned. If the <UCPTcount> property was not defined, the function will return all log entries in the log, going backward from the stop time. This may be useful for applications that need to read the newest information logged.

If you do not enter a start or stop time, the function will return all log entries for the applicable data points, up to the maximum.

You must enter the <UCPTstart> and <UCPTstop> properties as timestamps in local time, with appended time zone indicators to denote the difference between local time and UTC. For more information on this format, see Local Times and Coordinated Universal Time on page 6-12.

i.LON 100 Internet Server Programmer’s Reference 6-11

6.2.1.4.1 Local Times and Coordinated Universal Time

The timestamps for the <UCPTstart> and <UCPTstop> properties conform to the ISO 8601 standard. They are expressed in local time, with appended time zone indicators that show the relationship to the Coordinated Universal Time (UTC ).

UTC is an international time standard and is the current term for what was commonly referred to as Greenwich Meridian Time (GMT). Zero (0) hours UTC is midnight in Greenwich England, which lies on the zero longitudinal meridian. Universal time is based on a 24 hour clock, therefore, afternoon hours such as 4 pm UTC are expressed as 16:00 UTC. The timestamp uses the following format:

[YYYY-MM-DD]T[HH:MM:SS.MSS]+/-[HH:MM]

The third segment of the timestamp (+/-[HH:MM]) represents the difference between the local time listed in the second segment and UTC. This segment begins with a + or a -. The + indicates that the local time is ahead of UTC, and the - indicates the local time is behind UTC. Consider the following example:

2002-08-13T10:24:37.111+02:00

6.2.1.4.2 Sample SOAP Message

The following example returns a list of up to three log entries made by the Data Logger with index number 2 between 10/27/2002 02:00 and 11/228/2002 14:30:00 for the NVL_nviDlCount2 data point.

<Data> Parameter

<Data> <iLONDataLogger> <Log> <UCPTindex>2</UCPTindex> <UCPTpointName>NVL_nviDlCount2</UCPTpointName> <UCPTstart>2002-01-27T02:00:00.000+01:00</UCPTstart> <UCPTstop>2002-11-28T04:30:00.000+01:00</UCPTstop> <UCPTcount>3</UCPTcount> </Log> </iLONDataLogger> </Data>

i.LON 100 Internet Server Program6-12 mer’s Reference

<Result> Parameter

<Result> <iLONDataLogger> <Log> <UCPTindex>2</UCPTindex> <UCPTfileNa /root/data/log2.dat ileName> me> </UCPTf <UCPTstart>2002-08-29T10:30:11.000-07:00</UCPTstart> <UCPTstop>2002-08-29T14:34:20.000-07:00</UCPTstop> <UCPTlastEvent>2003-08-29T14:34:20.000-07:00</UCPTlastEvent> <UCPTlogLevel>8.5</UCPTlogLevel> <UCPTtotalCount>57</UCPTtotalCount> <Element> <UCPTpointName>NVL_nviDlCount2</UCPTpointName> <UCPTlocation>iLON100</UCPTlocation> <UCPTlogSourceAddress>0.0</UCPTlogSourceAddress> <UCPTlogTime>2002-08-29T10:30:11.000-07:00</UCPTlogTime> <UCPTvalue>0</UCPTvalue> <UCPTunit>units (delta)</UCPTunit> <UCPTpointStatus>AL_NO_CONDITION</UCPTpointStatus> </Element> <Element> <UCPTpointName>NVL_nviDlCount2</UCPTpointName> <UCPTlocation>iLON100</UCPTlocation> <UCPTlogSourceAddress>1.3</UCPTlogSourceAddress> <UCPTlogTime>2002-08-29T10:31:00.000-07:00</UCPTlogTime> <UCPTvalue 5 > > </UCPTvalue <UCPTunit>units (delta)</UCPTunit> <UCPTpointStatus>AL_NO_CONDITION</UCPTpointStatus> </Element> <Element> <UCPTpointName NVL_nviDlCount2</UCPTpointName> > <UCPTlocation>iLON100</UCPTlocation> <UCPTlogSourceAddress>1.3</UCPTlogSourceAddress> <UCPTlogTime>2002-08-29T10:32:00.000-07:00</UCPTlogTime> <UCPTvalue>20</UCPTvalue> <UCPTunit>units (delta) t> </UCPTuni <UCPTpointStatus>AL_NO_CONDITION</UCPTpointStatus> </Element> </Log> </iLONDataLogger> </Result>

The DataLoggerRead function includes several global properties at the beginning of the <Result> parameter. These properties provide information about the Data Logger and the log file the entries were read from. Table 17 describes these properties.

Table 17 DataLoggerRead Global Output Properties

Property Description

The index number assigned the Data Logger.

The name of the log file the Data Logger is using.

These properties represent timestamps indicating the log times of the first and last log entries in the log file. The timestamps are shown in local time, with appended time zone indicators showing the difference between local time and UTC. For more information on this, see Local Times and Coordinated Universal Time on page 6-12.

i.LON 100 Internet Server Programmer’s Reference 6-13

Property Description

This property contains a timestamp indicating the last time an entry in the log file was deleted with the DataLoggerClear function, or the last time an entry in the log was modified with the DataLoggerWrite function. The timestamp is displayed in local time, with an appended time zone indicator that indicates the difference between local time and UTC. For more information on this, see Local Times and Coordinated Universal Time on page 6-

12.

The volume of the log file that has been consumed, as a percentage. For example, the value 90.0 indicates that the log is 90% full.

This property contains the total number of entries contained in the data log read by the function.

The function also returns an <Element> element describing each log entry that met the selection criteria you defined in the <Data> parameter. Table 18 describes the properties listed within each of these elements.

Table 18 DataLogger Read <Element> Properties

Property Description

The name of the data point updated.

The source address of the data point. This is returned using the following format:

[Subnet.Node]

A timestamp indicating the time that the log entry was made. This timestamp is shown in local time, with an appended time zone indicator showing the difference between local time and UTC. For more information on this, see Local Times and Coordinated Universal Time on page 6-12.

Indicates the value definition currently being used by the data point. Value defintions are strings that represent preset values. They are created when a data point is added to the Data Server. For more information on this, see Chapter 5, Data Server.

This property will be returned empty if the data point was not using a value definition after the update.

The value the data point was updated to.

The unit type of the data point.

The status the data point was updated to.

6-14

i.LON 100 Internet Server Programmer’s Reference

6.2.1.5 DataLoggerClear

You can use the DataLoggerClear function to remove log entries from a Data Logger’s log file. You can specify which Data Logger is to be affected, and which log entries will be removed, by configuring the properties described in Table 19 into the <Data> parameter you supply to the function.

NOTE: This function only deletes the log entries. You can delete the Data Logger itself with the DataLoggerDelete function.

Table 19 DataLoggerClear Input Properties

Parameter Description

The index number of the Data Logger to be affected.

The name of the data point whose log entries are to be deleted. If you do not fill in this property, the function will delete log entries for all data points that the Data Logger is monitoring.

Use this property to specify the maximum number of log entries the function will delete. If you do not fill in this property, the function will delete all log entries for the applicable data point, or data points, that occurred within the interval defined by the <UCPTstart> and <UCPTstop> properties.

Use these fields to specify a time interval for the log entries to be deleted. You can specify a start and stop time, or just a stop time.

If you specify a start and stop time and the number of log entries during this interval exceeds the count entered, the function will delete the first group of log entries recorded during the interval.

If you only specify a stop time and the number of log entries before this time exceeds the count entered, the function will delete the first group of log entries recorded before the stop time.

If you do not enter a start or stop time, the function will delete all log entries for the applicable data points, up to the maximum.

The following call to DataLoggerClear deletes up to 200 log entries for data point NVL_nviDlCount2. These entries must have occurred between 1/27/2002 and 11/28/2002 (both at one hour ahead of UTC) to be deleted.

i.LON 100 Internet Server Programmer’s Reference 6-15

<Data> Parameter

<Result> Parameter

<Data> <iLONDataLogger> <Log> <UCPTindex>2</UCPTindex> <UCPTpointName>NVL_nviDlCount2</UCPTpointName> <UCPTstart>2002-01-27T00:00:00.000+01:00</UCPTstart> <UCPTstop>2002-11-28T00:00:00.000+01:00</UCPTstop> <UCPTcount>3</UCPTcount> </Log> </iLONDataLogger> </Data>

The DataLoggerClear function includes several properties in the <Result> parameter. These properties provide information about the Data Logger and the log file affected by the function. Table 20 describes these properties.

Table 20 DataLoggerRead Output Properties

Property Description

The index number assigned to the Data Logger.

The name of the log file the Data Logger is using.

The volume of the log file that has been consumed, as a percentage. For example, the value 90.0 indicates that the log is 90% full.

i.LON 100 Internet Server Program6-16 mer’s Reference

6.2.1.6 DataLoggerDelete

You can use the DataLoggerDelete function to delete a Data Logger. You must reference the Data Logger to be deleted by its index number in the <Data> parameter you supply to the function, as in the example below.

<Data> Parameter

<Result> Parameter

i.LON 100 Internet Server Programmer’s Reference 6-17

7 Alarm Generator

Use the Alarm Generator application to generate alarms based on the values of the data points in your network. Each time you create an Alarm Generator, you will select an input data point and a compare data point. The Alarm Generator will compare the values of these data points each time either one is updated. You will select the function the Alarm Generator will use to make the comparison. If the result of the comparison is true, an alarm will be generated, and the status (UCPTpointStatus) of the input data point will be updated to an alarm condition.

For example, you could select GreaterThan as the comparison function. The Alarm Generator would generate an alarm each time either data point is updated, and the value of the input data point is greater than the value of the compare data point. The Alarm Generator application includes many other comparison functions like this, such as Less Than, Less Than or Equal, Greater Than or Equal, Equal, and Null. Each comparison function is described in detail later in the chapter.

The Alarm Generator application also includes a comparison function called Limits. When you select this comparison function, you will specify four offset limits for the Alarm Generator. The four offset limits allow you to generate alarms based on how much the value of the input data point exceeds, or is exceeded by, the value of the compare data point. If the compare or input data points are updated, and the difference between their values exceeds any of the offset limits, an alarm will be generated.

You will define a hysteresis level for each alarm offset limit when you use the Limits comparison function. After an alarm has been generated based on an offset limit, the value of the input data point must return to the hysteresis level defined for that offset limit before the alarm clears, and before another alarm can be generated based on that offset limit. As a result, the Alarm Generator will not generate an additional alarm each time the input data point is updated after it reaches an alarm condition, but before it has returned to a normal condition. The relationship between the offset values, hysteresis levels, and alarm data points is described in more detail in the following sections.

All of the comparison functions have features like this that will allow you to throttle alarm generation. You can specifiy an interval (UCPTalarmSetTime) that must elapse between alarm generations for a data point. You can also define an interval (UCPTalarmClrTime) that must elapse after an alarm has returned to normal status before that alarm will be cleared. These features prevent the Alarm Generator from triggering multiple alarms each time the input data point reaches an alarm condition.

You can optionally select up to two alarm data points for each Alarm Generator, one of type SNVT_alarm and one of type UNVT_alarm2. The <UCPTpointStatus> of these data points, and of the input data point, will be updated to an alarm condition each time the Alarm Generator generates an alarm. The alarm data points are described in more detail later in the chapter.

You can use the Alarm Notifier application to generate e-mail messages when the alarm and input data points are updated to alarm conditions. For more information on this, see Chapter 9, Alarm Notifier.

i.LON 100 Internet Server Programmer’s Reference 7-1

7.1 AlarmGenerator.XML

The AlarmGenerator.XML file stores the configuration of the Alarm Generators that you have added to the i.LON 100. Each Alarm Generator is signified by an <Alarm> element in the XML file.

You can create new Alarm Generators using the AlarmGeneratorSet SOAP function, or by manually editing the AlarmGenerator.XML file, and rebooting the i.LON 100. The sections following this example provide instructions and guidelines to follow when doing so.

The following represents a sample AlarmGenerator.XML file for an i.LON 100 with one defined Alarm Generator.

xml version="1.0" ?>

LONAlarmGenerato

<i r>

<UCPTlastUpdate>2002-06-20T12:37:53Z UCPTlastUpdate> </

<UCPTdescrip >Heating Control</UCPTdescription> tion

<UCPTfbName>Alarm Generator- 0</UCPTfbName>

<UCPTalarmPriority>PR_LEVEL_1</UCPTalarmPriority>

<UCPTpointName>NVL_DataValueA1</UCPTpointName> </InputDataPoint> <CompareDataPoint>

<UCPTpointName>NVL_CompareValueA1</UCPTpointName> </CompareDataPoint> <AlarmDataPoint>

<UCPTpointName>NVL_AlarmGenOut1</UCPTpointName> </AlarmDataPoint> <Alarm2DataPoint>

<UCPTpointName>NVL_AlarmGenOut2</UCPTpointName> </Alarm2DataPoint> <UCPTcompFunction>FN_LIMIT</UCPTcompFunction> <UCPTalarmSetTime>

5.0</UCPThighLimit1Offset> <UCPThighLimit1Offset> <UCPThighLimit2Offset>5.0</UCPThighLimit2Offset> <SCPThystHigh1>50.00</SCPThystHigh1> <SCPThystHigh2 75.00</SCPThystHigh2> > <SCPThystLow1>50.00</SCPThystLow1> <SCPThystLow2>75.00</SCPThystLow2>

</Alarm>

</iLONAlarmGenerator>

0 03:00:00.000</SCPTalrmIhbT>

0 00:30:00.000</UCPTalarmSetTime> 0 00:45:00.000</UCPTalarmClrTime>

7-2 mer’s Reference

i.LON 100 Internet Server Program

7.2 Creating and Modifying the AlarmGenerator.XML File

You can create and modify the AlarmGenerator.XML file with the AlarmGeneratorSet SOAP function. The following section, Alarm Generator SOAP Interface, describes how to use AlarmGeneratorSet, and the other SOAP functions provided for the Alarm Generator application.

Alternatively, you can create and modify the AlarmGenerator.XML file manually using an XML editor, and download the file to the i.LON 100 via FTP. Echelon does not recommend this, as the i.LON 100 will require a reboot to read the configuration of the downloaded file. Additionally, the i.LON 100 performs error checking on all SOAP messages it receives before writing to the XML file. It will not perform error checking on any XML files you download via FTP, and thus the application may not boot properly.

However, if you plan to create and manage the XML file manually, you should review the rest of this chapter first, as it describes the elements and properties in the XML file that define each Alarm Generator’s configuration. For instructions on creating or modifying an XML file manually, see Manually Modifying an XML Configuration File on 15-1.

7.2.1 Alarm Generator SOAP Interface

The SOAP interface for the Alarm Generator application includes four functions. Table 21 lists and describes these functions. For more information, see the sections following Table 21.

Table 21 Alarm Generator SOAP Functions

Function Description

AlarmGeneratorList Use this function to generate a list of the Alarm Generators that

you have added to the i.LON 100. For more information, see AlarmGeneratorList on page 7-4.

AlarmGeneratorGet Use this function to retrieve the configuration of an Alarm

Generator. For more information, see AlarmGeneratorGet on page 7-5.

AlarmGeneratorSet Use this function to create a new Alarm Generator, or to overwrite

the configuration of an exisiting Alarm Generator. For more information, see AlarmGeneratorSet on page 7-16.

AlarmGeneratorDelete Use this function to delete an Alarm Generator. For more

information, see AlarmGeneratorDelete on page 7-17.

i.LON 100 Internet Server Programmer’s Reference 7-3

7.2.1.1 AlarmGeneratorList

Use the AlarmGeneratorList function to retrieve a list of the Alarm Generators that you have added to the i.LON 100. The AlarmGeneratorList function takes an empty string as its <Data> parameter, as in the example below.

The function returns the major and minor version numbers of the firmware implementation that the Alarm Generator application is using in the <Result> parameter. The <Result> parameter also includes an <Alarm> element for each Alarm Generator that you have added to the i.LON 100. The next section, AlarmGeneratorGet, describes the properties included in each <Alarm> element.

You could use the list of <Alarm> elements returned by this function as input for the AlarmGeneratorGet function. The AlarmGeneratorGet function would then return the configuration of every Alarm Generator included in the list.

<Data> Parameter

<Result> Parameter

Empty String

<Result> <iLONAlarmGenerator> <SCPTobjMajVer>1</SCPTobjMajVer> <SCPTobjMinVer>1</SCPTobjMinVer> <Alarm> <UCPTindex>0</UCPTindex> <UCPTdescription>Light Control</UCPTdescription> <UCPTfbName>Alarm Generator- 0</UCPTfbName> <UCPTlastUpdate>2002-06-20T12:37:05Z</UCPTlastUpdate> </Alarm> <Alarm> <UCPTindex>1</UCPTindex> <UCPTdescription> Heating Control </UCPTdescription> <UCPTfbName> Alarm Generator- 1</UCPTfbName> <UCPTlastUpdate>2002-06-25T18:45:18Z </UCPTlastUpdate> </Alarm> </iLONAlarmGenerator> </Result>

i.LON 100 Internet Server Program7-4 mer’s Reference

7.2.1.2 AlarmGeneratorGet

You can use the AlarmGeneratorGet function to retrieve the configuration of any Alarm Generator that you have added to the i.LON 100. You must reference the Alarm Generator whose configuration is to be retrieved by its index number in the <Data> parameter you supply to the function, as in the example below.

<Data> Parameter

<Result> Parameter

<Result> <iLONAlarmGenerator> <Alarm> <UCPTindex>1</UCPTindex> <UCPTlastUpdate>2004-05-14T19:21:39Z</UCPTlastUpdate> <UCPTdescription>Heating Controller</UCPTdescription> <UCPTfbName>Alarm Generator- 1</UCPTfbName> <SCPTalrmIhbT>0 00:00:00.000</SCPTalrmIhbT> <UCPTalarmPriority>PR_LEVEL_1</UCPTalarmPriority> <UCPTpollOnResetDelay>0.0</UCPTpollOnResetDelay> <UCPTpollRate>0.0</UCPTpollRate> <UCPTalarm2Description>none</UCPTalarm2Description> <InputDataPoint> <UCPTpointName>NVL_nviTemp0</UCPTpointName> </InputDataPoint> <CompareDataPoint> <UCPTpointName>NVL_nviTemp1</UCPTpointName> </CompareDataPoint> <AlarmDataPoint> <UCPTpointName>NVL_nvoAlarm0</UCPTpointName> </AlarmDataPoint> <Alarm2DataPoint> <UCPTpointName>NVL_nvoAlarm2</UCPTpointName> </Alarm2DataPoint> <UCPTcompFunction>FN_LIMIT compFunction> <UCPTalarmSetTime>0 00:00:00.000</UCPTalarmSetTime> <UCPTalarmClrTime>0 00:00:00.000</UCPTalarmClrTime> <UCPTlowLimit1Offset>4.0</UCPTlowLimit1Offset> <UCPTlowLimit2Offset>8.0</UCPTlowLimit2Offset> <UCPThighLimit1Offset>4.0</UCPThighLimit1Offset> <UCPThighLimit2Offset>8.0</UCPThighLimit2Offset> <SCPThystHigh1>2.0</SCPThystHigh1> <SCPThystHigh2>2.0</SCPThystHigh2> <SCPThystLow1>2.0</SCPThystLow1> <SCPThystLow2>2.0</SCPThystLow2> </Alarm> </iLONAlarmGenerator> </Result>

</UCPT

The function returns an <Alarm> element for each Alarm Generator referenced in the <Data> parameter you supplied to the function. The properties contained within each

i.LON 100 Internet Server Programmer’s Reference 7-5

<Alarm> element are initially defined when you create the Alarm Generator. You can write to them with the AlarmGeneratorSet function. Table 22 describes these properties.

When creating or writing to an Alarm Generator with the AlarmGeneratorSet function, all properties are mandatory unless otherwise noted. For more information on the AlarmGeneratorSet function, see AlarmGeneratorSet on page 7-16.

Table 22 AlarmGeneratorGet Output Properties

Property Description

The index number assigned to the Alarm Generator must be in the range of 0-32,767. As mentioned earlier, you can use the AlarmGeneratorSet function to create a new Alarm Generator, or to modify an existing Alarm Generator. If you do not specify an index number in the <Data> parameter you supply to AlarmGeneratorSet, the function will create a new Alarm Generator using the first available index number.

If you specify an index number that is already being used, the function will overwrite the configuration of the Alarm Generator using that index number with the settings defined in the <Data> parameter.

Optional. A timestamp indicating the last time the configuration of the Alarm Generator was updated. This timestamp uses the following format:

YYYY-MM-DDTHH:MM:SSZ

The first segment of the time stamp (YYYY-MM-DD) represents the date the configuration of the Alarm Generator was last updated. The second segment (THH:MM:SS) represents the time of day the configuration of the Alarm Generator was last updated, in UTC (Coordinated Universal Time).

For example, 2002-08-15T10:13:13Z indicates a UTC time of 10:13:13 AM on August 15, 2002.

The functional block name assigned to the Alarm Generator in LONMAKER. You can write to this property, but each time you use the i.LON 100 Configuration Software to view the Alarm Generator, it will be reset to match the functional block name defined in LONMAKER.

Optional. A user-defined description of the Alarm Generator. This can be a maximum of 228 characters long.

The time period for which alarm generation is to be inhibited after the application is enabled. This period must be entered using the following format:

DAYS HOURS:MINUTES:SECONDS.MILLISECONDS

For example, 3 13:44:02.155 indicates a time period of 3 days, 13 hours, 44 minutes and 2.155 seconds.

i.LON 100 Internet Server Program7-6 mer’s Reference

Property Description

Specifies the alarm priority that will be reported in the priority_level field of the alarm data points for the Alarm Generator. The alarm priority is independent of the alarm type. For a list of valid alarm priorities, see Alarm Priority Levels on page 7-11.

The time period to wait after enabling or starting the application before polling the value of the input data point. This field has a range of 0.0-

6553.0 seconds.

When the default value of 0.0 seconds is used, the Alarm Generator will resume polling the input data point at the interval specified by the <UCPTpollRate> property immediately after a reset.

The poll rate for the input and compare data points, in seconds. When this value is greater than 0, the Alarm Generator will poll the values of the input and compare data points each time this interval expires. This field has a range of 0-214,748,364 seconds.

When this value is 0, the Alarm Generator will not poll the value of the input and compare data points, and will only check for alarm conditons when it receives event-driven updates to the data points.

Optional. Enter the description field of the UNVT_alarm2 data point selected for the Alarm Generator. This data point can be selected by defining the <Alarm2DataPoint> property. This description could include the value that increased and caused the alarm, an alarm or error code defined by the manufacturer, or the alarm limit. This can be a maximum of 22 characters long, and will be inserted in the description field of the UNVT_alarm2 data point each time an alarm is generated.

i.LON 100 Internet Server Programmer’s Reference 7-7

Property Description

The input data point for this Alarm Generator. The data point must be referenced by its <UCPTpointName>.

Each time this data point is updated, its value will be compared to the value of the compare data point using the comparison function defined by the <UCPTcompFunction> property. If the result of the comparison is True, an alarm will be generated.

The <UCPTpointSatus> of this data point will be updated to the status AL_ALM_CONDITION when an alarm is generated, unless the <UCPTcompFunction> selected for the Alarm Generator is FN_LIMIT. In this case, the status will be updated to any of four alarm statuses, based on the offset limit that caused the alarm. For more information on this, see Hysteresis Levels and Offset Limits on page 7-13.

You can register the input data point with the Alarm Notifier application to generate alarm notifications and e-mail messages each time it is updated to an alarm status. For more information on this, see Alarm Notifier on page 8-1.

The compare data point for this Alarm Generator. The data point must be referenced by the <UCPTpointName> assigned to it in the Data Server, and must use the same format type as the input data point. The value of this data point will be compared to the value of the input data point each time either point is updated.

Use an NVC data point as the compare data point if you want your alarm generator to generate alarms based on a constant value configured through software, as opposed to a live value taken from the network.

7-8

i.LON 100 Internet Server Programmer’s Reference

Property Description

Optional. These properties define the Alarm Generator’s alarm data points. Each data point must be referenced by the <UCPTpointName> assigned to it in the Data Server. The data point chosen for the <AlarmDataPoint> must use the format type SNVT_alarm. The data point chosen for the <Alarm2DataPoint> must use the format type UNVT_alarm2.

Use a SNVT_alarm data point if your system can handle this LonMark standard type for alarming. Use a UNVT_alarm2 data point if your system will require the additional information you can provide with the <UCPTalarm2Description> property. If your system can directly access the <UCPTpointStatus> property of the input data point, you may not need to use alarm data points, as your Alarm Generators will update the input data point to an alarm status each time they generate an alarm. You can read this property from a data point with the DataPointRead or DataServerRead functions.

The <UCPTpointSatus> of the alarm data points will be updated to the status AL_ALM_CONDITION when an alarm is generated, unless the <UCPTcompFunction> is FN_LIMIT. In this case, the status will be updated to any of four alarm statuses, based on the offset limit that caused the alarm. For more information on this, see Hysteresis Levels and Offset Limits on page 7-13.

You can register these alarm data points with the Alarm Notifier application to generate alarm notifications and e-mail messages each time they are updated to an alarm status. For more information on this, see Alarm Notifier on page 8-1.

Specifies the function that the Alarm Generator will use to compare the values of the input data point and the compare data point. For descriptions of the comparison functions you can use, see Comparison Functions on page 7-12.

Specifies the time period an alarm condition must exist before the Alarm Generator will consider it a valid alarm and generate an alarm. You must use the following format for this property:

DAYS HOURS:MINUTES:SECONDS.MILLISECONDS

For example, 0 1:12:12.333 indicates a time period of 1 hour, 12 minutes and 12.333 seconds. The maximum value you can enter is: 0 1:59:59.999

The default value is: 0 00:00:00.000

i.LON 100 Internet Server Programmer’s Reference 7-9

Property Description

Specifies the time period to wait after the condition that caused an alarm has returned to normal status before the alarm will be cleared. You must use the following format for this property:

DAYS HOURS:MINUTES:SECONDS.MILLISECONDS

For example, 0 6:22:12.333 indicates a time period of 6 hours, 22 minutes and 12.333 seconds. The maximum value you can enter is: 0 1:59:59.999

The default value is: 0 00:00:00.000

Enter a scalar value for each of these properties. These values will be used as the offset limits for the Alarm Generator when the <UCPTcompFunction> property is set to FN_LIMIT. In this case, alarms will be generated when any of the following conditions are true:

• Value of Input Data Point> Value of Compare Data Point +highLimit1Offset

• Value of Input Data Point > Value of Compare Data Point +highLimit2Offset

• Value of Input Data Point < Value of Compare Data Point – lowLimit1Offset

• Value of Input Data Point < Value of Compare Data Point – lowLimit2Offset

The value entered for <UCPThighLimit2Offset> must be greater than that entered for <UCPThighLimit1Offset>, and the value entered for <UCPTlowLimit2Offset> must be less than that entered for <UCPTlowLimit1Offset>. The default value for each property is 0. If any of these properties are left empty, they will not be used to check for alarm conditions. When you set these properties, you must also set the corresponding hysteresis properties, which are described later in the table.

Each alarm condition caused by the offset properties will cause the <UCPTpointStatus> of the input data and alarm data points to be set to a different status. For more information on this, see see Hysteresis Levels and Offset Limits on page 7-13.

NOTE: If you use the AlarmGeneratorGet function to return the configuration of an Alarm Generator whose input or compare data points use the format type SNVT_temp_p#US or SNVT_temp#US, then the values of these properties will be displayed using the SNVT_temp_f#US format. This rule applies to all formats that use the #US specifier.

7-10

i.LON 100 Internet Server Programmer’s Reference

Property Description

When an alarm occurs based on one of the offest limits described above, the value of the input data point must reach the hysteresis value for that limit before the alarm can be cleared, and another alarm can be generated based on that offset limit.

This allows you to set up an Alarm Generator that will trigger an alarm once each time the value of the input data point reaches a certain level, as opposed to multiple times (which would occur each time the data point was updated and its value remained within the range specified by the offset limit).

Enter a scalar value for each of these properties. These values define the hysteresis level that will be used for each alarm offset limit. For a more detailed description of the hysteresis fields and how they relate to the offset limit values, see Hysteresis Levels and Offset Limits on page 7-13.

If you use the i.LON 100 Configuration Software to modify the configuration of an Alarm Generator after creating it with the SOAP/XML interface, all four hysteresis properties will be reset to the value chosen for <SCPThystHigh1>.

NOTE: If you use the AlarmGeneratorGet function to return the configuration of an Alarm Generator whose input data point uses the format type SNVT_temp_p#US or SNVT_temp#US, then the values of these properties will be displayed using the SNVT_temp_f#US format. This rule applies to all formats that use the #US specifier.

7.2.1.2.1 Alarm Priority Levels

You can select a priority level for the Alarm Generator by filling in the <UCPTalarmPriority> property. When doing so, you must reference each priority level with the identifier listed in Table 23.

Each time an Alarm Generator generates an alarm, the priority_level field of the alarm data points chosen for the Alarm Generator will be updates to the priority level chosen here.

Table 23 Alarm Priority Levels

Identifier Notes

PR_LEVEL_0 Lowest alarm priority level

PR_LEVEL_1

PR_LEVEL_2

PR_LEVEL_3 Highest alarm priority level

PR_1 Life Safety Fire Alarms

PR_2 Property Safety Fire Alarms

PR_3 Fire Supervisory Alarm

PR_4 Fire Trouble/Fault (Display)

PR_6 Fire Pre-Alarm, HVAC Critical Equipment Alarm

PR_8 HVAC Alarms (BACnet Priority 8)

i.LON 100 Internet Server Programmer’s Reference 7-11

Echelon i.LON 100 e2 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

3.3.1 Data Point Values and Priority Levels

that you must supply to the function, see DataPointWrite on page 3-3.

must supply to the function, see DataPointRead on page 3-7.

Table 7 Data Server XML Files

You can create and modify the DataLogger.XML file with the DataLoggerSet SOAP function. The following section, DataLogger SOAP Interface, describes how to use DataLoggerSet and the other SOAP functions provided for the Data Logger application.

You can create and modify the AlarmGenerator.XML file with the AlarmGeneratorSet SOAP function. The following section, Alarm Generator SOAP Interface, describes how to use AlarmGeneratorSet, and the other SOAP functions provided for the Alarm Generator application.