LNS Programmer's Guide Turbo Edition @echelon Corporation 078-0177-01F
Echelon, LON, LONWORKS, NodeBuilder, LonTalk, Neuron, LONMARK, LNS, LonBuilder, LonUsers, BeAtHome, LonManager, 3120, 3150, LonPoint, Digital Home, LONWORLD, ShortStack, i.LON, the Echelon logo, and the LONMARK logo are registered trademarks of Echelon Corporation. LNS Powered by Echelon, LonMaker, LonLink, LonResponse, OpenLDV, LONews, Open Systems Alliance, Panoramix, Panoramix Powered by Echelon, LONMARK Powered by Echelon, Powered by Echelon, and LonSupport are trademarks of Echelon Corporation.
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 LONWORKS and IP networks. These services include network management (network installation, configuration, maintenance, and repair) and system-wide monitoring and control.
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® Visual C++ (versions 6.0-7.1) and Microsoft Visual Basic 6.0.
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.
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.
Table of Contents Preface ................................................................................................................................................. i Purpose................................................................................................................................................ii Audience..............................................................................................................................................ii Examples.......................
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 ...............
Monitoring and Transactions ...............................................................................................66 Using Transactions With Collections...................................................................................66 Managing Sessions.......................................................................................................................67 Event Handling................................................................................................................
LNS Licensing Considerations .............................................................................................124 Configuring Devices.....................................................................................................................125 Generic Configuration Data..................................................................................................125 Application-specific Configuration Data..............................................................................
Installing Devices With Multiple Channels...............................................................................175 Channel Isolation Process.....................................................................................................176 Resolving Installation Failures ............................................................................................177 Moving Devices and Routers Between Channels ......................................................................
Data Source Options .............................................................................................................236 Resynchronizing Configuration Property Values ......................................................................238 Performance Considerations .......................................................................................................240 Data Formatting..............................................................................................................
Implementing an LNS Device Plug-In ..............................................................................................288 Managing Device Configuration .................................................................................................288 Chapter 13 - LNS Licensing ............................................................................................................. 289 Overview of LNS Licensing and Distribution ................................................................
Initializing a Network ...........................................................................................................339 Performing Network Management Tasks............................................................................341 Source Code Mappings ..........................................................................................................344 Monitor and Control Example ....................................................................................................
Chapter 1 - Installing the LNS Software This chapter describes how to install the LNS Turbo Edition software.
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 3rd party software: • FastObjects 9.
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.
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.
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.
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.
• 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.
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.
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.
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.
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.
lcaMgmtModePropagateConfigUpdates (note that prior to LNS Turbo Edition, this was lcaOnNet) and the Network Service Device is updated.
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.
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.
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.
LNS Turbo Edition also includes a new option (lcaReplaceFlagPropagateUpdates) for the ReplaceEx() method, which you can use to replace an AppDevice or Router.
of an entire network database, and report any errors or inconsistencies it discovers. It can optionally repair some of these errors during the validation process. Inconsistencies and errors that may be discovered during the database validation procedure include orphan objects (inaccessible objects in the database), broken interfaces, and duplicate objects. You can access the LNS Database Validation Tool by selecting LNS Database Validator from the Echelon LNS Utilities group in the Windows Programs menu.
collection. You may not want the application to copy every extension record stored in the object. You can use this property to mark which extension records the application should copy. • The ConstNodeConnChangeEvent event now returns additional values. Previously, the possible values that could be returned for the event’s ObjectChangeType element were contained in the ConstObjectChangeTypes constant.
Interface Compatibility LNS follows the Microsoft COM interface guidelines for maintaining interface compatibility. Methods and properties can be added to the LNS OCX interface, but existing interfaces cannot be modified. Automated comparison tools are run on the LNS interface at each release to verify that the COM interface rules are followed.
LNS Turbo Edition servers and clients do not interoperate with clients and servers of other LNS versions. When updating an LNS site with a central server and remote clients, the LNS Server PC must be updated first. LNS server-independent mode, introduced in LNS 3.0, will allow any remote clients that run only in server-independent mode to be stopped, updated, and restarted some time after the server is updated.
Common exception codes for particular methods can and should be handled specially to provide more guidance to your particular end-user. However, because the complete set of exception codes that can be thrown for a given method can be large, and because all exception codes must be handled by your application, you should also use a generic error handler in your application that will handle all errors returned by LNS.
be compatible with a previous implementation. However, in this release, the DataPoint object provides new functionality – including consistent field-by-field formatting between network variables and configuration properties, and client-specific formatting – that is the new standard for LNS data formatting. Formatting Enhancements The default Formatting Locale has been changed in this release from the System Default Locale to the User Default Locale.
Server installer will be available to LNS customers on the Echelon web-site, and on the LNS Application Developer’s Kit CD for redistribution by licensed LNS developers. For more information on the i.LON 1000 Internet Server and the i.LON 600 LONWORKS/IP Server in this document, see Chapter 11, LNS Network Interfaces. Flexible Program ID By default, LonMark devices with a given program ID are expected to have the same selfdocumentation data format.
circumstances will LNS write a constant device-specific configuration property to a device unless the configuration property’s DeviceSpecificAttribute property is set to False. Changeable Network Variable Types This feature has been supported to some extent for several LNS releases. Version 3.3 of the LonMark Application-Layer Interoperability Guidelines introduced a new, standard mechanism for supporting network variables with changeable types and sizes.
and the value of the SCPTnvType configuration property will be updated to inform the device of the network variable type. For ideal performance, an application using versions of LNS prior to LNS Turbo Edition should modify the SnvtId property first, and then the SCPTnvType configuration property. The operations should be performed in the same transaction.
Security New security features have been added to LNS since Release 3.0 to protect against unwanted access to sensitive data. In LNS 3.07, Echelon introduced the OpenLDV xDriver to support a new class of remote network interfaces, including the i.LON 10 Ethernet Adapter and the i.LON 100 Internet Server. The TCP/IP link to those new interfaces includes MD5 authentication and sequence numbering to prevent unauthorized access or replay attacks on the link.
Chapter 3 - LNS Overview This chapter provides an overview of the LNS network operating system. It introduces the various LNS components, and describes the fundamental network services provided by LNS. For an introduction to LONWORKS networks, see the Introduction to the LONWORKS System document, which is available for download from Echelon's web site at http://www.echelon.com/.
Introduction to LNS LONWORKS Network Services (LNS) is the control networking industry's first multi-client network operating system. Much like a standard operating system, which implements the fundamental operating tasks of a computer, the LNS network operating system encapsulates common LONWORKS network operations, providing the essential directory, installation, management, monitoring, and controlling services required by most network applications.
be anything from a remote monitoring station, to an installation laptop PC using wireless networking. Each client tool can have a different user interface, optimized to the particular network being managed (e.g. material handling, access control, gas analysis, or HVAC) or to the skill set of the user. By building application-specific knowledge into network tools, all or part of the commissioning process can be automated, further reducing commissioning time and training cost.
the network device represented by the object. This is described in more detail later in the chapter. LNS leverages Microsoft’s COM and ActiveX technologies, the Windows standard for component-based software, to simplify the development of network applications for Windows hosts. Using LNS, developers are free to take advantage of the support for ActiveX and COM components built into Windows development tools.
Remote Client Application(s) Local Client Application(s) Remote Access LNS Server LNS Server Utility LNS Global Database LNS Network Database Network 1 LNS Network Database Network 2 LNS Network Database Network 3 Figure 3.2 LNS Architecture The gray-shaded blocks in Figure 3.2 represent the LNS Server PC, and items on the LNS Server PC. This includes the LNS global database, any local LNS applications running on the LNS Server PC, and the LNS Server utility. In Figure 3.
Applications access the services provided by the LNS Server using the LNS Object Server. The LNS Object Server is a COM server that provides an interface, independent of any specific programming language, to the LNS Server and the LNS database.
Because subsystems are logical divisions of a network, and devices can belong to multiple logical divisions, you can create multiple subsystems that cross-reference a network for different purposes with your application, and add individual devices to each one. In this manner, devices could appear in multiple subsystems.
ObjectServer ComponentApp Extension NetworkInterface LdrfLanguage FormatLocale Network (3) System Channel NetworkServiceDevice Extension Extension NetworkServiceDevice TemplateLibrary Subsystem NetworkInterface ConnectDescTemplate Subsystem AppDevice DeviceTemplate AppDevice ComponentApp Interface NetworkInterface Subnet Interface Extension Subnet AppDevice Connections Interface Channel Interface MessageTag NetworkVariable DeviceTemplate Application NetworkVariable MessageTa
Network Service Devices You will notice in Figure 3.3 that each Network object includes a collection of NetworkServiceDevice objects. Each NetworkServiceDevice object represents a LONWORKS device implemented by LNS for use with that particular network. Each LNS application uses a Network Service Device to communicate with the application devices and routers on a LONWORKS network when installing, connecting, managing, and monitoring and controlling the network.
LNS Network Services The primary purpose of the LNS network operating system is to simplify the performance of network services. Network services are operations that fall into the following three major categories: • Network installation and configuration • Network maintenance and repair • System monitoring and control The first two categories are collectively called network management. The third category is called monitor and control.
• LonMark object access • Receiving service pin messages • Data formatting based on standard and user-defined resource files • Addition and removal of network variables, message tags and LonMark Functional Blocks on host-based devices that support dynamic interface components.
An application that accesses the LNS Server remotely can do so as a Lightweight Client or as a Full Client. A Lightweight Client is an application that communicates with the physical network through the LNS Server PC, via a TCP/IP connection. A Full Client is as application that has its own network interface, and thus communicates with the LNS Server PC through the network, as well as directly with devices on the network.
LNS Application and LNS Server PC LONWORKS Channel LONWORKS Device LONWORKS Device LONWORKS Device LONWORKS Device LONWORKS Device Figure 3.4 Network Communication as a Local Client Lightweight Client Applications Lightweight client applications run on a different PC than the LNS Server and the LNS database. The remote PC is connected to the LNS Server PC via TCP/IP sockets, as shown in figure 3.5.
connection to the LNS Server and the data monitoring and control are through the TCP/IP connection. On some PCs, if an established TCP/IP connection is idle for some time, the PC enters a power-save mode that causes TCP/IP disconnection. The LNS Server treats this as it would any other disconnection. Once the LNS Server detects the disconnection, the client application must reestablish its connection to the LNS Server by closing the System and Network, and then reacquiring and reopening them.
Lightweight Client applications, or the LNS Server PC. Therefore network variables, connections and monitor sets defined on the Network Service Device used by a remote Full client application are shared only by other remote Full clients on the same PC that are connected to the same network. Independent Clients If an application does nothing but perform monitor and control services, it does not need to access the LNS network database, and thus does not need to connect to the LNS Server.
convenience, Table 3.1 lists the remaining chapters of this document, and summarizes their contents. You should note that the remaining chapters of this document describe LNS methods, objects and properties as they pertain to each network management or monitor and control task. In many cases, you can find more extensive details about an object, property, method or event in the LNS Object Server Reference file.
Table 3.1 LNS Programmer’s Guide Document Roadmap Chapter Description Chapter 4, Programming an LNS Application This chapter describes the steps you need to take when initializing an LNS application, whether you plan to use that application for network management, or for monitor and control. This includes all the steps you need to take to open the LNS Object Server, and initially access a LONWORKS network. Separate instructions are provided for each of the client types introduced in this chapter.
Chapter Description Chapter 11, LNS Network Interface Devices This chapter describes the various network interfaces you can use with LNS. Chapter 12, Director Applications and Plug-Ins This chapter discusses the standards and development methodology for creating interoperable LNS director and plug-in applications. Chapter 13, LNS Licensing This chapter describes the LNS licensing model.
Chapter 4 - Programming an LNS Application This chapter describes the steps you will need to follow when initializing an LNS application, whether it is an application for network management, or for monitor and control. The tasks described in this chapter include how to initialize the LNS Object Server, how to open a network, and how to terminate an LNS application.
Programming an LNS Application This chapter describes the tasks you need to follow when initializing an LNS application. This includes the following steps: 1. Import the LNS ActiveX Control into your development environment. For more information on this, see the next section, Importing the LNS ActiveX Control. 2. Initialize the LNS Object Server, and open the network you plan to use. For more information on these tasks, see Initializing an LNS Application on page 48. 3.
Once the tool is part of the Visual Basic tool palette, you can add the LNS Object Server to an application by selecting the tool and dragging it onto one of the application’s forms. To do so, follow these steps: 1. Select the LNS Object Server icon on the Visual Basic tool palette. 2. Drag the Object Server control onto one of your application’s forms. By default, the name of the control will be [formName].LcaObjectServer1, where [formName] is the name of the form where you placed the control. 3.
2. Drag the Object Server control onto one of your application’s dialogs. 3. Change the control’s resource ID, as necessary, by right clicking on the newly added control and selecting Properties. This opens a dialog box containing the current resource ID and other properties of the control. 4. From the View menu, select Class Wizard. This opens the Visual C++ Class Wizard. 5. Select the Member Variables tab. 6.
Table 4.1 Initializing a Local Client Application Task Sample Code For More Information, See… Selecting the Local Access Mode ObjectServer.RemoteFlag = False Selecting the Access Mode on page 49 Specifying the License Mode ObjectServer.SetCustomerInfo(CustomerID,CustomerKey) Specifying the Licensing Mode on page 49 Opening the Object Server ObjectServer.
The CustomerID and CustomerKey parameter supplied to the function refer to the customer identification and key numbers that are printed on the back cover of the LNS Application Developer’s Kit CD-ROM jewel case. For more information on LNS licensing, and for more details on the differences between Standard Mode and Demonstration Mode, see Chapter 13, LNS Licensing.
property to NOTHING for Visual Basic, or NULL for Visual C++). This is described in more detail in Chapter 5. If multiple client applications have the same network open, they must either use the same network interface, or they must all be in engineered mode.
within the Networks collection. The name to use is specified by the Network object’s Name property. The following code fetches an existing network called “Building76” from the global database. Dim MyNetwork as LcaNetwork Set MyNetwork = MyNetworks.Item("Building 76") 3. Call the Open() method on the Network retrieved in step 2 to open its LNS network database. MyNetwork.Open() 4. Optionally repeat steps 2 and 3 to open more networks.
Task Opening a Network Sample Code Dim MyNetworks as LcaNetworks Dim MyNetwork as LcaNetwork ObjectServer.RemoteFlag = True Set MyNetworks = ObjectServer.Networks Set MyNetwork=NetworksCollection.Item("Building 75") MyNetwork.Open() For More Information, See.. Opening a Network on page 55 Selecting the Access Mode As described in Selecting the Access Mode on page 49, each application must have some means of determining whether it will run as a remote or local client.
Application Developer’s Kit CD-ROM jewel case. For more information on LNS licensing, and for more details on the differences between Standard Mode and Demonstration Mode, see Chapter 13, LNS Licensing. Opening the Object Server Once you have set the network access and license modes, you can open the Object Server, as shown below: ObjectServer.
Dim SelectedNI as LcaNetworkInterface Set SelectedNI = NICollection.Item("LON1") 3. Set the remote network interface for the LNS application to the network interface selected in step 2. ObjectServer.ActiveRemoteNI = SelectedNI Note that before you use a network interface, you may need to configure the network interface with the LONWORKS Interfaces application in the Windows control panel.
4. Optionally repeat steps 2 and 3 to open more networks. Note that a remote Full client application can access multiple networks simultaneously, but must use the same network interface to open each one. Once you have opened a network, you should follow the tasks described in the Opening a System section later in this chapter to configure and open the system.
In any of these cases, your client application should resort to using the Networks collection. Once opened, the entry for the network in the RemoteNetworks collection will be repaired. 3. Get the network to be opened. In this case, you need to specify the network to be opened by the Network object’s RemoteNetworkName property. The default value for the RemoteNetworkName property is r_, where represents the value assigned to the Network object’s Name property.
Task Sample Code For More Information, See.. Opening the Object Server ObjectServer.Open() Opening the Object Server on page 58 Opening a Network Dim Networks as LcaNetworks Dim MyNetwork as LcaNetwork Opening a Network on page 59 Set MyNetworks = ObjectServer.Networks Set MyNetwork=MyNetworks.Item("Building 75") MyNetwork.
Opening the Object Server Once you have set the network access mode, and licensing mode for your Lightweight client application, you can open the Object Server, as shown below: ObjectServer.Open() NOTE: If you will be opening any networks with an LNS application that is running as a Windows service, then the first application to open the LNS Object Server must also be running as a Windows service.
2. If this is the first time the network will be opened on the PC running your application, use the Networks collection object's Add() method to save the network's name, IP address, and port (identified by the database path) into the Windows Registry on the remote PC. In this case, the final createDatabase parameter you supply to the Add method must be set to True. Dim MyNetwork as LcaNetwork Set MyNetwork = MyNetworks.Add("Building 75", _ "lns://bldgServer.acme.
been previously opened by Local or Full client applications with the Network Service Device your application is using: Dim Dim Set Set IndependentNetworks as LcaNetworks MyNetwork as LcaNetwork IndependentNetworks = ObjectServer.VNINetworks MyNetwork= IndependentNetworks.Item("Building 75") 3. Call the OpenIndependent() method on the selected network: MyNetwork.OpenIndependent() 4.
3. If the System is being opened for the first time and can share media with other independently managed systems, configure the system to use shared media by setting the InstallOptions property to lcaSharedMedia. The default for this property is private media (lcaPrivateMedia). The shared media setting is typically required for systems with power line, RF, or LONWORKS/IP channels. Setting the InstallOptions property after you have initially opened a system has no effect.
5. For Full client applications, set the System object’s RemoteChannel property to the Channel object corresponding to the remote PCs channel. You do not need to perform this step if you are running a Local or Lightweight client application, if the system only contains one channel, or if the system contains multiple channels and only uses configured routers, bridges or physical repeaters.
management mode is set to lcaMgmtModePropagateConfigUpdates, all device configuration changes are immediately propagated to the network. Note that the system management mode is global, and affects all clients currently attached to the system. For more information on the system management mode, see System Management Mode Considerations on page 97. MySystem.MgmtMode = lcaMgmtModePropagateConfigUpdates 2. DiscoveryInterval Property.
object are not available until the system has been opened. See the LNS Object Server Reference help file for a complete list of the properties of the System object, and descriptions of those properties. Once you have opened the System object and set its parameters as you desire, you can begin programming your application to perform monitor and control operations, or to perform network management tasks. Echelon recommends that you review the rest of this chapter before proceeding to these tasks.
To explicitly start a transaction, call the System object’s StartTransaction() method. Once a transaction is started for an application, all network modifications invoked by that application will be considered part of the transaction. To end the transaction and save the changes, call the CommitTransaction() method. To abort the transaction and cause the LNS database to revert to its state prior to the start of the transaction, the application can use the CancelTransaction() method.
Echelon recommends that you use the handle or name assigned to an object to retrieve it from a collection. The handle may be most desirable, since it is a static, unique value. However, if you need to iterate through a collection using index numbers to retrieve each object, you should do so within a transaction.
subscribe your application to most events by invoking the Begin method (where represents the name of the event) for the desired event. Each separate application must subscribe to an event to receive that event (i.e. one client application subscribing to an event will not cause other client applications to receive that event). The source of a stream of events is called the event generator. An application that subscribes to a stream of events is called an event subscriber.
an automated installation tool. You could also use it to provide feedback to a user about the configuration state of devices or routers on your network. For example, when building a connection, you might want to be informed of devices that could not be updated. Or, upon receiving a commission status change event with an “update failed” code, your application could indicate this by drawing a red circle around the device’s icon.
• Event handlers should not try to release any event object parameters, per COM rules. LNS will handle this itself on return from the event handler. If a client needs to make a copy of an object parameter, it must AddRef() the object to ensure it remains valid. For more information on this, see Avoiding Memory Leaks with LNS on page 319. • Where possible, event handlers should avoid making new calls into LNS (especially modifying calls), except to extract information from any passed-in object parameters.
Some properties and methods normally return an object, e.g. the Add() method of the AppDevices collection, and some return a value. However, if an exception is generated, the return value has no meaning and is not used, and the returned object (were it to be non-zero) is not valid. Likewise, when you use the interface that returns HRESULT codes instead of producing exceptions, the accessors return data results via pointers (output parameters).
72 LNS Programmer's Guide
Chapter 5 - Network Management : Installing a Network This chapter describes how you can use LNS to install and configure a LONWORKS network. This includes descriptions of three installation scenarios you can use: automatic installation, ad hoc installation, and engineered mode installation.
LNS Network Installation Scenarios To understand what is required to install LONWORKS devices on a LONWORKS network, you should consider the types of control systems that LONWORKS networks replace. Many conventional control systems use wiring harnesses or point-to-point wires. In these systems, the wiring between devices serves two purposes when the devices are installed. It physically interconnects the devices, and it determines which control signals should be sent to which device.
device’s network address consists of three components — the device’s domain, the device’s subnet, and the device’s subnet ID. The LNS Object Server is responsible for assigning each device a unique network address when the device is installed. • Define the information that devices share with one another. Devices communicate with one another using high-level objects called network variables, or low-level messages.
scenarios. For example, you could begin defining a network’s devices and connections using the engineered system scenario. Once the network is commissioned, you could add additional devices to it using the ad hoc scenario. Engineered Mode Installation In the engineered mode installation, installation is a two-step process consisting of a definition phase and a commissioning phase.
Engineered Mode In the engineered mode installation scenario, the network installation consists of two phases: 1. A definition phase in which the user defines the configuration of the devices and connections on the network in the LNS database without physically modifying the network. 2. A commissioning phase in which the application loads the network configuration created during the definition phase from the LNS database into the physical devices on the network.
Initialize the Object Server and create or obtain the network you are defining. Open the network’s System object. See Chapter 4 for more information on these tasks. Define device templates for the devices you are going to install: DeviceTemplates.Add() DeviceTemplate.Import() Set the application into Engineered mode: Set NetworkServiceDevice.NetworkInterface = NOTHING Add devices and connections as your network design requires.
Chapter 4 describes how to specify a network interface for each client type. If your application has already done so, you can switch the application to engineered mode by setting the NetworkInterface property of the system's NetworkServiceDevice object to NOTHING. Dim MyNetworkServiceDevice as LcaNetworkServiceDevice Set MyNetworkServiceDevice = System.NetworkServiceDevice Set MyNetworkServiceDevice.NetworkInterface = NOTHING 3. Begin defining the devices and connections on your system.
device with the lcaConfigPropOptLoadValues and lcaConfigPropOptSetDefaults options set. Then, set individual configuration properties as desired using configuration property data points. Note that some configuration properties may need to be adjusted (or calibrated) during the commissioning phase as portions of the system are brought online and tested. For information on setting configuration property values, see Writing Configuration Property Values on page 128. 6.
The following properties cannot be read while the LNS Object Server is in engineered mode: • AppDevice.SelfDocumentation • AppDevice.State • AppDevice.DetailInfo • NetworkVariable.SelfDocumentation • Router.State • RouterSide.State • RouterSide.DetailInfo • NetworkVariable.Value Commissioning Phase During the commissioning phase, the configuration information defined during the definition phase is loaded into the devices on the network.
Open the network and system to be commissioned: Set MyNetworks=ObjectServer.Networks Set MyNetwork=MyNetworks.Item(“MyNetwork”) MyNetwork.Open() Specify a network interface, open the system, and set the system management mode to lcaMgmtModePropagateConfigUpdates : Set MySystems = MyNetwork.Systems Set MySystem = MySystems.Item(1) Set MyNSD.NetworkInterface = MyNetworkInterface MySystem.Open() MySystem.
2. Open the network and the system, and then set the system management mode to lcaMgmtModePropagateConfigUpdates. Before opening the system, make sure that your application has specified a network interface. Set MyNetworks = ObjectServer.Networks Set MyNetwork = MyNetworks.Item(“Broadcasting Center”) Set MySystems = MyNetwork.Systems Set MySystem = MySystems.Item(1) Set MySystem.NetworkInterface = MyNetworkInterface MySystem.Open() MySystem.
8. As you manage the network you have created, you may need to perform other maintenance tasks, such as the removal of devices and connections, and the replacement of devices. For details on how you can use LNS to perform these tasks, see Other Device Management Operations and page 129. Commissioning Phase, Multiple Networks When commissioning multiple networks that have similar configurations, it may be most efficient to use a "cookie cutter" approach.
networks, a 1-byte domain ID is sufficient, and allows for optimum performance. The domain ID is automatically selected when the shared media installation option is specified before the system is opened for the first time. 9. Set the System object’s MgmtMode property to lcaMgmtModePropagateConfigUpdates. 10. If any of the devices' Neuron IDs have not been specified, acquire and assign them using the methods described in the Neuron ID Assignment section on page 115. 11.
Initialize the Object Server, create the network, and open the system. Make sure that your application is attached to the network when doing so. See Chapter 4 for more information on these tasks. Make sure that the system management mode is set to propagate device configuration updates: System.MgmtMode = lcaMgmtModePropagateConfigUpdates Choose a task: Create a device Create or select the Subsystem object that will contain the new device: Subsystems.Add() Subsystems.
2. You can now begin defining the devices and connections on your network. Fetch the Subsystems collection from the System object, and then use the collection’s Item property to obtain the Subsystem you want to add the devices to. Alternatively, you can use the Add() method to create a new Subsystem. The returned Subsystem contains an AppDevices collection. You can add new devices using the AppDevices collection’s Add() method.
properties for that template were not uploaded after another device with the same template was commissioned. The next step of this procedure describes how you can upload the configuration properties for the template. MySystem.StartTransaction MyDevice.Commission() Set MyInterface = MyDevice.Interface If MyInterface.ConfigPropertiesAvailable Then MyDevice.DownloadConfigProperties _ (lcaConfigPropOptLoadValues OR lcaConfigPropOptSetDefaults) End If MySystem.
Automatic Installation In the automatic installation scenario, an embedded network tool automates installation tasks so that little or no user interaction is required. The steps you will need to take when performing an automatic installation are shown in figures 5.5. The sections following figure 5.5 describe these tasks in more detail.
Initialize the Object Server and create the network. Make sure that the application has specified a network interface, and then open the new network’s System object. See Chapter 4 for more information on these tasks. Define device templates for the devices you plan on installing: MyDeviceTemplates.Add() MyDeviceTemplate.Import() Make sure that the system management mode is set to propagate device configuration updates: MySystem.
Discovering and Installing Devices There are several main phases involved in the automatic installation scenario depicted in Figure 5.5. These phases are listed below: 1. The first step is to discover the devices that have been added to the network. There are several ways to discover new devices. For more information, see Discovering When New Devices are Attached to the Network on page 91. 2.
network database when your application receives the OnAttachment event. • Force the LNS Object Server to discover configured devices on a given domain, and all unconfigured devices on the network, by calling the System object’s DiscoverDevices() method. Unconfigured devices discovered by this method will be placed in the Discovered.Uninstalled subsystem. Configured devices will be placed in the Discovered.Installed subsystem.
For a device to provide location information to the application, there must be some way for the device to know its location. For example, each device’s location field can be programmed with a location code, and each device can be sent to the field with instructions for where the device is to be attached to the network. Alternately, a handheld tool could be used to set the location string of each device at installation time.
another subsystem before installing the device. Iterate through the AppDevices collection to find the device you want to move, and then call the AddReference() method on the destination Subsystem to move the device to the destination subsystem. If your application discovered a newly attached device via the OnSystemServicePin event, the new device’s handle would typically have been returned with the event. You can use that to locate the AppDevice in the Discovered.
4. For each device, start a transaction, and commission the device with the Commission() or CommissionEx() methods. Before committing the transaction, you should use the DownloadConfigProperties() method to synchronize the configuration property values in the physical device with those stored in the LNS database. Note that the ConfigPropertiesAvailable property of the device’s Interface must be set to True for you to call DownloadConfigProperties() at this point.
each method. For more information on this, see System Management Mode Considerations on page 97. Discovering When Devices are Detached or Replaced Your LNS application can check if devices are still present in the network by periodically attempting to communicate with them. One way to do so is to invoke the Test() method on each AppDevice you need to check on.
When you discover that a physical device has been permanently removed from the network, you should remove the AppDevice object associated with the device from the LNS database. See Removing Devices on page 137 for information on removing devices. Before doing so, you should note that device detachment might only signal that a repair operation is under way.
addition, any changes that affect the configuration of devices that have not yet been commissioned are deferred until those devices are commissioned. Note that the system management mode cannot be set to lcaMgmtModePropagateConfigUpdates while in engineered mode.
engineered mode. This will ensure that the configuration of the network is always synchronized with the information stored in the LNS database. However, you may want to change the system management mode to lcaMgmtModeDeferConfigUpdates before making extensive changes to a network, in order to minimize the impact of these changes on the operation of the system.
Tracking System Management Mode Changes The system management mode is global and affects all clients that are accessing the network. Because of this, you should consider registering your application for the OnSystemMgmtModeChangeEvent. You can do so by invoking the BeginSystemMgmtModeChangeEvent() method on the System object. Once your application registers for this event, it will be fired each time the system management mode changes.
• You should be aware that in some cases, remote Full client applications cannot open networks when the system management mode is set to lcaMgmtModeDeferConfigUpdates. This may be the case if the Full client application has not previously connected to the LNS Object Server, if the Full client application has changed channels, or if changes have been made to the database such that commissioning the Network Service Device may cause inconsistencies in the configuration of physical devices on the network.
102 LNS Programmer's Guide
Chapter 6 - Network Management: Defining, Commissioning and Connecting Devices This chapter provides additional details on how to perform the network installation tasks introduced in Chapter 5. This includes topics such as importing device interfaces, assigning network addresses, loading device applications, commissioning devices, synchronizing device configuration properties, and creating connections between devices.
Defining, Commissioning and Connecting Devices Chapter 5 of this document lists the tasks you need to perform when using LNS to install a LONWORKS network. This chapter provides extensive detail on how you should use LNS services to perform each task introduced in Chapter 5. This includes the following sections: • Device Interfaces. Each LONWORKS device has a device interface. The device interface represents the device’s functionality on the LONWORK network.
• A device interface file may include information that is not included in the device itself, such as network variable names. • A device interface file can be used even when the device cannot be accessed by the network engineering tool, such as during the definition phase of an engineered mode installation. • Importing from a device interface file may be substantially faster than recovering interface information from a device.
4. Call the Import() method on the new DeviceTemplate object to import the device’s external interface file. You will provide the location of the device interface files in the xifPath parameter you supply to the method. MyTemplate.Import (“C:\LonWorks\Import\Acme\Cooker.xif”) Device interface files may reside in any location that can be reached through the file system on the LNS Server PC. Thus, referencing a device interface file as C:\LonWorks\Import\Acme\Cooker.xif refers to the cooker.
Table 6.1 Program ID Format Program ID Segment Description F This represents the format identifier. This will be set to 8 for LonMark certified interoperable devices, 9 for draft (not certified) interoperable devices, or a value less than 8 for noninteroperable devices. Note that the LonMark Interoperability Association has reserved format identifiers 0xA..0xF for future use. M:MM:MM A series of 5 hexadecimal digits identifying the device manufacturer.
between different measurement systems, to provide alternate industry-specific measurement units, or to provide locale-specific formatting for times, dates, or numeric value separator characters. A LonMark Functional Block groups network variables and configuration properties that are related to a particular function of the device. LonMark Functional Blocks make a device easier to install and configure.
Scope Selector Scope Enumeration Scope Definition 0 lcaResourceScopeStandard Used for resource files containing standard definitions for all devices from any manufacturer. This selector value can only be used for resource files defined by the LONMARK Interoperability Association. The set of resource files named STANDARD. implements this scope. 1 lcaResourceScopeClass Used for resource files containing standard definitions for all devices of a specified device class from any manufacturer.
5 lcaResourceScopeMfgSubclass Used for resource files containing user definitions for all devices of a specified manufacturer, device class, and device subclass. This selector value can be used by a manufacturer for resource files that apply to all of the manufacturer’s devices of a specific device class and subclass. 6 lcaResourceScopeMfgModel Used for resource files containing user definitions for all devices of a specified manufacturer, device class, device subclass, and model.
SFPTnodeObject implements two network variables: nviRequest of type SNVT_obj_request, and nvoStatus of type SNVT_obj_status. It also implements a single configuration property: cpLocation of type SCPTlocation. The UFPTcooker LonMark Functional Block implements two network variables: nviEnable of type UNVTenable to enable the heaters, and nvoDemand of type UNVTdemand to request a time-slice of energy to be allocated.
Maintaining Device Interfaces With LNS The recommended way to manage your device interface and resource file sets is to register all required resource files with the resource catalog, and then to create your DeviceTemplate objects by importing the device interface files. Most LNS plug-in applications perform these tasks automatically. LNS Turbo Edition provides a set of tools that may be used to re-synchronize resources to interfaces, or interfaces to devices, when necessary.
Defining and Commissioning Devices This section describes the steps you need to take when installing and configuring devices on a network with the network installation scenarios described in Chapter 5 in detail. This includes the following sections: • Creating AppDevice Objects. One of the first steps you need to take when using LNS to define and commission a device is to create an AppDevice object to represent the device in the LNS database. This section describes how to do so. • Neuron ID Assignment.
physical or logical segment of your network, and each Subsystem has its own AppDevices and Routers collections. These collections contain the application devices and routers installed on that Subsystem. You can select a subsystem that already exists using the Item property of your Subsystems collection, or you can create a new subsystem with the Add() method. Set MySubsystems = MySystem.Subsystems Set MySubsystem = MySubsystems.Item("FireSubsystem") OR: Set MySubsystems = MySystem.
4. You should note that devices can be installed in multiple subsystems. You can use the AddReference() method to create a reference to a device that has already been added to another subsystem. Set MyAppDevice = OtherSubsystemAppDevices.Item(“Device 1”) Set MyAppDevices = MySubsystem.AppDevices MyAppDevices.
3. Assign the Neuron ID acquired in step 2 to the AppDevice object you created for the device whose service pin was activated. You can do so by writing to the AppDevice object’s NeuronId property. MyAppDevice.NeuronId = AcquiredNeuronId 4. Invoke the EndServicePinEvent() method to cancel your application’s subscription to service pin events. MySystem.
Find and Wink When it is impractical to activate a device’s service pin (for example, if the device is behind a wall or in a false ceiling), you can use the find and wink method to determine its Neuron ID. The LNS Object Server periodically looks for new devices that have been attached to the network, and places them in the Discovered.Uninstalled subsystem. When LNS discovers a device and places it in this subsystem, it sets the device’s Neuron ID automatically.
2. Get the AppDevices collection from this subsystem and iterate through the devices by index, using the Item property. To find the target, examine the properties of each AppDevice in the collection. For example, the program ID, channel ID, and location can be used to find the appropriate devices. The location field is a 6-byte field in the Neuron Chip used for storing installation-related information.
foreground task. For more information, see the help page for the DiscoverDevices() method in the LNS Object Server Reference help file. NOTE: You should not use find and wink on systems that use shared media. Instead, you should use the confirmed service pin protocol described earlier in this chapter, or you should manually enter the Neuron ID, as described in the next section. Manual Entry In many cases, the Neuron ID is manually supplied to the LNS application.
LonWorks\Import\Acme folder on the C: drive of the LNS Server PC. Application image files can also reside outside the LNS Server PC’s local storage and referred to via mapped network drives or fully qualified filenames. The device plug-in software that comes with most LONWORKS devices should install the application image files into the correct locations. 2. Call the Load() method on the AppDevice.
the device’s configuration as possible. These features are described in more detail later in the chapter. • If the device had been previously commissioned, and the device's old application image and its new application image have the same program ID but a different external interface, the LNS Object Server will leave the device in the unconfigured state, and the NS:#59 lcaErrNsProgramIntfMismatch exception will be thrown.
was created. If a DeviceTemplate and Channel were specified, the network address was assigned at that time. • Extracts the external interface from the device, if no DeviceTemplate object was specified when the AppDevice object was created. If a DeviceTemplate object was specified, the commission process will validate the DeviceTemplate object against the device interface on the physical device.
NOTE: As of LNS Turbo Edition, each DeviceTemplate object includes a DeviceValidation property. The DeviceValidation property determines what validation steps LNS will perform when you commission devices using that DeviceTemplate. For more information on this, see the next section, Device Validation Options. Echelon recommends that you perform initial commissions only while the system management mode is lcaMgmtModePropagateConfigUpdates.
Device Configuration Considerations Before commissioning a device, you should make sure that the configuration property information contained in the LNS database for the device is complete, and you should download the configuration property values in the LNS database into the physical device. To do so, call DownloadConfigProperties() on the AppDevice before you commission it. Use the lcaConfigPropOptLoadValues and lcaConfigPropOptLoadUnknown download options when you call DownloadConfigProperties().
Configuring Devices Application devices have many different types of configuration information. This data can be roughly organized into two classes, generic configuration data and application configuration data. This section defines these two classes of data, and describes how you should manage each device’s configuration. Generic Configuration Data Some configuration data is generic to all LONWORKS devices.
that template. The configuration property defaults are also defined for the DeviceTemplate, but the configuration properties of the devices using that template are not automatically set to the default values. If a DeviceTemplate was recovered from a device, the configuration properties for that template will initially be undefined. The ConfigPropertiesAvaliable property will be set to False in this case.
To set unknown configuration property values, use one of the following two methods: • If the device is using a device template based on an external interface file that defines default values for the device's configuration properties, set all unknown configuration properties in the physical device on the network to match the default values stored in the LNS database by calling DownloadConfigProperties() with the lcaConfigPropOptLoadUnknown and lcaConfigPropOptLoadValues options set.
Writing Configuration Property Values You can also use LNS to read or write to the values of the configuration properties on a device one at a time. To do so, call the GetDataPoint() method on the ConfigProperty object to acquire a DataPoint object. If you have not written a configuration property, or set its default value, you cannot read it if any of the following conditions are true: • The device has not been commissioned. • The LNS Object Server cannot communicate with the device.
Note: If you are using an explicit transaction to install and configure a device, you must commit the transaction before setting the device online. For more information on transactions, see Using Transactions and Sessions on page 65. If you are installing multiple devices at once, you should first install and configure all the devices, and then set them online. This prevents the devices from attempting to communicate on a partially installed network.
return the expected and actual values of the device attributes tested. If a test fails, the AuxResultData property of the TestInfo object will indicate whether a Neuron ID, domain ID, subnet/Node ID, or program ID mismatch caused the test to fail. When you call Test() on a router, a router failure can result in failure reports for all of the devices on channels that are accessed via the failed router.
notify some other component of your application to perform a thorough test on any suspect devices. For more guidelines on creating LNS event handlers, see Event Handling on page 67. Note that when a router becomes unattached, this will usually prevent LNS from communicating with any devices on the far side of the router, and it will prevent communication between devices on channels connected by the router. In this case, LNS will generate an OnAttachmentEvent for the router, but not for each affected device.
Read the SelfTestResults property of a LonMarkObject to perform a self-test on the LonMarkObject: Dim MyObjectStatus as LcaObjectStatus Set MyObjectStatus = LonMarkObject.SelfTestResults Does the test complete? If not, an exception will be thrown. Follow these steps: Poll the SelfTestInProgress property until it returns False. If yes, the self-test will return an ObjectStatus object. Examine the properties of the ObjectStatus object to see the results of the self-test.
application configuration data, it might also be necessary to set the configuration properties of the new device to match the configuration property values in the old device. As described earlier, the AppDevice object represents the logical attributes of a physical device in the LNS database, including its network address, connections, and configuration properties. When the AppDevice object is commissioned, it becomes associated with the physical device on the network.
automatically. However, you may need to manually replace your Network Service Device in some cases. You will need to use the PreReplace() method to do so. For example, you will need to use this method if you open a network remotely from a new PC, and want that client to use the Network Service Device configuration that was previously associated with another remote client PC (effectively moving the remote application and Network Service Device configuration from one PC to another).
1. Call the System object's StartTransaction() method. You should always call the Upgrade() method within a transaction. This allows for easy reversal of the upgrade. For more information on transactions, see Using Transactions and Sessions on page 65. 2. If the device upgrade includes new hardware, make sure the new physical device is attached to the network, and that the AppDevice object's NeuronId property is set to the proper Neuron ID. 3. Call the Upgrade() method on the AppDevice object.
assigned to the external interface component represented by this UpgradeIndo object in the external interface after the upgrade. ToOwnerIndex For UpgradeInfo objects that represent configuration properties that are contained within LonMarkObjects or network variables, this property returns the device index value assigned to the owner LonMarkObject or network variable in the external interface after the upgrade. Otherwise, this property returns –1.
Moving Devices Channels and Managing Networks With Multiple If you are managing a network with multiple channels, there are many special tasks you will need to perform. This includes the installation and configuration of the routers on your network. For information on these tasks, see Managing Networks with Multiple Channels on page 169. This section also discusses how you can move a device from one channel to another.
device was associated with accordingly, but will not signal an error if the device itself cannot be communicated with. To remove a given AppDevice object that is referenced in multiple subsystems, collect the list of subsystems it belongs to by reading the AppDevice object’s Subsystems property. This returns a Subsystems object. Obtain the AppDevices collection for each Subsystem object contained in the collection, and remove the AppDevice object from each of them.
Network variable selectors are 14-bit numbers assigned by the LNS Object Server that identify connected network variables (i.e. network variables that are part of the connection). Devices may use different names to refer to a network variable, or network variables may be located at different offsets within each device's memory, resulting in a different network variable index within each device. However, all network variables in a connection must have the same network variable selector value.
Device Two Device Five nvoSetPoint nviTemp Target Network Variables Target Network Variables Device Three Device One nviTemp2 Device Six Device Four nvoControl nvi_NV1 nvoStatus nviValue Hub Network Variable Hub Network Variable Figure 6.4 Example Connections Connection Rules There are several rules you need to consider when creating connections. For network variable connections, the LNS Object Server enforces these rules: • Network variables can only be connected to network variables.
entries must be defined when the application is created by the device manufacturer, and are located in non-volatile memory. Available alias table entries are used by the LNS Object Server to create connections that would otherwise violate the rule requiring devices to have no more than one input and, in some cases, one output network variable within a given connection group. Figure 6.5 shows an example of a connection that can only be made with aliases.
• The msg_in tag always acts as an input only. • If there is only one declared message tag in a connection, it acts as an output only. If there is more than one declared message tag in a connection, all of those declared message tags act as bi-directional ports. Adding Connections To create a connection, you must first select a hub network variable or message tag, a set of targets, and optionally, a connection description.
Modifying Connections This section describes how to add members to a connection, remove members from a connection, and delete a connection. To add more members to a connection, follow these steps: 1. Obtain the hub NetworkVariable or MessageTag for the connection you want to modify. 2. Start a transaction, and then invoke the AddTarget() method for each the new targets you want to add. It is not necessary to re-specify existing targets. You must limit the number of targets you add to 25 at a time. 3.
Mirrored Connections LNS allows network variables to participate in multiple connections. As a result, it is possible to create arbitrarily complex network variable connections on a LONWORKS network (subject to the constraints of the LonTalk protocol). A consequence of the superposition of connections is that a network variable may find itself in a "mirrored" connection segment.
collection objects, they may be searched by name or by index. The use of these collections is discouraged for large systems, as it may take a long time to access these collections. Using the OnNodeConnChange Event You may want your application to be notified when devices are added to or removed from connections on your system. You can accomplish this with the OnNodeConnChange event. To use the OnNodeConnChange event, call the BeginNodeConnChangeEvent() method on the System object.
Repeat count Calculated based on topology and service type. Repeat timer Calculated based on topology and service type. Receive timer Calculated based on topology and service type. Transaction timer Calculated based on topology and service type. Broadcast options No broadcast addressing. Alias options Use network variable aliases to resolve selector conflicts. See the LNS Object Server Reference help file for more detailed information on these properties.
Chapter 7 - Network Management: Optimizing Connection Resources This chapter describes advanced topics you may need to consider when managing the connections on your network. This includes considerations you should make when customizing your own connection description template, and guidelines to follow to maximize your network’s connection resources.
Using Custom Connection Description Templates As described in Chapter 6, the LNS Object Server provides connection descriptions in the form of ConnectDescTemplate objects that determine the behavior of a connection. Each network variable and message tag has a ConnectDescTemplate property containing its ConnectDescTemplate object. When a network variable or message tag acts as a connection hub, its ConnectDescTemplate is applied to that connection.
2. Set the properties of the ConnectDescTemplate object, as described in step 2 of the procedure in the previous section. Note that the aliasing options used for network variables in a connection are determined when the network variable is added to a connection. As a result, changing the AliasOptions property of a ConnectDescTemplate object will not affect the aliasing options applied to network variables that have already been added to connections using that template.
Property BroadcastOptions Description This property determines whether LNS will use group or broadcast addressing. You should note that when using group addressing, there are 256 distinct groups per network, and the group addresses consume address table entries in both the receiving and transmitting devices involved in the connection.
Property ServiceType Description This property allows you choose from the following messaging services: Acknowledged Unacknowledged Repeat Unacknowledged If your application will be sending messages to large numbers of devices at once, one of the unacknowledged messaging services may be desirable, as the acknowledgement messages may generate a significant amount of network traffic.
Network Design Time When designing a network, you should seek to achieve the most reliable solution, with the most economic use of network and device resources. In this discussion, which deals specifically with optimizing connection usage, network resources can be thought of as network variable selectors, group identifiers, and channel bandwidth. Address table entries and alias table space are the critical device resources.
network variable. This can be used to avoid joining or creating groups, as shown in figures 7.1 and 7.2 later in this section. For monitor and control applications, the benefit of this approach is that the monitoring tool does not have to join the group. The existing group of nodes 1,2,3 will remain as it is, and node 1 will also propagate network variable updates to the monitoring tool using a unicast connection with Subnet/Node ID addressing.
Node 2 Node 1 Node 2 Node 1 Node 3 Figure7.1 Monitoring as member of a group Node 3 Figure 7.2 Monitoring via network variable alias Using the AliasOptions and BroadcastOptions Properties Table 7.2 summarizes the effect of each possible combination of the values of the BroadcastOptions and AliasOptions properties. Table 7.
BroadcastOptions Values AliasOptions Values lcaAliasForSelectorConflicts lcaAliasForUnicasts lcaBroadcastGroup If the connection is using the acknowledged messaging service, this combination allows for subnet/node addressing and group addressed multicast connections. The unacknowledged/repeat messaging service also allows subnet broadcast addressing to be used, and the unacknowledged messaging service further allows the use of domain broadcast addressing.
A R S F E D T G C B U H J Figure 7.3 Ceiling Lighting With Occupancy Sensors And Connections Assuming each occupancy detector has only one relevant output network variable, a multicast connection will be used to connect sensor R to lamps A, B, D and E. By default, LNS will use a group to accomplish this. A group ID will be allocated, and one address table entry will be used on each of the five participating devices.
unicast connections will be processed as separate transactions, causing more network traffic than a single multicast update would have produced. Solving Problems With Your Connection Scenarios When planning connections for large systems, or for systems accommodating challenging scenarios, the system integrator might still face difficulties when managing network variable connections. This includes problems such as shortages of group identifiers, aliases, and address table space.
propagates all outgoing packets using domain broadcast addressing, the device only needs one address table entry per target domain since LNS only supports a single domain, plus one for turn-around connections directed to itself. Therefore, a good way to conserve address table space is to avoid using group connections, and instead build connections that use subnet broadcast addressing and the unacknowledged/repeat messaging service.
these pools can typically be overcome by allowing other types of resources to be consumed. For example, group IDs can be saved by using network variable aliases, and vice versa. Preferring aliases over group addressing, for example, can also impact the third resource: such a change might not only change the total number of address table entries required, but can also redistribute these address tables entries differently among the devices that participate in the connection.
Start Unicast? Yes Use acknowledged service with the transport properties set to their default values. Set the AliasOptions and BroadcastOptions properties as follows: AliasOptions = lcaAliasForSelectorConflicts, BroadcastOptions = lcaBroadcastNever No All targets on the same subnet? Yes Use the unacknowledged/repeat service with the default transport property values.
Conclusion Your LNS application should manage LONWORKS connections transparently, creating reliable connections with minimum system overhead. However, awareness of what connections will be added to a network in the future and of the network resources those connections will consume is essential when creating a network with a large number of connections.
162 LNS Programmer's Guide
Chapter 8 - Network Management: Advanced Topics This chapter describes advanced network management topics such as how to manage a Network Service Device, how to manage a network with multiple channels, how to create custom device interface components, and how to use LNS to change a network variable’s type.
Managing Network Service Devices This section describes special tasks you may need to perform when managing the Network Service Devices on your network. This includes the following: • Upgrading a Network Service Device • Moving a Network Service Device Upgrading a Network Service Device In some cases, it may necessary to upgrade a Network Service Device when you change its network interface. Generally, LNS will perform this upgrade automatically, as soon as the system is opened.
3. Call PreMove() on the AppDevice. When you call PreMove(), you must specify the destination channel as the newChannelObject element. You can optionally specify the destination subnet as the newSubnetObject element. Echelon recommends that you leave the newSubnetObject element empty, as LNS will then allocate the most suitable subnet for the destination location: NSDAppDevice.
You should note that when a Full client application opens a system using the Networks collection (as opposed to the RemoteNetworks collection), the LNS Object Server automatically determines the channel that the application’s Network Service Device is attached to. However, the LNS Object Server cannot determine the correct channel if the channel is one of several channels connected by routers that are configured as repeaters or permanent bridges (i.e.
To re-associate a client with the correct network service device and re-attach the client to the network, follow these steps: 1. Open the system, and get the Network Service Device to be attached to the network from the NetworkServiceDevices collection. Set MySystems = MyNetwork.Systems Set MySystem = MySystems.Item(1) MySystem.Open() Set MyNSDCollection = MySystem.NetworkServiceDevices Set MyNSD = MyNSDCollection.Item(“MyNSD”) 2.
networks, so that each network can maintain its private media status while sharing a physical TCP/IP connection. When creating a system that uses private media, you should set the system’s InstallOptions property to lcaPrivateMedia. When creating a system on a shared media system, set the InstallOptions property to lcaSharedMedia. Since there will be multiple networks sharing the media, you should also specify a unique domain ID for your system.
background discovery by setting DiscoveryInterval property to 0. This is done automatically when the InstallOptions property is set to lcaSharedMedia. • Use the confirmed service pin algorithm for device installation. When using shared media, there is always a small chance that when a service pin message is received, it is from a device in a neighboring system. The confirmed service pin algorithm is designed to ensure that devices being installed belong to the correct system.
from traffic that has to span multiple channels, which allows more effective use of available bandwidth. • You want to provide for fault tolerance in the event of a physical-layer fault, such as a short or open circuit. Only devices on the faulty channel would be affected by such faults. Devices on other channels are isolated from the fault by the routers or logical repeaters. Overview of Router Types and Operation A router connects two channels.
Channel 1 Channel 2 Router Router Channel 3 Router Channel 4 Figure 8.1 A Network with Multiple Channels A LONWORKS router can be configured as one of four router types: • A repeater forwards all valid packets received on one channel to the other channel, without regard for address. Repeaters extend the physical reach of a channel, while preventing corrupted packets from causing problems. You should not confuse a router configured as a repeater with a physical repeater.
As of LNS Turbo Edition, LNS does not support defining or modifying a router as a learning router. If an application defines a router as a learning router, or changes a routers class to lcaLearningRouter, the LNS Object Server will automatically change the class to lcaConfiguredRouter. See the next paragraph for a description of configured routers, and the advantages they provide. • A configured router forwards packets based on internal routing tables.
When LNS discovers a router, it will automatically create a channel for the far side, and will choose an existing channel for its near side. The far side channel may in fact be a duplicate of a user-defined channel. Assuming that your LNS application defined a logical definition of this router and specified the user defined channels, this discrepancy will be resolved when the router is commissioned, and LNS will delete the channel that it had created for the router’s far side.
which are connected by a permanent bridge. 3. The final rule allows for redundant routing when using configured routers. Redundant router topologies provide fault tolerance by providing more than one routing path from one channel to another. They are also required when all devices on a given channel may not be able to hear one another (referred to as an ear shot problem), e.g. on a radio frequency channel. An example of a redundant routing topology is shown in Figure 8.3 below.
document. Each Subsystem has a Routers collection containing the Router objects that represent your network’s routers, just as each Subsystem has an AppDevice collection containing the AppDevice objects for the network. Routers have a similar set of properties (e.g. State, Location) and methods (e.g. Add, Commission) as application devices.
allocate a logical address, compute routing tables, and calculate connection timers for the device. When the device is commissioned, the LNS Object Server will verify, as best it can, that the device is indeed attached to the expected channel. If it is not, an exception will be thrown.
Resolving Installation Failures There are a few cases where attempts to register, add, or commission a device on a network with multiple channels may fail or have negative side effects. This usually happens when you attempt to install a device that was previously configured as part of another network without deconfiguring it. You should also consider the following: • If the device to be installed is configured on a subnet in the system’s domain that violates the logical topology (i.e.
3. Call PreMove() on the device selected in step 2. You must specify the new channel for the device with the newChannelObject element, and you can optionally specify the new subnet for the device with the newSubnetObject element. Note that if you do not specify the new channel for the device, LNS will attempt to automatically determine the channel using the channel isolation process described previously in this chapter. MyAppDevice.PreMove(TargetChannel, NOTHING) 4.
break communication between the LNS Server and a remote Full client, the NS#182 lcaErrNsInsufficientRtrsForNsi exception will be thrown. Using Dynamic Device Interfaces As described in the Device Interfaces section in Chapter 6, each LONWORKS device contains a device interface that represents the device’s functionality. The device interface consists of network variables, configuration properties and LonMark Functional Blocks.
Main Interface Custom Interface #1 Custom Interface #2 Custom Interface #3 FBs FBs FBs FBs NVs NVs NVs NVs CPs Figure 8.4 Device Interfaces Table 8.1 describes some of the properties of the Interface object. Some of these properties apply to the device’s interfaces as a whole. Consult the LNS Object Server Reference help file for a complete list, and for more extensive descriptions of each property. Table 8.
Property Description MaxNVSupported This property specifies the maximum number of network variables (static or dynamic) that the Interface object can contain. MessageTags This property contains the Interface object’s collection of static MessageTag objects (i.e. the message tags originally included in the interface). NetworkVariables This property contains the Interface object’s NetworkVariables collection (i.e. the network variables included in the interface).
and message tags to the new Interface as you desire, provided that the device supports them. For more information on these tasks, see the following sections. Adding LonMark Functional Blocks To a 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 LonMark Functional Block for each switch.
Configuring LonMark Functional Blocks You can assign existing dynamic network variables to dynamic LonMark Functional Blocks using the AssignNetworkVariable() method, and you can unassign them using the UnassignNetworkVariable() method. Alternatively, you can create new network variables that will be automatically assigned to the network interface using the procedure described in the Creating Dynamic Network Variables section on page 184.
Set MyNewTag = MyMessageTags.Add(“newName”) 4. For information on using message tags and message monitor points for monitor and control operations, see Chapter 9, Monitor and Control. Creating Dynamic Network Variables You can add network variables to custom interfaces on devices that support dynamic network variables, to dynamic LonMarkObject objects, or to static LonMarkObject objects that support dynamic network variable assignment.
MoveToInterface() method to move a dynamic network variable from the main interface to a custom interface. Once you have done so, you could remove the network variable from the custom interface, and its removal would be propagated to the main interface. Tracking Custom Interface Changes You can use the OnNodeIntfChangeEvent event to keep track of when a device’s interface is modified. The OnNodeIntfChangeEvent event is fired whenever a device's interface is changed.
the Index, Length, and ObjectType properties of the TypeSpec object. If LNS is unable to find the resource file for the program ID entered in step 2, the LCA#154 lcaErrUnavailableResourceFiles exception will be thrown. If LNS finds the resource file but is unable to find the type name referenced in step 2, the LCA#155 lcaErrNotFoundInResourceFiles exception will be thrown. Be sure that the network variable can support the new type before assigning it.
network variable they apply to. For example, configuration properties for default, minimum, or maximum values are often defined as to be of an inheriting type. Such configuration properties will also change their data type if the type of the changeable type network variable changes, and the related data formatting may change.
188 LNS Programmer's Guide
Chapter 9 - Monitor and Control This chapter describes the LNS features you can use to monitor and control the devices on your network. Monitor and control is the process of reading and writing network variables, and sending explicit messages.
Introduction to Monitor and Control By definition, device applications only have a local view of the network. They know what data they receive from the network (usually without regard to which devices produce the data), and they know what data they produce (usually without regard to which devices will consume the data). However, in most control systems there is a need for an application that provides an overall view of the system.
to the value of the network variable, without creating a monitor point to represent the network variable. This chapter describes the LNS features you can use to perform these monitor and control operations. Table 9.1 describes each section included in this chapter. Echelon recommends that you review the entire chapter before developing your application, so that you are aware of all the monitor and control capabilities LNS provides. Table 9.
Section Description Using Configuration Properties In a Monitor and Control Application In some cases, you may want to write an application to control the values of the configuration properties on the devices on your network. This section provides guidelines to follow when doing so. Data Formatting This section describes how your application can format the data it obtains through monitor points and data points.
Use permanent monitor sets when you need to create monitor points that will be used often, or in multiple client sessions. If you need monitor points that will only be used once, or in a single client session, you should use temporary monitor sets. Temporary Monitor Sets Temporary monitor sets are opened automatically by LNS as they are created, and can only be accessed from the client that created them. They cannot be accessed from the permanent MonitorSets collections described in the previous section.
on the UseBoundUpdates property, see The Implicit Bound Network Variable Monitoring Scenario on page 220. Creating Monitor Sets The first step when creating a monitor and control application is to create a monitor set. To create a permanent monitor set, follow these steps: 1. Open the ObjectServer, Network, and System you plan to monitor and control, as described in Chapter 4, Programming an LNS Application. 2. Get the AppDevice object contained in the Network object's MyVNI property.
NvOptions property, the MsgOptions property, and the Tag property. You can use the NvOptions property, and the MsgOptions property to set the default monitoring options that will be applied to the monitor set. For more information on monitoring options, see Setting Monitoring Options on page 200. You can use the Tag property to store any information required to quickly and efficiently identify the monitor set, such as the name of the device you plan to monitor with the set.
3. Get the network variable(s) you will be monitoring: Set Set Set Set MyInterface = MyAppDevice.Interface MyNVs = MyInterface.NetworkVariables MyNV = MyNVs.Item(“nvoTemperature”) MyNV2 = MyNVs.Item(“nvoAlarm”) 4. Repeat steps 2 and 3 until you have acquired all the network variables you want to monitor, and get the monitor set that will contain the monitor points for these network variables. You should have first created a monitor set for this purpose, as described in the Creating Monitor Sets section.
Adding Message Monitor Points to a Monitor Set Each MonitorSet object contains a MsgMonitorPoints property. The MsgMonitorPoints property returns a collection of the message monitor points in the monitor set. There are two ways to use message monitor points. You can create a message monitor point to send messages to (and receive messages from) a single device on the network.
6. Get the monitor set you will use to monitor the messages. You should have first created a monitor set for this purpose, as described in Creating Monitor Sets. Remember that when adding monitor points to a monitor set, you should access the set through the MyVni property. Set MyMonSets = MonVNI.MonitorSets Set MyMonSet = MyMonSets.Item(“Monitor Set 1”) 7.
4. Get the device that you plan to send explicit messages to with the new message monitor point. Set MySubsystem =MySubsystems.Item(“Third Floor Room 7”) Set MyAppDevices = MySubsystem.AppDevices Set MyAppDevice= MyAppDevices.Item("Vent") 5. Get the msg_in message tag on the application device selected in step 4, and connect it to the dynamic message tag you created on the Network Service Device. Set MyInterface = MyAppDevice.Interface Set MyMessageTags = MyInterface.MessageTags Set MyTag = MyMessageTags.
Setting Monitoring Options Each MonitorSet object, and each individual MsgMonitorPoint and NvMonitorPoint object, contains properties that allow you to determine the behavior of the monitor set or monitor point while it is monitored and controlled. These properties are listed and described in the following sections. • MonitorSet.NvOptions and MonitorSet.MsgOptions – Each MonitorSet object contains an NvOptions property, and a MsgOptions property.
If you do not want a monitor point to use those default options during a particular monitoring session, you can change the options that will be used by writing to its CurrentOptions. All changes made to the CurrentOptions property take effect immediately. However, when the monitor set is closed, these changes will not be saved as the default options to be used the next time it is opened. The default options for each monitor point must be maintained using the DefaultOptions properties.
3. When a monitor set is opened, each network variable monitor point in the set will use the default options established in either step 1 or step 2. If you want a network variable monitor point to use different options during a given monitoring session, you can do so by writing to the NvMonitorPoint object’s CurrentOptions property after the monitor session has started (i.e. the monitor set has been opened). Remember that these changes take effect for the current session only.
Table 9.2 NvMonitorOptions Object Property Name Description Authentication This property is not used. If the UseBoundUpdates option for a monitor point is set to True, the monitor point’s authentication state is determined by the UseAuthenticationFlag property of the ConnectDescTemplate specified when the monitor point was created. Otherwise, the authentication state is set based on the monitored network variable’s current authentication state.
Property Name Priority Description This property determines whether or not priority messaging will be used when sending network variable updates during the current monitoring session. If True, priority messaging will be used. Setting this property through the NvOptions property of a permanent monitor set, or through the DefaultOptions property of a permanent network variable monitor point, does not have an effect.
Property Name ResetPollingIfUpdated Description Use this property to determine whether or not the poll interval for each network variable monitor point in the set will be reset whenever a new value for the point is received, either via a bound update or a read operation. If True, the poll interval will be reset. For example, consider a case where the poll interval is set to 100 seconds.
Property Name ServiceType Description This property determines the default messaging service to use when explicitly writing the network variable monitor point. This does not apply to polling or implicit or explicit bound monitoring. Setting this property through the NvOptions property of a permanent monitor set, or through the DefaultOptions property of a permanent network variable monitor point, does not have an effect.
Property Name Description SuppressPollingIfBound This property determines if polling will be turned off for monitor points whose target network variable is bound to the host device. If True, polling will be turned off. In this case, polling will be turned off even if the monitor point does not use bound updates, as long as the target network variable is bound to the host device through some other means.
Property Name UseBoundUpdates Description If set to True, this property enables implicit binding. With implicit binding enabled, LNS will attempt to create connections without user intervention. Changing this option through the CurrentOptions property does not have an effect. Before using this property, you should review the Using Network Variable Monitor Points section, which describes different ways you can use implicit binding. This property must be set to False for temporary monitor sets and points.
monitor point’s FilterCode property. Set MsgMonitorPointOptions =_ MyMsgMonitorPoint.DefaultOptions MsgMonitorPointOptions.FilterCode = 62 Set MyMsgMonitorPoint.DefaultOptions =_ MsgMonitorPointOptions NOTE: Because temporary monitor points are only used in a single client session, their DefaultOptions are not accessible. If you attempt to acquire the DefaultOptions property through a temporary monitor point, the LCA:#161 lcaErrNotAllowedOnTemporaryObject exception will be thrown.
Table 9.3 MsgMonitorOptions Object Property Name Authentication Description This property determines whether authentication will be used when sending explicit messages using this monitor point or monitor set. If this property is set to True, authentication will be used. Default Value: False FilterByCode This property indicates whether the FilterCode property will be used to filter message tag values.
Property Name Priority Description This property determines whether or not priority messaging will be used when sending explicit messages with this monitor set or monitor point. If True, priority messaging will be used. Setting this property through the MsgOptions property of a permanent monitor set, or through the DefaultOptions property of a permanent message monitor point, does not have an effect.
Property Name Retries Description This determines the number of retries to use for acknowledged, request/response, or repeat service messages. Setting this property through the MsgOptions property of a permanent monitor set, or through the DefaultOptions property of a permanent message monitor point, does not have an effect.
Opening and Enabling Monitor Sets After you have created a monitor set and defined its monitoring options, you can open it and enable it for monitor and control operations. Note that you will not be able to use a permanent monitor set that was created while the system management mode was lcaMgmtModeDeferConfigUpdates until the system management mode has been changed back to lcaMgmtModePropagateConfigUpdates.
You can also call the Disable() method on a specific NvMonitorPoint or MsgMonitorPoint object. This will override subsequent calls to the MonitorSet object's Enable() method. In other words, if you call the Disable() method on a monitor point named Point A, and then call the Enable() method on the monitor set containing Point A, Point A would not be enabled, but all other monitor points in the monitor set that have not been explicitly disabled would be.
method is most efficient if network variable values need to controlled individually, or if they need to be written infrequently and unpredictably. For more information on this, see Explicitly Reading and Writing Network Variable Monitor Points on page 215. • Explicit Bound Monitoring and Control. This method should only be used for fan-out connections, which is the process of a single host output network variable controlling two or more input device network variables.
Example of Explicitly Reading a Network Variable Monitor Point To recap the previous discussion, follow these steps to explicitly read a network variable value via a monitor point: 1. Create a monitor set on the device containing the network variables you want to monitor, as described in Creating Monitor Sets on page 194. Then, create a monitor point for each network variable you want to monitor, as described in Adding Network Variable Monitor Points to a Monitor Set on page 195. 2.
2. Acquire a DataPoint object to use to write the value of the network variable monitor point. Then, set the value of the DataPoint object and call the Write() method. LNS will update the value of the network variable being monitored with the new value. Set MyDataPoint = MyNvMonitorPoint.DataPoint MyDataPoint.FormattedValue = “75.0 1” MyDataPoint.Write() NOTE: If the AutoWrite property is set to True, you do not need to call the Write() method in this step.
To recap this discussion, make sure that you follow these steps when using the polled network variable monitoring scenario: 1. When you create your monitor points, you should consider setting the Tag property to a value you can use to identify the source device and network variable. 2. When you set the monitoring options for the monitor set, make sure that the PollInterval property is set to the interval at which you want to poll each network variable.
When you design such a monitoring application, you should bear in mind that the network’s primary focus is on the execution of the control algorithm, and that any network traffic generated, or any device or network resources consumed by your monitoring approach, should not prevent the network from fulfilling its primary task. You should design network applications to be as unobtrusive as possible. 4.
ByVal nvMonitorPoint As Object, _ ByVal dataPoint As Object, _ ByVal srcAddress As Object) If nvMonitorPoint.Tag = "Room Thermometer" Then roomTemp = dataPoint.FormattedValue End If End Sub Note that by using the OnNvMonitorPointUpdateEvent event as described in this section, you will receive the events through the LNS Object Server. You can use the ILcaNvMonitorPointListener interface to receive the events directly from the network variable monitor point, which may be more efficient.
4. Enable the monitor set, as described in Opening and Enabling Monitor Sets on page 213. Once implicit bound monitoring has started, your application will be informed of each network variable update via the OnNvMonitorPointUpdateEvent event. If you only want your application to be informed when the value of a network variable monitor point changes, set the ReportByException property to True when you set the monitoring options for the monitor point or monitor set.
Control Device nvoSetting Target Network Variables LNS Application PC Remote Display Device nvoSetPoint nviInput Figure 9.1 Fan-In Connection When monitoring a fan-in connection, you can monitor the input network variable, the output network variables, or both.
connected to an input on another device. However, this is usually not the appropriate setting for a fan-out connection, as this will generally result in sending out individual messages for each input network variable. You could then write to the value of the output network variable to update the values of all of the input network variables on the fan and vent devices at once. Figure 9.
4. You can now control the input network variables on the network by writing to the host network variable on the PC. Or, you can monitor value changes on the device network variables though the OnNvMonitorPointUpdateEvent event. Defining Host Network Variables An LNS application can dynamically create and delete local host network variables (i.e. network variables on the Network Service Device being used by the LNS application).
Monitoring Message Monitor Points The first step to take when monitoring application messages is to explicitly connect a message tag on an application device to the msg_in tag on your application’s Network Service Device. This will cause any messages sent by the device using the message tag to be delivered to the Network Service Device. The second step is to create a message monitor point to receive the messages.
To monitor messages that begin with a specific message code, set the FilterByCode monitoring options property to True, and the FilterCode property to the message code to be monitored when you set the monitoring options for the monitor set. To recap this discussion, follow these steps to monitor messages: 1. Create a monitor set, and add monitor points for the message tags you want to monitor. For more information on these tasks, see Creating Monitor Sets on page 194, and Managing Monitor Sets on page 195.
Private Sub lcaObjectServer_OnMsgMonitorPointUpdateEvent( _ ByVal msgMonitorPoint As Object, _ UpdateType As Integer, _ByVal inputDataPoint As Object, _ ByVal outputDataPoint as Object, _ ByVal srcAddress As Object) If msgMonitorPoint.Name = sensorMsgMonPoint _ AND UpdateType = lcaMonitorEventTypeMsgRequest Then outputDataPoint.Value = myResponseData End If End Sub Controlling Message Points You can send application messages to a device using MsgMonitorPoint objects.
connected to the PC running the application. Independent client applications read and write data directly to and from the devices on the network without writing to the LNS database. Temporary MonitorSets objects are not available to Independent client applications, and neither are the methods and properties of the AppDevice object.
3. Call the Advise() method on the MsgMonitorPoint object you want to monitor. Specify the COM object created in step 1 as the object element. At this point, LNS will stop generating the OnMsgMonitorPointErrorEvent and OnMsgMonitorPointUpdateEvent events for the monitor point, and the object specified as the object element will start receiving UpdateErrorEvent and UpdateEvent events for the monitor point.
3. Call the Advise() method on the network variable monitor point you want to monitor. Specify the COM object created in step 1 as the object element. At this point, LNS will stop generating the OnNvMonitorPointErrorEvent and OnNvMonitorPointUpdateEvent events for the monitor point, and the object specified as the object element will start receiving UpdateErrorEvent and UpdateEvent events for the monitor point.
with the configuration currently stored in the devices, even if database changes have been made subsequently while the system management mode is set to lcaMgmtModeDeferConfigUpdates. The configuration of the permanent monitor sets will not be updated to reflect the database changes until the management mode is changed to lcaMgmtModePropagateConfigUpdates, at which point the devices will also be updated.
Set MyInterface = MyAppDevice.Interface Set MyVariables = MyInterface.NetworkVariables Set MyNV = MyVariables.Item(“Input One”) 3. Use the GetDataPoint() method to create a DataPoint object for the network variable. The GetDataPoint() method takes a single input parameter that must be set to 0. Set MyDataPoint = MyNV.GetDataPoint(0) 4. To set the value of the network variable through the DataPoint object, set the Value, RawValue, or FormattedValue properties, and then call the Write() method.
names defined for the SNVT_defr_term type, such as DFT_TERM_LAST, to the FormattedValue property of the DataPoint. You should also note that this is the only property that enforces range limits (i.e. the Value and RawValue properties do not enforce these restrictions).
properties when it is absolutely necessary. For an overview of configuration property access performance, see Performance Considerations on page 240. Generally, you should perform configuration property management using the ConfigProperty objects stored in the LNS database, rather than by writing to the configuration property value directly via network variable writes.
property values to the device, call the DownloadConfigProperties() method with the lcaConfigPropOptLoadValues and lcaConfigPropOptExcludeDeviceSpecific options set. For more information on the UploadConfigProperties() and DownloadConfigProperties() methods, see Downloading and Uploading Configuration Properties on page 126. Using the GetDataPoint Method You can use a DataPoint object to read and write to the value of a configuration property.
ConfigProperty is not an array, specify 0 as the index parameter. The second parameter is the options element. This determines how LNS will apply changes you make to the DataPoint object to the LNS database, and to the physical device on the network. For more information on this, see the next section, Data Source Options. Note that you can change both of these options later by modifying the DataPoint object’s SourceIndex or SourceOptions properties. 3.
Table 9.4 Data Source Options Value lcaDataSourceOptionsNormal Description If you use this option to create a DataPoint, or if you set the SourceOptions property of the DataPoint to this value later, then the value of the ConfigProperty will be updated in the LNS database and in the physical device on the network each time you write to the value of the DataPoint. When you read the value of the DataPoint, the value will be read directly from the device if the source ConfigProperty is device-specific.
Value lcaDataSourceOptionsTypeDefaultValue Description If you use this option to create a DataPoint, or if you set the SourceOptions property of the DataPoint object to this value later, then the DataPoint will always return the default value of configuration properties using the same type as the source configuration property.
The DownloadConfigProperties() and UploadConfigProperties() generally affect all the configuration properties on a device. You can also use DataPoint objects to synchronize a single configuration property value in the LNS database with the value of the configuration property on the physical device. To do so, follow these steps: 1. Create a DataPoint object for the configuration property you want to update. Specify lcaDataSourceOptionsfromDevice as the options element when you call GetDataPoint().
Performance Considerations The performance of the monitoring application when reading configuration properties from the database depends on disk performance. When reading configuration property values from the device, rather than from the LNS database, the performance of monitoring configuration properties varies depending on the implementation method.
If a configuration property is implemented using a configuration network variable, the monitoring performance for that configuration property would be similar to the monitoring of an input network variable. When you write an application to monitor configuration property values, you should take the configuration property access method into account, as the time required to access the configuration properties on your network will impact the overall performance of your application.
resource file. See Chapter 6 for more detailed information on program IDs and scope selectors. The FormatSpec object contains a Scope property, a ProgramId property, an Index property, a FormatName property, and a FormatType property. To use these properties to change the base type of a monitor point or data point, follow these steps: 1. Access the FormatSpec object for the monitor point or data point whose base type you want to change. Dim MyFormatSpec as LcaFormatSpec Set MyFormatSpec = MyNvMonitorPoint.
Table 9.5 FormatSpec Object Properties Property Description AltFormatName This property contains an indexed list of all formats that can be applied to the type used by the network variable or data point. For example, in a FormatSpec object representing the SNVT_temp_f#US format (i.e. degrees Fahrenheit), this property would contain “SNVT_temp_f#US”, "SNVT_temp_f#SI", and "SNVT_temp_f#US_diff".
Property UnitsAdder Description This property indicates the value that should be added to the raw value of the data point or monitor point when it is unit-converted for display as a formatted value (via the FormattedValue property). This addition is performed after the raw value is multiplied based on the UnitsMultiplier property.
the PC running your 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.
Table 9.6 lists the various properties of the FormatLocale object, and describes how they affect the display of data stored in the FormattedValue property. For more detailed information on each property, consult the LNS Object Server Reference help file. Table 9.
Property Description ListSeparatorCharacter ListSeparatorCharacterSource The ListSeparatorCharacter property determines what character will be used to separate items in the formatted value that are returned as parts of a list. This applies to format specifications that specify the use of a localespecific separator character, e.g.
lcaFormatLocaleSourceManualSetting(2) value. Consult the LNS Object Server Reference for more information on these properties.
Chapter 10 - LNS Database Management This chapter provides information you will need when managing your LNS databases. This includes topics such as validating network databases, performing database back-ups, moving databases, and recovering network databases.
Overview of LNS Databases As described in Chapter 3, the LNS Server maintains two types of databases: the LNS global database and a set of LNS network databases. These are high-performance diskbased databases with in-memory caching to optimize repeated access to data. The LNS global database contains the Networks collection, meaning that it contains the names and locations of each of the network databases.
Backing Up Network Databases The ability to backup and restore an LNS database is a critical requirement for most systems. LNS provides a network recovery feature you can use to recover a lost database from the network, which is described later in this chapter. However, it is much more reliable to use an archived copy to restore a lost database, or a database that has become corrupted. Different factors can cause database corruption.
MyNetwork.Backup(“C:\MyBackupDBs\” & MyNetwork.Name) You can use this method to backup a network database at any time, including while the network is open and clients are attached to it. However, if a remote Full client application accesses the Networks collection while the database is being backed up, that network will not appear in the Networks collection.
Figure 10.1 LNS Database Validation Tool To start a database validation, follow these steps: 1. Open the LNS Database Validation Tool and select the network you want to validate from the Network to Validate: pull-down list. 2. Optionally click the Repair Database check-box if you want LNS to attempt to repair the errors it finds. 3. Click the Validate button to start the network validation. Status and result of the validation will appear in the scroll box at the bottom of the dialog.
Table 10.1 lists the properties of the DatabaseValidationReport object. See the LNS Object Server Reference help file for more details on the DatabaseValidationReport object and its properties. Table 10.1 DatabaseValidationReport Object Property PassedValidation Description This property will be set to True if the network passed the database validation. This will occur if no errors were discovered during the validation, or if all the errors discovered during the validation were repaired.
recommends that you perform the database validation while a minimal number of client applications are connected to the database. One suggested approach is to backup the database and restore it with a different name and location, and perform the validation on this restored database. This approach will minimize the disruption caused by the validation, and has the benefit of producing a backup whose validity is known.
3. Close the system. This detaches the Object Server from the network and shuts down the LNS Object Server. MySystem.Close() 4. Close the network. This closes the network database. MyNetwork.Close() 5. Call Remove()on the Networks collection to delete the network. The Remove() method deletes the network database directory, the network database, and the reference to the network within the global database: MyNetworks.Remove(MyNetwork.
(.BMP extension), and source files (.NC, .C and .H extensions). It is also a good idea to reinstall plug-in software that applies to device types that are used within this network with your data. Echelon recommends that you backup all these files before performing the move. NOTE: Figure 6.2 in Chapter 6 of this document depicts where the external interface files on a PC are stored.
a function of the number of devices, network variables, channels, and connections. • Network recovery only recovers attributes and properties stored in the devices on the network. LNS-specific information such as subsystem names and device names is not recovered. In addition, the recovery process will not create an exact duplicate of the original database.
• The recovery process has no way of determining what network variables are hubs, and what network variables are targets, in the connections on the recovered network. These relationships are arbitrarily assigned. Because the hub/target relationships may change, the recovery may not restore the proper connection descriptions to the connections on the recovered network. If the recovery is unable to determine the correct connection description for a connection, it uses the default connection description.
Performing a Network Recovery To recover a network database, you can use the LNS Database Recovery Wizard. The wizard takes your preferences on several guided pages, runs and controls the recovery process, and formats the resulting database by evaluating device resource files, device interface files, and device interface data. You can access the LNS Database Recovery Wizard by selecting Start>Programs>Echelon LNS Utilities>LNS Database Recovery Wizard.
7. Optionally add objects, set properties, and call methods. This includes defining DeviceTemplate objects, and setting network timers or other properties of the System object. If you add device templates at this time, your recovered devices will have more meaningful names for their device templates, and include more accurate default settings. Note that you cannot add any objects that consume network resources at this point, such as AppDevice, Router, Channel or Subnet objects.
During the recovery process, the LNS global database will be locked to prevent accidental modification while recovery is in progress. Other LNS applications should not make changes to the LNS network database while the network is being recovered. The recovery of a large network may take a long time. You can examine the System object’s RecoveryStatus property to see how a network recovery is progressing. You need to use a separate process to read the RecoveryStatus property.
ConfigProperties collection of the AppDevice for a ConfigProperty object with the TypeIndex property set to 17 (SCPT_location). D) When you find a SCPTlocation configuration property, parse it for the device’s subsystem path and name. Create the subsystem if it does not exist, and then invoke the AddReference() method to move the AppDevice to the new subsystem. Set the Name property of the AppDevice to the proper name, if it is available.
264 LNS Programmer's Guide
Chapter 11 - LNS Network Interfaces This chapter describes how to configure the various network interfaces you can use with LNS. It also describes the differences between standard and high performance network interfaces.
Network Interfaces Overview Each Network Service Device contains a network interface. The Network Service Device uses the network interface to communicate with the LONWORKS network, as the network interfaces provides the physical connection between the network and the LNS Server. Each network interface uses LonTalk messaging to communicate with the LONWORKS network and the devices on the network. This chapter contains information you will need when choosing a network interface.
Windows plug-and-play standard. This hardware may be used as an LNS high performance network interface by selecting PCL20VNI from the NI Application field of the LONWORKS Plug 'n Play control panel. It can be used as a standard interface by selecting NSIPCLTA from the NI Application field. PCLTA-21 Echelon’s PCLTA-21 card is a high performance network interface for desktop and embedded personal computers equipped with a 3V and 5V 32-bit PCI interface and a compatible operating system.
Power Line SLTA The Power Line SLTA is an EIA-232 compatible serial device that allows any PC with an EIA-232 interface to connect to and communicate with a LONWORKS network. The Power Line SLTA can be connected to host PC through a pair of modems and a telephone network, allowing for remote operations. It can be configured to answer incoming calls from remote hosts, or to initiate calls to remote hosts.
The following section describes some of the other differences in behavior between standard network interfaces and high performance network interfaces. Addressing All devices that communicate on a LonTalk channel must have a Neuron ID and a domain/subnet/node address. When using a high performance network interface, these addresses are stored on the PC containing the network interface. Standard network interfaces store these addresses on the network interface.
Most standard network interfaces can only support a single outstanding transaction at a time. This means that in order to poll 2 network variables, the first poll must be completed before the second can start. Note that unlike most other standard network interfaces, an i.LON 100 Internet Server can support up to 15 simultaneous subnet/node or group addressed transactions.
You should note that if a high performance network interface is replaced with another high performance network interface, the new network interface will use the same Neuron ID as the old one. Changing the network interface’s Neuron ID does not affect the operation of Local or Lightweight clients. However, if the Neuron ID assigned to a Full client’s network interface has been modified, it may be necessary to use the PreReplace() method to replace the Network Service Device when using it to open a network.
In Figure 11.1, the LNS Server is using xDriver to connect to two i.LON 10 Ethernet Adapters. The OpenLDV xDriver integrates with LNS at the same point as other LNS network interfaces such as the PCC-10 and the PCLTA-20. The OpenLDV xDriver supports scalable access to many network interface devices. The default xDriver implementation uses the Windows Registry as a database to store the information it requires to connect to each network interface.
LNS Application and LNS Server PC Echelon LONWORKS/IP Configuration Server PC LONWORKS/IP (LAN, WAN) LONWORKS/IP Router (i.LON 600 LONWORKS/IP Server or i.LON 1000 Internet Server) Traditional LONWORKS Channel (TP/FT-10) LONWORKS Device LONWORKS Device LONWORKS Device LONWORKS Device Figure 11.2 LonWorks/IP Interfaces NOTE: LONWORKS /IP channels in LNS Turbo Edition require the use of the new Echelon LONWORKS/IP Configuration Server. As a result, if an i.
LNS does not include external interface files for Network Service Devices. However, it does create default DeviceTemplate objects for use by Network Service Devices. As described earlier in this chapter, the network interface used by a Network Service Device can affect the Network Service Device’s capabilities. Some of these capabilities (e.g. maximum number of groups) affect how LNS will configure the Network Service Device.
Table 11.1 Network Service Devices Program ID Usage 90000010103800000 Used when the Network Service Device uses a high performance network interface, a LONWORKS/IP interface, or when LNS is opened in engineered mode. 90000010103800001 Used when the Network Service Device uses a standard network interface. 90000010103800002 Used when the Network Service Device uses a standard network interface that supports enhanced authentication commands, such as an i.LON 100 Internet Server.
276 LNS Programmer's Guide
Chapter 12 - Director Applications and Plug-Ins This chapter discusses the standards and development methodology for creating interoperable LNS director and plug-in applications.
Introduction to the LNS Plug-In Model All LNS applications achieve a level of interoperability by using the common API provided by the LNS Server, and by using the LNS global database and shared network databases. The shared network databases allow one LNS application to add a new device to a network, and for all other LNS applications attached to the database to immediately know about the new device.
downloaded from Echelon’s website at http://www.echelon.com/. You should consult this manual before developing an LNS component application. LNS Plug-In API Director applications call plug-ins using the LNS Plug-In API. This ActiveX-based API defines an automation object that provides a standard interface between a director application and a plug-in. Director applications can launch plug-ins and communicate with them using the methods and properties of the automation object.
Registering Plug-In Commands in the Windows Registry Registration commands for plug-ins must also be registered in the Windows Registry. Registration commands are plug-in commands automatically invoked by a director application to register the plug-in application’s commands within an LNS network database.
To accomplish these tasks, the LNS director application must have access to the Windows Registry, to the LNS Object Server hierarchy, and must implement the clientside of the LNS plug-in API. Implementing the Client-Side LNS Plug-In API The LNS Plug-In API is a simple COM interface that defines a list of properties and methods by name.
This will release the reference to the plug-in, and will therefore stop the director from accessing the plug-in application’s properties and methods through the MyPlugIn variable. However, releasing the reference will not terminate the plug-in itself. The LNS Plug-In Programmer’s Guide contains a section called How Plug-Ins Know When To Exit that addresses the plug-in lifetime considerations for the plug-in developer. The director application is free to hold on to the reference.
Figure 12.1 LNS Plug-Ins and the Windows Registry Note that the default value for each plug-in listed in the Plug-In Windows Registry key equals the plug-in application’s Registered Server Name. For example, Figure 12.1 shows details for the Echelon LNS Report Generator plug-in, whose default value and registered server name is “EchelonLNSReportGenerator.Application.” The director application must inspect the Plug-In Windows Registry key.
• If a ComponentApp object that relates to the current plug-in (stored in the Windows Registry as the registered server name) can be found, but its VersionNumber is less than the Version advertised in the Windows Registry, the plug-in must be re-registered with LNS. To register or re-register a plug-in, the director connects to the plug-in and calls its SendCommand() method with the CommandID argument set to lcaCommandRegister(50).
In other cases, specifically for cases where no or multiple plug-ins have been marked as the default provider, the director provides some user interface that lets the user to choose between all applicable plug-in applications and the director’s own generic solution. For operations that relate to a device, the DeviceTemplate object provides a ComponentApps collection.
ObjectServer 4 ComponentApp Continue search for applicable plug-ins here. Start search here unless the action applies to a specific system or a subelement thereof. System Subsystem ComponentApp 3 Continue search for applicable plug-ins here. Start search here unless the action applies to a device or a sub-element thereof. AppDevice DeviceTemplate 2 Continue search for applicable plug-ins here. Start search here unless the action applies to a functional block or a subelement thereof.
The SendCommand() method and related properties are detailed in the How Plug-Ins Work - The Details section in the LNS Plug-In Programmer’s Guide. When calling the SendCommand() method, you should note that some objects support alternative addressing syntax used with the objectName parameter, as detailed in Appendix C of the LNS Plug-In Programmer’s Guide.
Implementing an LNS Plug-In An LNS plug-in is implemented as an ActiveX automation server. In Visual Basic, this is done by creating a Sub Main, defining Sub Main as the startup form, and implementing a public Application class. Implementing an LNS Device Plug-In Device plug-ins are a special class of plug-ins that are specific to a particular device type (i.e. program ID).
Chapter 13 - LNS Licensing This chapter describes the LNS licensing mechanism, including how LNS applications register with the LNS Server and how end-users consume and replenish LNS Device Credits.
Overview of LNS Licensing and Distribution The LNS licensing model is based on LNS Device Credits. Each LNS Server PC contains a number of LNS Device Credits, and you need one LNS Device Credit for each application device you commission on a network. The LNS Object Server tracks these LNS Device Credits automatically, and removes an LNS Device Credit from the credit pool each time a device is commissioned.
minimum purchase requirements, with the Echelon Software License Generator product separately available from Echelon. Contact your Echelon sales representative for details. The end-user should also use the LNS Server License Transfer Utility to transfer the LNS Device Credits and the license in order to move the LNS Server to another PC. The LNS Device Credits and license are transferred together. It is not possible to move some of the LNS Device Credits on a PC to another PC.
and begins tracking the number of deficit credits. For more information on the OnLicenseEvent event, see Tracking License Events on page 293. If the number of deficit credits in use is reduced to zero, either by installing more LNS Device Credits on the LNS Server PC, or by removing devices from the network, the timer will reset and the LNS Server will return to normal operation. If the timer expires or the number of deficit credits used exceeds the maximum, the LNS Server will no longer operate.
credits are in use, and therefore there is no time limit. The special value of 254 indicates that the application is operating in Demonstration Mode, or that the application is a legacy (LNS 1.x) application, and there is no time limit. • DeficitCredits: The number of deficit credits currently being used. • LicensedCredits: The number of LNS Device Credits licensed on the LNS Object Server. This number does not include the number of deficit credits allowed. • LicenseType: The type of license in effect.
• LIC_DEFICIT: A credit or debit has been charged, and the number of licensed LNS Device Credits has been exhausted. As described in the Standard Mode section on page 291, the LNS Object Server will continue to run for a 14-day grace period during which the deficits credits can be used. Read the DaysRemaning and DeficitCredits properties of the CreditInfo object returned by the event to determine how many deficit credits are available, and how much longer the LNS Server license is valid for.
RestoreLicense() method is called with the wasLNS parameter set to False, the LNS Server will debit LNS Device Credits based on the commissioned count. Licensing and Device Manufacturing In a manufacturing setting, you may want to load devices with the same configuration information. The AppDevice object's Replace() method is a convenient way to configure devices quickly in an "assembly line" fashion.
Figure 13.1 LNS Server License Wizard 2. This window contains the current license status of the PC running the utility, and the number of LNS Device Credits available on the PC. Enter the number of LNS Device Credits you want to add in the Enter credits to add text-box, and click the Next button. This opens the order processing window shown in figure 13.2.
Figure 13.2 Order Processing Window. 3. The order processing window contains the information you need to provide to Echelon to order additional LNS Device Credits. You can copy this information to a Windows clipboard by clicking the Copy to Clipboard button. This generates an order form containing the required customer information, which you can paste into a document and send to Echelon (or an authorized distributor) via mail, fax, or email.
Figure 13.3 Upgrade Completion Window. Using the LNS Server License Transfer Utility You can use the LNS Server License Transfer Utility to transfer an LNS Server license between two LNS Server PCs. The transfer is a 3-step process. To begin, open the LNS Server License Transfer Utility through the Echelon LNS Utilities group in the Windows Programs menu, and follow these steps: 1. The initial window displays a welcome message. Click Next to open the dialog shown in Figure 13.4.
Figure 13.4 Transfer Step Selection Window 2. There are three tasks you will perform with this window. Select the task you are currently performing, and click Next to continue. These tasks must be performed in the order they are listed. You must perform steps 1 and 3 are on the PC that will receive the transferred credits, and you must perform step 2 on the PC providing the credits. A floppy disk or a shared drive, such as a mapped network drive, is required to complete the transfer.
Figure 13.5 Shared Drive Selection Window 3. Select the drive to act as the transfer location from the pull-down list, and click Back to return to the dialog shown in Figure 13.4. Then, continue with Step 2 of the transfer operation.
Chapter 14 – Distributing LNS Applications This chapter describes how you should redistribute your LNS applications, including how to use the LNS Redistributable Maker utility and how to install your LNS application.
Distributing LNS Applications If you are using the LNS Application Developer’s Kit, you can distribute your LNS applications, but you cannot distribute any of the LNS runtime files installed on your development PC. If you want to redistribute LNS applications, you must purchase the LNS Redistribution Kit. When you install this product, the Echelon LNS Redistribution Kit program directory is created. This directory contains the LNS Redistributable Maker utility.
1. Click Next to begin using the utility. This opens the dialog shown in Figure 14.2. Figure 14.2 Redistributable Source Path Selection Dialog 2. Figure 14.2 illustrates the redistributable source path selection window. Select the path of the source redistributables folder, and click Next to continue. This opens the dialog shown in Figure 14.3.
Figure 14.3 Redistributable Selection Dialog 3. Figure 14.3 illustrates the redistributable selection window. Select LNS Server or LNS Remote, depending on whether your application will operate locally or exclusively remotely. If you select the LNS Remote option, your application must set the RemoteFlag property to True before opening the LNS Object Server, as described in Chapter 4 of this document.
Figure 14.4 Initial Credit Selection Dialog 4. The LNS Redistributable Maker can allocate a number of LNS Device Credits to be available to the LNS Server installed with your application. Use the dialog shown in figure 14.4 to determine how many LNS Device Credits will be available. Once the LNS Server redistributable package is installed and registered with a Type 3 license, the LNS Device Credits allocated in this step will be enabled for the user.
Figure 14.5 Select Setup Package Destination Folder Dialog 5. Specify the location of the setup packages that are generated. If you specify a folder name that does not exist, the LNS Redistributable Maker utility will create that folder automatically. You can produce various redistributable setup packages. For instance, you may want to sell different versions of your product, where each version of the product differs by the number of LNS Device Credits that are initially included with it.
not need to use setup.exe, and should use the simpler _SetupLNS.dll, as described in the following sections. The setup.exe application introduces a noticeable delay after the LNS runtime installation progress dialogs are complete, potentially causing it to appear as if your installation is complete before it actually finishes. For this reason, Echelon recommends using _SetupLNS.dll in the Windows Installer environments where it is supported. Even though Echelon recommends that you use _SetupLNS.
Once the LONWORKS path key has been created, you cannot modify it to point to an alternate folder. If the LONWORKS path key is changed after it has been initially set, some or all of the Echelon software installed on your machine could malfunction. For compatibility with all releases of Echelon products, the value of the LonWorks Path entry should be a full path, including drive designation, and never end in a slash, “\”. Step 2: Preset the LNS Network Database Path Like LNS 3.
The statement, “The setup cannot continue” may be confusing to the users of your installation, even if you ignore the return code from setup.exe and continue your installation. In order to avoid this dialog, you must check for this case before running setup.exe, and avoid any attempt to install over a greater version of the LNS runtime.
The LNS Application Developer’s Kit and LNS Server Edition products both install the version 3 Microsoft XML Parser. Using _SetupLNS.dll _SetupLNS.dll is a Windows Installer DLL. This means that if it is embedded within your Windows Installer based installation, you can call its functions within your Custom Actions. No parameters are passed to Windows Installer DLLs.
Property Description DLL Filename \_SetupLNS.dll Install Execute Sequence The _SetupLNS.dll component provides the following features: 1. The _SetupLNS.dll custom actions take care of all LNS version checking that is required to install an LNS runtime of a particular version. The version that it attempts to install is based on the _SetupLNS.
In order to find the LNS runtime installation files when the Custom Action is called, the _SetupLNS.dll makes the following assumptions about the configuration of your installation and installation medium. It assumes that there is a Windows Installer property named SETUPEXEDIR defined, and that this property gives an absolute directory location on your source medium.
Chapter 15 - Advanced Topics This chapter addresses a number of advanced topics that are not described in the previous chapters. This includes using LNS to perform file transfers, using the OnSystemNssIdle event, portable and remote tool development guidelines, multi-threading, avoiding memory leaks with LNS, and creating interoperable LNS client applications.
File Transfer Each System object contains a FileTransfer object. This object represents a LonMark file transfer session involving a group of application devices. For example, you might set up a file transfer to upload log files from some of the application devices on your network. You should note that file transfer can only be performed with devices that implement the LonTalk file transfer protocol, and that implement user-files. NOTE: Configuration property template and value files are not user-files.
Dim fileBuffer as Variant Dim byte1 as Byte fileBuffer = MyFileTransfer.ReadFile() byte1 = fileBuffer(1) The ReadFile() method returns an array of bytes of the length transferred. Your application should query the returned Variant to determine the number of available bytes, which could be as little as 0 if an error occurred. To write a file to a device or group of devices, follow these steps: 1. Obtain a FileTransfer object from the System object's FileTransfer property.
should never be updated, as this defines the application interface. The configuration property value file must be updated with ConfigProperty objects or with the DownloadConfigProperties() method to ensure that the LNS database is kept in synch with the values in the configuration value file. For more information on this, see Downloading and Uploading Configuration Properties on page 126.
application should provide feedback and the ability to cancel operations. For example, when displaying a list box of devices in the system, you could provide a Cancel button and display an hourglass while creating the list. When operating remotely, your application should also disable operations that are not supported remotely to prevent the user from selecting them. For example, if your application provides a network recovery command, this command should be disabled when running remotely.
Registering a Mobile Application Mobile network tools should set the PingClass property of their NetworkServiceDevice object to either PingClassMobile or PingClassTemporary. Use PingClassMobile if your application is a permanent part of the network (i.e. it will always be somewhere on the network), but may move from place to place. The LNS Server checks for the presence of mobile devices at the highest frequency, by default every minute.
functions will be executed by an internal LNS thread, as opposed to the thread that instantiated the Object Server. While it is usually more efficient to use direct callback, especially when writing a monitor and control application, or an application that you expect to receive a large number of events, you should be aware that this turns the application into a multi-threaded application.
NOTE: LNS uses an optimized memory allocator that manages its own local heap. This allocator holds most memory that it allocates for future re-use. Therefore, early in an application's run-time, memory usage may continually climb. However, it will eventually reach a point of stabilization. At this point, the memory allocator will have enough memory in its pool so that it does not need to request more memory from the system. Memory freed internally is kept by the allocator, and then re-used.
Dim Dim Dim Dim MySubsystems As LcaSubsystems MySubsystem As LcaSubsystem MyDevices As LcaAppDevices MyBuzzer As LcaAppDevice Set Set Set Set MySubsystems = MySystem.Subsystems MySubsystem = MySubsystems.Item(“Shared Devices.Alarms”) MyDevices = MySubsystem.AppDevices MyBuzzer = MyDevices.Item(“Buzzer”) The following example combines expressions to retrieve the “Alarm Buzzer” AppDevice object with a single line of code: Dim MyBuzzer As LcaAppDevice Set MyBuzzer = MySystem.Subsystems.
Echelon strongly recommends the exclusive use of early binding techniques. Note that LNS director applications may have to use late binding strategies when accessing LNS plug-in software. See the Implementing an LNS Director Application section on page 280 for more information on this. The shorthand using a combined subsystem path such as “Shared Devices.Alarm” as shown in the above example is supported directly by the LcaSubsystems object.
Appendix A - Deprecated Methods and Obsolete Files This appendix lists LNS methods, properties and objects that should no longer be used in LNS Turbo Edition. It also lists files installed with previous versions of LNS that are no longer used, but not removed by the LNS Turbo Edition installation.
Deprecated Methods, Objects, Properties and Events As of LNS Turbo Edition, some methods, objects, properties and events have been deprecated. This section provides a list of those items. Some have been deprecated because they were never implemented in LNS, or because they are no longer applicable or useful. Others have been deprecated because they have been replaced by new features with better functionality.
Build Method (U) CloseComponent Method (U) Export Method (AppDevice and DeviceTemplate Objects) (U) GetElement Method (BA) GetElementFromDevice Method (BA) GetField Method (NetworkVariable Object) (BA) GetRawValues Method (BA) GetRawValuesFromDevice Method (BA) Link Method (U) Lock Method (U) OpenComponent Method (U) Purge Method (BA) RecoverFromNssDb Method (U) Remove Method (Networks Collection) (BA) SetCapacity Method (NLA) SetElement Method (BA) SetElementFromDevice Method (BA) SetRawValues Method (BA)
DsService Property (BA) DsUseBoundUpdates Property (BA) DynamicNvPersistenceMode Property (BA) ExportDirectory Property (U) ExportFormat Property (U) FormatLocale Property (BA) GraphicsDirectory Property (U) HardwareTemplate Property (U) HardwareTemplates Property (U) LockDuration Property (U) ProgramTemplate Property (U) ProgramTemplates Property (U) RawValue Property (ConfigProperty Object) (BA) RawValueFromDevice Property (ConfigProperty Object) (BA) RemoteIgnorePendingUpdate Property (BA) SingleUserMode
Table A.2 Obsolete Application Developer’s Kit Files Installation Directory File Name \import Actuator.xif, Actuator.xfb, analog.h, anlgsnsr.apb, anlgsnsr.nc, anlgsnsr.xif, display.h, rtclock.h, scptanlg.apb, scptanlg.nc, scptanlg.xfb, scptanlg.xif, sensor.xif, sensor.xfb, temperat.h \DataServer Include\dsv.h, Include\LnsDsError.h, Lib\lcadatsv.lib \NetworkServices\include Neuron.h, ni.h, ni_app.h, ni_callb.h, ni_comm.h, ni_mgmt.h, ni_nmexp.h, ni_nmext.h, ni_slta.h, ni_snvt.
328 LNS Programmer's Guide
Appendix B – LNS, MFC and ATL This section provides information you may find useful when using LNS with MFC and ATL.
LNS, MFC and ATL Versions 6.0 and higher of Microsoft Visual C++ offer two ways to import the interfaces exposed by the LNS Object Server ActiveX Control into an existing project: the MFC Class Wizard, and the ATL #import statement described in Chapter 4 of this document. As of LNS Turbo Edition, the legacy MFC wrappers, in the files lcaobjsv.h, lcaobjsv3.h, and lcaobjsv.cpp, are no longer included with the LNS Application Developer's Kit.
Object Server and also advise for LNS Object Server events. This code is included in the LNSMonitorCtrl.cpp file included with the LNS Turbo Edition examples suite. HRESULT CLNSMonitorCtrlApp::OpenLca() { HRESULT hResult = S_OK; hResult = m_pObjectServer.CreateInstance (_T("LonWorksObjectServer.1")); if (hResult != S_OK) { // failed to create object server instance m_IDS = IDS_FAILED_OBJSERVER; return hResult; } // Creating ObjectServer Event Handler...
lca::lcaEventIdNvMonitorPointEvent, OnNvMonitorPointEvent, &OnNvMonitorPointEventInfo) SINK_ENTRY_INFO(IDC_EVENTS, lca::DIID__DLcaObjectServerEvents, lca::lcaEventIdMsgMonitorPointEvent, OnMsgMonitorPointEvent, &OnMsgMonitorPointEventInfo) END_SINK_MAP() The wrapper function in lcaobjsv.
2. Select the Projects tab on the dialog that opens, and select MFC AppWizard (exe). Then, enter a project name and verify that the Create a new workspace option is selected. Click OK to continue. 3. This opens the MFC AppWizrd – Step 1 dialog. Select Dialog based as the type of application, and click Finish. 4. This opens the New Project Information dialog. Click OK. At this point, an empty dialog with OK and Cancel buttons opens. 5.
Figure B.1 Visual C++ Toolbox Drag this new icon anywhere onto the empty dialog mentioned in step 4. 10. Right-click the new icon, and select Class Wizard from the pop-up menu that appears. This opens the MFC Class Wizard dialog. 11. Select the Message Maps page. Then open the Add Class… drop-down list and select the From a type library… submenu. This opens the Import from Type Library dialog. Enter c:\lonworks\bin\lcaobjsv.ocx (or whatever the Path to control field was set to in step 6) and click Open. 12.
1. Open the lcaobjsv3.h file. From the Edit menu, select Replace. In the Find what field, enter “ILca.” Note that the first two letters are capitalized. In the Replace with field, enter “Lca.” Note that the first letter is capitalized. 2. Click Replace all, and then save the changes to the file. 3. Open the LcaObjSv.cpp file, and make the same change to this file as described in steps 1 and 2. The class wrappers are now complete, with all LNS Turbo Edition features available.
336 LNS Programmer's Guide
Appendix C – LNS Turbo Edition Example Application Suite This appendix provides an overview of the example applications included with LNS Turbo Edition. This includes an example network management application, an example monitor and control application, and an example director application.
LNS Turbo Edition Example Application Suite LNS Turbo Edition features several example applications you will find useful when developing your own applications. This appendix provides an overview of each application. In addition, each application includes comments that provide more specific detail on the example code.
Figure C.1 Example Network Management Application The following sections describe how you can use this dialog, and reference the location of the source code you can view to see how the tasks you perform are accomplished using LNS. Initializing a Network There are several steps you need to take when opening a network with an LNS application, as described in Chapter 4 of this document. To initialize the example network management application, follow these steps from the dialog shown in Figure C.1: 1.
In addition, the Network Name drop-down box will list all networks accessible by your application as soon as you select a client type. For source code information, see CDlgInitializeGeneral::SelectClientType in the dlginitializegeneral.cpp file. The client type is passed into m_iClientType. The description of the monitor and control example later in this appendix provides more details on each of the client types you can select. 2. From the Interface Name drop-down box, select a network interface.
device configuration updates to the network. This allows devices, dynamic network variables, and network variable connections to be quickly created in the network database. The Network Path text box displays the current network’s DatabasePath property. It is read-only before the database name string is edited, and after a new database name is selected. Otherwise, it is possible to alter the path name while the Object Server is initialized as a local client.
in Figure C.2, the Lamp_02, Lightswitch_01 and Thermostat_03 devices all belong to the 111 Main.First Floor.Bathroom subsystem. The bottom part of the dialog provides LNS licensing information relevant to your network, and information on the resources available to your network. For source information on this part of the dialog, see the lcahelper.cpp file and CDlgMain::RefreshStatistics() in the dlgmain.cpp file.
• Set device template defaults from device • Upload value set to unknown in the LNS database • Set all configuration property values to unknown. Each of these choices causes the application to call either the DownloadConfigProperties() or the UploadConfigProperties() methods with the appropriate options set. Consult Chapter 6 of this document, or the LNS Object Server Reference help file, for more information on these methods. 5. Click OK.
Item Diagnose Button Description This command exposes the following network management tasks of the AppDevice or Router objects: • Wink Device (AppDevice objects only) • Go Offline • Go Online • Test Device • Reset Device These operations, along with a Results Pane are displayed through the Device Diagnostics dialog that opens when you select the Diagnose button.
Table C.2 Example Network Management Application Task Initialize and open the LNS ObjectServer GUI Code CDlgInitialize LNS Interface Code CLcaHelper::OpenObjectServer CDlgInitializeLicense CDlgInitializeGeneral Create a network database based on a database template. CDlgInitializeGeneral CLcaNetMgmtHelper::CreateNetwork() Add an LNS Server reference for a Lightweight client application. CDlgInitializeGeneral CLcaNetMgmtHelper::CreateNetworkReference() Open a network.
Task GUI Code Creating connections between devices. LNS Interface Code CLcaNetMgmtHelper::CreateNetworkVariableConne ctions_ForEventBasedMonitoring CLcaNetMgmtHelper ::CreateNetworkVariableConnections_ForHVAC CLcaNetMgmtHelper::CreateNetworkVariableConne ctions_ForLightingControl Configuring devices using ConfigProperty objects. CDlgIdentify_CpUpdate CDlgIdentify_CpUpdate::OnOK Testing devices. CDlgDiagnostics CDlgDiagnostics::OnTest Moving devices between subsystems and between channels.
Figure C.3 Example Monitor and Control Application The following section describes how you can use this dialog, and reference the location of the source code you can view to see how the tasks you perform are accomplished using LNS. 1. First, select a client type. This determines how the example monitor and control application will connect to the LNS Server. The different client types are introduced in Chapter 3 of this document.
1. Close the monitor and control application, and launch the network management application from the client PC. 2. Select Remote Lightweight Client as the Client Type option. 3. Type in the network name 4. The Network Path textbox will turn into Server IP address and port and will be enabled. Enter this information using the following format: . 5. Click Manage. 6. Close the network management application.
names of all networks in the Networks, RemoteNetworks or VNINetworks collections, as dictated by the client type selected in step 1. If Server Independent was selected, the VNINetworks collection is used. If Remote Full client using Remote Networks Collection was selected, the RemoteNetworks collection is used. In all other cases, the Networks collection is used. For source code information, see CLcaMonitorDlg::OnSelchangeNetworkName() in the LcaMonitorDlg.cpp file. 4.
7. If you clicked the Temporary Monitor Set button in step 6, a dialog with a tree view of the AppDevice objects installed on your network will open. Select the AppDevice object containing the network variable(s) you want to monitor. A temporary monitor set will be created containing a network variable monitor point for every network variable on the devices main and custom interfaces.
Task GUI Code Use of the Tag property for “pigeonholing” data values LNS Interface Code CLcaMonitorHelper::CreateMonitorPointTag in CLcaMonitorHelper:: AddNVMonitorPoints CLcaMonitorHelper:: AddMsgMonitorPoints CLcaMonitorHelper::AddTemporaryNVMonitorPoints CLcaMonitorHelper::AddTemporaryMsgMonitorPoints Change event tracking. Handling events CEventSink::OnNvMonitorPointEvent Explicitly reading or writing a monitor point.
Figure C.5 Example Director Application Dialog To use the example director application, select the network you want to open from the Network drop-down box. Then, select a network interface from the Network Interface drop-down box and click Open Network. You can then use the 4 tabs of the dialog shown in Figure C.5, as described below: • Select the Registry Entries tab to display the keys and associated class IDs for the plug-in applications associated with the network.
The System Registered list shows the names of the plug-in applications that have been registered for use with the open network’s system. It lists the associated RegisteredServer property of the ComponentApp object for the lcaCommandIdRegister command in the ComponentApps collection of the System scope. • Select the LNS Collections tab to display the list of all the ComponentApp objects in the database, based on scope. • Select the Plug-in Launching tab to invoke commands on target devices on the network.
