LM-UG1 6/19/06 9:30 AM Page 1 LonWorks® Network XML Programmer's Guide LonMaker® User’s Guide www.echelon.
Echelon, LON, LONWORKS, LonTalk, Neuron, LONMARK, 3120, 3150, LNS, LonMaker, and the Echelon logo are trademarks of Echelon Corporation registered in the United States and other countries. LonPoint and LonSupport are trademarks of Echelon Corporation. Other brand and product names are trademarks or registered trademarks of their respective holders.
Table of Contents Preface ..................................................................................................... v Audience......................................................................................................... vi Related Reading............................................................................................. vi Content ...........................................................................................................
Properties within Application Device Object Elements..................... 28 Example............................................................................................ 30 Properties within Device Template Object Elements ....................... 31 Example............................................................................................ 31 Message Tags......................................................................................... 31 Attributes.....................................
Preface This guide describes how to create and modify a LonMaker network using the LonMaker XML Plug-in. It explains how to start the LonMaker XML Plug-in, export a LonMaker network to a LonMaker network XML file, and then import it back to create a new network or update an existing network. It provides the XML schema that defines the format of a LonMaker network XML file, and it details the actions and attributes you can specify for the elements in a LonMaker network XML file.
Purpose This guide explains how to programmatically interface with the LonMaker XML Plug-in to update and create a LonMaker network. Audience This guide is intended for software developers creating applications interfacing with the LonMaker XML Plug-in. The applications may be written in any language that supports COM components or ActiveX controls, including Microsoft® Visual C# and Microsoft Visual Basic.
You can also view free online training or enroll in training classes at Echelon or an Echelon training center to learn more about developing devices. You can find additional information about LonMaker training at www.echelon.com/training. You can obtain technical support via phone, fax, or e-mail from your closest Echelon support center. The contact information is as follows (check www.echelon.
1 Using the LonMaker XML Plug-in This chapter explains how to write a director application that invokes the export and import functions of the LonMaker XML Plug-in. It describes the optional export and import automation properties you can set. It provides code samples that demonstrate how to invoke the export and import commands and how to define automation properties. It describes how to create a trace log in order to help troubleshoot your director application.
Introduction You can speed up your network design and ensure your devices are configured correctly by creating a custom LonMaker user interface. Creating a custom LonMaker user interface is simple: you create a an application that reads or writes XML files and then invokes the LonMaker XML Plug-in to automatically export the LonMaker network created and import it into an LNS application.
Tip: You can download an assembly provided by Echelon, named PlugInWrapper.dll, to expedite the development of your custom LonMaker application. You can use this assembly instead of developing your own director application. To use the PlugInWrapper.dll file, you must have LNS Turbo Editions 3.23 (or newer) installed on your computer. The PlugInWrapper.dll file and the latest LNS Service Pack are available on the Echelon Web site at www.echelon.com/downloads. After you download the PlugInWrapper.
Defining Export Automation Properties You can define standard LNS Plug-in properties and the following export automation properties in the director application. See Appendix B of the LNS Plug-In Programmer’s Guide for more information about the standard plug-in properties you can define. Property Name XmlFileName Type BSTR Description Specifies the path and name of the XML file to be created. If a file with the specified name already exists, it will be overwritten.
Property Name Type Description exported data. TemplateExport ConnDescExport Long Long Specifies which device templates are to be included in the exported XML file. Specify one of the following options: • 0. Reports all device templates defined in the network. This is the default. • 1. Does not report any device templates. • 2. Reports only device templates that are referenced in the exported data. Specifies which connection description templates are to be included in the exported XML file.
// *Insert export automation properties before invoking send command* // Option to export NV and device-specific values m_lmXml.XmlOptions = 0x10 | 0x40; //Option to export subsystem specified in SendCommand m_lmXml.ExportScope = 2; m_lmXml.SendCommand(23, 5, "MyXmlNetwork/MyXmlNetwork/Subsystem 1"); m_lmXml.Visible = true; } } } Importing a LonMaker Network You can use the LonMaker XML Plug-in to automate the importing of a LonMaker network.
Defining Import Automation Properties You can define standard LNS Plug-in properties and the following import automation properties in the director application. See Appendix B of the LNS Plug-In Programmer’s Guide for more information about the standard plug-in properties you can define. Property Name XmlFileName Type BSTR LogFileName BSTR XmlOptions Long Description Specifies the full path of the XML file to be imported. The file must already exist.
// Option to suppress status and options dialog m_lmXml.XmlOptions = 0x01 | 0x02; //Option to create and specify location of import log m_lmXml.LogFileName = "C:\\Lm\\XML\\XML Network\\ImportLog.XML"; m_lmXml.SendCommand(23, 5, "MyXmlNetwork/MyXmlNetwork/Subsystem 1"); m_lmXml.Visible = true; } } } Troubleshooting a Director Application You can create a trace log to verify that the LonMaker XML Plug-in is receiving the commands and options specified in your director application.
Tip: You can import two or more individual XML files to overcome order dependencies in your XML data that are incompatible with this sequence. How the LonMaker XML Plug-in Updates Objects The LonMaker XML Plug-in updates objects by matching the object elements in the XML file to their corresponding objects in the LNS network database.
10 Using the LonMaker XML Plug-in
2 Using the XML Schema This chapter provides an overview of the XML schema that defines the structure and content of a LonMaker network XML file. It lists the actions and properties you can set for each object element in a LonMaker network XML file. It provides examples of how each object element appears in a LonMaker network XML file. It includes a programming example that demonstrates how to export, modify, and import a LonMaker network XML file.
XML Schema Overview The LonMaker XML plug-in includes an XML schema that defines the structure and content of a LonMaker network XML file. The XML schema documents the XML file generated and read by the LonMaker XML plug-in. You can use the XML schema to validate the contents of a LonMaker network XML file to some extent. For example, the XML schema validates the length and characters for the string values of object properties; however, it does not validate the numeric and enumerated values.
The applicable Action attributes and properties for each object element are detailed in the next section, Setting Object Attributes and Properties Overview. Name The names of an object element and its properties generally match those in the LNS network database (without the leading “Lca”).
• • • • • • • Configuration properties Targets Extensions Channels Connection descriptions Device templates Component applications For each object, individual tables that describe the applicable attributes and properties that you can set are provided. Functional block, network variable, message tag, and configuration property properties are reported within both application device and device template object elements.
RootSubsystem Y Y DomainId Y Y ExportScope Y N Subsystems Y Y Channels DeviceTemplates ConnectDescTemplates Y Y Y Y Y Y The LNS Subsystem that contains all of the objects reported in the XML file. If the entire network is reported, this value is empty. On import, this value specifies the subsystem into which items are to be created; however, you can override this value. Series of 0, 2, 6, or 12 hex digits reporting the domain ID of the network.
NV/message tag target definitions. See Targets for more information on using subsystem references.
Example Subsystem 2 XML NETWORK Subsystem 2 Subsystem 1.Subsystem 2 6 LONBASIC Subsystem 4.890000 6.
The possible values are as follows: 0 ConfiguredRouter 1 LearningRouter 2 RepeaterRouter 3 BridgeRouter 4 PermanentRepeaterRouter 5 PermanentBridgeRouter 18 Location LocationText Y Y Y Y Description Y Y AuthenticationEnabled Y Y InitialAuthenticationKey Y Y Shape/StencilName Y Y Shape/MasterName Y Y Shape/PinX Y Y Shape/PinY Y Y CommissionStatus Y N AttachmentStatus Y N If you do not specify the Class property when you create a router, “Configured Router” is the default route
PingClass Y Y An enumerated value indicating the expected movement of the router, which determines the frequency in which it is pinged. The possible values are as follows: 0 Default (default ping interval is used) 1 Mobile (1-minute ping interval is used) 2 Temporary (2-minute ping interval is used) 3 Stationary (15-minute ping interval is used) 4 Permanent (device is not pinged).
800600000000 False LonPoint3 LonPoint Router 4.510000 2.
Commission State CP 0 1 0 1 2 3 4 False True DEFAULT ONLINE OFFLINE DISABLE RESTORE 0 FROM_DB 1 FROM_DEVICE 2 DEFAULTS image search path. If an application image is specified, the file exists, and the Commission attribute is set to True, the image is written to the device. This field is empty by default. You must set this property to True to enable commission-related operations. You can specify the state of the router application.
NeuronId Y Y On export, this property is only reported if the value is non-empty. On import, the value of this property must be unique within the network. Location Y Y The location value reported as 12 hex digits. LocationText Y Y The location value reported as ASCII text. Non-printable ASCII characters are reported as \xHH, where HH is two hex digits. If both the Location and LocationText properties are specified, the value in the Location property will be used on import.
is non-empty. Priority Y Y On export, the current value (specified manually or selected automatically) is reported. There is no indication of how the value was selected. On import, LNS will automatically select a priority slot for the application device if you specify a value of 255. AliasCapacity Y N The number of alias table entries available on the application device. AliasUseCount Y N The number of alias table entries consumed by the application device.
is to be assigned. Subnet/Name Y Y If you specify a subnet name or ID that differs from the current subnet, the import operation will attempt to move the application device to the specified subnet. If you specify both the subnet name and ID, the subnet name will first be used to look up the subnet. If the subnet is not identified, the subnet ID will be used.
Functional Blocks Attributes Attribute Action Ref Applicable Values 1 IGNORE 2 CREATE 3 CREATE_UNIQUE 4 UPDATE 5 MODIFY 6 DELETE 7 COMMISSION Description/Notes If you are creating a dynamic functional block, you must specify the functional block’s Name, and FunctionalProfile properties. If you delete a dynamic functional block, it is removed from both the LNS network database and your network drawing on import.
3 4 5 6 Manf ManfDevClass ManfDevClassSubClass ManfDevType Virtual functional blocks do not contain this property. IsDynamic IsVirtualFb Y Y N N An enumerated value indicating whether the functional block is static or dynamic. The possible values are as follows: 0 False (static) 1 True (dynamic) An enumerated value indicating whether the functional block is a virtual functional block.
information. Example AI- 1 False Analog Input[0] Echelon Analog/Digital Input Manf UFPTAnalogDigitalInput LonPoint3 Analog Input 5.860000 2.
Example Analog Input[1] False Analog Input[1] Echelon Analog/Digital Input Manf UFPTAnalogDigitalInput A generic object without feedback, used with any form of sensor AI_Analog_2
Direction IsTypeConfigurable Y Y Y N TypeSpec/Scope Y Y TypeSpec/ProgramId Y Y TypeSpec/TypeName Y Y Format Y Y IsDynamic Y N approved functional profile, or by the user (in the case of a network variable not specified in those guidelines. The LonMark Member Number can be specified when creating a dynamic NV during import; however, the value cannot be modified on an existing NV. An enumerated value indicating the direction of the NV.
Selector Y N Specifies the selector used for the NV alias. Value Y N HasShape Y Y To report NV values, you must specify the Export NV values option (&H10) in the XMLOptions export automation property (see Invoking the Export Feature in Chapter 1). If the NV value cannot be read from the application device, the text string “?Unknown” is reported. An enumerated value indicating whether the NV is represented by a shape on the FB shape in the network drawing.
Properties within Device Template Object Elements Supported by Function? Property Name Export Y Import Y Index Y N LonMarkMemberIndex Y N ProgrammaticName Y N LonMarkMemberNumber Y N DirectionID Y N IsTypeConfigurable Y N TypeSpec/Scope Y N TypeSpec/ProgramId Y N TypeSpec/TypeName Y N ConnDesc Y N ConfigProperties Y N Description/Notes There are no modifiable ConfigProperties properties in a device template; therefore these entries are ignored during import.
definitions. See Targets for more information. Properties within Application Device Object Elements Supported by Function? Property Name Export Y Import Y Direction Y Y Description/Notes The name of the message tag. An enumerated value indicating the direction of the message tag. The possible values are as follows: 0 1 2 You cannot modify this property on existing message tags.
False Properties within Device Template Object Elements Supported by Function? Property Name Export Y Import Y Direction Y Y AddressTableIndex Y N ConnDesc Y N Description/Notes Example msg_in Input 65534 ConnectDescTemplate_0 Configuration Properties Attributes Attribute Action 1 4 5 7 Applicable Values IGNO
Dimension Y N FlagsByte Y N The number of elements in the CP are reported. A value of 1 indicates a single element. A value greater than 1 indicates multiple elements (an array for example). An enumerated value indicating the type of flag set on the CP. The possible values are as follows: 1 Disabled (the CP can only be changed when the application device is disabled). 2 Offline (the CP can only be changed when the application device is offline). 4 Constant (the CP is read-only).
Properties within Device Template Object Elements Supported by Function? Property Name Export Y Import N DeviceSpecificAttribute Y Y ConstantAttribute Y Y Dimension Y N FlagsByte Y N Value Y N Description/Notes If you set the ConstantAttribute to True in the DeviceTemplate object element, the Value properties in the ApplicationDevice object element are ignored on import.
SubsystemName Y Y DeviceName Y Y FunctionalBlockName Y Y TargetName Y Y or override components of the referenced object. On export, the subsystem name is reported relative to the root subsystem of the export. See Using References in this section for more details. On import, the name can be specified as either an absolute path or a relative path. Specifies the name of the application device of the target NV/message tag. Specifies the name of the functional block of the target NV/message tag.
TargetSub AO- 1 AFB- 1 A1 The NV/message tag connection will use the existing connection description if the recompute request fails for any reason. Extensions Attributes Attribute Action 1 2 3 4 5 6 7 Applicable Values IGNORE CREATE CREATE_UNIQUE UPDATE MODIFY DELETE COMMISSION Description/Notes To create an extension record, you must specify the Name property.
4 5 6 7 8 9 10 11 13 16 17 18 19 22 23 27 8194 8195 8209 8210 8211 8208 38 Value/Data Y Y Value/ NumberDimensions Y Y Value/ ElementSize Y Y Value/ Dimension Y Y Value/ Dimension / LBound Y Y R4 R8 CY DATE BSTR DISPATCH ERROR BOOL UNKNOWN I1 UI1 UI2 UI4 INT UINT SAFEARRAY ARRAY_I2 ARRAY_I4 ARRAY_UI1 ARRAY_UI2 ARRAY_UI4 ARRAY_I1 Floating point Floating point Signed decimal: Unsigned decimal (high order 32 bits: low order 32 bits) Floating point Character string Hex Signed decimal Signed d
Value/ Dimension/ NumberElements Y Y assumed. Applies to array values. Specifies the number of elements in the current dimension. On import, this value must be specified, and it must be greater than 0.
11 27 28 29 24 16 17 15 15 25 26 255 30 152 142 143 144 Delay Y Y TP/RS485-1250 DC-78 DC-625 DC-1250 FO-20S PL-20C-LOW PL-20N-LOW PL-20A PL-20A-LOW IP-10L IP-10W BACKPLANE CUSTOM FO-20L DC33-78 DC33-625 DC33-1250 The expected longest round-trip time of a message traveling on the channel. You can specify the value of the Delay property, but the fact that the value has been overridden is not reported. If you want to use the default value, set this property to 0.
reported. UseAuthenticationFlag Y Y An enumerated value indicating whether the NV/MT connection uses authentication. The possible values are as follows: 0 1 UsePriorityFlag Y Y An enumerated value indicating whether the NV/MT connection uses priority messaging.
of “None” is reported on export. ReceiverTimer Y Y An encoded integer. If you have not overridden the default receiver timer, this property is not reported on export. To use the LNS default value on import, delete this property. RepeatCount Y Y If you have not overridden the default repeat count, this property is not reported on export. To use the LNS default value on import, delete this property. RepeatTimer Y Y An encoded integer.
ReceiveTimer TransmitTimer 0 3 1 6 UnackdRpt 0 Device Templates Attributes Attribute Action 1 2 3 4 5 6 Applicable Values IGNORE CREATE CREATE_UNIQUE UPDATE MODIFY DELETE Description/Notes Device templates will match existing
Classification/ ModelNo Y N Only reported if Format is 8 or 9. DeviceValidation Y Y An enumerated value indicating the level of validation performed by LNS when you commission an application device. The possible values are as follows: 0 1 2 4 Normal NoChannelValidation NoProgramInterfaceValidation NoProgramIdValidation An instance of this property is reported on export for each validation option you have set.
Component Applications (Plug-Ins) Component Application objects are reported on export at the system level (in which case they are reported at the same level as the Channels, DeviceTemplates, ConnectDescTemplates, and RootSubsystem elements), the DeviceTemplates level, and within the FunctionalBlocks property at the DeviceTemplates level.
4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 46 Systems Subsystem Subsystems AppDevice AppDevices Router Routers RouterSide Channel Channels NetworkInterface NetworkInterfaces Subnet Subnets Connections Interface Interfaces TemplateLibrary NetworkVariable NetworkVariables MessageTag MessageTags ConfigProp ConfigProps LonMarkObject LonMarkObjects ComponentApp ComponentApps HardwareTemplate Ha
69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 DefaultAppFlag Y Y CommandId Y Y If this flag is modified on import, you must update other conflicting plug-ins to clear the default flag. An enumerated value that specifies the operation performed by the plug-in.
41 50 51 60 61 VersionNumber ManufacturerId Y Y Y Y Replace Register Unregister Recover MonitorRecovery Specifies the plug-in version. Specifies the plug-in manufacturer. Example Echelon LonPoint Configuration EchelonLonPointConfiguration.
//create Directory for XML file DirectoryInfo di = Directory.CreateDirectory("C:\\Lm\\XML\\MyNetwork\\"); //create XML file m_lmXml.XmlFileName = "C:\\Lm\\XML\\MyNetwork\\Export.XML"; // Create the XML writer options XmlWriterSettings settings = new XmlWriterSettings(); settings.ConformanceLevel = ConformanceLevel.Document; settings.Indent = true; settings.IndentChars = (" "); //Create the XML Writer using (XmlWriter writer = XmlWriter.Create(m_lmXml.XmlFileName)) { writer.
writer.WriteStartElement("IsVirtualFb"); writer.WriteAttributeString("ID", "0"); writer.WriteString("False"); writer.WriteEndElement(); writer.WriteElementString("ProgrammaticName", "Digital Encoder[0]"); writer.WriteElementString("FuncProfileName", "Echelon Digital Encoder"); writer.WriteStartElement("Scope"); writer.WriteAttributeString("ID", "3"); writer.WriteString("Manf"); writer.WriteEndElement(); writer.WriteElementString("FuncProfileProgrammaticName", "UFPTDigitalEncoder"); writer.
writer.WriteEndElement(); // End NetworkVariable Element writer.WriteEndElement(); // End NetworkVariables Element writer.WriteEndElement(); // End FunctionalBlock Element writer.WriteEndElement(); // Write functional block #2 writer.WriteStartElement("FunctionalBlock"); writer.WriteAttributeString("Handle", "3"); writer.WriteElementString("Name", "Digital Output[0]"); writer.WriteStartElement("IsVirtualFb"); writer.WriteAttributeString("ID", "0"); writer.WriteString("False"); writer.
// End NetworkVariable Element writer.WriteEndElement(); // End NetworkVariables Element writer.WriteEndElement(); // End FunctionalBlock Element writer.WriteEndElement(); // End FunctionalBlocks Element writer.WriteEndElement(); //End AppDevice Element writer.WriteEndElement(); //End AppDevices Element writer.WriteEndElement(); //End Subsystem Element writer.WriteEndElement(); //End Top-level Subsystem writer.WriteEndElement(); //Start Channels writer.WriteStartElement("Channels"); //Write Channel writer.
//Option to create and specify location of import log m_lmXml.LogFileName = "C:\\Lm\\XML\\MyNetwork\\Import.
54 Using the XML Schema
Appendix A LonWorks Network XML Schema This appendix presents the XML schema that defines the structure and content of a LonMaker network XML file.
LONWORKS XML Schema The XML schema used for LonWorks network is as follows: PAGE 65
PAGE 68
PAGE 69
PAGE 70 <
<
LM-UG1 6/19/06 9:30 AM Page 1 LonMaker User’s Guide ® LonMaker® User’s Guide www.echelon.
