Echelon i.LON SmartServer 2.0 User Manual

i.LON®SmartServer 2.0

Programmer's Reference

®

078-0347-01D

Echelon, LON, LONWORKS, LonTalk, Neuron, LONMARK, 3120, 3150, LNS,
LonMaker, and the Echelon logo are trademarks of Echelon Corporation
registered in the United States and other countries. LonPoint and LonSupport
are trademarks of Echelon Corporation.

Other brand and product names are trademarks or registered trademarks of
their respective holders.

Neuron
for use in equipment or systems which involve danger to human health or
safety or a risk of property damage and Echelon assumes no responsibility or
liability for use of the Neuron

Parts manufactured by vendors other than Echelon and referenced in this
document have been described for illustrative purposes only, and may not
have been tested by Echelon. It is the responsibility of the customer to
determine the suitability of these parts for each application.

ECHELON MAKES NO REPRESENTATION, WARRANTY, OR CONDITION OF ANY
KIND, EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE OR IN ANY
COMMUNICATION WITH YOU, INCLUDING, BUT NOT LIMITED TO, ANY IMPLIED
WARRANTIES OF MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS FOR ANY
PARTICULAR PURPOSE, NONINFRINGEMENT, AND THEIR EQUIVALENTS.

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.

Printed in the United States of America.
Copyright ©1997–2010 by Echelon Corporation.
Echelon Corporation
www.echelon.com

Chips, LonPoint Modules, and other OEM Products were not designed

Chips or LonPoint Modules in such applications.

ii

Table of Contents

1 Introduction to the SmartServer 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 SmartServer SOAP/XML Interface Upgrades.................................1-2

1.4.1 Version 4.0 SOAP Message Name Schema.............................1-3

2 SOAP Messages and the SmartServer WSDL File...................... 2-1

2.1 SmartServer Naming Structure .......................................................2-1

2.2 SmartServer WSDL File..................................................................2-2

2.3 Security............................................................................................2-2

2.4 SOAP Request and Response Message Structure.........................2-2

2.4.1 SOAP Request ..........................................................................2-3

2.4.2 SOAP Response .......................................................................2-4

2.5 SOAP Messages Formats...............................................................2-4

2.5.1 SOAP Envelope.........................................................................2-5

2.5.2 SOAP Header............................................................................2-5

2.5.3 SOAP Body................................................................................2-6

2.5.4 Namespace................................................................................2-9

2.5.5 SOAP Message Schema...........................................................2-9

2.5.6 SOAP Function Types...............................................................2-9

2.5.7 SOAP Message Attributes.......................................................2-11

2.5.8 Using xSelect Statements in SOAP Message Requests ........2-11

2.6 Data Point References ..................................................................2-14

2.7 UCPTcurrentConfig.......................................................................2-15

2.8 Fault Structure...............................................................................2-15

2.9 LonString type ...............................................................................2-15

2.10 SOAP Message Examples............................................................2-15

2.10.1 Configuration Data.................................................................2-16

2.10.2 Web Binding ..........................................................................2-17

2.10.3 Data Log Read ......................................................................2-18

3 SmartServer Applications and the SOAP/XML Interface............ 3-1

3.1 Overview of SmartServer Applications............................................3-1

3.2 SmartServer XML Configuration Files.............................................3-2

3.2.1 Modifying the XML Configuration Files......................................3-2

3.3 SmartServer Resource Files ...........................................................3-3

3.3.1 Standard Network Variable Type (SNVT)

Device Resource Files...............................................................

3.3.2 Standard Configuration Property Type (SCPT)

Device Resource Files...............................................................

3.3.3 User-Defined Network Variable Type (UNVT)

Device Resource Files...............................................................

3.3.4 User-Defined Configuration Property Type (UCPT)

Device Resource Files...............................................................

3.3.5 Data Point Templates................................................................3-4

3.3.6 Data Formatting.........................................................................3-4

3.4 SOAP Functions..............................................................................3-5

3.4.1 List Functions ............................................................................3-5

3.4.2 Get Functions ............................................................................3-6

3.4.3 Set Functions.............................................................................3-6

3.4.4 Read Functions .........................................................................3-7

i.LON SmartServer 2.0 Programmer’s Reference

iii

3-3
3-3
3-4
3-4

3.4.5 Write Functions..........................................................................3-7

3.4.6 Delete Functions........................................................................3-7

3.5 Performance Issues.........................................................................3-7

4 Using the SmartServer Data Server ............................................. 4-1

4.1 Creating and Modifying the Data Point XML Files...........................4-2

4.2 Overview of the Data Point XML File ..............................................4-3

4.3 Data Server SOAP Interface ...........................................................4-4

4.3.1 Using the List Function on the Data Server...............................4-4

4.3.2 Using the Get Function on the Data Server ..............................4-5

4.3.3 Using the Set Function on the Data Server.............................4-10

4.3.4 Using the Read Function on the Data Server..........................4-11

4.3.5 Using the Write Function on the Data Server..........................4-15

4.3.6 Using the Invoke Function to Reset Data Point Priorities .......4-17

4.3.7 Data Point Values and Priority Levels.....................................4-17

4.3.8 Using the Delete Function on the Data Server........................4-18

4.4 Using the Web Binder Application.................................................4-19

4.4.1 Using the List Function on a Web Connection ........................4-20

4.4.2 Using the Get Function on a Web Connection........................4-21

4.4.3 Using the Set Function on a Web Connection ........................4-23

4.4.4 Using the Delete Function on a Web Connection ...................4-24

5 Data Loggers.................................................................................. 5-1

5.1 Overview of the Data Logger XML File ...........................................5-1

5.2 Creating and Modifying the Data Logger XML File .........................5-2

5.3 Data Logger SOAP Interface...........................................................5-3

5.3.1 Using the List Function on a Data Logger.................................5-3

5.3.2 Using the Get Function on a Data Logger.................................5-4

5.3.3 Using the Set Function on a Data Logger .................................5-8

5.3.4 Using the Read Function on a Data Logger..............................5-9

5.3.5 Using the Clear Function on a Data Logger............................5-12

5.3.6 Using the Delete Function on a Data Logger ..........................5-13

6 Alarm Generator............................................................................. 6-1

6.1 Overview of the Alarm Generator XML File.....................................6-1

6.2 Creating and Modifying the Alarm Generator XML File ..................6-2

6.3 Alarm Generator SOAP Interface....................................................6-2

6.3.1 Using the List Function on an Alarm Generator ........................6-3

6.3.2 Using the Get Function on an Alarm Generator........................6-3

6.3.3 Using the Set Function on an Alarm Generator ......................6-12

6.3.4 Using the Delete Function on an Alarm Generator .................6-13

7 Alarm Notifier ................................................................................. 7-1

7.1 Overview of the AlarmNotifier XML File ..........................................7-2

7.2 Creating and Modifying the Alarm Notifier XML File .......................7-3

7.3 Alarm Notifier SOAP Interface.........................................................7-4

7.3.1 Using the List Function on an Alarm Notifier.............................7-4

7.3.2 Using the Get Function on an Alarm Notifier.............................7-5

7.3.3 Using the Set Function on an Alarm Notifier ...........................7-17

7.3.4 Using the Read Function on an Alarm Notifier........................7-18

7.3.5 Using the Write Function on an Alarm Notifier Log File ..........7-22

7.3.6 Using the Clear Function on an Alarm Notifier Log File..........7-23

7.3.7 Using the Delete Function on an Alarm Notifier ......................7-24

8 Analog Function Block.................................................................. 8-1

8.1 Overview of the AnalogFB XML File ...............................................8-1

i.LON SmartServer 2.0 Programmer’s Reference

iv

8.2 Creatin g a n d M o di f yi n g th e A n al o g F u n ct i on a l B lo c k X M L Fi le...........8-2

8.3 Analog Functional Block SOAP Interface........................................8-2

8.3.1 Using the List Function on an Analog Functional Block............8-2

8.3.2 Using the Get Function on an Analog Functional Block............8-3

8.3.3 Using the Set Function on an Analog Functional Block ..........8-12

8.3.4 Using the Delete Function on an Analog Function Block........8-13

9 Scheduler........................................................................................ 9-1

9.1 Overview of the Scheduler XML File...............................................9-2

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

9.3 Scheduler SOAP Interface ..............................................................9-3

9.3.1 Using the List Function on a Scheduler.....................................9-4

9.3.2 Using the Get Function a Scheduler .........................................9-4

