Echelon LNS User Manual

LNS Programmer's Guide

Turbo Edition

@echelon

C o r p o r a t i o n

078-0177-01F

Echelon, LON, L LonTalk, Neuron, L

ONWORKS, NodeBuilder,

ONMARK, LNS, LonBuilder,

LonUsers, BeAtHome, LonManager, 3120, 3150, LonPoint, Digital Home, L

ONWORLD,

ShortStack, i.LON, the Echelon logo, and the

ONMARK logo are registered trademarks of

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

ONMARK Powered by Echelon, Powered by

L Echelon, and LonSupport are trademarks of Echelon Corporation.

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

Neuron

Chips 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

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 AND YOU RECEIVE NO WARRANTIES OR CONDITIONS, EXPRESS, IMPLIED, STATUTORY OR IN ANY COMMUNICATION WITH YOU, AND ECHELON SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

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

Echelon Corporation www.echelon.com

Preface

The LNS

network operating system provides a comprehensive set of software tools that allows multiple network applications to perform a broad range of services

over L

ONWORKS

and IP networks. These services include network management (network installation, configuration, maintenance, and repair) and system-wide monitoring and control. This guide describes how to use the LNS Object Server ActiveX Control to write LNS applications on a

Microsoft Windows

Server 2003, Windows XP, or Windows

2000 host PC.

LNS Programmer's Guide i

Purpose

This guide describes how to use the LNS Object Server ActiveX Control to develop an LNS application on a Microsoft Windows Server 2003, Windows XP, or Windows 2000 host PC.

Audience

This guide is intended for software developers creating LNS applications. LNS applications may be written in any language that supports COM Components or ActiveX controls, including Microsoft

6.0. Readers of this guide should have programming experience in such a language, and familiarity with L introduction to L System document available at www.echelon.com

ONWORKS

ONWORKS technology can be found in the Introduction to the LONWORKS

Visual C++ (versions 6.0-7.1) and Microsoft Visual Basic

technology and COM/ActiveX control concepts. An

Examples

Throughout this guide, Visual Basic code examples are used to illustrate concepts. To make the examples more easily understood, they have been simplified. Error checking has been removed, and in some cases, the examples are only fragments that will not compile.

For complete examples, see the example applications provided with the LNS Application Developer’s Kit. This includes example network management, monitor and control, plugin and director, and xDriver applications. Appendix C of this document describes the example applications in more detail.

Technical Support

If you have technical questions that are not answered within this document or the online help files provided with the LNS Application Developer’s Kit, you can contact Echelon for technical support. Your LNS Application Developer’s Kit distributor may also provide technical support. In addition, you can enroll in training classes at Echelon to learn more about LNS.

You can find out more about Echelon’s technical support and training services on the Echelon Support home page at http://www.echelon.com/support

System Requirements

System requirements and recommendations for the PC on which the LNS Application Developer’s Kit and LNS Redistribution Kit, as well as the LNS Server or LNS Remote Client redistributions, will run are listed below.

LNS Programmer's Guide

Development System

The following requirements are for the PC on which the LNS Application Developer’s Kit or LNS Redistribution Kit will be run:

• Windows Server 2003, Windows XP, or Windows 2000

• Pentium III 600 MHz or faster

• 256 MB RAM (512 MB RAM recommended)

• 50 MB or more of free disk space. For highest performance during

development, Echelon recommends using a high-performance hard disk.

• Any Windows application development tool that supports the use of COM components or ActiveX controls. Echelon has tested and offers technical assistance on the following development environments only:

• Microsoft Visual Basic 6.0, Service Pack 6 or higher

• Microsoft Visual Studio .NET 2003 (C++, used with ATL or MFC)

• CD-ROM drive

• Mouse or compatible pointing device

• LNS Network Interface card. Chapter 11 of this document lists and

describes the compatible LNS Network Interface cards. Note that an Ethernet card can function as an LNS Network Interface if you are using Echelon's i.LON 1000 Internet Server or the i.LON 600 L Server, and can also be used to access network interfaces such as the

i.LON 100 Internet Server or the i.LON 10 Ethernet Adapter.

• The minimum screen size required to use all LNS utilities is SVGA 800x600.

ONWORKS/IP

LNS Server PC for a Smaller Network

The following requirements are for a PC on which an LNS Server for a smaller network will be run.

• Windows Server 2003, Windows XP, or Windows 2000

• Pentium 100MHz or faster

• 50 MB or more of free disk space, not taking into account the size of the

LNS application and LNS network databases

• 256 MB RAM or more, depending upon the requirements of the LNS applications that will be running in addition to the LNS Server

• LNS Network Interface card. Chapter 11 of this document lists and describes the compatible LNS Network Interface cards. Note that an Ethernet card can function as an LNS Network Interface if you are using Echelon's i.LON 1000 Internet Server or the i.LON 600 L Server, and can also be used to access network interfaces such as the

i.LON 100 Internet Server or the i.LON 10 Ethernet Adapter.

• The minimum screen size required to use all LNS utilities is SVGA 800x600.

ONWORKS/IP

LNS Programmer's Guide

iii

LNS Server PC for a Larger, Busier Network

These requirements and recommendations are also valid for a PC on which a large network database is engineered before the LNS Server for that network becomes operational.

• Windows Server 2003, Windows XP, or Windows 2000

• Pentium 4 1GHz or faster

• 50 MB or more of free disk space, not taking into account the size of the

LNS application and LNS network databases. For highest performance during development, Echelon recommends using a high-performance hard disk.

• 512 GB RAM or more, depending upon the requirements of the LNS applications that will be running in addition to the LNS Server. Echelon recommends that you have between 500 MB and 1 GB available.

• LNS Network Interface card. Chapter 11 of this document lists and describes the compatible LNS Network Interface cards. Note that an Ethernet card can function as an LNS Network Interface if you are using Echelon's i.LON 1000 Internet Server or the i.LON 600 L Server, and can be used to access network interfaces such as the i.LON 100 Internet Server or the i.LON 10 Ethernet Adapter.

• The minimum screen size required to use all LNS utilities is SVGA 800x600.

ONWORKS/IP

LNS Remote Client PC

The following requirements are for a PC on which the LNS Remote Client redistribution will be run.

• Windows Server 2003, Windows XP, or Windows 2000

• Pentium 100MHz or faster

• 50 MB or more of free disk space, not taking into account the size of the

LNS application and LNS network databases

• 128 MB RAM or more, depending upon the requirements of the LNS applications that will be running in addition to the LNS Server

i.LON 100 Internet Server or the i.LON 10 Ethernet Adapter.

• The minimum screen size required to use all LNS utilities is SVGA 800x600.

ONWORKS/IP

LNS Programmer's Guide

Table of Contents

Preface ................................................................................................................................................. i

Purpose................................................................................................................................................ii

Audience..............................................................................................................................................ii

Examples.............................................................................................................................................ii

Technical Support...............................................................................................................................ii

System Requirements ........................................................................................................................ii

Development System ...................................................................................................................iii

LNS Server PC for a Smaller Network.......................................................................................iii

LNS Server PC for a Larger, Busier Network ...........................................................................iv

LNS Remote Client PC ................................................................................................................iv

Table of Contents................................................................................................................................v

Chapter 1 - Installing the LNS Software....................................................................................... 1

