Echelon LonWorks Network XML User Manual

LonWorks® Network XML Programmer's Guide

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

Chips, LonPoint Modules, and other OEM

Products were not designed 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

Chips or

LonPoint Modules in such applications.

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–2011 by Echelon
Corporation.
Echelon Corporation
www.echelon.com

Table of Contents

Preface ..................................................................................................... v

Audience......................................................................................................... vi

Related Reading............................................................................................. vi

Content...........................................................................................................vi

For More Information and Technical Support................................................. vi

1 Using the LonMaker XML Plug-in .................................................... 1

Introduction......................................................................................................2

Using the LonMaker XML Plug-in....................................................................2

Exporting a LonMaker Network.................................................................3

Invoking the Export Feature ...............................................................3

Defining Export Automation Properties..............................................4

Importing a LonMaker Network.................................................................6

Invoking the Import Command...........................................................6

Defining Import Automation Properties ..............................................7

Troubleshooting a Director Application.....................................................8

Creating and Updating a LonMaker Network............................................8

How the LonMaker XML Plug-in Creates and Updates a Network....8

How the LonMaker XML Plug-in Updates Objects.............................9

2 Using the XML Schema................................................................... 11

XML Schema Overview.................................................................................12

Header ....................................................................................................12

Object Elements......................................................................................12

Name................................................................................................13

Handle Attribute................................................................................13

Action Attribute.................................................................................13

Setting Object Attributes and Properties Overview.......................................13

Networks.................................................................................................14

Attributes...........................................................................................14

Properties .........................................................................................14

Example............................................................................................15

Subsystems.............................................................................................15

Attributes...........................................................................................15

Properties .........................................................................................16

Example............................................................................................17

Routers....................................................................................................17

Attributes...........................................................................................17

Properties .........................................................................................17

Example............................................................................................19

Application Devices.................................................................................20

Attributes...........................................................................................20

Properties .........................................................................................21

Example............................................................................................24

Functional Blocks....................................................................................25

Attributes...........................................................................................25

Properties within Application Device Object Elements.....................25

Example............................................................................................27

Properties within Device Template Object Elements.......................27

Example............................................................................................28

Network Variables...................................................................................28

Attributes...........................................................................................28

LonWorks Network XML Programmer’s Guide iii

Properties within Application Device Object Elements.....................28

Example............................................................................................30

Properties within Device Template Object Elements.......................31

Example............................................................................................31

Message Tags.........................................................................................31

Attributes...........................................................................................31

Properties within Application Device Object Elements.....................32

Example............................................................................................32

Properties within Device Template Object Elements.......................33

Example............................................................................................33

Configuration Properties.........................................................................33

Attributes...........................................................................................33

Properties within Application Device Object Elements.....................33

Example............................................................................................34

Properties within Device Template Object Elements.......................35

Example............................................................................................35

Targets....................................................................................................35

Attributes...........................................................................................35

Properties .........................................................................................35

Example............................................................................................36

Using References.............................................................................36

Updating Connection Descriptions...................................................36

Extensions...............................................................................................37

Attributes...........................................................................................37

Properties .........................................................................................37

Example............................................................................................39

Channels.................................................................................................39

Attributes...........................................................................................39

Properties .........................................................................................39

Example............................................................................................40

Connection Descriptions.........................................................................40

Attributes...........................................................................................40

Properties .........................................................................................40

Example............................................................................................42

Device Templates ...................................................................................43

Attributes...........................................................................................43

Properties .........................................................................................43

Example............................................................................................44

Component Applications (Plug-Ins) ........................................................45

Attributes...........................................................................................45

Properties .........................................................................................45

Example............................................................................................48

Programming Example..................................................................................48

Appendix A LonWorks Network XML Schema.................................. 55

LONWORKS XML Schema........................................................................56

iv Preface

Preface

This guide describes how to create and modify a LonMaker network using the

LonMaker XML Plug-in. It explains how to start the LonMaker XML Plug-in, export

a LonMaker network to a LonMaker network XML file, and then import it back to

create a new network or update an existing network. It provides the XML schema

that defines the format of a LonMaker network XML file, and it details the actions

and attributes you can specify for the elements in a LonMaker network XML file.

LonWorks Network XML Programmer’s Guide v

Purpose