9.3.3 Using the Read Function on a Scheduler................................9-12

9.3.4 Using the Set Function on a Scheduler...................................9-14

9.3.5 Using the Delete Function on a Scheduler..............................9-17

10 Calendar........................................................................................ 10-1

10.1 Overview of the Calendar XML File...............................................10-1

10.2 Creating and Modifying the Calendar XML File.............................10-2

10.3 Calendar SOAP Interface..............................................................10-2

10.3.1 Using the List Function on a Calendar ..................................10-2

10.3.2 Using the Get Function a Calendar.......................................10-2

10.3.3 Using the Set Function on a Calendar ................................10-12

10.3.4 Using the Read Function on a Calendar .............................10-13

10.3.5 Using the Delete Function on a Calendar ...........................10-15

11 Real-Time Clock........................................................................... 11-1

11.1 Overview of the Real-Time Clock XML File...................................11-1

11.2 Creating and Modifying the Real-Time Clock XML File ................11-1

11.3 Real-Time Clock SOAP Interface..................................................11-2

11.3.1 Using the List Function on a Real-Time Clock......................11-2

11.3.2 Using the Get Function on a Real-Time Clock......................11-2

11.3.3 Using the Set Function on a Real-Time Clock ......................11-4

11.3.4 Using the Delete Function on a Real-Time Clock.................11-5

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

12.1 Overview of the Type Translator XML File....................................12-1

12.2 Creating and Modifying the Type Translator XML File..................12-2

12.3 Type Translator SOAP Interface...................................................12-2

12.3.1 Using the List Function on a Type Translator .......................12-2

12.3.2 Using the Get Function on a Type Translator .......................12-3

12.3.3 Using the Set Function on a Type Translator........................12-5

12.3.4 Pre-Defined Type Translator Rules.......................................12-6

12.3.5 Using the Delete Function on a Type Translator.................12-14

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

13.3 Type Translator Rule SOAP Interface...........................................13-2

13.3.1 Using the List Function on a Type Translator Rule...............13-3

13.3.2 Using the Get Function on a Type Translator Rule...............13-3

13.3.3 Using the Set Function on a Type Translator Rule .............13-11

13.3.4 Using the Delete Function on a Type Translator Rule ........13-12

i.LON SmartServer 2.0 Programmer’s Reference

v

14 LONWORKS Driver ......................................................................... 14-1

14.1 LONWORKS Networks.....................................................................14-1

14.1.1 Using the List Function on a LONWORKS Network .................14-1

14.1.2 Using the Get Function on a LONWORKS Network ................14-1

14.1.3 Using the Set Function on a LONWORKS Network.................14-5

14.1.4 Using the Delete Function on a LONWORKS Network..........14-11

14.2 LONWORKS Channels...................................................................14-11

14.2.1 Using the List Function on a LONWORKS Channel ..............14-11

14.2.2 Using the Get Function on a LONWORKS Channel ..............14-12

14.2.3 Using the Set Function on a LONWORKS Channel...............14-16

14.2.4 Using the Delete Function on a LONWORKS Channel..........14-16

14.3 LONWORKS Devices.....................................................................14-17

14.3.1 Using the List Function on a LONWORKS Device.................14-17

14.3.2 Using the Get Function on a LONWORKS Device .................14-19

14.3.3 Using the Set Function on a LONWORKS Device.................14-26

14.3.4 Using the Delete Function on a LONWORKS Device............14-32

14.4 Routers........................................................................................14-32

14.5 Remote Network Interface...........................................................14-34

14.6 LONWORKS Functional Blocks .....................................................14-34

14.6.1 Using the List Function on a LONWORKS

Functional Block..................................................................

14.6.2 Using the Get Function on a LONWORKS

Functional Block..................................................................

14.6.3 Using the Set Function on a LONWORKS

Functional Block..................................................................

14.6.4 Using the Delete Function on a LONWORKS

Functional Block..................................................................

14.7 Network Variables (LONWORKS Data Points)..............................14-40

14.7.1 Using the List Function on Network Variables ....................14-40

14.7.2 Using the Get Function on Network Variables ....................14-41

14.7.3 Using the Set Function on a Network Variable ...................14-45

14.7.4 Using the Delete Function on a Network Variable ..............14-45

14.8 Configuration Properties (LONWORKS Data Points).....................14-46

14.9 LONWORKS Connections..............................................................14-47

14-35
14-36
14-39
14-40

15 Modbus Driver.............................................................................. 15-1

15.1 Modbus Channels..........................................................................15-1

15.1.1 Using the List Function on Modbus Channels.......................15-1

15.1.2 Using the Get Function on Modbus Channels ......................15-1

15.1.3 Using the Set Function on Modbus Channels.......................15-5

15.1.4 Using the Delete Function on Modbus Channels..................15-6

15.2 Modbus Devices............................................................................15-7

15.2.1 Using the List Function on Modbus Devices.........................15-7

15.2.2 Using the Get Function on Modbus Devices.........................15-7

15.2.3 Using the Set Function on Modbus Devices .........................15-9

15.2.4 Using the Delete Function on Modbus Devices ..................15-10

15.3 Modbus Virtual Functional Blocks...............................................15-10

15.4 Modbus Data Points....................................................................15-10

15.4.1 Using the List Function on Modbus Data Points .................15-11

15.4.2 Using the Get Function on Modbus Data Points.................15-12

15.4.3 Using the Set Function on Modbus Data Points .................15-16

15.4.4 Using the Delete Function on Modbus Data Points ............15-17

16 M-Bus Driver................................................................................. 16-1

16.1 M-Bus Channels............................................................................16-1

i.LON SmartServer 2.0 Programmer’s Reference

vi

16.1.1 Using the List Function on M-Bus Channels .........................16-1

16.1.2 Using the Get Function on M-Bus Channels.........................16-1

16.1.3 Using the Set Function on M-Bus Channels .........................16-4

16.1.4 Using the Delete Function on M-Bus Channels ....................16-5

16.2 M-Bus Devices ..............................................................................16-6

16.2.1 Using the List Function on M-Bus Devices............................16-6

16.2.2 Using the Get Function on M-Bus Devices ...........................16-6

16.2.3 Using the Set Function on M-Bus Devices..........................16-10

16.2.4 Using the Delete Function on M-Bus Devices.....................16-11

16.3 M-Bus Virtual Functional Blocks..................................................16-11

16.4 M-Bus Data Points.......................................................................16-11

16.4.1 Using the List Function on M-Bus Data Points....................16-12

16.4.2 Using the Get Function on M-Bus Data Points ...................16-12

16.4.3 Using the Set Function on M-Bus Data Points....................16-15

16.4.4 Using the Delete Function on M-Bus Data Points...............16-16

17 Virtual Driver................................................................................. 17-1

17.1 Virtual Channels............................................................................17-1

17.1.1 Using the List Function on Virtual Channels .........................17-1

17.1.2 Using the Get Function on Virtual Channels.........................17-1

17.1.3 Using the Set Function on Virtual Channels .........................17-3

17.1.4 Using the Delete Function on a Virtual Channel ...................17-4

17.2 Virtual Devices...............................................................................17-4

17.2.1 Using the List Function on Virtual Devices............................17-4

17.2.2 Using the Get Function on Virtual Devices............................17-4

17.2.3 Using the Set Function on Virtual Devices............................17-6

17.2.4 Using the Delete Function on Virtual Devices.......................17-7

17.3 Virtual Functional Blocks...............................................................17-7

17.4 Virtual Data Points.........................................................................17-8

17.4.1 Using the List Function on Virtual Data Points......................17-8

17.4.2 Using the Get Function on Virtual Data Points......................17-9

17.4.3 Using the Set Function on Virtual Data Points....................17-11

17.4.4 Using the Delete Function on Virtual Data Points...............17-12

18 File System Data .......................................................................... 18-1

18.1 Using the List Function on File System Data................................18-1

18.2 Using the Read Function on File System Data .............................18-1

18.3 Using the Write Function on File System Data..............................18-3

18.4 Using the Delete Function on File System Data............................18-4

19 System Information Methods...................................................... 19-1

19.1 System Service Methods...............................................................19-1

19.1.1 TCP/IP Settings.....................................................................19-2

19.1.2 Time Settings.........................................................................19-4

19.1.3 Security Settings....................................................................19-5

19.1.4 Static System Information......................................................19-7

19.1.5 Real-Time System Information..............................................19-9

19.1.6 E-Mail Settings ....................................................................19-11