System Requirements ........................................................................................................................2

3rd Party Software...............................................................................................................................2

Installing the LNS Application Developer’s Kit...............................................................................2

Installing the LNS Application Developers Kit Software .........................................................2

Installing the LNS Redistribution Kit........................................................................................3

Developing Your LNS Application..............................................................................................4

Chapter 2 - What’s New in Turbo Edition..................................................................................... 5

Performance Enhancements ..............................................................................................................6

New Features......................................................................................................................................6

Enhanced Data Formatting.........................................................................................................7

GetDataPoint Method ...........................................................................................................7

FormatLocales Collection......................................................................................................7

Changeable Network Variable Types .........................................................................................9

Improved Support for Dynamic Interfaces.................................................................................9

Improved Monitoring Performance.............................................................................................11

Using Permanent Monitor Sets ............................................................................................11

Using Temporary Monitor Sets ............................................................................................12

Availability of Network Resource Information ..........................................................................13

Enhanced LonMark Interoperability..........................................................................................13

Improved Device Commissioning Performance .........................................................................14

System Management Mode Enhancements ...............................................................................15

Enhanced Configuration Property Management.......................................................................16

Online Database Validation and Backup...................................................................................16

Miscellaneous ...............................................................................................................................17

New LNS Runtime Installations.................................................................................................18

Compatibility ......................................................................................................................................18

Interface Compatibility ...............................................................................................................19

Database .......................................................................................................................................19

Runtime Component Updates.....................................................................................................19

Application Developer’s Kit Include Files ..................................................................................20

Exception Codes ...........................................................................................................................20

New Features ...............................................................................................................................21

Propagating Device Changes While Offnet .........................................................................21

Dynamic Functional Blocks ..................................................................................................21

DataPoint Object Improvements ..........................................................................................21

Formatting Enhancements ...................................................................................................22

Enhanced LonMark Interoperability ...................................................................................22

LNS Programmer's Guide

LonWorks Interfaces Control Panel .....................................................................................22

Support for i.LON 1000, i.LON 600 and ANSI/CEA-852 Channels ..................................22

Flexible Program ID ..............................................................................................................23

Modifiable Device-Specific Configuration Properties .........................................................23

Changeable Network Variable Types ..................................................................................24

Security ...............................................................................................................................................26

Chapter 3 - LNS Overview................................................................................................................ 27

Introduction to LNS ...........................................................................................................................28

The LNS Programming Model...........................................................................................................29

LNS Components................................................................................................................................30

LNS Databases and the LNS Server ..........................................................................................30

LNS Object Server .......................................................................................................................31

LNS Object Server Hierarchy...............................................................................................32

Network Service Devices .............................................................................................................35

Network Interfaces ......................................................................................................................35

LNS Network Services .......................................................................................................................36

Network Management .................................................................................................................36

Monitor and Control ....................................................................................................................37

LNS Clients.........................................................................................................................................37

Local Client Applications ............................................................................................................38

Lightweight Client Applications.................................................................................................39

Full Client Applications...............................................................................................................40

Independent Clients.....................................................................................................................41

Getting Started ...................................................................................................................................41

Chapter 4 - Programming an LNS Application ........................................................................... 45

Programming an LNS Application ....................................................................................................46

Importing the LNS ActiveX Control .................................................................................................46

Importing the Control into Visual Basic 6.0 ..............................................................................46

Importing the Control into Visual C++ ......................................................................................47

Initializing an LNS Application ........................................................................................................48

Initializing a Local Client Application .......................................................................................48

Selecting the Access Mode ....................................................................................................49

Specifying the Licensing Mode .............................................................................................49

Opening the Object Server....................................................................................................50

Selecting a Network Interface ..............................................................................................50

Opening a Network ...............................................................................................................51

Initializing a Remote Full Client Application............................................................................52

Selecting the Access Mode ....................................................................................................53

Specifying the License Mode.................................................................................................53

Opening the Object Server....................................................................................................54

Selecting a Network Interface ..............................................................................................54

Opening a Network ...............................................................................................................55

Initializing a Remote Lightweight Client Application ..............................................................57

Selecting the Remote Access Mode.......................................................................................58

Specifying the License Mode.................................................................................................58

Opening the Object Server....................................................................................................59

Opening a Network ...............................................................................................................59

Initializing an Independent Client .............................................................................................60

Opening a System...............................................................................................................................61

Setting System Parameters.........................................................................................................63

Using Transactions and Sessions ......................................................................................................65

Managing Transactions ...............................................................................................................65

LNS Programmer's Guide

Monitoring and Transactions ...............................................................................................66

Using Transactions With Collections...................................................................................66

Managing Sessions.......................................................................................................................67

Event Handling...................................................................................................................................67

Exception Handling............................................................................................................................70

Terminating an LNS Application ......................................................................................................71

Chapter 5 - Network Management : Installing a Network ........................................................ 73

LNS Network Installation Scenarios ................................................................................................74

Installation Scenarios ..................................................................................................................75

Engineered Mode Installation ..............................................................................................76

Ad Hoc Installation ...............................................................................................................76

Automatic Installation ..........................................................................................................76

Engineered Mode................................................................................................................................77

Definition Phase...........................................................................................................................77

Commissioning Phase..................................................................................................................81

Commissioning Phase, Multiple Networks..........................................................................84

Ad Hoc Installation ............................................................................................................................85

Automatic Installation .......................................................................................................................89

Discovering and Installing Devices ............................................................................................91

Discovering When New Devices are Attached to the Network ..........................................91

Installing Devices ..................................................................................................................93

Discovering When Devices are Detached or Replaced ........................................................96

System Management Mode Considerations .....................................................................................97

lcaMgmtModePropagateConfigUpdates.....................................................................................97

lcaMgmtModeDeferConfigUpdates.............................................................................................98

Intended Usage of the System Management Mode ...................................................................98

Changing the System Management Mode .................................................................................99

Tracking Device Updates ......................................................................................................99

Tracking System Management Mode Changes ...................................................................100

Affects on Network Management Methods and Properties................................................100

Chapter 6 - Network Management: Defining, Commissioning and Connecting

Devices ................................................................................................................................................. 103

Defining, Commissioning and Connecting Devices..........................................................................104

Device Interfaces ................................................................................................................................104

Program IDs and DeviceTemplate Objects ................................................................................106

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

Scope Selectors ......................................................................................................................108

The Bigger Picture .......................................................................................................................110

Maintaining Device Interfaces With LNS..................................................................................112

Defining and Commissioning Devices...............................................................................................113

Creating AppDevice Objects........................................................................................................113

Neuron ID Assignment ................................................................................................................115

Service Pin .............................................................................................................................115

Find and Wink .......................................................................................................................117

Manual Entry ........................................................................................................................119

Loading Device Application Images ...........................................................................................119

Post-Load State .....................................................................................................................120

Reloading a Device's Application .........................................................................................121

Commissioning Devices ...............................................................................................................121

Using the Commission and Commission Ex Methods ........................................................122

Device Validation Options ....................................................................................................123

Device Configuration Considerations ..................................................................................124

LNS Programmer's Guide

vii

LNS Licensing Considerations .............................................................................................124

Configuring Devices.....................................................................................................................125

Generic Configuration Data..................................................................................................125

Application-specific Configuration Data..............................................................................125