This guide explains how to programmatically interface with the LonMaker XML Plug-in to update and
create a LonMaker network.

Audience

This guide is intended for software developers creating applications interfacing with the LonMaker
XML Plug-in. The applications may be written in any language that supports COM components or
ActiveX controls, including Microsoft
should have programming experience in such a language, and familiarity with L
LNS Plug-ins, COM/ActiveX control concepts, and XML.

® Visual C# and Microsoft Visual Basic. Readers of this guide

ONWORKS technology,

Related Reading

Introduction to the LONWORKS Platform—Introduces the basics of the LONWORKS platform.
LNS Plug-in Programmer’s Guide—Describes how to write LNS plug-ins.
LNS Programmer’s Guide—Describes the standards and development methodology for creating

interoperable LNS director and plug-in applications.
LonMaker User’s Guide— Describes how to use the LonMaker Integration Tool to design,

commission, monitor and control, maintain, and manage a network.
Go to the LonMaker Web site at

and any available updates for your software. Go to
documentation.

www.echelon.com/lonmaker for the latest versions of documentation

types.lonmark.org for updated resource file

Content

This guide includes the following content:

• Using the LonMaker XML Plug-in. Explains how to write a director application that invokes the

export and import functions of the LonMaker XML Plug-in. Describes the export and import
automation properties you can set. Provides code samples that demonstrate how to invoke the
export and import commands and how to define automation properties. Describes how to create a
trace log in order to help troubleshoot your director application

• Using the XML Schema. Provides an overview of the XML schema that defines the structure and

content of a LonMaker network XML file. Explains the elements in the header of the XML file.
Describes the various object elements that may be included in the XML file and the actions that
can be performed on them during import. Lists the attributes and properties you can set for each
object element in a LonMaker network XML file. Provides examples of how each object element
appears in a LonMaker network XML file. Describes how to define target object references.
Includes a programming example that demonstrates how to export, modify, and import a
LonMaker network XML file.

• Appendix A—LonWorks Network XML Schema. Presents the XML schema that defines the

structure and content of a LonMaker network XML file.

For More Information and Technical Support

If you have technical questions that are not answered by this document, you can contact technical
support. Free e-mail support is available or you can purchase phone support from Echelon or an
Echelon support partner. See
training services.

vi Preface

www.echelon.com/support for more information on Echelon support and

You can also view free online training or enroll in training classes at Echelon or an Echelon training
center to learn more about developing devices. You can find additional information about LonMaker
training at

www.echelon.com/training.

You can obtain technical support via phone, fax, or e-mail from your closest Echelon support center.
The contact information is as follows (check

www.echelon.com/support for updates to this

information):

Region Languages Supported Contact Information

The Americas

English
Japanese

Echelon Corporation
Attn. Customer Support
550 Meridian Avenue
San Jose, CA 95126
Phone (toll-free):

1.800-258-4LON (258-4566)
Phone: [phone]
Fax: [phone]

[e-mail]

Europe

Japan

China

English
German
French
Italian

Echelon Europe Ltd.
Suite 12
Building 6
Croxley Green Business Park
Hatters Lane
Watford
Hertfordshire WD18 8YH
United Kingdom
Phone: [phone]
Fax: [phone]

[e-mail]

Japanese Echelon Japan

Holland Hills Mori Tower, 18F
5-11.2 Toranomon, Minato-ku
Tokyo 105-0001
Japan
Phone: [phone]
Fax: [phone]

[e-mail]

Chinese
English

Echelon Greater China
Rm. 1007-1008, IBM Tower
Pacific Century Place
2A Gong Ti Bei Lu
Chaoyang District
Beijing 100027, China
Phone: [phone]
Fax: [phone]

[e-mail]

Other Regions

English
Japanese

Phone: [phone]
Fax: [phone]

[e-mail]

LonWorks Network XML Programmer’s Guide vii

1

Using the LonMaker XML Plug-in

This chapter explains how to write a director application that invokes the export and

import functions of the LonMaker XML Plug-in. It describes the optional export and

import automation properties you can set. It provides code samples that demonstrate

how to invoke the export and import commands and how to define automation

properties. It describes how to create a trace log in order to help troubleshoot your

director application.

ONWORKS Network XML Programmer’s Guide 1

L

Introduction