19.1.7 IP-852 Router Settings ........................................................19-12

19.1.8 IP-852 Router Statistics.......................................................19-14

19.1.9 LonScanner Protocol Analyzer............................................19-15

19.1.10 Reboot...............................................................................19-16

19.2 System Test Methods..................................................................19-16

19.2.1 SMTP E-Mail Server Test....................................................19-16

19.2.2 IP-852 Configuration Server Test........................................19-19

19.2.3 Connection Test ..................................................................19-20

i.LON SmartServer 2.0 Programmer’s Reference

vii

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

20.1 Referencing and Inheriting from the WSDL...................................20-1

20.1.1 Referencing and Inheriting from the WSDL

Using .NET 3.5 Framework...................................................

20.1.2 Referencing and Inheriting from the WSDL

Using .NET 2.0 Framework...................................................

20.2 Instantiating and Initializing the Web Service Client ...................20-11

20.2.1 Instantiating the Web Service Client in

Visual C# .NET 3.5..............................................................

20.2.2 Instantiating the Web Service Client in

Visual C# .NET 2.0..............................................................

20.2.3 Instantiating the Web Service Client in

Visual Basic .NET 3.5..........................................................

20.3 Calling Web Services Methods....................................................20-14

20.3.1 Reading and Writing Data Point Values in

Visual C# .NET 3.5..............................................................

20.3.2 Reading and Writing Data Point Values in

Visual C# .NET 2.0..............................................................

20.3.3 Reading and Writing Data Point Values in

Visual Basic .NET 3.5..........................................................

20.4 Accepting a Web Binding From a SmartServer...........................20-20

20-1
20-6

20-11
20-13
20-14

20-15
20-16
20-19

21 Programming Examples.............................................................. 21-1

21.1 Visual C#.NET Examples..............................................................21-1

21.1.1 Reading and Writing Data Point Values in

Visual C# .NET......................................................................

21.1.2 Creating and Reading a Data Logger in Visual C# .NET......21-2

21.1.3 Creating a Scheduler and Calendar in

Visual C# .NET......................................................................

21.1.4 Creating and Installing a LONWORKS Device in

Visual C# .NET....................................................................

21.1.5 Commissioning External Devices in

Visual C# .NET....................................................................

21.1.6 Discovering and Installing External Devices

in Visual C# .NET................................................................

21.1.7 Configuring the SmartServer in

Visual C# .NET....................................................................

21.2 Visual Basic.NET Examples........................................................21-30

21.2.1 Reading and Writing Data Point Values in

Visual Basic.NET.................................................................

21.2.2 Creating and Reading a Data Logger in

Visual Basic. NET...............................................................

21.2.3 Creating a Scheduler and Calendar in

Visual Basic.NET.................................................................

21.2.4 Creating and Installing a LONWORKS Device in

Visual Basic.NET.................................................................

21.2.5 Commissioning External Devices in

Visual Basic.NET.................................................................

21.2.6 Discovering and Installing External Devices in

Visual Basic.NET.................................................................

21.2.7 Configuring the SmartServer in Visual Basic.NET..............21-51

21-1

21-7
21-15
21-18
21-21
21-26

21-30
21-31
21-34
21-42
21-44
21-47

22 Programming the SmartServer with Java.................................. 22-1

22.1 Setting up the Java Programming Environment............................22-1

i.LON SmartServer 2.0 Programmer’s Reference

viii

22.1.1 Installing Echelon SmartServer JAX-ES

Programming Example..........................................................

22.1.2 Installing Eclipse IDE for Java EE Developers......................22-1

22.1.3 Installing the Java Development Kit ......................................22-1

22.1.4 Installing Maven 2.2.1............................................................22-1

22.1.5 Setting System Environment Variables.................................22-2

22.2 Creating a JAX-WS Client.............................................................22-3

22.3 Java Programming Examples......................................................22-17

22.3.1 Reading and Writing Data Point Values in Java .................22-17

22.3.2 Creating and Reading a Data Logger in Java.....................22-19

22.3.3 Creating and Installing a LONWORKS Device in Java ..........22-23

22.3.4 Discovering and Installing External Devices in JAVA .........22-26

22-1

Appendix A: SOAP Tester Example...................................................A-1

i.LON SmartServer 2.0 Programmer’s Reference

ix

i.LON SmartServer 2.0 Programmer’s Reference

x

1 Introduction to the SmartServer SOAP/XML Interface

The SmartServer 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 with the
SmartServer Web pages, as described in the i.LON SmartServer 2.0 User’s Guide. The i.LON
SmartServer 2.0 User’s Guide provides instructions to follow when configuring the SmartServer
applications with the SmartServer Web interface, as well as general information on the different
SmartServer applications, and guidelines to follow when using these applications.

You can also use the SOAP/XML interface provided with the SmartServer to configure 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 a
protocol for exchanging XML-based messages over TCP/IP networks, normally using HTTP. SOAP
enables different applications and devices to communicate with each other, regardless of platform, by
sending SOAP messages to each other.

The configuration of each SmartServer application is stored in an XML file. The SmartServer 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 SmartServer 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 SmartServer. The content of the SOAP message is based on the input you supply to the
function. The SmartServer 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 SmartServer is operating.

It is important to note that the XML files described in this document store the configurations of the
SmartServer applications. They do not store the data generated by these applications. The real-time
data generated by the SmartServer's applications is stored in RAM and log data are stored on the flash
disk.

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

1.1

About This Document

This document describes the XML files that store the configurations of the various SmartServer
applications, and the SOAP functions you can use with each application. The SOAP interface
provided with the SmartServer 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 SmartServer applications by manually creating and

modifying the XML configuration files. Once you have created the XML files, you can download
them to the SmartServer via FTP. The SmartServer will read the downloaded files and adjust its
operating parameters accordingly the next time it is rebooted.

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 SmartServer, and
instructions to follow when downloading these files to the SmartServer. The XML files used by the
SmartServer applications conform to the XML 1.0 Technical Recommendation:

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

i.LON SmartServer 2.0 Programmer’s Reference

1-1

Echelon strongly recommends that you use the SOAP interface to configure the applications of
your SmartServer. The SmartServer 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 SmartServer 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
SmartServer while it is operating, and the SmartServer 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 SmartServers, and would like to use the same configuration on
each one. In that case, you could configure one of the SmartServers, copy its XML files, and
download them to the appropriate directories of the other SmartServers to obtain the same
configuration in all of them.

1.2

Programming Samples

Chapter 21 of this document includes programming samples written in
.NET, and Java

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 Chapters 2 and 3 before proceeding to the rest of this document and learning about
the functions and applications of the SOAP/XML interface. Chapter 2,

SmartServer WSDL, describes the WSDL file which defines the SOAP/XML interface. Chapter 3,
SmartServer Applications and the SOAP/XML Interface, provides an overview of the SmartServer

applications and includes a roadmap to follow when configuring those applications with a SOAP
application.

You can begin to learn how to program the SmartServer using SOAP/XML using the iLON SOAP
Tester (version 2.0.3994). The SOAP Tester is an unsupported engineering-level tool provided by
Echelon that lets you perform functional testing of the SmartServer’s pre-defined SOAP functions and
your user-defined SOAP functions. You can do w nl oad the SOAP Tester from the i.LON SmartServer
Community Web site at

4.03), the SOAP Tester is also included on the i.LON SmartServer 2.0 DVD in the
iLon100\iLon100\unsupported\SoapTester folder. For more information on using the SOAP Tester,

Appendix A: SOAP Tester Example.

see
You can also learn how to program the SmartServer using SOAP/XML by installing an HTTP

debugging proxy program like Charles on your computer. The Charles proxy records all SOAP and
other HTTP traffic to and from your computer. You can use Internet Explorer to perform normal
operations with the SmartServer Web interface and record the SOAP messages that are being sent to
the SmartServer. You can download a free trial version of the Charles proxy from the Charles Web
site. For more information on using and downloading the Charles proxy, go to the Charles Web site at

www.charlesproxy.com.

to illustrate concepts described in this manual. To make these samples more easily

http://ilonsmartserver.com/files. If you have a SmartServer 2.0 (Release

Visual C# .NET, Visual Basic

SOAP Messages and the

1.4

SmartServer SOAP/XML Interface Upgrades

The format and contents of the SOAP messages you can send to a SmartServer are defined by the
SOAP namespace that the SmartServer is using. The SOAP/XML interface used for the SmartServer
(software version 4.0) is new. It uses a common set of generic methods (list, get, set, delete, read,
write, clear, and invoke) for retrieving and configuring the data of the various SmartServer
applications. This differs from the SOAP/XML interface that was used for e3 (software version 3.0)
release, in which each application had its own specialized set of messages and structures.