Setting Devices Online ................................................................................................................128

Other Device Management Operations ............................................................................................129

Testing Devices and Detecting Device Failures.........................................................................129

Using the OnAttachment Event...........................................................................................130

Performing Diagnostics on LonMarkObjects.......................................................................131

Replacing Devices ........................................................................................................................132

Replacing Network Service Devices .....................................................................................133

Upgrading Devices .......................................................................................................................134

Decommissioning Devices ...........................................................................................................136

Moving Devices and Managing Networks With Multiple Channels ........................................137

Removing Devices ........................................................................................................................137

Removing Devices From Multiple Subsystems ...................................................................137

Connecting Devices ............................................................................................................................138

Connection Rules .........................................................................................................................140

Adding Connections .....................................................................................................................142

Modifying Connections ................................................................................................................143

Listing Connections and Connection Members ...................................................................144

Using the OnNodeConnChange Event ................................................................................145

Connection Descriptions..............................................................................................................145

Chapter 7 - Network Management: Optimizing Connection Resources ................................ 147

Using Custom Connection Description Templates ..........................................................................148

Setting ConnectDescTemplate Properties..................................................................................149

Optimizing Connection Resources.....................................................................................................151

Network Design Time ..................................................................................................................152

Alias Options..........................................................................................................................152

Broadcast Options .................................................................................................................153

Using the AliasOptions and BroadcastOptions Properties ................................................154

Example Connection Scenario: Building Controls.....................................................................155

Solving Problems With Your Connection Scenarios ..................................................................157

Shortage of Groups ................................................................................................................157

Shortage of Address Table Space .........................................................................................157

Shortage of Aliases ................................................................................................................158

Summary of Resource Shortage Recommendations............................................................158

Predictive Strategies...................................................................................................................159

Conclusion ....................................................................................................................................161

Chapter 8 - Network Management: Advanced Topics................................................................ 163

Managing Network Service Devices..................................................................................................164

Upgrading a Network Service Device.........................................................................................164

Moving a Network Service Device ..............................................................................................164

Remote Full Clients...............................................................................................................165

Using the PreReplace Method ..............................................................................................166

Using Shared Media...........................................................................................................................167

Managing Networks with Multiple Channels ..................................................................................169

Overview of Router Types and Operation ..................................................................................170

Explicitly Controlling Channel Allocation...........................................................................172

Explicitly Controlling Subnet Allocation .............................................................................173

Installing and Configuring Routers............................................................................................174

Installation Order..................................................................................................................175

viii

LNS Programmer's Guide

Installing Devices With Multiple Channels...............................................................................175

Channel Isolation Process.....................................................................................................176

Resolving Installation Failures ............................................................................................177

Moving Devices and Routers Between Channels ......................................................................177

Removing Routers ........................................................................................................................178

Using Dynamic Device Interfaces .....................................................................................................179

Accessing a Device Interface .......................................................................................................179

Adding a Custom Interface to a Device................................................................................181

Adding LonMark Functional Blocks To a Custom Interface..............................................182

Adding Message Tags To a Custom Interface .....................................................................183

Creating Dynamic Network Variables.................................................................................184

Tracking Custom Interface Changes ...................................................................................185

Changeable Network Variable Types ...............................................................................................185

SCPTnvType Configuration Properties......................................................................................186

Chapter 9 - Monitor and Control .................................................................................................... 189

Introduction to Monitor and Control.................................................................................................190

Temporary and Permanent Monitor Sets .........................................................................................192

Permanent Monitor Sets .............................................................................................................192

Temporary Monitor Sets..............................................................................................................193

Creating Monitor Sets........................................................................................................................194

Managing Monitor Sets......................................................................................................................195

Adding Network Variable Monitor Points to a Monitor Set .....................................................195

Adding Message Monitor Points to a Monitor Set .....................................................................197

Setting Monitoring Options.........................................................................................................200

Network Variable Monitor Point Options............................................................................201

Message Monitor Point Options ...........................................................................................208

Opening and Enabling Monitor Sets.................................................................................................213

Using the Enable Method .....................................................................................................213

Using Network Variable Monitor Points ..........................................................................................214

Explicitly Reading and Writing Network Variable Monitor Points .........................................215

Example of Explicitly Reading a Network Variable Monitor Point...................................216

Example of Explicitly Writing a Network Variable Monitor Point....................................216

Polled Network Variable Monitoring..........................................................................................217

Setting the Poll Interval .......................................................................................................218

Example of a Network Variable Event Handler .................................................................219

The Implicit Bound Network Variable Monitoring Scenario....................................................220

The Explicit Bound Network Variable Monitoring and Control Scenario ...............................221

Fan-in Connections ...............................................................................................................221

Fan-out Connections .............................................................................................................222

Creating and Using Host Network Variables......................................................................223

Using Message Monitor Points..........................................................................................................224

Monitoring Message Monitor Points ..........................................................................................225

Receiving Message Monitor Point Updates .........................................................................226

Example Message Monitor Point Event Handler................................................................226

Controlling Message Points.........................................................................................................227

Developing Remote Monitor and Control Applications ...................................................................227

Tracking Monitor Point Updates.......................................................................................................228

System Management Mode Considerations .....................................................................................230

Directly Reading and Writing Network Variables...........................................................................231

Data Points and Enumerated Types...........................................................................................232

Using Configuration Properties In a Monitor and Control Application .........................................233

Device-Specific Configuration Properties...................................................................................234

Using the GetDataPoint Method ................................................................................................235

LNS Programmer's Guide

Data Source Options .............................................................................................................236

Resynchronizing Configuration Property Values ......................................................................238

Performance Considerations .......................................................................................................240

Data Formatting.................................................................................................................................241

FormatSpec Property...................................................................................................................241

Reading the FormatSpec Object ...........................................................................................242

CurrentFormatLocale ..................................................................................................................244

Creating FormatLocale Objects............................................................................................245

Chapter 10 - LNS Database Management ..................................................................................... 249

Overview of LNS Databases ..............................................................................................................250

Automatic Database Upgrade............................................................................................................250

Backing Up Network Databases .......................................................................................................251

Backup Method ............................................................................................................................251

Validating Network Databases .........................................................................................................252

LNS Database Validation Tool ...................................................................................................252

Validate Method...........................................................................................................................253

Special Considerations ................................................................................................................254

Using the CompactDb() Method..................................................................................................255

Removing Network Databases ..........................................................................................................255

Moving Network Databases...............................................................................................................256

Network Recovery...............................................................................................................................257

Network Recovery Inconsistencies .............................................................................................258

Performing a Network Recovery .................................................................................................260

Application-Level Recovery .........................................................................................................262

Recovery and Mirrored Connections...........................................................................................263

Chapter 11 - LNS Network Interfaces ........................................................................................... 265

Network Interfaces Overview ............................................................................................................266

Standard and High Performance Network Interfaces .....................................................................266

Addressing .............................................................................................................................269

LonTalk Transactions ...........................................................................................................269

Number of Groups .................................................................................................................270

Supporting Multiple Networks.............................................................................................270

Neuron Ids .............................................................................................................................270

Using xDriver Interfaces....................................................................................................................271

Using LONWORKS/IP Interfaces .....................................................................................................272

Network Interfaces and Network Service Devices...........................................................................273