You can speed up your network design and ensure your devices are configured correctly by creating a
custom LonMaker user interface. Creating a custom LonMaker user interface is simple: you create a
an application that reads or writes XML files and then invokes the LonMaker XML Plug-in to
automatically export the LonMaker network created and import it into an LNS application. You can
configure your custom LonMaker application so that it is the only user interface required to create a
LonMaker network, which is ideal if the network includes only devices that are supported by your
application. Alternatively, you can configure your custom application so that user interacts with it and
the resulting LonMaker network (for example, the network includes devices not supported by your
custom application). Writing a custom LonMaker user interface provides a simpler, quicker
alternative to creating a custom LNS application. It also provides a more flexible solution than
creating a Visio add-on.

To develop a custom LonMaker user interface, you need to create an application that does the
following:

1. Optionally invokes the LonMaker XML Plug-in and exports all or part of a LonMaker drawing as

an XML file. See
on exporting a LonMaker network.

2. Creates or modifies the XML file to create and configure the desired devices, functional blocks,

network variables, and network variable /message tag connections in a LonMaker network. See
Setting Object Attributes and Properties in Chapter 2 for more information on creating and
configuring LonMaker network object s

Exporting a LonMaker Network in the following section for more information

3. Invokes the LonMaker XML Plug-in and imports the XML file created into the LonMaker tool or

other LNS application. See
information on importing a LonMaker network.

Note: This document uses a series of C# code examples, created with Microsoft Visual Studio 2008,
to demonstrate the concepts being described. You can create your custom LonMaker application using
any .NET environment such as C# or Visual Basic.

Importing a LonMaker Network in the following section for more

Using the LonMaker XML Plug-in

You can use the LonMaker XML Plug-in to automate exporting and importing your LonMaker
network to an LNS application. The LonMaker XML Plug-in provides a programmatic interface to the
XML import and export features in the LonMaker tool. The LonMaker XML Plug-in is registered at
the network level; therefore, it only needs to be registered once on a computer for it to be used to
export or import any LonMaker network.

To use the LonMaker XML Plug-in to automate the exporting and importing of a network, you
implement a director application that invokes the export or import command of the LonMaker XML
Plug-in and defines the export or import automation properties. You can also define standard LNS
plug-in properties in the director application.

Director applications use the LNS Plug-In API to invoke plug-in applications. The interface between
director applications and plug-ins consists of standard ActiveX automation interfaces. This
ActiveX-based API defines an automation object that provides a standard interface between a director
application and a plug-in. Director applications can launch plug-ins and communicate with them using
the methods and properties of the automation object. A set of ActiveX exceptions is defined for
passing back error information from the plug-in to the director. See the LNS Plug-In Programmer’s
Guide for more information about using the LNS plug-in interface and API, and creating director
applications.

2 Using the LonMaker XML Plug-in

Tip: You can download an assembly provided by Echelon, named PlugInWrapper.dll, to expedite the
development of your custom LonMaker application. You can use this assembly instead of developing
your own director application. To use the PlugInWrapper.dll file, you must have LNS Turbo
Editions 3.23 (or newer) installed on your computer. The PlugInWrapper.dll file and the latest LNS
Service Pack are available on the Echelon Web site at www.echelon.com/downloads.

After you download the PlugInWrapper.dll file, add it as a reference in your development
environment. For example, if you are using Microsoft Visual Studio, click Project, click Add

Reference, click Browse, and then select the PlugInWrapper.dll file. You then reference the
PlugInWrapper.dll file in your code. You can then programmatically export and import LonMaker

networks with the LonMaker XML Plug-in following the Visual C# code samples provided in the
subsequent sections.

Exporting a LonMaker Network

You can use the LonMaker XML Plug-in to automate the exporting of a LonMaker network. To do
this, create a director application that does the following:

1. Defines the export automation properties.

2. Invokes the export command of the LonMaker XML Plug-in.

Invoking the Export Feature

The export feature of the LonMaker XML plug-in implements the Report (23) SendCommand request
and registers for a subsystem object, which consists of the object class (Subsystem, 5) and the
subsystem name. The following Visual C# code example demonstrates how you can invoke the
LonMaker XML Plug-in export command.

using System;
using System.Collections.Generic;
using System.IO;
using System.Text;
using System.Threading;
using System.Xml;
using PlugInWrapper; //reference to Echelon PluginWrapper.dll file.