There have been three different SOAP namespaces introduced during the four releases of the i.LON
servers. The version 1.0 namespace was introduced for Release 1.0, the version 1.1 namespace was

i.LON SmartServer 2.0 Programmer’s Reference

1-2

introduced for the e2 release, and the version 3.0 namespace was introduced for the e3 release.
Support for the different namespaces as follows:

• i.LON 100 servers running the Release 1.0 software only support the version 1.0 namespace. This

means that a SmartServer running the Release 1.0 software can only respond to SOAP messages
from other SmartServers running the Release 1.0 software.

• i.LON 100 servers running the e2 software support the version 1.0 and 1.1 namespaces. This

means that an i.LON 100 server running the e2 software can respond to SOAP messages from
other i.LON 100 servers that are running the Release 1.0 or the e2 software.

• i.LON 100 servers running the e3 software support the version 1.1 and 3.0 namespaces. This

means that i.LON 100 servers running the e3 software can respond to SOAP messages sent from
other i.LON 100 servers that are running the e2 or e3 software.

• SmartServers running the SmartServer software support only the version 4.0 namespace. This

means that SmartServers running the SmartServer software can respond to SOAP messages sent
from other SmartServers. SmartServers running the SmartServer software cannot respond to
SOAP messages sent from i.LON 100 servers running the e3 software.

The following section,
SOAP/XML interface between SOAP namespace versions ‘3.0’ and ‘4.0’ (i.e. between the e3 and
SmartServer releases).

Note: This manual often refers to the i.LON 100 and SmartServer releases by the version numbers
used in their SOAP namespace. For example, the SmartServer release is referred to by its software
version number, which is ‘4.0’, and the i.LON 100 e3 release is referred to as ‘3.0’. For more
information on the SOAP namespace, see

1.4.1

Version 4.0 SOAP Message Name Schema

The SOAP/XML interface used for the SmartServer (version 4.0) uses a new message name schema.
It uses a common set of generic methods (List, Get, Set, Delete, Read, Write, Clear, and Invoke) for
retrieving and configuring the data of the var i ous SmartServer applications. This section provides an
overview of the changes made to the SOAP message name schema from version 3.0.

Version 4.0 SOAP Message Name Schema, describes the changes made to the

Chapter 2 of this document.

1.4.1.1 Version 3.0 Message Name Schema

The message name schema used for version 3.0 was <Application>_<Message>_<Parameter>. The
Parameter was optional and normally not used. The Message was normally List, Get, Set or Delete.

The following provides examples of version 3.0 request messages:

TypeTranslator_List, TypeTranslator _ Ge t_Rule, Read, DriverMOD_Set_Template

The response messages were identified by the message name plus the string <Response>.
The schema was: <Application>_<Message>_<Parameter>Response.

With the version 3.0 message name schema, there were numerous specialized SOAP messages and
SOAP structures, resulting in limited flexibility and intricate handling of a large number of Java or C#
proxy classes.

1.4.1.2 Version 4.0 Message Name Schema

Version 4.0 uses a single set of messages that are common to all applications. The messages for
retrieving and modifying configurat i o n dat a con si s t s of List, Get, Set, and Delete, and the messages for
retrieving and changing state information are Read and Write.

i.LON SmartServer 2.0 Programmer’s Reference

1-3

i.LON SmartServer 2.0 Programmer’s Reference

1-4

2 SOAP Messages and the SmartServer 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:

•

SmartServer Naming Structure. The section describes how the SmartServer’s data configuration is organized.

•

SmartServer WSDL File. This section describes the version 4.0 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. This section describes the security provided by the SmartServer for SOAP applications.

•

•

SOAP Request/Response Structure. This section demonstrates the structure of the SOAP request
and response messages used by Version 4.0.

•

SOAP Message Formats. This section describes the formats that must be used for all SOAP
messages that are sent to and from the SmartServer. A SOAP message is sent to the SmartServer
each time you invoke any of the functions described in this document.

Data Point References. The section describes the SmartServer’s new method for refere n ci ng dat a

•

points on the SmartServer’s embedded applications.

•

UCPTCurrentConfig. This section describes the new <UCPTcurrentConfig> element included in
List response messages. This element indicates the namespace version of the client that last set the

configuration of an item.
Fault Structure. This section describes the new <Fault> structure, which combines the faultcode

•

and faultstring elements and enables a client to check only for the existence of a fault structure
instead of having to check for both elements.

LonString Type. This section describes the E_LonString type that is used for enumerations or

•

element values that have format descriptions that depen d o n refe rences to ot her dat a point formats.

•

SOAP Examples. This section includes SOAP examples that demonstrate how to use the Version

4.0 SOAP interface to get the configuration of data point, write a value to a data point in a Web
connection, and read the data in a data logger.

2.1

SmartServer Naming Structure

The naming convention used for the SmartServer’s configuration and data items follows the

ONWORKS network hierarchy (network/channel/device/functional block/data point).

L
When the SmartServer accesses a device, that device is attached to a given channel in a network. In

the same manner, a data point exists on a functional block that is part of the device. This structure is
reflected by the network/channel/device/functional block/data point naming scheme.

Assuming that there is a channel named “myChannel” on a network called “myNetwork”, the name of a
device accessed through “myChannel” must begin with “myChannel”. For example, the default
<UCPTname> property of the internal automated system device on the SmartServer (i.LON App) is
Net/LON/i.LON App. This means that the SmartServer is located on a channel named LON on a
network named Net. Further consider that i.LON App has a Digital Input 1 functional block that
contains an nvoClsValue_1 data point. By default, the <UCPTname> property of the nvoClsValue_1
data point is Net/LON/iLON App/Digital Input 1/nvoClsValue_1. Note that a <UCPTname>
property has to have at least the size of one char and must be unique in the
network/channel/device/functional block/data point collection.

i.LON SmartServer 2.0 Programmer’s Reference

2-1

2.2

SmartServer WSDL File

Each SmartServer includes two WSDL (Web Service Description Language) files: iLON100.wsdl and
iLON100_System.wsdl.

The iLON100.wsdl file defines most of the SmartServer SOAP/XML interface, and contains all the
information an application will require to use the SOAP/XML interface. The iLON100_System.wsdl
contains the system service methods used to check and configure the SmartServer’s settings.

When writing applications to use the SOAP/XML interface, some tools can import these WSDL files
and automatically build a class structure for sending and receiving each message. The WSDL files are
compatible with numerous programming development environments, such as Microsoft

®

Studio
For more detailed information on using a WSDL file as a web service in a .NET programming

environment, see
follow when you reference the version 4.0 WSDL file with a Microsoft Visual Studio project. For
more detailed information on using a WSDL file as a web service in a Java programming environment,
see

2.3

Security

You can add a basic level of security to the SOAP/XML interface with the i.LON Web Server
Security and Parameters program. You can use this utility to add password protection to all web

content served by the SmartServer. Basic Access Authentication is the security mechanism used by
the SmartServer Web server for HTTP transactions. Basic Access Authenti cat i on is described by the
IETF in RFC 2617:

2008, Microsoft Visual Studio 2005, and Eclipse JAVA EE

Chapter 20. In addition, Chapter 20 contains step-by-step instructions you can

Chapter 22.

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

.

®

Visual

If you want all SOAP messages sent to your SmartServer to be authenticated, use the i.LON Web
Server Security and Parameters program to password protect the SmartServer SOAP endpoint at the
following path: /WSDL/v4.0/iLON100.WSDL.

A user name and password will then be required each time a SOAP message is sent to the SmartServer.
Since SOAP uses HTTP as a transport, you can use the user name and passwo r d pair fo r an e nti re
HTTP session. As a result, you can use a single user name and password to authenticate access to Web
pages that send or receive multiple SOAP messages. If a SOAP message is sent to a SmartServer 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 Appendix C of the i.LON SmartServer 2.0
User’s Guide.

To protect FTP access to the XML configuration files, the SmartS erver re quires a user name and
password for every FTP session. This username and password default to “ilon”, and can be re-defined
with the Setup - Security Web Page. See Chapter 3 of the i.LON SmartServer 2.0 User’s Guide for
how to use this Web page.

2.4

SOAP Request and Response Message Structure