Chapter 12 - Director Applications and Plug-Ins........................................................................ 277

Introduction to the LNS Plug-In Model ............................................................................................278

LNS Plug-In API.................................................................................................................................279

Registering Plug-Ins...........................................................................................................................279

Registering a Plug-In in the LNS Database ..............................................................................279

Registering a Plug-In in the Windows Registry ........................................................................279

Registering Plug-In Commands in the Windows Registry........................................................280

Accessing Extension Data..................................................................................................................280

Implementing an LNS Director Application.....................................................................................280

Implementing the Client-Side LNS Plug-In API.......................................................................281

Detecting Existing Plug-Ins ........................................................................................................282

Registering Plug-Ins ....................................................................................................................283

Detecting Applicable Plug-Ins.....................................................................................................284

Launching Plug-Ins......................................................................................................................286

Advanced Plug-In Management Tasks.......................................................................................287

Implementing an LNS Plug-In ..........................................................................................................288

LNS Programmer's Guide

Implementing an LNS Device Plug-In ..............................................................................................288

Managing Device Configuration .................................................................................................288

Chapter 13 - LNS Licensing ............................................................................................................. 289

Overview of LNS Licensing and Distribution ..................................................................................290

Demonstration Mode ..........................................................................................................................291

Standard Mode ...................................................................................................................................291

Entering the Standard Mode ......................................................................................................292

Protecting Your Keys ............................................................................................................292

Viewing License Status ...............................................................................................................292

Tracking License Events .............................................................................................................293

License Event Types..............................................................................................................293

Licensing and Network Recovery ......................................................................................................294

Licensing and Device Manufacturing ...............................................................................................295

Testing Devices ............................................................................................................................295

Using the LNS License Utilities........................................................................................................295

Using the LNS Server License Wizard.......................................................................................295

Using the LNS Server License Transfer Utility ........................................................................298

Chapter 14 – Distributing LNS Applications ............................................................................... 301

Distributing LNS Applications..........................................................................................................302

Using the LNS Redistributable Maker Utility ..........................................................................302

Adding the LNS Runtime to an LNS-based Product Installation ............................................306

Using setup.exe......................................................................................................................307

Using _SetupLNS.dll.............................................................................................................310

LNS Server and Remote Client Runtime Incompatibility..................................................312

Windows Installer and InstallShield Caveats.....................................................................312

Chapter 15 - Advanced Topics......................................................................................................... 313

File Transfer .......................................................................................................................................314

Using the OnSystemNssIdleEvent....................................................................................................316

Developing Remote Tools ...................................................................................................................316

Developing Mobile Tools ....................................................................................................................317

Registering a Mobile Application................................................................................................318

Moving a Mobile Application to a New Channel .......................................................................318

Multi-Threading and LNS Applications ...........................................................................................318

Avoiding Memory Leaks with LNS ...................................................................................................319

Debugging LNS Applications.............................................................................................................320

LNS and Line-Safe Expressions ........................................................................................................320

LNS and Internet Information Services ...........................................................................................322

Appendix A - Deprecated Methods and Obsolete Files.............................................................. 323

Deprecated Methods, Objects, Properties and Events .....................................................................324

Deprecated Objects ......................................................................................................................324

Deprecated Methods ....................................................................................................................324

Deprecated Properties .................................................................................................................325

Deprecated Events .......................................................................................................................326

Obsolete Files......................................................................................................................................326

Appendix B – LNS, MFC and ATL................................................................................................... 329

LNS, MFC and ATL ...........................................................................................................................330

Generating the Legacy MFC Class Wrapper Files ....................................................................332

Appendix C – LNS Turbo Edition Example Application Suite................................................. 337

LNS Turbo Edition Example Application Suite ...............................................................................338

Network Management Example .................................................................................................338

LNS Programmer's Guide

Initializing a Network ...........................................................................................................339

Performing Network Management Tasks............................................................................341

Source Code Mappings ..........................................................................................................344

Monitor and Control Example ....................................................................................................346

Source Code Mappings ..........................................................................................................350

xDriver Example Applications ....................................................................................................351

Example Director Application.....................................................................................................351

xii

LNS Programmer's Guide

Chapter 1 - Installing the LNS

Software

This chapter describes how to install the LNS Turbo Edition software.

LNS Programmer's Guide

System Requirements

System requirements and recommendations for the PC on which the LNS Application Developer’s Kit, LNS Server or LNS Remote Client redistributions will run are listed in the System Requirements section on page ii of this document. Before installing any LNS software, you should make sure the installation PC meets these requirements.

3rd Party Software

Before installing the LNS Application Developer’s Kit, you should note that LNS installs the following 3

• FastObjects 9.5. LNS uses FastObjects 9.5 as its object database engine.

• CrypKey 5.7. LNS uses CrypKey 5.7 as part of its licensing software.

• Microsoft XML Parser 3.0

You should be aware of this if you are using other versions of these products on your target PC. In addition, you should be aware that when service packs and fixes for these products are released, it may have ramifications for the LNS runtime software.

party software:

Installing the LNS Application Developer’s Kit

To install the LNS Application Developer’s Kit and begin developing an LNS application, follow these steps:

1. Install the LNS Application Developer’s Kit.

2. If you are planning to redistribute your LNS applications, install the LNS Redistribution Kit.

3. Start developing your LNS application.

Installing the LNS Application Developers Kit Software

The LNS Application Developer's Kit uses an automated, Windows-based installation program called SETUP. Because the LNS Application Developer’s Kit CD contains compressed files, you cannot install the software by copying the files directly to your hard disk. This section describes how you can install the LNS Application Developer’s Kit.

You should stop all LNS-based applications, utilities and services before performing this installation. This includes the LNS Server application, the OpenLDV xDriver connection broker, and any LNS client applications running as Windows services. You will need to manually restart these services after you complete the installation.

In addition, you must log in as a member of the Administrators user group when installing the LNS Application Developer’s Kit. To install the LNS software, perform the following steps:

LNS Programmer's Guide

like any other Windows program, e.g. by selecting the Run... item from the Start menu of the Windows task bar, browsing to the Setup application, and clicking Open.

2. This opens the LNS Application Developer’s Kit screen. Select Install Products, and then select LNS Application Developer’s Kit to begin installing the LNS Application Developer’s Kit software.

3. This opens the Welcome window. Click Next to continue.

4. This opens the License Agreement window. Read the license agreement, and if you agree to the terms of the license agreement, click I accept the terms in the license agreement. Then, click Next.

5. This opens the Customer Information dialog. Enter your name in the

User Name text box, and enter your company name in the Organization text box. If you want the LNS Application Developer’s Kit to be available to anyone who logs onto your PC, select Anyone who uses this computer. Or, select Only for me if only you should have

access to the LNS Application Developer’s Kit. Then, click Next to continue.

6. This opens the Ready to Install the Program window. Click Install to begin the installation.

7. When LNS has completed the installation, a confirmation dialog will appear. Click Finish to exit the installation and return to the main LNS Application Developer’s Kit screen.

Installing the LNS Redistribution Kit

If you are using the LNS Application Developer’s Kit, you may distribute your LNS applications, but may not distribute any of the LNS runtime files. If you want to redistribute LNS runtimes files, you must use the LNS Redistribution Kit. See Chapter 14, Distributing LNS Applications, for more information on redistributing LNS applications.