//You can use download and reference this instead of
//creating your own director application.

namespace myLmXmlNetwork

{
class myLmXmlNetwork
{
static void Main(string[] args)
{
//Create an instance of the LonMaker plug-in using its registered

LonMakerXmlPlugIn m_lmXml = new LonMakerXmlPlugIn();

//Set the network name property to open the network
m_lmXml.NetworkName = "MyXmlNetwork";

//Invoke the send command to specify the action and target
//object. The send command uses the following syntax:
//(23, 5, “network/system/subsystem[/subsystem…])”

m_lmXml.SendCommand(23, 5, "MyXmlNetwork/MyXmlNetwork/Subsystem 1");

//Make plug-in visible so it shows itself
m_lmXml.Visible = true;
}
}
}

//ActiveX name, which is "EchelonLonMakerXML.Application"

ONWORKS Network XML Programmer’s Guide 3

L

Defining Export Automation Properties

You can define standard LNS Plug-in properties and the following export automation properties in the
director application. See Appendix B of the LNS Plug-In Programmer’s Guide for more information
about the standard plug-in properties you can define.

Property Name Type Description

XmlFileName BSTR Specifies the path and name of the XML file to be created.

If a file with the specified name already exists, it will be
overwritten. If a name is not specified, the default name
will be as follows: <LM DB Dir >\XML\<network
name>\Export[_index].XML.

<LM DB Dir> is the LonMaker drawing and database
directory. Typically, this is C:\LM.

<network name> is the name of the network being exported.
index is a decimal number appended to the file name or

incremented to make the file name unique.
The directory specified for the XML file must already exist.

XmlOptions Long Specifies export options. You can specify multiple options

by ORing the following values together:

• &H01. Suppress status dialog. The XML plug-in does

not display a status dialog. The status dialog shows the
progress of the export operation and any errors
encountered.

• &H02. Suppress options dialog. The XML plug-in

does not display an export options dialog. If you do not
set this option, you are prompted to specify the export
options (including whether to cancel the export).
Defaults for the options dialog are based on the
parameters sent to the plug-in.

• &H10. Export NV values. Reports the values of the

NVs of all commissioned devices in the XML file.
This can significantly increase the time required to
export the XML file.

• &H20. Export self-documentation. Reports

self-documentation data for commissioned devices in
the XML file. This can significantly increase the time
required to export the XML file.

• &H40. Export device-specific CPs. Reports the values

of the device-specific CPs of commissioned devices in
the XML file. This can significantly increase the time
required to export the XML file.

ChannelExport Long Specifies which channels are reported in the exported XML

file. Specify one of the following options:

• 0. Reports all channels defined in the network. This is

the default.

• 1. Does not report any channels.

• 2. Reports only channels that are referenced in the

4 Using the LonMaker XML Plug-in

Property Name Type Description

exported data.

TemplateExport Long Specifies which device templates are to be included in the

exported XML file. Specify one of the following options:

• 0. Reports all device templates defined in the network.

This is the default.

• 1. Does not report any device templates.

• 2. Reports only device templates that are referenced in

the exported data.

ConnDescExport Long Specifies which connection description templates are to be

included in the exported XML file. Specify one of the
following options:

• 0. Reports all connection description templates defined

in the network. This is the default.

• 1. Does not report any connection description

templates.

• 2. Reports only connection description templates that

are referenced in the exported data.
ExportComment BSTR Inserts a comment as a text string in the exported XML file.
ExportScope Long Specifies the subsystems to be included in the exported

XML file. The application devices and routers located in
the specified subsystems are included in the exported XML
file. Specify one of the following options:

• 0. Reports all subsystems. Ignores the subsystem

specified in the SendCommand request. This is the

default.

• 1. Reports the subsystem specified in the

SendCommand request and all of its nested

subsystems.

• 2. Reports only the subsystem specified in the

SendCommand request. Nested subsystems are not

reported.

The following example adds code to set optional expo rt pr o pert i es.

using System;
using System.Collections.Generic;
using System.IO;
using System.Text;
using System.Threading;
using System.Xml;
using PlugInWrapper;

namespace myLmXmlNetwork