This section demonstrates the generic format of a complete request/response transaction. Italicized
text denotes type definitions and values that are based on the message or use-case. For examples of
actual request/response transactions, see Section 2.10,

SOAP Message Examples.

i.LON SmartServer 2.0 Programmer’s Reference

2-2

2.4.1

SOAP Request

<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Header>
<p:messageProperties xmlns:p="http://wsdl.echelon.com/web_services_ns/ilon100/v4.0/message/">
</p:messageProperties>
</soap:Header>
<soap:Body>
<MessageName xmlns="http://wsdl.echelon.com/web_services_ns/ilon100/v4.0/message/">

<iLonItem>

<xSelect>xSelectStatement</xSelect>
<Item xsi:type=“type”>
<UCPTname>networkName/channelName/deviceName/functionBlockName/pointName<UCPTname>
<Parameter1>Parameter1Value</Parameter1>

<Parameter2>Parameter2Value</Parameter2>
...
</Item>
<Item xsi:type=“type”>
<UCPTname>networkName/channelName/deviceName/functionBlockName/pointName1<UCPTname>
<Parameter1>Parameter1Value</Parameter1>

<Parameter2>Parameter2Value</Parameter2>
...
</Item>
...
</iLonItem>
</MessageName>
</soap:Body>
</soap:Envelope>

i.LON SmartServer 2.0 Programmer’s Reference

2-3

2.4.2

SOAP Response

<?xml version="1.0" encoding="utf-8" ?>
<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENV=http://schemas.xmlsoap.org/soap/envelope/
xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Header>
<p:messageProperties xmlns:p="http://wsdl.echelon.com/web_services_ns/ilon100/v4.0/message/">
<p:UCPTtimeStamp>2005-02-02T11:30:15.220+01:00</p:UCPTtimeStamp>
<p:UCPTuniqueId>030000066f02</p:UCPTuniqueId>
<p:UCPTipAddress>172.25.143.222</p:UCPTipAddress>
<p:UCPTport>80</p:UCPTport>
<p:UCPTlastUpdate>2005-02-02T11:31:41Z</p:UCPTlastUpdate>
<p:UCPTprocessingTime>90</p:UCPTprocessingTime>
</p:messageProperties>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<MessageNameResponse xmlns="http://wsdl.echelon.com/web_services_ns/ilon100/v4.0/message/">

<iLonItem>

<UCPTfaultCount>0</UCPTfaultCount>
<Item xsi:type=“type”>
<UCPTname>networkName/channelName/deviceName/functionBlockName/pointName<UCPTname>

<Parameter1>Parameter1Value</Parameter1>

<Parameter2>Parameter2Value</Parameter2>
...
</Item>
<Item xsi:type=“type” >
<UCPTname>networkName/channelName/deviceName/functionBlockName/pointName1<UCPTname>

<Parameter1>Parameter1Value</Parameter1>

<Parameter2>Parameter2Value</Parameter2>
...
</Item>
...
</iLonItem>
</ MessageNameResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

2.5

SOAP Messages Formats

A SOAP message is sent to the SmartServer each time you invoke a SOAP function. The content of
the SOAP message and the affect it has on the SmartServer is based on the input you supply to the
function. Using the Set function for example, the SmartServer 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 item. The following sections go through each
part of the SOAP messages to describe the interface.

SOAP messages are XML documents that are transferred from one entity to another; therefore, the first
line in any SOAP message is always the XML version header. SOAP 1.1 and 1.2 both conform to
XML 1.0, so this line will not need to change if the SOAP version is updated.

For more information on the types referenced in this section, see the Version 4.0 XML schema type
(iLON100.xsd), which is installed in the L

ONWORKS\iLon100\images\iLon100 4.0x\web\WSDL\v4.0

folder on your computer when you install the SmartServer software.
Note: All SOAP messages sent to and from the SmartServer 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 message, as shown in the following sections. However, this restriction is not enforced by
the SmartServer software. As a result, the SmartServer 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 SmartServer. 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.

i.LON SmartServer 2.0 Programmer’s Reference

2-4

2.5.1

SOAP Envelope

The SOAP envelope is the highest level in a SOAP message. The SOAP envelope is the highest level
of a SOAP message. The SOAP envelope for any message sent to the SmartServer must conform to
the W3C SOAP 1.1 proposed Technical Recommendation:
http://www.w3.org/TR/2000/NOTE-SOAP-20000508/. The SOAP envelope portion of the sample
input message shown in section 2.3 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>

Note: The fourth line of this example includes the symbol “...” This denotes the location of the SOAP
body, which is described in section 2.5. 3.

2.5.1.1 W3C Namespaces Supported in Version 4.0

Version 4.0 supports the following W3C namespaces:

<SOAP-ENV:Envelope
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENV=http://schemas.xmlsoap.org/soap/envelope/
xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
...
</SOAP-ENV:Envelope>

2.5.2

SOAP Header

The SOAP header contains general information about the entire message. This section is also tightly
controlled by the W3C standards. Each 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.

Note: The Version 4.0 SOAP header is only used in a response message (except for the
UCPTvalueFormat for WebBinder response messages). You do not need to supply this information
for a SOAP request.

The following provides an example of a SOAP header in a SOAP response message:

<SOAP-ENV:Header>
<p:messageProperties
xmlns:p="http://wsdl.echelon.com/web_services_ns/ilon100/v4.0/message/">
<p:UCPTtimeStamp>2008-02-25T15:10:35.360-08:00</p:UCPTtimeStamp>
<p:UCPTuniqueId>030000197B82</p:UCPTuniqueId>
<p:UCPTipAddress>10.2.124.82</p:UCPTipAddress>
<p:UCPTport>80</p:UCPTport>
<p:UCPTlastUpdate>2008-02-25T19:11:19Z</p:UCPTlastUpdate>
<p:UCPTprocessingTime>90</p:UCPTprocessingTime>
</p:messageProperties>
</SOAP-ENV:Header>

The SOAP header consists of a complex type with six fields descri bi n g di f f erent pr o pert ies of the
message:

i.LON SmartServer 2.0 Programmer’s Reference

2-5

<UCPTtimeStamp>

<UCPTuniqueId>

<UCPTipAddress>

<UCPTport>

A time stamp indicating when the message was sent. Per the
ISO 8601 standard, the timestamp is in local time, with
appended time zone indicators to denote the difference between
local time and UTC.

A unique identifier assigned to the SmartServer. By default, this
is set to the third Neuron ID in the block of 16 Neuron IDs the
SmartServer. You can define the unique ID.

The IP address of the SmartServer that sent the SOAP message.
The IP address in this field depends on the network interface

used for the SOAP request/response transaction. The
SmartServer has two network interfaces: the LAN interface and
the PPP interface (modem). As a result, when the SmartServer
responds to a SOAP request from the LAN interface, the
response header will contain the LAN IP address, and when an
outgoing WebBinder SOAP message uses the LAN interface, the
SOAP request header will contain the LAN IP address.

Conversely, when a SOAP request is received over a PPP
connection, including GPRS connections, the SOAP response
header will contain the IP address of the PPP interface, and
outgoing WebBinder SOAP messages sent over the PPP
interface will contain the IP address of the PPP interface in the
request header.

The HTTP port of the SmartServer that sent the SOAP message

<UCPTlastUpdate>

<UCPTprocessingTime>

2.5.3

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.

Request messages are identified by the message name for the SOAP call, and the response messages
are identified by the message name plus the string “Response”. The message name, which serves as
the element name within the XML structure, is uniquely identified by the SmartServer namespace.

Each and every SOAP message in the version 4.0 WSDL has one parameter named <iLonItem>. The
<iLonItem> property is a structure derived from E_xSelect and has a type of Item_Coll. The SOAP
body of the sample input message shown in section 2.4 includes the following:

A timestamp indicating the last time the configuration of any of
the applications of the SmartServer was modified. After a
reboot, the timestamp is set to match the reboot time. The
timestamp is in local time.

The time elapsed in milliseconds from the server (SmartServer
or LNS Proxy Web service) receiving a SOAP request to
sending the SOAP response.

i.LON SmartServer 2.0 Programmer’s Reference

2-6

<soap:Body>
<MessageName xmlns="http://wsdl.echelon.com/web_services_ns/ilon100/v4.0/message/">

<iLonItem>

<xSelect>xSelectStatement</xSelect>
<Item xsi:type=“type”>
<UCPTname>networkName/channelName/deviceName/functionBlockName/pointName<UCPTname>

<Parameter1>Parameter1Value</Parameter1>