In LNS Turbo Edition, the LNS Server and LNS Remote Client installations, which are created and installed with the LNS Redistribution Kit, have been recreated as Windows Installer installations. This is to make LNS installations more compatible with recent versions of Windows. For more information on this change, see New LNS Runtime Installations on page 18.

You must log in as a member of the Administrators user group when installing the LNS Redistribution Kit. To install the LNS Redistribution Kit, follow these steps:

1. Insert the LNS Application Developer's Kit CD into a CD-ROM drive. If the start-up window does not automatically start after a few seconds, start the setup program manually. You can start the start-up program like any other Windows program, e.g. by selecting the Run... item from the Start menu of the Windows task bar, browsing to the Setup application, and clicking Open.

2. This opens the LNS Redistribution Kit screen. Select Install Products, and then select LNS Redistribution Kit to begin installing the LNS Redistribution Kit software.

LNS Programmer's Guide

3. This opens the Welcome window. Click Next to continue.

4. This opens the License Agreement window. Read the license agreement, and if you agree to the terms of the license agreement, click I accept the terms in the license agreement. Then, click Next.

5. This opens the Customer Information dialog. Enter your name, company name, and product serial number in the appropriate text boxes. If you want the LNS Redistribution Kit to be available to anyone who logs onto your PC, select Anyone who uses this computer. Or, select Only for me if only you should have access to the LNS Redistribution Kit. Then, click Next to continue.

6. This opens the Ready to Install the Program window. Click Install to begin the installation.

7. When LNS has completed the installation, a confirmation dialog will appear. Click Finish to exit the installation and return to the main LNS Redistribution Kit screen.

Developing Your LNS Application

Your applications will access the network services provided by LNS using the LNS Object Server ActiveX Control. This control gives you access to the LNS object hierarchy, where each object corresponds to physical and logical objects in your network. Your LNS applications will retrieve information from the LNS network operating system via the object hierarchy. You will also use the hierarchy to access device information directly. In short, everything will be done through the hierarchy.

You do not need to understand or use every object in the hierarchy to write a useful LNS application. However you should be familiar with most of the objects in the hierarchy. You should read the remainder of the LNS Programmer’s Guide for information on the LNS programming model, and detailed instructions on how you should write your LNS applications.

The next chapter describes the new features that have been added to LNS for Turbo Edition. The following chapter (Chapter 3, LNS Overview) provides an overview of the LNS object hierarchy, and a roadmap you can follow through the rest of this document.

LNS Programmer's Guide

Chapter 2 - What’s New in

Turbo Edition

This chapter introduces the new features that have been added to LNS for Turbo Edition, and describes how LNS performance has improved in Turbo Edition. It also provides guidelines to follow when upgrading your applications to use Turbo Edition.

LNS Programmer's Guide

Performance Enhancements

For Turbo Edition, numerous internal changes have been made that will significantly improve the speed, performance and stability of most LNS applications. This includes improved internal use of transactions, locking and indexing for faster database operations.

Internal indexing in some of the major LNS collections has been vastly improved, so the time required to access items from these collections has been reduced from a linear-time operation (varying with respect to the size of the collection) to a relatively small, constant-time operation. For large networks with large databases, this will make for a noticeable performance improvement when you use the Item property, the

ItemByHandle() method, the ItemByIndex() method, or the ItemByProgrammaticName() method to retrieve an object from the following

collections:

• AppDevices Collection (when accessed through Subsystem object)

• NetworkVariables Collection

• ConfigProperties Collection

• LonMarkObjects Collection

• MessageTags Collection

• Routers Collection

The introduction of temporary monitor sets in Turbo Edition will improve the performance of your monitor and control applications. Temporary monitor sets serve the same purpose as the permanent monitor sets that were introduced in Release 3.0. However, temporary monitor sets are not stored in the LNS database. As a result, it takes considerably less time to create temporary monitor sets than it does to create permanent monitor sets. Temporary monitor sets can only be used in a single client session by the client application that created them. In contrast, permanent monitor sets can be used by multiple clients in multiple client sessions. If you are creating a monitor and control application that does not need to re-use monitor sets and monitor points, you can maximize your application’s performance by using temporary monitor sets. For more information on temporary monitor sets, see the next section, New Features.

New Features

This section describes the major features that have been added to LNS for Turbo Edition. This includes the following topics:

• Enhanced Data Formatting

• Changeable Network Variable Types

• Improved Support for Dynamic Interfaces

• Improved Monitoring Performance

• Availability of Network Resource Information

LNS Programmer's Guide

• Enhanced LonMark Interoperability

• Improved Device Commissioning Performance

• System Management Mode Enhancements

• Enhanced Configuration Property Management

• Online Database Validation and Backup

Enhanced Data Formatting

LNS 3.0 featured the introduction of the DataPoint object, which you can use to read and write to the values of monitor points. Formatting of DataPoint objects is handled locally, in the client process. As a result, formatting changes made to the value of a monitor point through a data point by a given application do not affect other applications that are reading the value of the same monitor point. This eliminates any confusion caused when separate client applications need to format data independently.

In LNS Turbo Edition, you can create DataPoint objects to read and write the values of network variables and configuration properties, as well as to the values of monitor points. LNS Turbo Edition also features several modifications and enhancements to the DataPoint object that will allow each client application to better format and display the data it accesses through DataPoint objects. This section describes these changes.

GetDataPoint Method

The ConfigProperty and NetworkVariable objects now include an additional method, the GetDataPoint() method. This method returns a DataPoint object you can use to read and write to the value of the configuration property or network variable. Most of the properties and methods you can use with each DataPoint you access through a configuration property or a network variable are the same as those you could use with the DataPoint objects accessed through monitor points in LNS 3.0. For more information on using DataPoint objects to access network variables, see Directly Reading and Writing Network Variables on page 231. For more information on using

DataPoint objects to access configuration properties, see Using Configuration Properties In a Monitor and Control Application on page 233.

In addition, several properties have been added to the DataPoint object in this release: the SourceOptions, SourceIndex, MinValue and MaxValue properties. You can use the SourceOptions and SourceIndex properties to identify the type of source object used to create a data point. You can use the MinValue and MaxValue properties to identify or set the minimum and maximum values that should be assigned to a scalar data field. For more information on these properties, see the LNS Object Server Reference help file.

FormatLocales Collection

The new FormatLocales collection is another feature that you can take advantage of when using DataPoint objects. Each FormatLocale object contains a series of properties that reflect a particular geographical area’s conventions for data display. These conventions affect how data should be displayed in that area, including factors

LNS Programmer's Guide

such as language, measurement system (U.S. or Systeme Internationale), date formats, time formats, and decimal number formats. The settings of a FormatLocale object determine how data accessed through the FormattedValue properties of all DataPoint objects will be displayed when your application uses that FormatLocale object.

Each client application can select the FormatLocale object it will use by passing that FormatLocale to the CurrentFormatLocale property of the ObjectServer object before opening any networks and formatting any data. As a result, client applications in different regions can use their own sets of local formats when displaying data, without affecting the data formatting used by other clients. This greatly reduces the risk of your application returning information that is confusing or misleading due to formatting changes made by another application.

You can access the FormatLocales collection through the FormatLocales property of the ObjectServer object. When initialized, the FormatLocales collection contains 4 pre-defined FormatLocale objects:

1. UserDefaultRegionalSettings. This is the default value for the CurrentFormatLocale property. When you use this FormatLocale object, all the properties will be set based on the user-defined Windows regional settings for the user currently logged onto the PC running your application. You can change the regional settings on a PC using the Windows control panel Regional Options applet. Consult the Microsoft Developer’s Network (MSDN) documentation of the Win32 GetLocaleInfo() function for more information on the Windows regional settings.

2. SystemDefaultRegionalSettings. When you use this FormatLocale object, all the properties will be set based on the default Windows regional settings on the PC running the application. The default settings may vary, depending on which operating system is installed on the PC. Consult the MSDN documentation of the Win32 GetLocaleInfo() function for more information on the Windows Regional settings.

3. LonMarkCompatibility. When you use this FormatLocale object, all properties will be set so that formatted data will be displayed based on the LonMark

standards used prior to LNS 3.0, when localized formatting was not available. In this case, Systeme Internationale measurement units, LonMark-defined time and date formats, and U.S. options for everything else, will be used to display all formatted data.

4. ISO8601DateAndTime. When you use this FormatLocale object, the settings will be the same as the LonMarkCompatibility settings, except for the localized time and date formats, which will be based on the ISO 8601 standard. This standard helps avoid confusion that may be caused by the different national notations used for dates and times, and increases the portability of computer user interfaces.

The pre-defined FormatLocale objects are read-only, but you can create custom FormatLocale objects to suit the specific needs of your application with the Add method of the FormatLocales collection. Note that all custom FormatLocale objects are instantiated with the same initial settings as the pre-defined UserDefaultRegionalSettings FormatLocale object described above.

For more information on the FormatLocales collection, see Data Formatting on page

241.

LNS Programmer's Guide

Changeable Network Variable Types

Each NetworkVariable object contains a new property called the ChangeableTypeSupport property, which indicates whether or not you can use LNS to change the network variable’s type. If the ChangeableTypeSupport property is set to lcaNvChangeableTypeSdOnly or lcaNvChangeableTypeSCPT, you can change the network variable’s type. You can do so by modifying the NetworkVariable object’s new TypeSpec property.

The TypeSpec property returns a TypeSpec object. If a network variable supports changeable types, you can change the various properties of the TypeSpec object (ProgramId, Scope, TypeName), and then pass it back to the TypeSpec property to change the network variable’s type. Alternatively, you can write the TypeSpec property of one network variable to the TypeSpec property of another network variable. By doing so, you can change the type of a network variable to any type contained in your local set of resource files, provided that the device containing the network variable supports the selected type.

If a network variable supports changeable types via a SCPTnvType configuration property (as specified in version 3.3 of the LonMark Application-Layer Interoperability Guidelines), LNS will automatically set the value of the SCPTnvType configuration property when the network variable’s TypeSpec or SnvtId property is changed.

For more information on LNS support for changeable network variable types, see Changeable Network Variable Types on page 185.

Improved Support for Dynamic Interfaces

A typical device in a LONWORKS network uses a static interface, consisting of a static set of LonMark Functional Blocks, member network variables and configuration properties that define the device’s functionality in the system. In most cases, this functionality is dependent upon the device’s hardware and defined by the device manufacturer.

Sometimes, there is a need to modify this functionality. For example, controller devices may be used to control other devices. As a result, the number of components required for a controller device’s interface is often an attribute of the network configuration (e.g. how many devices it is controlling), rather than of the device’s hardware. Ideally, the resources on these controllers would be allocated dynamically, in order to fit the changing requirements of a given network as devices are added to it.

In Release 3.0, LNS supported dynamic network variables, which solved one aspect of the dynamic allocation of resources on a controller. However, dynamic network variables do not convey semantic information to a device or an LNS application in the same way that LonMark Functional Blocks and LonMark Functional Block membership do. In order to support the dynamic definition of a controller’s interface in Turbo Edition, LNS has been enhanced to support additional dynamic interface components.

Dynamic LonMark Functional Blocks and dynamic network variables can only be added to application devices that support them. For example, Network Services Devices support up to 4096 dynamic network variables, but do not support dynamic LonMark Functional Blocks. The number of LonMark Functional Blocks and dynamic network variables that a device supports is documented in the device’s external interface file and selfdocumentation. LNS reads this information from the external interface file when it is

LNS Programmer's Guide

imported, or from the device’s self-documentation when it uploads the device’s device template.

In LNS, an application device’s interface is represented by an Interface object. The Interface objects contained by an application device may be the device’s main, static interface, or they may be custom interfaces that have been added to the device dynamically, using the new features described in this section. You can access the main interface of a device through the AppDevice object’s Interface property. Main interfaces are static interfaces that cannot be modified.

You can access the collection of custom interfaces that have been added to a device through the device’s Interfaces property. If supported by the device, you can modify these custom interfaces by adding or removing objects from their NetworkVariables, LonMarkObjects, and MessageTags collections.

Or, you can add custom Interface objects to a device by accessing the Interfaces collection through the device’s Interfaces property, and then calling the Add() method. Once you have created a custom Interface object, you can modify it to suit your exact needs.

You can access the collection of LonMark Functional Blocks defined on the custom Interface. A LonMark Functional Block represents a collection of network variables and configuration properties on a device that perform a related function. For example, a digital input device with four switches could contain one functional block for each switch.

In LNS, LonMark Functional Blocks are represented by LonMarkObject objects. Each Interface object contains a LonMarkObjects property, which you can use to access the collection of LonMark Functional Blocks defined on that Interface. If the interface supports dynamic LonMark Functional Blocks, you can add and remove LonMarkObject objects from the collection using the Add() and Remove() methods. In addition, you can assign and un-assign existing network variables to and from the LonMarkObject objects using the AssignNetworkVariable() and UnassignNetworkVariable() methods. You can check if an Interface object supports the addition of dynamic LonMarkObject objects by reading the Interface object’s DynamicLonMarkObjectCapacity property. You can check if an Interface object supports the addition of dynamic network variables by reading the Interface object’s MaxNvSupported and StaticNvCount properties.

You can also access the collection of network variables defined on an Interface or on a LonMarkObject through the object’s NetworkVariables property. This property contains the entire set of NetworkVariable objects defined on that Interface. You can use the Add() and Remove() methods to modify this collection on your custom Interface objects as you desire.

In LNS Turbo Edition, each custom Interface object also contains a

DynamicMessageTags collection. You can use this collection to add dynamic MessageTag objects to the interface. This allows you to add message tags to any device

that supports monitor sets, and use those message tags to send explicit messages from that device to a group of devices, as with static message tags. For example, consider the case of a Network Service Device. Network Service Devices do not contain static message tags. However, you can now add dynamic message tags to the AppDevice object associated with a NetworkServiceDevice. Once you have added to a message tag to a Network Service Device, you can connect the message tag to the devices you want to send the messages to. Following that, you can create a message monitor point on the Network

LNS Programmer's Guide

Service Device that specifies the new dynamic message tag as the monitor target. Then, open the monitor set and use the message monitor point to send messages from the Network Service Device to the devices bound to the message tag. Note that you can still use message monitor points to send messages to individual application device, as described in Chapter 9 of this document.