{
class myLmXmlNetwork
{
static void Main(string[] args)
{
LonMakerXmlPlugIn m_lmXml = new LonMakerXmlPlugIn();

m_lmXml.NetworkName = "MyXmlNetwork";

ONWORKS Network XML Programmer’s Guide 5

L

// *Insert export automation properties before invoking send command*

m_lmXml.XmlOptions = 0x10 | 0x40;

//Option to export subsystem specified in SendCommand

m_lmXml.SendCommand(23, 5, "MyXmlNetwork/MyXmlNetwork/Subsystem 1");
m_lmXml.Visible = true;
}
}
}

// Option to export NV and device-specific values

m_lmXml.ExportScope = 2;

Importing a LonMaker Network

You can use the LonMaker XML Plug-in to automate the importing of a LonMaker network. To do
this, create a director application that does the following:

1. Defines the import automation properties.

2. Invokes the import command of the LonMaker XML Plug-in.

Invoking the Import Command

The import feature of the LonMaker XML plug-in implements the user level (10000) SendCommand
request and registers for a subsystem object, which consists of the object class (Subsystem, 5) and the
subsystem name. The following Visual C# code example demonstrates how you can invoke the
LonMaker XML Plug-in import command.

using System;
using System.Collections.Generic;
using System.IO;
using System.Text;
using System.Threading;
using System.Xml;
using PlugInWrapper; //reference to Echelon PluginWrapper.dll file.

//You can use download and reference this instead of
//creating

namespace myLmXmlNetwork

{
class myLmXmlNetwork
{
static void Main(string[] args)
{
//Create an instance of the LonMaker plug-in using its registered

//ActiveX name, which is "EchelonLonMakerXML.Application"

LonMakerXmlPlugIn m_lmXml = new LonMakerXmlPlugIn();

//Set the network name property to open the network
m_lmXml.NetworkName = "MyXmlNetwork";

//Invoke the send command to specify the action and target
//object. The send command uses the following syntax:
//(10000, 5, “network/system/subsystem[/subsystem…])”

m_lmXml.SendCommand(10000, 5, "MyXmlNetwork/MyXmlNetwork/Subsystem 1");

//Make plug-in visible so it shows itself
m_lmXml.Visible = true;
}
}
}

your own director application.

6 Using the LonMaker XML Plug-in

Defining Import Automation Properties

You can define standard LNS Plug-in properties and the following import automation properties in the
director application. See Appendix B of the LNS Plug-In Programmer’s Guide for more information
about the standard plug-in properties you can define.

Property Name Type Description

XmlFileName BSTR Specifies the full path of the XML file to be imported. The

file must already exist.

LogFileName BSTR Specifies the full path of a log file to be created during the

import. The log file reports the results of the import. If a
file already exists with the same name, it will be
overwritten.

If you do not specify a name or the field is empty, the log
file is not created

The directory specified for the log file must already exist.

XmlOptions Long Specifies export options. You can specify multiple options

by ORing the following values together.

• &H01. Suppress status dialog. The XML plug-in does

not display a status dialog. The status dialog shows the

progress of the import operation and any errors.

• &H02. Suppress options dialog. The XML plug-in

does not display an import options dialog. If this

option is not set, you are prompted to specify the

import options (including whet her to ca ncel the

import). Defaults for the options dialog are based on

the parameters sent to the plug-in.

• &H04. Import the XML data into the subsystem

specified in the SendCommand request. If you do not

set this option, the data is imported into the subsystem

specified as the root subsystem in the XML file (if the

root subsystem value is empty or missing, the data is

imported into the first top-level subsystem in the

network). The default is to import the data based on the

subsystem specified in the imported XML file.

The following example adds code to set optional import properties.

using System;
using System.Collections.Generic;
using System.IO;
using System.Text;
using System.Threading;
using System.Xml;
using PlugInWrapper;

namespace myLmXmlNetwork

{
class myLmXmlNetwork
{
static void Main(string[] args)
{
LonMakerXmlPlugIn m_lmXml = new LonMakerXmlPlugIn();

// *Insert import automation properties before invoking send command*

m_lmXml.NetworkName = "MyXmlNetwork";

ONWORKS Network XML Programmer’s Guide 7

L

m_lmXml.XmlOptions = 0x01 | 0x02;

//Option to create and specify location of import log

m_lmXml.SendCommand(23, 5, "MyXmlNetwork/MyXmlNetwork/Subsystem 1");
m_lmXml.Visible = true;
}
}
}