<Parameter2>Parameter2Value</Parameter2>
...
</Item>
...
</iLonItem>
</MessageName>
</soap:Body>

<SOAP-ENV:Body>
<MessageNameResponse xmlns="http://wsdl.echelon.com/web_services_ns/ilon100/v4.0/message/">

<iLonItem>

<UCPTfaultCount>0</UCPTfaultCount>
<Item xsi:type=“type”>
<UCPTindex>0</UCPTindex>
<UCPTname>networkName/channelName/deviceName/functionBlockName/pointName<UCPTname>

<Parameter1>Parameter1Value</Parameter1>

<Parameter2>Parameter2Value</Parameter2>
...
</Item>
...
</iLonItem>
</MessageNameResponse>
</SOAP-ENV:Body>

2.5.3.1 Fault Messages (Application Layer)

The SOAP body in the response for every function in the SOAP/XML interface contains information
indicating whether any errors occurred whil e proces sing the request. Each item instance can contain a
fault object. An item instance without a fault object indicates an item that was successfully processed.

The following examples demonstrate instances that succeeded (no fault objects), an instance that was
applied but is not valid (faultType="_warning"), and an instance that was rejected
(faultType="_error"). The <UCPTfaultCount> tag informs the client about the number of warnings
and errors that have occurred. If <UCPTfaultCount> is 0, then no faults occurred.

Example 1 (warning occurs at the item level):

<SetResponse xmlns="http://wsdl.echelon.com/web_services_ns/ilon100/v4.0/message/">
<iLonItem>
<UCPTfaultCount>1</UCPTfaultCount>
<Item>

<fault>
<faultcode faultType="_warning">4</faultcode>
<faultstring xml:lang="en-US">fault string</faultstring>
</fault>

<UCPTname>networkName/channelName/deviceName/myAG</UCPTname>
</Item>
<Item>
<UCPTname>networkName/channelName/deviceName/yourAG</UCPTname>
</Item>
</iLonItem>
</SetResponse>

Although an item instance has a warning fault code, it can still be processed. All other item instances
with a fault object can be processed.

Example 2 (error occurs at the item level):

<SetResponse xmlns="http://wsdl.echelon.com/web_services_ns/ilon100/v4.0/message/">
<iLonItem>
<UCPTfaultCount>1</UCPTfaultCount>
<Item>

i.LON SmartServer 2.0 Programmer’s Reference

2-7

<fault>
<faultcode faultType="_error">6</faultcode>
<faultstring xml:lang="en-US">Instance doesn't exist</faultstring>
</fault>

<UCPTname>Net/VirtCh/iLON App</UCPTname>
</Item>
</iLonItem>
</SetResponse>

Example 3 (error occurs at the global level):

<SetResponse xmlns="http://wsdl.echelon.com/web_services_ns/ilon100/v4.0/message/">
<iLonItem>

<UCPTfaultCount>1</UCPTfaultCount>
<fault>
<faultcode faultType="_error">3</faultcode>
<faultstring xml:lang="en-US">invalid xSelect expression</faultstring>
</fault>

</iLonItem>
</SetResponse>

Because the error occurs at the global level (the error does not occur with a specific item instance),
none of the items are processed.

2.5.3.2 Fault Messages (SOAP Layer)

The SOAP fault message is a standard way to report back unexpected SO AP behavior to the originator
of the message. This response message has a different format than the response message for a message
call that succeeds, and it adheres to a standard format for SOAP 1.1 fault messages. In Version 4.0, all
applications will stop processing when an error occurs . In addition, the applications will return with
the following message:

<?xml version="1.0" encoding="utf8" ?>
<SOAP-ENV:Envelope SOAP-ENV:encodingStyle=
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<SOAP-ENV:faultcode>1</SOAP-ENV:faultcode>
<SOAP-ENV:faultstring>soap fault</SOAP-ENV:faultstring>
<SOAP-ENV:detail>Details</<SOAP-ENV:detail>>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

http://schemas.xmlsoap.org/soap/encoding/

2.5.3.3 Error Codes

The error codes used by the SmartServer applications are as follows:

Error Code Error Description Comment

0 No Error
1 Unknown message call
2 Parameter error
3 XML/Parser Error
4 Tag missing
5 <UCPT name> missing
6 <UCPT name> not found
7 <UCPT name> invalid
8 Can’t create For example FB, Data point

9 Can’t delete For example FB, Data point
10 Can’t set For example FB, Data point
11 Format Error
12 Command failed
13 Given Data point has not the given Index
14 Data point Name not found

i.LON SmartServer 2.0 Programmer’s Reference

2-8

Error Code Error Description Comment

15 No Data

2.5.4

Namespace

The namespace uniquely identifies message names, parameters, and types within the message call. On
the SmartServer, the namespace identifier displays both the product name and the embedded software
version. This enables a mechanism to distinguish the SOAP interface of different Echelon products
and versions. To ensure that this string points to a unique name on the Internet, the namespace
includes the echelon.com domain suffix. For release 4.0 of the SmartServer the Namespace is as
follows:

2.5.5

Version 4.0 uses a single set of messages that are common to all applications. The message for
obtaining a list of items with a specific xSelect type is List. The messages for retrieving and modifying
configuration data consist of List, Get, Set, and Delete. The messages for retrieving and changing
dynamic data (for example, data point state and values) are Read and Write.

The Get, Set, and Delete messages and the Read and Write messages contain and return one element of
a collection type. There are only three Collection types which contain objects of one of the following
types: Item (for some request/responses), Item_Cfg (for configuration information), and Item_Data
(for state information).

All types defined in the schema part of the version 4.0 iLon100.wsdl file follow a strict naming
convention. The most important naming conventions you need to adhere to are as follows:

http://wsdl.echelon.com/web_services_ns/ilon100/v4.0/

SOAP Message Schema

• The prefix used is always the destination separated be an “_”, e.g.: (for example,

UFPTalarmNotifier_ or Dp_)

• Configuration item types always inherit from Item_Cfg and have the postfix “_Cfg” (for example,

UFPTalarmNotifier_Cfg or Dp_Cfg).

• State item types always inherit from Item_Data and have the postfix “_Data” (for example, UFPTalarmNotifier_Data

or Dp_Data).

• Specialized item types have the postfix “_Invoke” and are used with the general Invoke method (for exampl e,

Dp_ResetPrio_Invoke).

2.5.6

SOAP Function Types

The Item type is the common base type for all other top level types which can be added to one of the
Item collections. It contains some common elements and attributes and the fault structure. The types
Item_Cfg and Item_Data inherit from Item; therefore, Item_Cfg is the base types for any configuration
information type, and Item_Data is the base type for any state information type.

i.LON SmartServer 2.0 Programmer’s Reference

2-9

Item_Data and Item_Cfg inherit from Item

Because Item is the base class for all types passed in the Get /Set /Delete, Read /Write, and Invoke
functions, you can pass any kind of configuration or state information in the corresponding message.

Message Name Description Request Object Response Object

List Retrieves a list of Items. xSelect Item_Coll
Get Retrieves the configuration of

items.

Set Creates items or overwrites

the configuration of existing
items.

Delete Deletes an item. Item_Coll Item_Coll
Read Reads the value and status of

items.

Write Writes values or states to

items.

Invoke Sends a network management

command to a L
device or calls special
functions on applications or
data points.

All requests for information (Read and Get, and Delete and Invoke messages) are called with Item_Coll
as the collection type. Item_Coll is a collection of Item and can thus contain any type (also Item_Cfg
and Item_Data).

ONWORKS

Item_Coll Item_CfgColl

Item_CfgColl Item_Coll

Item_Coll Item_DataColl

Item_DataColl Item_Coll

Item_Coll Item_Coll

The Set-Response and Get-Request messages use the Item_CfgColl, which is a collection of types
containing configuration data. The Read-Response and Write-Request messages use the
Item_DataColl collection, which is a collection of types containing dynamic data.

i.LON SmartServer 2.0 Programmer’s Reference

2-10

Collection type Item type of

You can cast an item to a more specialized type using meta data (the xsi:type attribute) that is passed
along with the application data. The xsi:type attribute describes the actual type of an item and is
passed as an attribute of the <Item> element. If the sent type is the expected base type (Item, Item_Cfg
or, Item_Data), no xsi:type attribute is sent. For more information on xsi types, go to
www.w3.org/TR/xmlschema-1/#Instance_Document_Construction.

2.5.7

SOAP Message Attributes

Version 4.0 SOAP request messages support some attributes, and the response messages from the
SmartServer always contain all attributes. If the data type of an item is not the declared as a base type
in the SOAP request (Item, Item_Cfg, or Item_Data), the xsi:type attribute will be added to the item
instance. Note that you do not have to set the xsi:type attribute in a SOAP request if you are using a
SOAP framework like .NET or one of Java’s SOAP frameworks. This is because the xsi:type attribute
is part of the XML Schema specification, and it will be added automatically.

For more information on the xsi:type attribute, see the Version 4.0 XML schema type (iLON100.xsd),
which is installed in the L
computer when you install the SmartServer software.

2.5.8

Using xSelect Statements in SOAP Message Requests

You can use xSelect statements in List, Get, Read, and Delete messages to filter the items returned by
the function. The xSelect statement queries the item instances in a given data set and returns those
items meeting the specified criteria. The xSelect statement provides some of the functionality of the
xPath language defined by the W3C, except that you can compare strings to dates using compare
operators “<”, “>”, and “=”.

Each xSelect statement should specify an xsi (item) type. An xSelect statement may reference an item
identifier <UCPTname> and contain some predicates [predicate1] [ predicate2]. In any xSelect
statement, the predicates may include a <UCPTlastUpdate> expression and a position () expression.
Common predicates used include contains and starts-with.

The predicates are processed as a cascade of queries. For example, you could first use a
<UCPTlastUpdate> query to get the items that were updated during a specific time period and then
query items 10 to 20 returned by the first result using a position() expression.

ONWORKS\iLon100\images\iLon100 4. 0x\web\WSDL\v4.0 folder on your

i.LON SmartServer 2.0 Programmer’s Reference

2-11

The following code samples demonstrate supported xSelect statements.
Example 1 – List or Get all channels on the SmartServer:

<iLonItem>
<xSelect> = "//Item[@xsi:type="Channel_Cfg"] </xSelect>
</iLonItem>

Example 2 – List or Get all LONWORKS channels on the SmartServer that were updated after a specific
time:

<iLonItem>
<xSelect>//Item[@xsi:type="LON_Channel_Cfg"][UCPTlastUpdate >"2008-04-01T00:00:00
</xSelect>
</iLonItem>

"]

Example 3 – List or Get all LONWORKS application devices of a specific type (by name) on a specific
channel.

<iLonItem>
<xSelect>//Item[@xsi:type="LON_Device_Cfg"][contains(UCPTname,"Net/LON/DIO")]</xSelect>
</iLonItem>

Example 4 – List or Get all instantiated functional blocks on the SmartServer automated systems
device [i.LON App (internal)]:

<iLonItem>
<xSelect>//Item[@xsi:type="Fb_Cfg"][starts-with(UCPTname,"Net/LON/")][UCPThidden=0]</xSelect>
</iLonItem>

Example 4 – List, Get, or Read all data points on the Digital Input 1 functional block on the internal
i.LON App device:

<iLonItem>
<xSelect>//Item[@xsi:type="Dp_Cfg"]
[starts-with(UCPTname, "Net/LON/iLON App/Digital Input 1/")]</xSelect>
</iLonItem>

Example 5 – Get all SNVT_switch data points on the SmartServer that were updated in the time line
defined by <UCPTlastUpdate>:

<iLonItem>
<xSelect>
//Item[@xsi:type="Dp_Cfg"][UCPTformatDescription="#0000000000000000[0].SNVT_switch"]
[UCPTlastUpdate >"2008-04-01T00:00:00" and UCPTlastUpdate <"2008-04-07T00:00:00"]
</xSelect>
</iLonItem>

Example 6 – List, Get, or Read the data points on the internal i.LON App device in the time line
defined by <UCPTlastUpdate> to return a maximum of the 11th to 29th data points:

<iLonItem>
<xSelect>//Item[@xsi:type="Dp_Cfg"] [starts-with(UCPTname,"Net/LON/iLON App/")]
[UCPTlastUpdate > "2008-04-01T15:30:21Z" and UCPTlastUpdate < "2008-04-08T15:30:21Z"]
[position()>10 and position()<30]
</xSelect>
</iLonItem>

Example 7 – List or Get all instantiated Alarm Generators on the internal i.LON App device;

<iLonItem>
<xSelect>//Item[@xsi:type="UFPTalarmGenerator_Cfg"]</xSelect>
</iLonItem>

Example 8 – Read the first 10 events scheduled in a Scheduler on the internal i.LON App device:

<iLonItem>

<xSelect>//Item[@xsi:type=”UFPTscheduler_Data”]

</xSelect>
</iLonItem>

i.LON SmartServer 2.0 Programmer’s Reference

[UCPTname="Net/LON/iLON App/Scheduler"]
[UCPTeventFilter="EF_SCHEDULE"][position()<10]"

2-12

Example 9 – Select a formatter report:

xSelect = "//Item[@xsi:type=”TemplateManager_NVT_Cfg”][UCPTlanguage="enu"]

[UCPTname="#0000000000000000[0].standard"][position()>=0 and
position()<10]"

Notes:

• For List functions, you must include an xSelect statement in the SOAP message request.

• For Get, Delete, and Read functions, the xSelect statement in the SOAP message request is

optional.
o If a Get, Delete, or Read function is called only with an xSelect statement, the function returns

all items of the specified xsi type that meet the criteria specified in the xSelect statement.

o If a Get, Delete, or Read function is called with an xSelect statement and one or more item

instances, the xSelect statement is overlaid on the item instances. This means that the xSelect
statement is an and expression (not an or expression or an exclusive or expression).

• You can only filter for properties that are included in a message response (except for the

<UCPTlastUpdate> property, which you can always filter). In a List request of Dp_Cfg items
(data points on the Data Server) for example, you can filter on the <UCPTname> property, but
you cannot filter on the <UCPTformatDescription>. In a Get request of Dp_Cfg items, however,
you can filter on the <UCPTformatDescription> property because this property is returned in the
Get message response.

• The SmartServer can only process one item type (xsi:type) per SOAP message (e.g., only

Channel_Cfg, LON_Dp_Cfg, or UFPTalarmGenerator). This is also true for xSelect responses
(except for UCPTlastUpdate which is a special case), Set messages, and other SOAP commands.
The first item type specified is always the one returned in the response message.

• Not all properties can be filtered and not all filter combinations work.

2.5.8.1 xsi Types

The following section lists the common xsi (items) types that you will include in xSelect statements.
For a list of all the item types included in the SOAP interface, see the Version 4.0 XML schema type
(iLON100.xsd), which is installed in the L
folder on your computer when you install the SmartServer software

Driver Item xsi type

General (no Driver)

Network Network_Cfg
Channel Channel_Cfg
Device Device_Cfg
Functional Block Fb_Cfg

SmartServer Applications

Alarm Generator UFPTalarmGenerator_Cfg
Alarm Notifier UFPTalarmNotifier_Cfg
Analog Functional Block UFPTanalogFunctionBlock_Cfg
Calendar UFPTcalendar_Cfg
Data Logger UFPTdataLogger_Cfg
Digital Input UFPTdigitalInput_Cfg
Digital Ouput UFPTdigitalOutput_Cfg
Node Object UFPTnodeObject_Cfg
Pulse Counter UFPTpulseCounter_Cfg
Real-TimeClock UFPTrealTimeClock_Cfg
Scheduler UFPTscheduler_Cfg

ONWORKS\iLon100\images\iLon100 4.0x\web\WSDL\v4.0

i.LON SmartServer 2.0 Programmer’s Reference

2-13

Driver Item xsi type

Type Translator UFPTtypeTranslator_Cfg
Type Translator Rule UFPTtypeTranslator_Rule_Cfg

Data Point (configuration) Dp_Cfg
Data Point (data) Dp_Data
Data Point Reset Priority Dp_ResetPrio_Invoke

LONWORKS Network LON_Network_Cfg
Channel LON_Channel_Cfg
Device LON_Device_Cfg
Router LON_Device_Router_Cfg
RNI LON_Device_RNI_Cfg
Functional Block LON_Fb_Cfg
Network Variable LON_Dp_Cfg
Configuration Property LON_Cp_Dp_Cfg
Configuration Property File LON_Cp_File_Cfg

Modbus Network MOD_Network_Cfg
Channel MOD_Channel_Cfg
Device MOD_Device_Cfg
Functional Block MOD_Fb_Cfg
Data Point MOD_Cp_Dp_Cfg