To help you keep track of changes related to these new dynamic interface capabilities, the OnNodeIntfChangeEvent, which is fired each time a device’s external interface is changed, has been modified for Turbo Edition. The OnNodeIntfChangeEvent event now returns several new values indicating that interface changes related to these new features have been made. For example, once an application registers for this event, it will be fired each time a network variable is added or removed from a LonMarkObject, or each time a LonMarkObject is added to an interface.

For a general overview of device interfaces, see Device Interfaces on page 104. For details on how you can use the dynamic device interface features described in this section, see Using Dynamic Device Interfaces on page 179.

Improved Monitoring Performance

As of LNS Turbo Edition, there are two separate types of MonitorSet objects: permanent MonitorSet objects, which can be used in multiple client sessions, and temporary MonitorSet objects, which can only be used in a single client session by the application that created them.

If you need monitor points that will only be used in a single client session, you should use temporary MonitorSet objects, as it takes less time and database resources to create them. If you are creating a group of monitor points that you need to use in multiple client sessions, you must use the permanent MonitorSet objects.

This section describes the major differences between permanent and temporary monitor sets.

Using Permanent Monitor Sets

Each Network object contains a MyVNI property, which returns an AppDevice object representing your client's Network Service Device on the network. You can use this AppDevice to access all the permanent MonitorSet objects that are stored in the LNS database for your client’s Network Service Device. Echelon recommends that you only use the MyVni property to access MonitorSet objects when creating permanent MonitorSet objects, or when modifying the configuration of those MonitorSet objects. For actual monitor and control operations with permanent monitor sets, use the CurrentMonitorSets property of the Network object.

The CurrentMonitorSets property returns a collection of all the permanent MonitorSet objects on a network that are currently stored in your client’s Network Service Device. This is useful if you have created monitor sets while the system management mode is set to lcaMgmtModeDeferConfigUpdates (note that prior to LNS Turbo Edition, this was lcaOffNet). Although those monitor sets exist in the LNS database and can be accessed through the MyVni collection mentioned in the previous paragraph, they will not be commissioned into the Network Service Device, and cannot be used for monitoring operations, until the system management mode is set to

LNS Programmer's Guide

lcaMgmtModePropagateConfigUpdates (note that prior to LNS Turbo Edition, this was lcaOnNet) and the Network Service Device is updated. The collection accessed through the CurrentMonitorSets property allows access to all the monitor sets in your Network Service Device that you can currently open and enable on a network (the collection accessed through the MyVni property allows access to these monitor sets, as well as those in the LNS database that have not yet been commissioned into your client PC’s Network Service Device). You can use all the monitor sets obtained through the CurrentMonitorSets property as runtime monitor sets, meaning that you can enable them and use them for monitoring operations. However, persistent changes to their configuration are not allowed when accessed through this collection. As noted previously, you should use the collection obtained through the MyVni property when you need to change the persistent configuration of your client’s local MonitorSet objects.

NOTE: You can access the CurrentMonitorSets collection when running in independent mode (i.e. without connection to the LNS Server PC).

Using Temporary Monitor Sets

If you need monitor points that will only be used in a single client session, you should use temporary MonitorSet objects. As of LNS Turbo Edition, you can create a temporary monitor set with the CreateTemporaryMonitorSet() method of the Network object.

The properties and methods that can be used on a temporary MonitorSet object and the monitor points it contains are generally the same as those that can be used on a permanent MonitorSet object and its monitor points. However, if you have been using permanent MonitorSet objects with LNS 3.0, you should note a few exceptions to this rule.

Temporary MonitorSet objects cannot be created or used while in independent mode. The Open() and Close() methods have no effect on temporary MonitorSet objects, because temporary MonitorSet objects are opened as soon as they are created, and closed when they are released, or when the client session in which they were created ends. You should also note that temporary monitor sets are not enabled as they are opened. You must explicitly enable temporary monitor sets and temporary monitor points with your application using the applicable Enable method. For this purpose, the MsgMonitorPoint object now includes an Enable method.

In addition, the DefaultOptions properties stored in MsgMonitorPoint and NvMonitorPoint objects in temporary monitor sets are read-only. The values applied to these properties are taken from the temporary monitor set’s MsgOptions or NvOptions properties.

Monitor points in temporary monitor sets do not support the use of connection description templates to define certain monitoring options, as monitor points in permanent monitor sets do. As a result, you must set the connDesc element to NULL when you use the Add() method to add a message monitor point or network variable monitor point to a temporary monitor set.

There is one other variance to note when you use temporary MonitorSet objects. Network variable monitor points in temporary monitor sets cannot be automatically bound to the monitoring node. As a result, the UseBoundUpdates property of all temporary monitor sets and monitor points can only be set to False, meaning that you cannot use LNS to implicitly connect network variables monitored by temporary monitor

LNS Programmer's Guide

points to the host PC. However, you can still connect network variables to your Network Service Device using explicit connections, and utilize these with the SuppressPollingIfBound property.

For more information on monitor and control in this document, see Chapter 9.

Availability of Network Resource Information

The NetworkResources property has been added to the System object for Turbo Edition. This property returns a NetworkResources object that provides access to important network resource information for a system, including the number of AppDevices and Routers that have been installed on the system, the number of exclusive and sharable network variable selectors available on the system, and the number of subnets and group IDs allocated on the system.

This information is useful if you are managing a large system. For example, if you are writing an application that creates large numbers of multicast connections on a system, you will need to know how many groups and exclusive selector are available on the system. Or, if you are merging two LNS databases, you will need to know how many subnets, groups, and exclusive selectors have been assigned in each database, to make sure that the merged database will not exceed the limits for each resource.

For more information on the NetworkResources object and its properties, see the LNS Object Server Reference section of the LNS Application Developer’s Kit help file.

Enhanced LonMark Interoperability

Several changes have been made to LNS Turbo Edition to comply with version 3.3 of the LonMark Application-Layer Interoperability Guidelines, and to better support the latest versions of the LonMark standard resource files.

When importing a device interface from an external interface file, previous versions of LNS would set the Mode property of all LonMarkObject objects defined in the device interface to one of two values. It would set the Mode property of a LonMarkObject object to 0 if the LonMarkObject object’s TypeIndex property was in the range of standard Functional Profile Template (FPT) indices, or to 3 if the LonMarkObject object’s TypeIndex property was in the range of user-defined FPT indices. Turbo Edition features automatic scope determination, which means LNS will now search the set of installed and cataloged resource files to find the most device-specific match for the FPT, and set the LonMarkObject object’s Mode property based on this determination when the device interface is imported. If no match is found, LNS will set the LonMarkObject object’s Mode property to lcaResourceScopeUnknown.

In addition, the ResyncToResources() method has been added to the DeviceTemplate object. You can use this method to re-synchronize a device template with modified or newly accessible device resource file information. This may be necessary if you are upgrading to the current version of the LonMark resource files, or if you imported a device’s external interface file before the resource files for that device were available in the resource file catalog.

To complement this change, the ResyncToTemplate() method has been added to the AppDevice object. You can use this method at any time to re-synchronize the configuration of an AppDevice with the DeviceTemplate it is using. This may be

LNS Programmer's Guide

necessary if you have recently re-imported a device’s external interface file, or if you have used the ResyncToResources() method to update the DeviceTemplate that the device is using.