// Option to suppress status and options dialog

m_lmXml.LogFileName = "C:\\Lm\\XML\\XML Network\\ImportLog.XML";

Troubleshooting a Director Application

You can create a trace log to verify that the LonMaker XML Plug-in is receiving the commands and
options specified in your director application. This is typically only done dur ing app lication
development and debugging. To create a trace log for the LonMaker XML Plug-in, do the following:

1. Open the Windows registry editor. Click Start on the taskbar, click Run, type regedit, and then

click OK. The Registry Editor dialog ope n s.

2. Browse to the HKEY_LOCAL_MACHINE\SOFTWARE\LonWorks\ LonMaker for

Windows folder.

3. On the Edit menu, point to New, and then click String Value on the shortcut menu.

4. Type TraceLmXml.

5. In the right pane, right-click the TraceLmXml entry and then click Modify on the shortcut menu.

The Edit String dialog opens.

6. In the Value Data box, enter 1 and then click OK.
The LonMaker XML Plug-in will now create a trace file in C:\LonWorks\LonMaker\

PlugIn_LmXml.log that reports all of the commands and options that it has received from the director
application.

Creating and Updating a LonMaker Network

You can create a new network or update an existing LONWORKS network by importing a LonMaker
network XML file with the LonMaker XML Plug-in. This section describes how the LonMaker XML
Plug-in creates and updates networks and how it updates individual objects in the LNS network
database.

How the LonMaker XML Plug-in Creates and Updates a Network

On import, the LonMaker XML Plug-in processes the data from the RootSubsystem specified in the
XML file. If this value is not defined or it is empty, the first top-level subsystem is assumed. The
plug-in then makes five passes through the XML data , per fo rming the following actions:

1. Create, update, and delete subsystems. Deleting a subsystem also deletes all devices in that

subsystem. Channels and connection descriptions are also created and updated (they are deleted
on the fourth pass).

2. Create, update, and delete application devices, routers, functional blocks, and NVs/message tags.

Device templates are also imported, as required.

3. Create and update NV/message tag connections.

4. Delete channels, device templates, and connection descriptions.

5. Commission application devices and routers and load the specified application image (.APB) into

them.

8 Using the LonMaker XML Plug-in

Tip: You can import two or more individual XML files to overcome order dependencies in your XML
data that are incompatible with this sequence.

How the LonMaker XML Plug-in Updates Objects

The LonMaker XML Plug-in updates objects by matching the object elements in the XML file to their
corresponding objects in the LNS network database. To make a match, the plug-in first attempts to use
the NeuronID property (devices only), provided that is has a non-zero, non-empty value; then the
Name property; and finally the Handle attribute.

Once an object element in the XML file has been matched with an object in the LNS network database,
the plug-in updates the properties of the object and its child objects. Only those properties that are
specified in the XML file are updated (default values are not assumed). In addition, the properties of
child objects are only updated if the child object itself is specified. Note that child obj ects are not
deleted if they are not specified.

Notes:

• The plug-in will only update an object in the LNS network database if it is contained within the

same scope specified in the XML file. For example, if an application device is matched using the
NeuronID property, but the subsystem specified in the XML file for the application device does
not match the one in the LNS network database, the plug-in will report an error and the application
device will not be updated.

• If you specify the CREATE action on an object in the XML file, the plug-in will only create a

new object if it cannot locate a corresponding object in the LNS network database. If the object
does exist in the LNS network database, the object and its child objects are ignored.

ONWORKS Network XML Programmer’s Guide 9

L

10 Using the LonMaker XML Plug-in

2

Using the XML Schema

This chapter provides an overview of the XML schema that defines the

structure and content of a LonMaker network XML file. It lists the actions

and properties you can set for each object element in a LonMaker network

XML file. It provides examples of how each object element appears in a

LonMaker network XML file. It includes a programming example that

demonstrates how to export, modify, and import a LonMaker network XML

file.

ONWORKS Network XML Programmer’s Guide 11

L

XML Schema Overview

The LonMaker XML plug-in includes an XML schema that defines the structure and content of a
LonMaker network XML file. The XML schema documents the XML file generated and read by the
LonMaker XML plug-in. You can use the XML schema to validate the contents of a LonMaker
network XML file to some extent. For example, the XML schema validates the length and characters
for the string values of object properties; however, it does not validate the numeric and enumerated
values.

The XML schema includes a header that defines the context of the XML data and object elements that
correspond to objects in the LNS network database. The following sections summarize the header and
object elements. All elements in the XML schema have a predefined standard or derived type to
enforce L

The complete XML schema is included as Appendix A. You can also view the XML schema by using
an XML editor to open the LonWorksNetwork.xsd file in the Echelon LonMaker XML Interface
folder. To access this folder, browse to LonMaker\XMLin your L
(C:\LonWorks by default) or click Start on the taskbar, point to Programs, point to the Echelon
LonMaker folder, and then click Echelon LonMaker XML Interface.

Header

The header of the XML schema includes the following elements listed in order of sequence:

ONWORKS or LNS specific constraints.

ONWORKS directory

• Name. Specifies the name of the LNS network database from which the XML data was exported.

This field is optional upon import.

• ReportCreated. Specifies the data and time in which the exported XML file was created. This

field is ignored upon import.

• RootSubsystem. Specifies the context of the subsystems, application devices, and routers in the

XML file. All subsystems in the XML file must be dependents of the root subsystem. On import,
if the root subsystem is empty or not specified, either the subsystem specified in the
SendCommand request or the first top-level subsystem is assumed. You can use absolute or
relative references to this subsystem for object elements in other subsystems such as connection
targets. For absolute references, you use a leading “\” character; for relative references, you use a
“$”character.

• DomainID. Specifies the domain ID of the network. If specified upon import, the domain ID of

the network will be updated if it differs from the value supplied. The ID is specified as a series of
0, 2, 6, or 12 hex digits.

• ExportScope. Specifies the scope of the exported data.

<xs:element name="LonWorksNetwork">
<xs:complexType>
<xs:sequence>
<xs:element name="Name" type="xs:string" minOccurs="0" />
<xs:element name="ReportCreated" type="xs:dateTime" minOccurs="0" />
<xs:element name="RootSubsystem" type="xs:string" minOccurs="0" />
<xs:element name="DomainId" type="xs:string" minOccurs="0" />
<xs:element name="ExportScope" type="enumType" minOccurs="0" />

Object Elements

Object elements are complex XML elements that correspond to objects in the LNS network database.
Object elements include subsystems, application devices, routers, functional blocks, network variables,
channels, and so on. Object elements may include a Name property, Handle attribute, Action
attribute, and various properties. The following sections describe the Name property, Handle
attribute, and Action attribute.

12 Using the XML Schema

The applicable Action attributes and properties for each object element are detailed in the next section,
Setting Object Attributes and Properties Overview.

<xs:complexType name="objectType">
<xs:sequence />
<xs:attribute name="Handle" type="xs:integer" use="optional" />
<xs:attribute name="Action" type="xs:string" use="optional" />
</xs:complexType>

Name

The names of an object element and its properties generally match those in the LNS network database
(without the leading “Lca”). The names are different in instances where the LNS name is misleading,
obsolete, or not defined.

Handle Attribute

Most object elements contain an integer Handle attribute that corresponds to a unique, persistent
property of the object that can be used by LNS to access the object within the specified context. In
many cases, the Handle of the object element corresponds to the LNS handle for that object; however,
in some cases, the Handle corresponds to an index. For example, the Handle for functional blocks
and network variables corresponds to the object’s index number within the device or functional block,
respectively.

Action Attribute

Most object elements contain an enumerated, case-insensitive Action attribute that is applied upon
import. The Action attribute has seven possible values:

• CREATE. Creates the object if it does not exist already. If it does exist, the object and all of its

child objects are ignored.

• CREATE_UNIQUE. Forces the creation of a new object. In cases where the object name is not

unique, an instance number is appended (or incremented) to make the name unique.

• UPDATE. Creates the object if it does not already exist; updates the object if it does exist. This

is the default.

• MODIFY. Ignores the object if it does not already exist; updates the object if it does exist.

• DELETE. Deletes the object if it exists.

• IGNORE. Ignores the object and all of its dependents.

• COMMISSION. Indicates that the commissioning-related attributes of appl i cat i on de vi ces or

routers are to be updated. You can specify this action for subsystems, application devices, or
routers. If you specify this action for any other object, the behavior is the same as if you had
specified the MODIFY action: the object is ignored if it does not already exist or updated if it
does. The commissioning action and related attributes are detailed later in this chapter.

Setting Object Attributes and Properties Overview

You can set the attributes and properties for the following object elements that may be included in a
LonMaker network XML file (listed in order of level in the XML file):

• Networks

• Routers

• Subsystems

• Application devices

• Functional blocks

• Network variables

• Message tags

ONWORKS Network XML Programmer’s Guide 13

L

• Configuration properties

• Targets

• Extensions

• Channels

• Connection descriptions

• Device templates

• Component applications

For each object, individual tables that describe the applicable attributes and properties that you can set
are provided. Functional block, network variable, message tag, and configuration property properties
are reported within both application device and device template object elements. The properties
reported within each of these object elements vary; therefore, separate property tables are provided for
each object element. Properties that are reported within both object elements are described in the
application device property table; the description is not repeated in the device template property table.

An example is provided after each properties table that demonstrates the structure and content of the
object element.

Notes:

• Most object elements contain a Handle attribute that generally corresponds to the object’s LNS

handle; therefore, this attribute is not listed in the properties tables.

• If you use the CREATE action on an object element, do not specify the Handle attribute. This

may result in unintended behavior. If you use the CREATE_UNIQUE action, the Handle
attribute is ignored.

• You can use absolute or relative references for objects in one subsystem that refer to objects in

another subsystem. For absolute references, you use a leading “\” character in the beginning of the
subsystem path; for relative references, you use a “$”character. You can use forward or backward
slashes as delimiters between subsystem names.

• Enumerated properties have both decimal ID and case-insensitive string values. The values appear

in the following format: <propname ID= “decimal ID”> string literal </propname>. On import,
the string value is checked first to determine the appropriate action. If the string value is not
defined or does not match an existing value in the LNS network database, the ID is then used. If
the ID is not specified, the property is not updated. The string and decimal values for enumerated
properties are listed in the property description.

Networks

The network is the top level of the XML file. It includes the report options, and it contains all other
object elements in the XML file.

Attributes

Networks do not have any attributes.

Properties

Supported by

Function?

Property

Name Y N The name of the LNS network database/network.
ReportCreated Y N The date and time the XML report was created.

Comment Y N A text string providing additional comments or

Export Import

Format of date is YYYY-MM-DDThh:mm : ss

description for the export.

Description

14 Using the XML Schema

RootSubsystem Y Y The LNS Subsystem that contains all of the objects

reported in the XML file. If the entire network is
reported, this value is empty.

On import, this value specifies the subsystem into
which items are to be created; however, you can
override this value.

DomainId Y Y Series of 0, 2, 6, or 12 hex digits reportin g t he

domain ID of the network.

ExportScope Y N Enumerated value indicating the specified export

scope. The possible values are as follows:

0 ALL
1 SUBSYSTEM_TREE
2 SUBSYSTEM
3 SELECTION

Subsystems Y Y The top level subsystem containing all other

Channels Y Y See Channels for more information.
DeviceTemplates Y Y See Device Templates for more information.
ConnectDescTemplates Y Y See Connection Descriptions for more information.

subsystems, application devices, and routers.
See Subsystems for more information.

Example

<LonWorksNetwork>
<Name>XML Network</Name>
<ReportCreated>2006-07-14T10:54:55</ReportCreated>
<RootSubsystem/>
<DomainId>31</DomainId>

<ExportScope ID="0">ALL</ExportScope>
<Subsystems/>
<Subsystem/>
<Routers/>

<AppDevices/>
<Channels/>
<DeviceTemplates/>
<ConnectDescTemplates/>

</LonWorksNetwork>

Subsystems

Attributes

Applicable

Attribute

Action 1 IGNORE

Ref <reference name> Allows references to the subsystem in

Values

2 CREATE
3 CREATE_UNIQUE
4 UPDATE
5 MODIFY
6 DELETE
7 COMMISSION

Description/Notes

If you are creating a subsystem, you must
specify the subsystem’s Name property.

If you specify the COMMISSION action, the
subsystem properties are not updated; however,
the properties of all application devices, routers,
and subsystems contained within the subsystem
are updated.

ONWORKS Network XML Programmer’s Guide 15

L