M_Bus Network MBS_Network_Cfg
Channel MBS_Channel_Cfg
Device MBS_Device_Cfg
Functional Block MBS_Fb_Cfg
Data Point MBS_Cp_Dp_Cfg

Virtual Network Virtual_Network_Cfg
Channel Virtual_Channel_Cfg
Device Virtual_Device_Cfg
Functional Block Virtual_Fb_Cfg
Data Point Virtual_Cp_Dp_Cfg

2.6

Data Point References

The SmartServer has a more abstract and flexible method for referencing data points on the
SmartServer’s embedded applications by their parent functional blocks. Primarily, the data point type
is not specified by the tag name (for example, the SNVT_alarm_2 output tag is obsolete). In Version

4.0, each functional block representing a Smart Ser ver embedded application has a collection of data
point references. The data point type is specified by the dpType attribute, and it is a reference to the
data point’s programmatic name as defined in the functional profile template. Some functional
blocks also extend the base data point reference XML type. In these cases, the <DataPoint> tag also
has an xsi:type attribute with the derived type.

The following code samples demonstrate how data points on the SmartServer’s embedded applications
are referenced. In the first example, the nvoAgAlarmFlag data point on an Alarm Generator functional
block is referenced. In the second example, the nvoDlLevAlarm data point on a Data Logger
functional block is referenced:

<DataPoint dpType="nvoAlarmFlag" discrim="dir_out">
<UCPTname>Net/LON/iLON App/Alarm Generator[0]/nvoAgAlarmFlag[0]</UCPTname>
<UCPTformatDescription>#0000000000000000[0].SNVT_switch</UCPTformatDescription>
</DataPoint>

i.LON SmartServer 2.0 Programmer’s Reference

2-14

<DataPoint dpType="nvoLevelAlarm" discrim="dir_out">
<UCPTname>Net/LON/iLON App/Data Logger[0]/nvoDlLevAlarm[0]</UCPTname>
<UCPTformatDescription>#0000000000000000[0].SNVT_alarm</UCPTformatDescription>
</DataPoint>

2.7

UCPTcurrentConfig

Each application on the SmartServer stores the namespace version of the client that last set its
configuration (via a Set function) its last configuration. When a client sends a List function in a SOAP
request, the SOAP response returns the UCPTcurrentConfig tag, which contains this information. The
client should check this tag because new namespaces may contain new or different tags that older
clients will not understand.

If a SmartServer responds with a newer UCPTcurrentConfig, the client should allow the user either to
continue using the older tool with the risk that it may overwrite changes made with a newer tool, or fail
and preserve the configuration created by the new tool.

The following code demonstrates the UCPTcurrentConfig tag returned by a SOAP response after
receiving a List function in a SOAP request.

<UCPTcurrentConfig>4.0</UCPTcurrentConfig>

2.8

Fault Structure

The faultcode and faultstring are now combined in a fault structure. If a fault structure exists, both the
faultcode and faultstring elements exist. This enables a client to check only for the existence of a fault

structure instead of having to check for both elements.
The following code demonstrates the fault structure used in Version 4.0.

<fault>
<faultcode faultType="_error">4</faultcode>
<faultstring xml:lang="en-US">fault string</faultstring>
</fault>

2.9

LonString type

The Version 4.0 XML schema declares the type E_LonString, which is a string type and has a value
that represents a L
string that contains the format description of the item. The WSDL uses the E_LonString type for
enumerations or element values that have format descriptions that depend on references to other data
point formats.

The following code sample demonstrates the LonFormat attribute of the E_LonStri n g type.

<UCPTvalue LonFormat="#0000000000000000[0].SNVT_switch">100.0 1</UCPTvalue>
<UCPTvalue LonFormat="#0000000000000000[0].SNVT_switch.value">100.0</UCPTvalue>
<UCPTvalue LonFormat="#0000000000000000[0].SNVT_switch.state">1</UCPTvalue>
<UCPTvalue LonFormat="UCPTvalueDef">ON</UCPTvalue>
<UCPTpointStatus LonFormat="UCPTpointStatus">AL_NUL</UCPTpointStatus>

When you use the Read function on a data point on the Data Server (xsi type = Dp_Cfg), the
E_LonString type has a unit attribute that specifies the unit strings defined for the data point.

<UCPTvalue LonFormat="#0000000000000000[0].SNVT_switch" Unit="value, state ">0.0 0</UCPTvalue>

2.10

SOAP Message Examples

ONWORKS value. The E_LonString also contains the LonFormat attribute which is a

The following examples demonstrate how to use the Version 4.0 SOAP interface to get the
configuration of data point, write a value to a data point in a Web connection, and read the data in a
data logger.

i.LON SmartServer 2.0 Programmer’s Reference

2-15

2.10.1

Configuration Data

The following example demonstrates how to use a Get function to obtain the configuration of a data
point on the Data Server (Dp_Cfg) using the unique <UCPTname> of the data point.

Request Message

<?xml version='1.0' encoding='utf-8'?>
<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SOAP-ENV:Header>
<p:messageProperties xmlns:p="http://wsdl.echelon.com/web_services_ns/ilon100/v4.0/message/">
<p:UCPTtimeStamp>2008-04-08T11:37:32.156-07:00</p:UCPTtimeStamp>
<p:UCPTuniqueId>0300000A5BF2</p:UCPTuniqueId>
<p:UCPTipAddress>10.2.124.53</p:UCPTipAddress>
<p:UCPTport>80</p:UCPTport>
<p:UCPTlastUpdate>2008-04-08T18:22:52Z</p:UCPTlastUpdate>
<p:UCPTprocessingTime>20</p:UCPTprocessingTime>
</p:messageProperties></SOAP-ENV:Header>
<SOAP-ENV:Body>
<Get xmlns="http://wsdl.echelon.com/web_services_ns/ilon100/v4.0/message/">
<iLonItem>
<Item xsi:type="Dp_Cfg">
<UCPTname>Net/LON/iLON App/VirtFb/nviSwitch_3</UCPTname>
</Item>
</iLonItem>
</Get>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Response Message

<?xml version="1.0" encoding="utf-8" ?>
<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"><SOAP-ENV:Header>
<p:messageProperties xmlns:p="http://wsdl.echelon.com/web_services_ns/ilon100/v4.0/message/">
<p:UCPTtimeStamp>2008-04-08T11:56:41.116-07:00</p:UCPTtimeStamp>
<p:UCPTuniqueId>0300000A5BF2</p:UCPTuniqueId>
<p:UCPTipAddress>10.2.124.53</p:UCPTipAddress>
<p:UCPTport>80</p:UCPTport>
<p:UCPTlastUpdate>2008-04-08T18:22:52Z</p:UCPTlastUpdate>
<p:UCPTprocessingTime>46</p:UCPTprocessingTime>
</p:messageProperties>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<GetResponse xmlns="http://wsdl.echelon.com/web_services_ns/ilon100/v4.0/message/">
<iLonItem >
<UCPTfaultCount>0</UCPTfaultCount>
<Item xsi:type="Dp_Cfg" >
<UCPTname>Net/LON/iLON App/VirtFb/nviSwitch_3</UCPTname>
<UCPTannotation>Dp_In;xsi:type="LON_Dp_Cfg"</UCPTannotation>
<UCPThidden>0</UCPThidden>
<UCPTlastUpdate>2008-03-26T16:16:43.070-07:00</UCPTlastUpdate>
<UCPTformatDescription>#0000000000000000[0].SNVT_switch</UCPTformatDescription>
<UCPTlength>2</UCPTlength>
<UCPTdirection LonFormat="UCPTdirection" >DIR_IN</UCPTdirection>
<UCPTunit field="" >value, state</UCPTunit>
<UCPTunit field="value" >% of full level</UCPTunit>
<UCPTunit field="state" >state code</UCPTunit>
<UCPTbaseType LonFormat="UCPTbaseType" >BT_STRUCT</UCPTbaseType>
<UCPTmaxFields>2</UCPTmaxFields>
<SCPTmaxSendTime>0.0</SCPTmaxSendTime>
<SCPTminSendTime>0.0</SCPTminSendTime>
<SCPTmaxRcvTime>0.0</SCPTmaxRcvTime>
<ValueDef>
<UCPTindex>0</UCPTindex>
<UCPTname>OFF</UCPTname>
<UCPTvalue LonFormat="#0000000000000000[0].SNVT_switch" >0.0 0</UCPTvalue>

i.LON SmartServer 2.0 Programmer’s Reference

2-16