There are several other changes that you may find useful when using the LonMark resource files. For example, the TypeInherits property has been added to the ConfigProperty object. This property indicates whether or not the configuration property inherited its type from the network variable that the configuration property applies to. If a configuration property inherits its type, you may need to program your application to account for changes to the configuration property’s type. For example, consider a configuration property with the TypeInherits property set to True. If the configuration property applies to a network variable, and an application changes the network variable’s type, then LNS would change the data display format of the configuration property automatically, since the TypeInherits property is set to True. You would need to know about this change when reading the value of the configuration property, and you can use this property to keep track of which configuration properties could be modified by LNS in this fashion.

In addition, the IndexToSNVT property has been added to the LonMarkAlarm object. The IndexToSNVT property contains the device index number of the network variable on the LonMarkObject that caused the current alarm condition (i.e. the condition summarized by the LonMarkAlarm object). This will allow you to quickly identify all alarm conditions that occur on your network. Note that the LonMarkAlarm object supports alarming on devices that implement their alarms through SNVT_alarm network variables, but not through the more recent SNVT_alarm2 type. However, SNVT_alarm2 type network variables can be monitored and controlled using standard monitor and control techniques.

Finally, the OnLonMarkObjectStatusChangeEvent event has been added to LNS to allow you to track when an LNS application on your system changes the status of a LonMarkObject object.

Consult the LNS Object Server Reference help file for more information on the properties and methods introduced in this section. For general information on device resource files and device interfaces, see Device Interfaces on page 104

Improved Device Commissioning Performance

When you commission a device using an LNS version prior to Turbo Edition, LNS validates that the device is on the intended channel, and that it is using a program interface consistent with the definition in the LNS database. This validation is provided to catch simple errors that might otherwise cause serious system problems. However, performing this validation requires the transmission of several messages, which may significantly increase the time required to commission a slow network with simple nodes. For systems whose content is extremely well controlled, the benefits of validation may not be worth the extra time the validation process incurs.

For this reason, the DeviceValidation property has been added to the DeviceTemplate object. You can use this property to determine what validation steps LNS will perform when commissioning devices that use that DeviceTemplate. This may be useful if you are commissioning a large number of devices, and are confident that the devices contain the correct program information and are installed on the correct

LNS Programmer's Guide

channel. In this case, you can modify the DeviceValidation property to bypass parts of the validation process, and reduce the time it takes to commission those devices.

You should be aware that if parts of the validation process are disabled, the risk of network configuration problems due to inconsistent device settings will increase. If you disable the validation process, you should be sure that the Channel and ProgramId properties of the AppDevice objects using the device template have valid settings before commissioning, upgrading or replacing those devices. Skipping this validation, and then commissioning a device with the wrong interface may make subsequent communication with the device impossible. Note that you can also use this property to force a validation check of a device, by setting the DeviceValidation property to perform all validation steps, and then re-commissioning the device.

In addition, the SelfDocConsistency property has been added to the DeviceTemplate object. This property determines how much LNS will assume about the self-documentation of devices that are using the device template. This affects how LNS will read the self-documentation data of those devices, and what level of program interface validation LNS will perform when commissioning those devices. Some settings of this property allow LNS to assume higher degrees of self-documentation consistency among devices using this template, and cause LNS to operate more efficiently when updating those devices during the commissioning process. However, these settings may cause problems if the device developer has produced multiple devices that have the same program ID, but use different self-documentation strings or formats, as version 3.3 of the LonMark Application-Layer Interoperability Guidelines allows.

For more information on device commissioning, and on the features described in this section, see Commissioning Devices on page 121.

System Management Mode Enhancements

Several changes have been made to enhance the LNS operation when the system management mode (MgmtMode property) is set to lcaMgmtModeDeferConfigUpdates. Before considering these changes, you should note that new names for the system management mode settings have been provided in Turbo Edition. The old names still exist in LNS for compatibility reasons, but the documentation refers only to the new names. The new lcaMgmtModeDeferConfigUpdates value maps to the old lcaOffNet value, and the new lcaMgmtModePropagateConfigUpdates value maps to the old lcaOnNet value.

When the system management mode is set to lcaMgmtModeDeferConfigUpdates, all network configuration changes caused by your application will be applied to the LNS database, but not to the physical devices on the network. Prior to LNS Turbo Edition, these changes would be queued and then applied to all the physical devices as soon as the network management was set back to lcaMgmtModePropagateConfigUpdates. However, as of LNS Turbo Edition, you can call the new PropagateDeviceConfigUpdates() method on a device to apply configuration changes that affect only that device (such as configuration property values) to the device without changing the system management mode back to lcaMgmtModePropagateConfigUpdates. This may be useful if you have configuration changes pending for a large number of devices, and only want to apply them to a subset of those devices. This method will not propagate updates that affect multiple devices, such as changes to addresses or connections.

LNS Programmer's Guide

LNS Turbo Edition also includes a new option (lcaReplaceFlagPropagateUpdates) for the ReplaceEx() method, which you can use to replace an AppDevice or Router. If you call the Replace() method, or if you call the ReplaceEx() method without specifying the lcaReplaceFlagPropagateUpdates option, on a device while the system management mode is set to lcaMgmtModeDeferConfigUpdates, the physical devices will not be updated with configuration changes caused by the replace process until the system management mode is set back to lcaMgmtModePropagateConfigUpdates. You can now use the ReplaceEx() method with the lcaReplaceFlagPropagateUpdates option to replace devices while the system management mode is still set to lcaMgmtModeDeferConfigUpdates. This may be useful if there are configuration changes pending for a large number of devices, and you want to replace a device without waiting for all of those changes to be applied. A similar option is also provided for use with the new CommissionEx() method, which you can use to re-commission a device while the system management mode is set to

lcaMgmtModeDeferConfigUpdates.

Finally the OnSystemMgmtModeChangeEvent event has been added to the ObjectServer object. Once an application registers for this event, it will be fired each time the system management mode changes.

For more information on the features described in this section, see Chapter 6, Defining, Commissioning and Connecting Devices.

Enhanced Configuration Property Management

Several properties have been added to the ConfigProperty object that will allow your application to better identify the source and configuration of a ConfigProperty object. For example, in some cases the value stored in the LNS database for a configuration property may not match the actual value of the configuration property in the physical device on the network. To help you make this determination, the ValueStatus has been added to the ConfigProperty object. The ValueStatus property indicates whether or not the value currently stored in the LNS database for a configuration property matches the value stored in the physical device on the network.

Two additional properties, the DeviceSpecificAttribute and ConstantAttribute properties, have been added to the ConfigProperty object. These properties allow you to read and write the device-specific and constant attributes of the configuration property with your LNS application.

For more information on these configuration property attributes, see the Configuration

Property Flags section of version 3.3 of the LonMark Application-Layer Interoperability Guidelines. For more information on configuration properties in this document, and for

information on how you might want to use configuration properties within an LNS application, see Using Configuration Properties In a Monitor and Control Application on page 233.

Online Database Validation and Backup

LNS Turbo Edition features two new ways to help you maintain your LNS network databases: online backup and database validation. You can perform database validations using the LNS Database Validation Tool, or by calling the Validate() method on a Network object. When you perform a database validation, LNS will process the contents

LNS Programmer's Guide

+ 338 hidden pages

Echelon LNS User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual