Echelon i.LON 100 e2 User Manual

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

+ 193 hidden pages