Echelon LNS Plug-in User Manual

0 7 8 - 0 3 9 3 - 0 1 A®LNS®Plug-in Programmer’s Guide Release 4

1 Introduction This chapter describes the types of plug-ins that are used with LONWORKS networks, and it describes how director applications request

Introduction An LNS plug-in is an out-of-process automation server that implements the COM-based LNS Plug-in API so that it may be instantiated and co

configuration properties and enforce limits on configuration property values. You can create a device plug-in executable that operates on multiple de

• A simple out-of-process server task model that supports plug-ins in the .NET environment (LNS plug-ins are out-of-process COM servers, for which su

2 Creating and Redistributing LNS Device Plug-ins This chapter explains how to create an LNS device plug-in using the LNS Plug-in Framework Develope

Creating and Redistributing Plug-ins Overview You can use the LNS Plug-in Framework Developer’s Kit to create an LNS device plug-in and create an inst

• The ObjectServer folder is common to all computers with the LNS Server runtime installed. • The Assemblies folder contains the .NET assemblies re

Creating the Plug-in Project You can create a C# or VB.NET plug-in project using Microsoft Visual Studio 2005 (or later) following these steps (note t

• In the Default namespace property, change the namespace to <YourCompany>.<YourProject>. • In the Assembly name property, enter a uniqu

Echelon, LON, LonWorks, Neuron, 3120, 3150, Digital Home, i.LON, LNS, LonMaker, LonMark, LonPoint, LonTalk, NodeBuilder, ShortStack, and the Echelon l

7. Copy the PostBuild.bat file from the LonWorks\ObjectServer\Examples\PluginFramework\ExampleCSPlugin to your project folder. 8. In the Post-bui

13. Select the Echelon.LNS.Interop and the Echelon.LNS.Plugin.Framework .NET assemblies, and then click OK. • Echelon.LNS.Interop enables your ap

Implementing the Plug-in Server Class To implement your plug-in server class, modify the source as follows: 1. Add using System.Runtime.InteropServic

5. Add a PluginInfo public static property that returns a reference to a PluginInfo object that describes your plug-in. For efficiency, you should r

Field Description MultiObject Indicates to a director whether the plug-in supports MultiObject functionality. When supported, the MultiObject functi

Field Description Prelaunch Indicates to a director whether the director may launch the plug-in in the background before the plug-in is needed. Supp

Field Description Scope A ComponentAppScope value identifying the scope of the plug-in’s command. This is known as the command scope, which should no

"Tests device.", // Description EnumCommandIds.Test, // CommandId

Field Description ObjectName The fully specified name of the LNS object on which to perform the command, as specified by the director. LcaObject A

Registering DeviceTemplate and LonMarkObject Scoped Plug-in Commands The LNS Plug-in Framework does not currently support registration of DeviceTempla

Table of Contents Preface ... vi Purpose ...

Redistributing your Plug-in After you have developed and tested your plug-in, you can create an installation project for it so that you can distribute

3 How Plug-ins Work with Directors This chapter details how directors and plug-ins interact. Once you understand the basic interaction between dire

How Plug-ins Are Represented in the LNS Object Server The LNS network database represents physical objects on a LONWORKS network with objects in the d

computer while checking to make sure that it does not overwrite newer versions. Next, the setup program adds a number of items to the Windows registr

1. The plug-in fetches the appropriate ComponentApps collection, based on the scope of the action. If the scope of the action is device or functiona

The plug-in does not need to register its registration command; the director will automatically add the registration command by adding a ComponentApp

Director Action Plug-in Response requests. The Plug-in Framework automatically manages the plug-in’s reference counts. See How Plug-ins Know When T

Director Action Plug-in Response Releases the instance of the plug-in it created. COM decrements the plug-in’s usage count. If this is the last use

5. If the plug-in has not set the MultiObject value in the Windows registry to 1, release the reference to it. SingleInstance functionality is descr

How Directors Pass Object Names The objectName parameter of the SendCommand() method specifies the location of the target object in the LNS object hie

Appendix F Running the ACME Example C# Plug-in... 51

with the (now terminated) plug-in will result in exceptions in the directors. The desired behavior would be for the plug-in to become invisible (inst

After creating an instance of a plug-in, the director can set any property at any time, with the exception that the NetworkInterfaceName property, whi

Appendix A Standard Plug-in Commands This appendix lists the standard commands that may be implemented by plug-ins. Plug-ins may also implement manu

The following table lists the standard LNS plug-in commands. Command Description LcaCommandBrowse 20 Monitor and control the object. LcaCommandBuil

Appendix B Standard Plug-in Properties This appendix lists the standard properties that must be implemented by plug-ins, as well as optional properti

The following table lists the standard LNS plug-in properties. Note that the property names CharacterEncoding and LanguageId are reserved for future

Name Type Description Batch Read-Write Long The optional Batch property allows plug-ins that support the MultiObject feature to cache incoming reques

Name Type Description Prelaunch Long The optional Prelaunch property allows a director to launch the plug-in in the background, typically when the di

Name Type Description Version Read-Only String Version number of the plug-in. The version number is in “<major release>.<minor release>”

Appendix C Standard Plug-in Object Classes This appendix lists the standard classes of objects that may be passed to plug-ins, as well as the address

The following table lists the standard LNS plug-in classes. Object Class ID Addressing Syntax LcaClassIdAppDevice 7 network/system.subsystem[.subs

Object Class ID Addressing Syntax LcaClassIdExtension 50 extension (for Object Server) network/extension network/system.subsystem[.subsystem…]/appDe

Object Class ID Addressing Syntax LcaClassIdNetworkInterfaces 15 network/LcaNetworkServiceDevice:networkServiceDevice network/system LcaClassIdNetwo

Appendix D Standard Plug-in Exceptions This appendix lists the standard exceptions that may be thrown by plug-ins. Plug-ins may also throw manufactu

The following table lists the standard LNS plug-in exceptions. Exception Code Description LcaComponentErrCantFindObject 20005 The plug-in could no

Appendix E Glossary This appendix provides definitions for key terms and concepts associated with plug-ins.

Glossary Action A command/object class pair implemented by a plug-in. A plug-in is defined by the actions that it can perform (for example, by the se

The items managed by LNS. LNS treats each network as a collection of objects. These objects include application devices, routers, connections, funct

Preface You can use LNS device plug-ins to simplify the installation of your devices for network integrators. This manual provides an overview of the

The command scope of an action is indicated by the ComponentApps collection that the command is in. If an action is in the ObjectServer object’s Comp

Appendix F Running the ACME Example C# Plug-in This appendix describes the function of the ACME Example C# Plug-in provided with the LNS Plug-in Fram

Running the ACME Example C# Plug-in After installing the LNS Plug-in Framework Developer’s Kit, the ACME Example C# Plug-in will be installed on your

3. Register the ACME Example C# Device Plug-in (Version 1.0) plug-in and observe register command calls. The following image shows a representat

5. Observe the command calls that occur after selecting the describe device command. 6. The ACME Example Device Plug-in dialog opens and displays th

www.echelon.com

Purpose This document describes how to write LNS plug-ins using .NET programming languages such as C# and Visual Basic .NET. After reading this docum

LNS®Programmer’s Guide Describes how to use the LNS Object Server ActiveX Control to develop an LNS application on a Microsoft Windows Vista™, Server

Region Languages Supported Contact Information Europe English German French Italian Echelon Europe Ltd. Suite 12 Building 6 Croxley Green Busin